@celestia-island/hikari 0.47.0 → 0.48.0

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");
+  });
 });