@celestia-island/hikari 0.47.1 → 0.48.0

package/package.json

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

package/src/components/HkBlockingToast.scss

@@ -9,7 +9,9 @@
 .hk-blocking-toast-container {
   position: fixed;
   top: 4rem;
-  inset-inline-end: 1rem;
+  /* Same viewport gutter the anchored popups clamp to (16px desktop /
+   * 8px mobile) — the toast stack is a floating layer too. */
+  inset-inline-end: var(--viewport-gutter, 1rem);
   z-index: var(--hk-z-toast, 4000);
   max-width: 24rem;
   pointer-events: none;

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 { viewportGutterPx } from "../runtime/viewportGutter";
 import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
 import "./HkMenu.scss";
 
@@ -58,8 +59,6 @@ export interface HkMenuItem {
   children?: HkMenuItem[];
 }
 
-/** Viewport padding mirrored from HkSelectPanel's popout geometry. */
-const VIEWPORT_PAD = 8;
 /** Width estimate used ONLY to pick a cascade's flip side; the real
  *  panel box is measured by HkSelectPanel itself. */
 const CASCADE_PANEL_W = 224;
@@ -415,8 +414,10 @@ export default defineComponent({
             const r = row.getBoundingClientRect();
             if (!r.width && !r.height) return pointRect(0, 0); // detached
             const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
-            const openRight = r.right + cascadeW <= window.innerWidth - VIEWPORT_PAD;
-            const left = openRight ? r.right : Math.max(VIEWPORT_PAD, r.left - cascadeW);
+            // 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);
             return pointRect(left, r.top);
           },
           contains: (node) => !!rowRefs.value[id]?.contains(node),
@@ -438,11 +439,13 @@ export default defineComponent({
           if (!r.width && !r.height) return pointRect(0, 0);
           const gap = props.offset; // visual-space gap, same as the native placements
           const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
-          const openRight = r.right + gap + cascadeW <= window.innerWidth - VIEWPORT_PAD;
+          // Shared viewport gutter (--viewport-gutter: 8 mobile / 16 desktop).
+          const pad = viewportGutterPx();
+          const openRight = r.right + gap + cascadeW <= window.innerWidth - pad;
           const left =
             side === "right" && openRight
               ? r.right + gap
-              : Math.max(VIEWPORT_PAD, r.left - cascadeW - gap);
+              : Math.max(pad, r.left - cascadeW - gap);
           return pointRect(left, r.top);
         },
         contains: (node) => !!props.anchorRef?.contains(node),

package/src/components/HkModal.tsx

@@ -115,6 +115,20 @@ export function resolveModalWidth(width: string): string {
   return value;
 }
 
+/**
+ * Cap the resolved max-width so the centered desktop frame always keeps
+ * the shared viewport gutter (--viewport-gutter: 16px desktop / 8px
+ * mobile) clear on both sides — a frame wider than the window can spare
+ * used to run edge-to-edge. `100%` resolves against the fixed frame's
+ * containing block (the initial containing block), so the cap tracks the
+ * live window; the ≤767px sheet branch overrides max-width with
+ * `100% !important` in the SCSS, so the intentional full-bleed mobile
+ * sheet is untouched.
+ */
+export function modalFrameMaxWidth(resolved: string): string {
+  return `min(${resolved}, calc(100% - 2 * var(--viewport-gutter, 16px)))`;
+}
+
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -194,7 +208,9 @@ export default defineComponent({
 
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
-    const resolvedWidth = computed(() => resolveModalWidth(props.width));
+    const resolvedWidth = computed(() =>
+      modalFrameMaxWidth(resolveModalWidth(props.width)),
+    );
     // Layer/dialog name: the explicit surface name wins over the header
     // title (which header-less surfaces never pass).
     const resolvedSurfaceName = computed(() => props.surfaceTitle ?? props.title);

package/src/components/HkModal.width.test.tsx

@@ -104,11 +104,15 @@ describe("HkModal width rendering", () => {
 
   it("renders a named preset as the frame's max-width", async () => {
     const content = await mountModal("sm");
-    expect(content.style.maxWidth).toBe("32rem");
+    expect(content.style.maxWidth).toBe(
+      "min(32rem, calc(100% - 2 * var(--viewport-gutter, 16px)))",
+    );
   });
 
   it("renders an arbitrary CSS length as the frame's max-width", async () => {
     const content = await mountModal("560px");
-    expect(content.style.maxWidth).toBe("560px");
+    expect(content.style.maxWidth).toBe(
+      "min(560px, calc(100% - 2 * var(--viewport-gutter, 16px)))",
+    );
   });
 });

package/src/components/HkPopover.scss

@@ -9,7 +9,7 @@
 
 .hk-popover-panel {
   min-width: 0;
-  max-height: min(70vh, calc(100vh - 2 * 8px));
+  max-height: min(70vh, calc(100vh - 2 * var(--viewport-gutter, 16px)));
   /* Width MUST be position-independent (max-content, viewport-capped).
    * The anchored panel is fixed-positioned with shrink-to-fit sizing,
    * and computePosition places it as `left = anchorEnd - panelWidth`
@@ -21,9 +21,10 @@
    * wider frame by frame (demo.dev field report 2026-09-07). Pinning
    * the width to max-content breaks the loop: the panel sizes to its
    * content wherever it sits, and positioning converges in one pass.
-   * VIEWPORT_PAD is 8 (script side). */
+   * The script-side pad reads the same --viewport-gutter token
+   * (runtime/viewportGutter). */
   width: max-content;
-  max-width: calc(100vw - 2 * 8px);
+  max-width: calc(100vw - 2 * var(--viewport-gutter, 16px));
 }
 
 /* Pop motion family tokens (--hk-pop-* in theme.scss) — the reference

package/src/components/HkPopover.sheet-maxwidth.test.ts

@@ -6,8 +6,9 @@
  * / HkSelectPanel sheets, hence "some have it, some don't").
  *
  * Root cause: the base `.hk-popover-panel` rule sets
- * `max-width: calc(100vw - 2 * 8px)` (the anchored panel's
- * anti-ratchet clamp, #421). The mobile sheet branch overrides
+ * `max-width: calc(100vw - 2 * <viewport pad>)` (the anchored panel's
+ * anti-ratchet clamp, #421; today the shared `--viewport-gutter` token).
+ * The mobile sheet branch overrides
  * `width: auto` but inherited the max-width, over-constraining the
  * inline `left: 0; right: 0` docking — the used width resolved to
  * 100vw - 16px and LTR dropped the `right` constraint. Pinned here so

package/src/components/HkPopover.surfacevars.test.ts

@@ -27,7 +27,9 @@ describe("HkPopover glass layer surface hooks", () => {
   it("pins the anchored panel width to max-content and resets the sheet", () => {
     const base = src.match(/\.hk-popover-panel\s*{[^}]*}/)![0];
     expect(base).toContain("width: max-content");
-    expect(base).toContain("max-width: calc(100vw - 2 * 8px)");
+    // The viewport caps ride the shared --viewport-gutter token (16px
+    // desktop / 8px mobile) — the same value the script-side clamp reads.
+    expect(base).toContain("max-width: calc(100vw - 2 * var(--viewport-gutter, 16px))");
     const sheet = src.match(/\.hk-popover-panel\.hk-is-sheet\s*{[^}]*}/)![0];
     expect(sheet).toContain("width: auto");
   });

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 { clampWithGutter, viewportGutterPx } from "../runtime/viewportGutter";
 import { useI18n } from "../i18n/context";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
@@ -39,8 +40,6 @@ function parsePlacement(p: PopupPlacement): { side: BaseSide; align: Align } {
   return { side, align: align ?? "center" };
 }
 
-const VIEWPORT_PAD = 8;
-
 export default defineComponent({
   name: "HkPopover",
   props: {
@@ -323,6 +322,10 @@ export default defineComponent({
       }
       const vw = window.innerWidth;
       const vh = window.innerHeight;
+      // 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.
+      const pad = viewportGutterPx();
 
       let { side } = parsePlacement(props.placement);
       const { align } = parsePlacement(props.placement);
@@ -331,25 +334,25 @@ export default defineComponent({
         if (side === "bottom") {
           const spaceBelow = vh - anchorRect.bottom;
           const spaceAbove = anchorRect.top;
-          if (spaceBelow < panelRect.height + VIEWPORT_PAD && spaceAbove > spaceBelow) {
+          if (spaceBelow < panelRect.height + pad && spaceAbove > spaceBelow) {
             side = "top";
           }
         } else if (side === "top") {
           const spaceAbove = anchorRect.top;
           const spaceBelow = vh - anchorRect.bottom;
-          if (spaceAbove < panelRect.height + VIEWPORT_PAD && spaceBelow > spaceAbove) {
+          if (spaceAbove < panelRect.height + pad && spaceBelow > spaceAbove) {
             side = "bottom";
           }
         } else if (side === "right") {
           const spaceRight = vw - anchorRect.right;
           const spaceLeft = anchorRect.left;
-          if (spaceRight < panelRect.width + VIEWPORT_PAD && spaceLeft > spaceRight) {
+          if (spaceRight < panelRect.width + pad && spaceLeft > spaceRight) {
             side = "left";
           }
         } else if (side === "left") {
           const spaceLeft = anchorRect.left;
           const spaceRight = vw - anchorRect.right;
-          if (spaceLeft < panelRect.width + VIEWPORT_PAD && spaceRight > spaceLeft) {
+          if (spaceLeft < panelRect.width + pad && spaceRight > spaceLeft) {
             side = "right";
           }
         }
@@ -374,7 +377,7 @@ export default defineComponent({
       } else {
         crossPos = anchorStart + (anchorSize - panelSize) / 2;
       }
-      crossPos = Math.max(VIEWPORT_PAD, Math.min(crossPos, viewportSize - panelSize - VIEWPORT_PAD));
+      crossPos = clampWithGutter(crossPos, panelSize, viewportSize, pad);
 
       if (side === "bottom") {
         c.top = anchorRect.bottom + off;
@@ -391,13 +394,13 @@ export default defineComponent({
       }
 
       if (side === "bottom") {
-        c.top = Math.max(VIEWPORT_PAD, Math.min(c.top!, vh - panelRect.height - VIEWPORT_PAD));
+        c.top = clampWithGutter(c.top!, panelRect.height, vh, pad);
       } else if (side === "top") {
-        c.bottom = Math.max(VIEWPORT_PAD, Math.min(c.bottom ?? 0, vh - panelRect.height - VIEWPORT_PAD));
+        c.bottom = clampWithGutter(c.bottom ?? 0, panelRect.height, vh, pad);
       } else if (side === "right") {
-        c.left = Math.max(VIEWPORT_PAD, Math.min(c.left!, vw - panelRect.width - VIEWPORT_PAD));
+        c.left = clampWithGutter(c.left!, panelRect.width, vw, pad);
       } else {
-        c.right = Math.max(VIEWPORT_PAD, Math.min(c.right ?? 0, vw - panelRect.width - VIEWPORT_PAD));
+        c.right = clampWithGutter(c.right ?? 0, panelRect.width, vw, pad);
       }
 
       coords.value = c;

package/src/components/HkSelect.scss

@@ -119,6 +119,17 @@
   position: fixed;
   min-width: 180px;
 
+  /* Width is position-independent (same contract as .hk-popover-panel):
+   * max-content sizes the popout to its rows wherever it sits, instead
+   * of shrink-to-fitting against `viewport - left` — an anchor near the
+   * right screen edge used to squeeze the panel down to the leftover
+   * space. The viewport cap (2 × the --viewport-gutter token, 16px
+   * desktop / 8px mobile) bounds it on both edges; the inline
+   * matchAnchorWidth min-width still wins over both, as documented
+   * above. */
+  width: max-content;
+  max-width: calc(100vw - 2 * var(--viewport-gutter, 16px));
+
   /* Pop motion family — the popout grows out of the anchor edge (or
    * midpoint, for the -center placements) it sits on (data-side/data-align
    * are set by HkSelectPanel from the RESOLVED placement, including after

package/src/components/HkSelectPanel.popoutwidth.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Source contract for the select popout host's position-independent width
+ * (2026-09-14 user report: the "jump to date" tooltip on a screen-edge
+ * FAB collapsed to a one-glyph column — the same shrink-to-fit class the
+ * popover fixed in #421. HkSelectPanel's desktop popout was the last
+ * anchored surface still sizing against `viewport - left`; an anchor
+ * near the right edge squeezed the panel down to the leftover space).
+ *
+ * The host must keep:
+ *   - `width: max-content` — size to the rows wherever the anchor sits;
+ *   - the viewport cap on `--viewport-gutter` (16px desktop / 8px
+ *     mobile) — the panel can never exceed the space between the
+ *     gutters, matching .hk-popover-panel;
+ *   - the `min-width: 180px` floor — which must stay BEATABLE by the
+ *     inline matchAnchorWidth style (stylesheet loses to inline on the
+ *     same element; declaration ORDER inside this block is irrelevant,
+ *     so it is deliberately not pinned here).
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkSelect.scss"), "utf-8");
+
+describe("HkSelectPanel popout viewport width contract", () => {
+  const block = scss.match(/\.hk-select-popout-host\s*{[\s\S]*?^\}/m)?.[0] ?? "";
+
+  it("declares the host block", () => {
+    expect(block).not.toBe("");
+  });
+
+  it("sizes the popout to its content (width: max-content)", () => {
+    expect(block).toContain("width: max-content;");
+  });
+
+  it("caps the popout at the viewport gutter on both edges", () => {
+    expect(block).toContain(
+      "max-width: calc(100vw - 2 * var(--viewport-gutter, 16px));",
+    );
+  });
+
+  it("keeps the 180px floor on the host (narrow anchors never collapse the panel)", () => {
+    expect(block).toContain("min-width: 180px;");
+  });
+});

package/src/components/HkSelectPanel.test.tsx

@@ -324,13 +324,14 @@ describe("HkSelectPanel custom invocation", () => {
     expect(host.dataset.side).toBe("top");
 
     // A centered panel poking past the left edge clamps to the viewport
-    // pad instead of mirroring the overflow to both sides: anchor
-    // 0..40 → raw left (20 - 180/2) = -70 → clamped to 8.
+    // gutter instead of mirroring the overflow to both sides: anchor
+    // 0..40 → raw left (20 - 180/2) = -70 → clamped to the desktop
+    // gutter (16px; happy-dom's viewport is desktop-width).
     anchor.getBoundingClientRect = () =>
       ({ top: 500, bottom: 520, left: 0, right: 40, width: 40, height: 20 }) as DOMRect;
     window.dispatchEvent(new Event("resize"));
     await nextTick();
-    expect(host.style.left).toBe("8px");
+    expect(host.style.left).toBe("16px");
   });
 
   it("reports center alignment through an auto-flip so the pop origin follows", async () => {
@@ -371,7 +372,8 @@ describe("HkSelectPanel custom invocation", () => {
 
   it("clamps a centered popout at the right viewport pad near the right edge", async () => {
     // Anchor hugging the right edge: raw balanced left 1100 + (80 - 180)/2
-    // = 1050 would poke past 1200 - 8 - 180 = 1012 → pinned at the pad.
+    // = 1050 would poke past 1200 - 16 - 180 = 1004 → pinned at the
+    // desktop gutter.
     // The expected left edge is viewport arithmetic, so pin the width here
     // (happy-dom's bare default is 1024 — the afterEach reset only helps
     // full-file runs, not -t filtering; afterEach re-asserts 1200 anyway).
@@ -386,7 +388,7 @@ describe("HkSelectPanel custom invocation", () => {
     await nextTick();
 
     const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
-    expect(host.style.left).toBe("1012px");
+    expect(host.style.left).toBe("1004px");
   });
 
   it("clamps a tall flipped popout into the viewport instead of going negative", async () => {
@@ -419,11 +421,11 @@ describe("HkSelectPanel custom invocation", () => {
       await nextTick();
 
       const top = Number.parseInt(host.style.top, 10);
-      // Whole panel on-screen: top edge at/inside the viewport pad and the
-      // bottom edge inside it too — overflow beyond that is the panel's
-      // own internal scroll, never off-screen geometry.
-      expect(top).toBeGreaterThanOrEqual(8);
-      expect(top + 576).toBeLessThanOrEqual(800 - 8);
+      // Whole panel on-screen: top edge at/inside the viewport gutter and
+      // the bottom edge inside it too — overflow beyond that is the
+      // panel's own internal scroll, never off-screen geometry.
+      expect(top).toBeGreaterThanOrEqual(16);
+      expect(top + 576).toBeLessThanOrEqual(800 - 16);
     } finally {
       window.innerHeight = prevHeight;
     }

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 { clampWithGutter, viewportGutterPx } from "../runtime/viewportGutter";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
@@ -72,8 +73,6 @@ export type SelectPanelPlacement =
   | "top-center"
   | "top-end";
 
-const VIEWPORT_PAD = 8;
-
 export default defineComponent({
   name: "HkSelectPanel",
   props: {
@@ -542,16 +541,19 @@ export default defineComponent({
       const phRaw = panelRef.value?.offsetHeight || 0;
       const pw = pwRaw > 0 ? pwRaw * z : Math.max(r.width, 180);
       const ph = phRaw > 0 ? phRaw * z : 200;
+      // The shared viewport gutter (--viewport-gutter: 8px mobile / 16px
+      // desktop), read per positioning pass.
+      const pad = viewportGutterPx();
       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 - VIEWPORT_PAD) {
+      if (side === "bottom" && top + ph > window.innerHeight - pad) {
         side = "top";
         top = r.top - props.offset - ph;
-      } else if (side === "top" && top < VIEWPORT_PAD) {
+      } else if (side === "top" && top < pad) {
         side = "bottom";
         top = r.bottom + props.offset;
       }
@@ -566,22 +568,20 @@ 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.
-      const maxTop = Math.max(VIEWPORT_PAD, window.innerHeight - VIEWPORT_PAD - ph);
-      top = Math.min(Math.max(top, VIEWPORT_PAD), maxTop);
+      top = clampWithGutter(top, ph, window.innerHeight, pad);
       // -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).
-      let left =
+      const left =
         align === "center"
           ? r.left + (r.width - pw) / 2
           : props.placement.endsWith("-end")
             ? r.right - pw
             : r.left;
-      const maxLeft = Math.max(VIEWPORT_PAD, window.innerWidth - VIEWPORT_PAD - pw);
-      left = Math.min(Math.max(left, VIEWPORT_PAD), maxLeft);
+      const clampedLeft = clampWithGutter(left, pw, window.innerWidth, pad);
       coords.value = {
         top: `${Math.round(top / z)}px`,
-        left: `${Math.round(left / z)}px`,
+        left: `${Math.round(clampedLeft / z)}px`,
         ...(props.matchAnchorWidth ? { minWidth: `${Math.round(r.width / z)}px` } : {}),
       };
     }

package/src/components/HkToast.scss

@@ -1,7 +1,9 @@
 .hk-toast-container {
   position: fixed;
   top: 4rem;
-  inset-inline-end: var(--space-16, 1rem);
+  /* Same viewport gutter the anchored popups clamp to (16px desktop /
+   * 8px mobile) — the toast stack is a floating layer too. */
+  inset-inline-end: var(--viewport-gutter, 1rem);
   /* Toast band — the topmost popup z band (POPUP_Z_BANDS.toast; mirror in
      theme.scss). The live value arrives inline from the popup manager. */
   z-index: var(--hk-z-toast, 4000);

package/src/components/HkTooltip.scss

@@ -16,6 +16,14 @@
   padding: var(--space-4) var(--space-8);
   border: none;
   border-radius: var(--radius-sm);
+  /* Width is position-independent (same contract as .hk-popover-panel):
+   * max-content sizes the bubble to its text wherever it sits — a fixed
+   * element otherwise shrink-to-fits against `viewport - left` and a
+   * trigger near the screen edge squeezes it into a one-glyph column.
+   * The inline style from runtime/tooltipPosition carries the same
+   * declaration; this sheet rule keeps the bridge/standalone faces
+   * covered even where the inline pass does not run. */
+  width: max-content;
   /* Default cap lives on the popup so the inline maxWidth prop
      legitimately overrides it (the content div would shadow the prop). */
   max-width: 280px;

package/src/components/HkTooltip.test.tsx

@@ -223,4 +223,16 @@ describe("HkTooltip anchoring", () => {
     await settle();
     expect(popup().style.maxWidth).toBe("220px");
   });
+
+  it("sizes the popup to its content (max-content) for the gutter clamp", async () => {
+    // The compression fix: the popup box must be position-independent
+    // (width: max-content) so a screen-edge trigger cannot shrink it to
+    // the containing block's leftover space; applyTooltipPosition then
+    // clamps the measured box into the viewport gutter (no-op here —
+    // happy-dom reports a zero rect).
+    const { container } = mount({ text: "sized", delay: 0 });
+    enter(container);
+    await settle();
+    expect(popup().style.width).toBe("max-content");
+  });
 });

package/src/components/HkTooltip.tsx

@@ -1,6 +1,6 @@
 import { computed, defineComponent, onBeforeUnmount, onMounted, ref, Teleport, type CSSProperties, type PropType } from "vue";
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
-import { tooltipPositionStyle, type TooltipPlacement } from "../runtime/tooltipPosition";
+import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
 import "./HkTooltip.scss";
 
 export default defineComponent({
@@ -14,7 +14,7 @@ export default defineComponent({
   setup(props, { slots }) {
     const visible = ref(false);
     const wrapperRef = ref<HTMLElement | null>(null);
-    const tooltipStyle = ref<CSSProperties>({});
+    const popupRef = ref<HTMLElement | null>(null);
     let showTimer: ReturnType<typeof setTimeout> | null = null;
 
     // Registers with the popup manager (kind "tooltip") so tooltips hold
@@ -31,13 +31,16 @@ export default defineComponent({
     });
 
     function updatePosition() {
-      if (!wrapperRef.value) return;
+      if (!wrapperRef.value || !popupRef.value) return;
       const rect = wrapperRef.value.getBoundingClientRect();
       // Placement geometry lives in the shared runtime helper (it also
       // serves the document-level tooltip bridge) — including the
       // ancestor-zoom division that keeps teleported popups pinned to
-      // their trigger inside scaled roots.
-      tooltipStyle.value = tooltipPositionStyle(rect, props.placement, props.maxWidth);
+      // their trigger inside scaled roots, and the measure-and-clamp pass
+      // that keeps the measured bubble inside the viewport gutter (flip,
+      // cap, shift) instead of spilling off-screen or shrinking to the
+      // containing block's leftover space.
+      applyTooltipPosition(popupRef.value, rect, props.placement, props.maxWidth);
     }
 
     function show() {
@@ -74,10 +77,12 @@ export default defineComponent({
       visible.value ? "hk-tooltip-visible" : "",
     ]);
 
-    const popupStyle = computed<CSSProperties>(() => ({
-      ...tooltipStyle.value,
-      ...(zIndex.value != null ? { zIndex: zIndex.value } : {}),
-    }));
+    // Only the popup-manager z rides the vnode; the geometry is written
+    // straight onto the element by applyTooltipPosition (same as the
+    // tooltip bridge) so a re-render can never clobber a clamp shift.
+    const popupStyle = computed<CSSProperties>(() =>
+      zIndex.value != null ? { zIndex: zIndex.value } : {},
+    );
 
     return () => (
       <span
@@ -94,6 +99,7 @@ export default defineComponent({
         </span>
         <Teleport to="body">
           <div
+            ref={popupRef}
             class={tooltipCls.value}
             style={popupStyle.value}
           >

package/src/runtime/index.ts

@@ -13,9 +13,19 @@ export {
 } from "./imageFallback";
 export {
   tooltipPositionStyle,
+  applyTooltipPosition,
+  resolveTooltipFlip,
   TOOLTIP_GAP_PX,
   type TooltipPlacement,
 } from "./tooltipPosition";
+export {
+  viewportGutterPx,
+  clampWithGutter,
+  VIEWPORT_GUTTER_VAR,
+  MOBILE_GUTTER_PX,
+  DESKTOP_GUTTER_PX,
+  GUTTER_MOBILE_MAX_WIDTH,
+} from "./viewportGutter";
 export {
   sanitizeHistoryUrl,
   installHistorySafetyNet,

package/src/runtime/tooltipBridge.ts

@@ -9,8 +9,8 @@
 //     → the element's title is moved aside into `data-hk-title` and the
 //       attribute is REMOVED — the native tooltip can no longer appear
 //     → after the delay the shared `.hk-tooltip-popup` element is filled,
-//       positioned (tooltipPositionStyle: same placement/zoom math as
-//       HkTooltip) and faded in
+//       positioned (applyTooltipPosition: same placement/zoom math as
+//       HkTooltip, plus the viewport-gutter clamp) and faded in
 //   disengage (pointerout / focusout / scroll / resize / Esc); pointerdown
 //     only hides the popup — the hold stays so no native tooltip flashes
 //     → the popup fades out and the title attribute is RESTORED, so
@@ -28,7 +28,7 @@
 // popups share the tooltip z band with component tooltips. Installing
 // twice on the same document is idempotent: the second install returns
 // the first install's uninstall.
-import { tooltipPositionStyle, type TooltipPlacement } from "./tooltipPosition";
+import { applyTooltipPosition, type TooltipPlacement } from "./tooltipPosition";
 import { usePopupManager, type PopupHandle } from "./usePopupManager";
 import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
 // The popup reuses HkTooltip's popup classes — carry the sheet so a host
@@ -127,12 +127,16 @@ function showPopup(state: BridgeState, el: Element) {
   if (!text || !state.popup.isConnected) return;
   state.content.textContent = text;
   // Same geometry as component tooltips: the fixed popup pins to the
-  // trigger rect with the shared placement switch (ancestor zoom aware).
-  Object.assign(state.popup.style, tooltipPositionStyle(
+  // trigger rect with the shared placement switch (ancestor zoom aware),
+  // then the measured box is clamped into the viewport gutter — a title
+  // trigger hugging the screen edge shows a full-width bubble shifted
+  // inside the gutter, never the squeezed leftover-space column.
+  applyTooltipPosition(
+    state.popup,
     el.getBoundingClientRect(),
     state.placement,
     state.maxWidth,
-  ));
+  );
   state.popup.classList.add("hk-tooltip-visible");
   el.setAttribute("aria-describedby", state.describedBy);
   state.shown += 1;

package/src/runtime/tooltipPosition.test.ts

@@ -1,6 +1,11 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { TOOLTIP_GAP_PX, tooltipPositionStyle } from "./tooltipPosition";
+import {
+  TOOLTIP_GAP_PX,
+  applyTooltipPosition,
+  resolveTooltipFlip,
+  tooltipPositionStyle,
+} from "./tooltipPosition";
 
 /** A 100x40 rect at (200,100) — big enough for every placement side. */
 function rect(): DOMRect {
@@ -11,6 +16,34 @@ function rect(): DOMRect {
   } as DOMRect;
 }
 
+function box(left: number, top: number, width: number, height: number): DOMRect {
+  return {
+    left, top, width, height,
+    right: left + width, bottom: top + height,
+    x: left, y: top,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+/** A probe element whose gBCR answers with a queued rect sequence. */
+function probePopup(rects: DOMRect[]): HTMLElement {
+  const el = document.createElement("div");
+  el.dataset.tooltipProbe = "true";
+  document.body.appendChild(el);
+  let i = 0;
+  el.getBoundingClientRect = () => rects[Math.min(i++, rects.length - 1)]!;
+  return el;
+}
+
+const PREV_INNER = { width: window.innerWidth, height: window.innerHeight };
+
+afterEach(() => {
+  window.innerWidth = PREV_INNER.width;
+  window.innerHeight = PREV_INNER.height;
+  vi.restoreAllMocks();
+  document.querySelectorAll(".hk-tooltip-popup, [data-tooltip-probe]").forEach((el) => el.remove());
+});
+
 describe("tooltipPositionStyle", () => {
   it("pins the popup 8px outside the rect with per-placement transforms", () => {
     expect(TOOLTIP_GAP_PX).toBe(8);
@@ -38,4 +71,182 @@ describe("tooltipPositionStyle", () => {
     expect(style.maxWidth).toBe("180px");
     expect(tooltipPositionStyle(rect(), "top").maxWidth).toBeUndefined();
   });
+
+  it("sizes the popup to its content so the containing block cannot compress it", () => {
+    // THE compression fix: a fixed element shrink-to-fits against
+    // `viewport - left`, so a trigger near the right edge used to squeeze
+    // the bubble into a one-glyph column. max-content is position-
+    // independent (same contract as .hk-popover-panel).
+    expect(tooltipPositionStyle(rect(), "top").width).toBe("max-content");
+    expect(tooltipPositionStyle(rect(), "right", "120px").width).toBe("max-content");
+  });
+});
+
+describe("applyTooltipPosition without layout", () => {
+  it("degrades to the pure placement style when the box measures zero", () => {
+    const popup = probePopup([box(0, 0, 0, 0)]);
+    applyTooltipPosition(popup, rect(), "top");
+    expect(popup.style.top).toBe("92px");
+    expect(popup.style.left).toBe("250px");
+    expect(popup.style.transform).toBe("translate(-50%, -100%)");
+    expect(popup.style.width).toBe("max-content");
+    // No clamp pass ran: no caps, no gutter writes.
+    expect(popup.style.maxWidth).toBe("");
+    expect(popup.style.maxHeight).toBe("");
+  });
+
+  it("still honors the maxWidth prop on the zero-layout path", () => {
+    const popup = probePopup([box(0, 0, 0, 0)]);
+    applyTooltipPosition(popup, rect(), "top", "220px");
+    expect(popup.style.maxWidth).toBe("220px");
+  });
+});
+
+describe("applyTooltipPosition viewport clamping", () => {
+  it("shifts a centered bubble back inside the right-edge gutter", () => {
+    // Mobile viewport (375px → 8px gutter). Trigger at 300..340, the
+    // centered 120px bubble would span 260..380 — 13px past the gutter.
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    const trigger = box(300, 300, 40, 40);
+    const popup = probePopup([box(260, 348, 120, 32)]);
+    applyTooltipPosition(popup, trigger, "bottom");
+    // The shift lands on the WRITTEN anchor (style.left is the box
+    // center under translate(-50%)): 320 - 13 = 307, visual box 247..367.
+    expect(popup.style.left).toBe("307px");
+    expect(popup.style.top).toBe("348px");
+    expect(popup.style.maxWidth).toBe("");
+  });
+
+  it("flips to the opposite side when the preferred one is starved", () => {
+    // Trigger hugging the top edge: a top popup cannot clear the gutter,
+    // bottom has room → the popup flips below the trigger.
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    const trigger = box(100, 2, 40, 18);
+    const popup = probePopup([box(120, -22, 200, 32), box(120, 28, 200, 32)]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.transform).toBe("translate(-50%, 0)");
+    expect(popup.style.top).toBe("28px"); // rect.bottom + 8
+    expect(popup.style.left).toBe("120px"); // hcenter, unshifted
+  });
+
+  it("caps a bubble that cannot fit between the gutters, then shifts", () => {
+    // A 400px bubble on a 375px viewport: max-width caps it to
+    // 375 - 2*8 = 359px and the centered remainder shifts inside.
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    const trigger = box(100, 300, 40, 40);
+    const popup = probePopup([box(-80, 232, 400, 60), box(-80, 232, 359, 60)]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.maxWidth).toBe("359px");
+    // Base anchor 120 - shift dx 88 (visual -80 → gutter 8) = 208.
+    expect(popup.style.left).toBe("208px");
+  });
+
+  it("clips a viewport-tall tooltip instead of spilling past the edge", () => {
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    // Preferred side keeps the flip away (top space 392 > bottom 219) so
+    // the case isolates the height cap + clip.
+    const trigger = box(160, 400, 40, 40);
+    const popup = probePopup([box(100, 20, 160, 700), box(100, 20, 160, 651)]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.maxHeight).toBe("651px"); // 667 - 2*8
+    expect(popup.style.overflow).toBe("hidden");
+  });
+
+  it("writes the shift divided by the cumulative root zoom", () => {
+    // chest's root-level DPI zoom: style px are local (divided by the
+    // zoom) while the measured box and the viewport are visual.
+    window.innerWidth = 1200;
+    window.innerHeight = 800;
+    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);
+    const trigger = box(1180, 100, 20, 40);
+    // Base right placement at zoom 2: left = (1200+8)/2 = 604 local, the
+    // 300px bubble spans visual 1208..1508 — past the gutter AND the
+    // starved right side, so it flips left and shifts the remainder.
+    const popup = probePopup([box(1208, 100, 300, 40), box(886, 100, 300, 40)]);
+    applyTooltipPosition(popup, trigger, "right");
+    expect(popup.style.transform).toBe("translate(-100%, -50%)");
+    // Flip rewrite: (1180 - 8)/2 = 586 local; visual box 886..1186, 2px
+    // past the 1184 gutter line → dx -2 visual = -1 local: 586 - 1 = 585.
+    expect(popup.style.left).toBe("585px");
+  });
+
+  it("keeps the width cap through a flip (cap + flip combined)", () => {
+    // R1 verification defect: applyBase on the flipped side used to reset
+    // maxWidth, so the uncapped box was measured and pinned — one edge at
+    // the gutter, the opposite 33px PAST the viewport. The cap belongs to
+    // the box, not the side: it must survive the flip.
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    const trigger = box(300, 300, 40, 40); // right edge at 340
+    const popup = probePopup([
+      box(348, 304, 400, 32), // base "right": 400px wide → cap 359px
+      box(348, 304, 359, 32), // capped re-measure → right side starved
+      box(-67, 304, 359, 32), // flipped "left": uncapped-width visual box
+    ]);
+    applyTooltipPosition(popup, trigger, "right");
+    expect(popup.style.maxWidth).toBe("359px"); // must survive the flip
+    expect(popup.style.transform).toBe("translate(-100%, -50%)");
+    // Shift pins 292 + 75 = 367 → visual box 8..367, exactly inside the
+    // gutters on BOTH edges (375 - 8 = 367).
+    expect(popup.style.left).toBe("367px");
+  });
+
+  it("keeps the height cap and clip through a flip (cap + flip combined)", () => {
+    // The near-top-edge tall tooltip: guaranteed flip (the top side
+    // cannot hold it) — the height cap must not be reset by the flip
+    // rewrite, or the pinned box spills 41px past the bottom edge.
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    const trigger = box(160, 4, 40, 18);
+    const popup = probePopup([
+      box(100, -704, 160, 700), // base "top": 700px tall → cap 651px
+      box(100, -704, 160, 651), // capped re-measure → top starved
+      box(100, 30, 160, 651), // flipped "bottom" visual box
+    ]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.maxHeight).toBe("651px");
+    expect(popup.style.overflow).toBe("hidden");
+    expect(popup.style.transform).toBe("translate(-50%, 0)");
+    // 30 - 22 = 8 → visual box 8..659, inside the bottom gutter (667-8).
+    expect(popup.style.top).toBe("8px");
+  });
+});
+
+describe("resolveTooltipFlip", () => {
+  const vw = 375;
+  const vh = 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");
+  });
+
+  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");
+    const floorTrigger = box(100, 640, 40, 20);
+    expect(resolveTooltipFlip(floorTrigger, "bottom", { width: 200, height: 32 }, vw, vh, 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");
+  });
 });

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 { clampWithGutter, viewportGutterPx } from "./viewportGutter";
 
 export type TooltipPlacement = "top" | "bottom" | "left" | "right";
 
@@ -20,6 +21,14 @@ export const TOOLTIP_GAP_PX = 8;
  * px back up at paint, so the visual rect values must be written divided
  * by the cumulative zoom or the tooltip drifts zoom× off its trigger
  * (chest's root-level manual DPI scale).
+ *
+ * `width: max-content` is the position-independence contract (same rule
+ * as .hk-popover-panel): a fixed element otherwise shrink-to-fits against
+ * `viewport - left`, so a trigger near the viewport edge squeezes the
+ * bubble down to the leftover space — the vertical one-glyph-per-line
+ * column on mobile (the jump-to-date tooltip report). max-content sizes
+ * the box to its text wherever it sits; applyTooltipPosition then clamps
+ * it back into the viewport.
  */
 export function tooltipPositionStyle(
   rect: DOMRect,
@@ -30,6 +39,7 @@ export function tooltipPositionStyle(
   const local = (v: number) => `${v / z}px`;
   const style: CSSProperties = {};
 
+  style.width = "max-content";
   if (maxWidth) {
     style.maxWidth = maxWidth;
   }
@@ -59,3 +69,152 @@ export function tooltipPositionStyle(
 
   return style;
 }
+
+/** Space left on each side of the trigger rect, minus the trigger gap. */
+function sideSpace(
+  rect: DOMRect,
+  side: TooltipPlacement,
+  vw: number,
+  vh: number,
+): number {
+  switch (side) {
+    case "top":
+      return rect.top - TOOLTIP_GAP_PX;
+    case "bottom":
+      return vh - rect.bottom - TOOLTIP_GAP_PX;
+    case "left":
+      return rect.left - TOOLTIP_GAP_PX;
+    case "right":
+      return vw - rect.right - TOOLTIP_GAP_PX;
+  }
+}
+
+/** The side opposite `placement` (the only flip tooltips ever need). */
+function oppositeSide(placement: TooltipPlacement): TooltipPlacement {
+  switch (placement) {
+    case "top":
+      return "bottom";
+    case "bottom":
+      return "top";
+    case "left":
+      return "right";
+    case "right":
+      return "left";
+  }
+}
+
+/**
+ * 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.
+ */
+export function resolveTooltipFlip(
+  rect: DOMRect,
+  placement: TooltipPlacement,
+  popup: { width: number; height: number },
+  vw: number,
+  vh: number,
+  gutter: number,
+): TooltipPlacement {
+  const preferred = sideSpace(rect, placement, vw, vh);
+  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);
+  return alternateSpace > preferred ? alternate : placement;
+}
+
+/**
+ * Position a live popup element against a trigger rect: apply the shared
+ * placement style, then measure the REAL box and pull it inside the
+ * viewport gutter — capping an oversized bubble, flipping the side when
+ * the preferred one is starved, and shifting the remainder so no edge
+ * ever crosses the gutter (the mobile/desktop --viewport-gutter token).
+ *
+ * Without layout (happy-dom/jsdom, hidden popups) measurement reports a
+ * zero rect and the call degrades to exactly the pure
+ * tooltipPositionStyle output — the clamps are additive, never
+ * load-bearing for the base anchor math.
+ */
+export function applyTooltipPosition(
+  popup: HTMLElement,
+  rect: DOMRect,
+  placement: TooltipPlacement,
+  maxWidth?: string,
+): void {
+  // Fresh base every call: a previous show's caps (maxWidth/maxHeight)
+  // must not leak into this one's box.
+  const applyBase = (side: TooltipPlacement) => {
+    popup.style.maxWidth = maxWidth ?? "";
+    popup.style.maxHeight = "";
+    popup.style.overflow = "";
+    Object.assign(popup.style, tooltipPositionStyle(rect, side, maxWidth));
+  };
+  applyBase(placement);
+
+  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;
+  const gutter = viewportGutterPx();
+  const z = ancestorZoom(popup);
+
+  // Cap a bubble that cannot fit between the gutters: max-width reflows
+  // the text (break-word wraps it), max-height clips the pathological
+  // viewport-tall title (tooltips are pointer-events: none — scrolling
+  // one is unreachable, so clipping beats spilling past the edge). The
+  // caps live in their own writer because the FLIP below rewrites the
+  // base style — without re-applying them, the flipped side would
+  // measure and pin the UNCAPPED box and spill past the opposite edge.
+  let capW = "";
+  let capH = "";
+  let clip = false;
+  const maxW = vw - 2 * gutter;
+  const maxH = vh - 2 * gutter;
+  if (box.width > maxW) {
+    capW = `${maxW / z}px`;
+  }
+  if (box.height > maxH) {
+    capH = `${maxH / z}px`;
+    clip = true;
+  }
+  const applyCaps = () => {
+    if (capW) popup.style.maxWidth = capW;
+    if (capH) {
+      popup.style.maxHeight = capH;
+      popup.style.overflow = "hidden";
+    }
+  };
+
+  let measured = box;
+  if (capW || capH) {
+    applyCaps();
+    measured = popup.getBoundingClientRect();
+  }
+
+  const side = resolveTooltipFlip(rect, placement, measured, vw, vh, gutter);
+  let final = measured;
+  if (side !== placement) {
+    applyBase(side);
+    applyCaps(); // caps survive the flip — they belong to the box, not the side
+    final = popup.getBoundingClientRect();
+  }
+
+  // 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;
+  if (dx !== 0 || dy !== 0) {
+    const curLeft = Number.parseFloat(popup.style.left) || 0;
+    const curTop = Number.parseFloat(popup.style.top) || 0;
+    popup.style.left = `${curLeft + dx / z}px`;
+    popup.style.top = `${curTop + dy / z}px`;
+  }
+}

package/src/runtime/viewportGutter.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  DESKTOP_GUTTER_PX,
+  MOBILE_GUTTER_PX,
+  VIEWPORT_GUTTER_VAR,
+  clampWithGutter,
+  viewportGutterPx,
+} from "./viewportGutter";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scaleSrc = readFileSync(join(here, "../scale.scss"), "utf-8");
+const vendoredSrc = readFileSync(join(here, "../styles/theme/scale.scss"), "utf-8");
+
+const PREV_INNER_WIDTH = window.innerWidth;
+
+afterEach(() => {
+  window.innerWidth = PREV_INNER_WIDTH;
+  vi.restoreAllMocks();
+});
+
+/** Force the :root computed style to answer `value` for the gutter var. */
+function stubRootVar(value: string) {
+  const original = window.getComputedStyle.bind(window);
+  vi.spyOn(window, "getComputedStyle").mockImplementation(((el: Element) => {
+    if (el === document.documentElement) {
+      return {
+        getPropertyValue: (name: string) => (name === VIEWPORT_GUTTER_VAR ? value : ""),
+      } as unknown as CSSStyleDeclaration;
+    }
+    return original(el);
+  }) as typeof window.getComputedStyle);
+}
+
+describe("viewportGutterPx", () => {
+  it("reads a positive px token off :root verbatim", () => {
+    stubRootVar("20px");
+    expect(viewportGutterPx()).toBe(20);
+  });
+
+  it("ignores non-px, garbage and non-positive token values", () => {
+    // A var() can reach the reader unresolved ("1rem" parseFloats to 1)
+    // and a garbage value must never SHRINK the gutter — all fall back.
+    for (const bad of ["", "  ", "bogus", "1rem", "0px", "-4px", "16"]) {
+      stubRootVar(bad);
+      expect(viewportGutterPx(), `token ${JSON.stringify(bad)}`).toBe(
+        PREV_INNER_WIDTH < 768 ? MOBILE_GUTTER_PX : DESKTOP_GUTTER_PX,
+      );
+    }
+  });
+
+  it("falls back by breakpoint without a token: 8px mobile / 16px desktop", () => {
+    window.innerWidth = 375;
+    expect(viewportGutterPx()).toBe(MOBILE_GUTTER_PX);
+    window.innerWidth = 767;
+    expect(viewportGutterPx()).toBe(MOBILE_GUTTER_PX);
+    window.innerWidth = 768;
+    expect(viewportGutterPx()).toBe(DESKTOP_GUTTER_PX);
+    window.innerWidth = 1280;
+    expect(viewportGutterPx()).toBe(DESKTOP_GUTTER_PX);
+  });
+
+  it("keeps the token and the breakpoint fallback numerically in sync", () => {
+    // The media query in scale.scss writes the same numbers this module
+    // falls back to — the contract that lets CSS caps and JS clamps
+    // never drift.
+    expect(scaleSrc).toContain(`${VIEWPORT_GUTTER_VAR}: ${DESKTOP_GUTTER_PX}px;`);
+    const media = scaleSrc.match(
+      new RegExp(`@media \\(max-width: 767px\\)\\s*{\\s*:root\\s*{[^}]*${VIEWPORT_GUTTER_VAR}: ${MOBILE_GUTTER_PX}px;`),
+    );
+    expect(media, "mobile media override in scale.scss").not.toBeNull();
+  });
+
+  it("ships the token in the vendored scale sheet too", () => {
+    // vendoredSync.test.ts enforces byte-level sync; this pins the
+    // semantic (a host loading only the composed sheets still gets the
+    // token the JS reader looks for).
+    expect(vendoredSrc).toContain(`${VIEWPORT_GUTTER_VAR}: ${DESKTOP_GUTTER_PX}px;`);
+  });
+});
+
+describe("clampWithGutter", () => {
+  it("keeps a fitting box untouched", () => {
+    expect(clampWithGutter(100, 200, 1200, 16)).toBe(100);
+  });
+
+  it("pins an overflowing box to the far gutter", () => {
+    expect(clampWithGutter(1100, 200, 1200, 16)).toBe(984);
+    expect(clampWithGutter(-70, 180, 1200, 16)).toBe(16);
+  });
+
+  it("collapses to the gutter when the box cannot fit at all", () => {
+    expect(clampWithGutter(50, 5000, 1200, 16)).toBe(16);
+  });
+});

package/src/runtime/viewportGutter.ts

@@ -0,0 +1,73 @@
+// Shared viewport-edge gutter — the one number every floating layer keeps
+// between itself and the viewport edge.
+//
+// HkPopover / HkSelectPanel / HkMenu each used to carry a private
+// `VIEWPORT_PAD = 8` with no desktop variant, and HkTooltip carried no
+// clamp at all (a tooltip anchored near the right edge was squeezed to
+// the leftover shrink-to-fit space — one or two glyphs per line). This
+// module replaces all of them: the magnitude lives in the
+// `--viewport-gutter` L2 token (scale.scss, 16px desktop / 8px mobile via
+// the <768px media query), and the JS side reads that SAME token so the
+// CSS caps (`calc(100vw - 2 * var(--viewport-gutter))`) and the clamp
+// math can never drift apart. Hosts that never load the scale sheet fall
+// back to the same numbers derived from innerWidth.
+//
+// Deliberately NOT zoom-corrected: the consumers (HkPopover's visual-px
+// clamp, tooltipPosition's visual-space shift) all work in root visual
+// coordinates and pass the value straight through, matching the 8px
+// behavior this replaces. A one-zoom-step error in an 8–16px gutter is
+// invisible; a missing clamp was not.
+
+/** The L2 token carrying the gutter (declared in scale.scss). */
+export const VIEWPORT_GUTTER_VAR = "--viewport-gutter";
+
+/** Fallback gutter on mobile-width viewports (innerWidth < 768). */
+export const MOBILE_GUTTER_PX = 8;
+
+/** Fallback gutter on desktop-width viewports, and the SSR answer. */
+export const DESKTOP_GUTTER_PX = 16;
+
+/** The breakpoint the CSS media query in scale.scss mirrors. */
+export const GUTTER_MOBILE_MAX_WIDTH = 768;
+
+/**
+ * The viewport gutter in CSS px. Reads `--viewport-gutter` off
+ * `:root` when it resolves to a positive px length (the shipped scale
+ * sheet always declares it), else falls back to 8px below the 768px
+ * breakpoint and 16px at or above it — the exact numbers the media
+ * query writes.
+ */
+export function viewportGutterPx(win?: Window | null): number {
+  if (typeof window === "undefined") return DESKTOP_GUTTER_PX;
+  const w = win ?? window;
+  try {
+    const raw = w
+      .getComputedStyle(w.document.documentElement)
+      .getPropertyValue(VIEWPORT_GUTTER_VAR)
+      .trim();
+    // px-only by contract: a var() can reach us unresolved ("1rem" would
+    // parseFloat to 1) and a garbage value must never shrink the gutter.
+    if (raw.endsWith("px")) {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed > 0) return parsed;
+    }
+  } catch {
+    /* no DOM — fall through to the breakpoint fallback */
+  }
+  return w.innerWidth < GUTTER_MOBILE_MAX_WIDTH ? MOBILE_GUTTER_PX : DESKTOP_GUTTER_PX;
+}
+
+/**
+ * Clamp a cross/main-axis coordinate so a box of `size` px stays inside
+ * `[gutter, viewportSize - gutter]`. This is the clamp shape every
+ * anchored surface shared (HkPopover's cross + main axis, HkSelectPanel's
+ * top/left): below the gutter when it fits, else pinned to the gutter.
+ */
+export function clampWithGutter(
+  value: number,
+  size: number,
+  viewportSize: number,
+  gutter: number,
+): number {
+  return Math.max(gutter, Math.min(value, viewportSize - size - gutter));
+}

package/src/scale.scss

@@ -69,8 +69,25 @@
   --z-header: 100;
   --z-sidebar: 900;
 
+  /* Viewport gutter — the minimum distance every floating layer (tooltip,
+   * popover, menu, select popout, modal frame, toasts) keeps from the
+   * viewport edge. Anchored popups clamp their position to it; intentional
+   * full-bleed surfaces (drawers, bottom sheets) are exempt. 16px on
+   * desktop-width viewports, 8px on mobile (runtime/viewportGutter.ts
+   * reads the same token so the JS clamps and the CSS caps never drift). */
+  --viewport-gutter: 16px;
+
   /* Fonts — keep in sync with packages/vue/src/theme/fontContext.ts */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
   --font-reading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", "PingFang SC", "Microsoft YaHei", monospace;
 }
+
+/* Mobile viewports halve the floating-layer gutter. The breakpoint mirrors
+ * runtime/useBreakpoint (isMobile = width < 768) so the CSS override and
+ * the JS fallback switch on the same line. */
+@media (max-width: 767px) {
+  :root {
+    --viewport-gutter: 8px;
+  }
+}

package/src/styles/theme/scale.scss

@@ -71,8 +71,25 @@
   --z-header: 100;
   --z-sidebar: 900;
 
+  /* Viewport gutter — the minimum distance every floating layer (tooltip,
+   * popover, menu, select popout, modal frame, toasts) keeps from the
+   * viewport edge. Anchored popups clamp their position to it; intentional
+   * full-bleed surfaces (drawers, bottom sheets) are exempt. 16px on
+   * desktop-width viewports, 8px on mobile (runtime/viewportGutter.ts
+   * reads the same token so the JS clamps and the CSS caps never drift). */
+  --viewport-gutter: 16px;
+
   /* Fonts — keep in sync with packages/vue/src/theme/fontContext.ts */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
   --font-reading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", "PingFang SC", "Microsoft YaHei", monospace;
 }
+
+/* Mobile viewports halve the floating-layer gutter. The breakpoint mirrors
+ * runtime/useBreakpoint (isMobile = width < 768) so the CSS override and
+ * the JS fallback switch on the same line. */
+@media (max-width: 767px) {
+  :root {
+    --viewport-gutter: 8px;
+  }
+}