@celestia-island/hikari 0.45.8 → 0.46.0

package/src/runtime/imageFallback.ts

@@ -0,0 +1,125 @@
+// installHkImageFallback — document-level "invalid image" rendering.
+//
+// A broken <img> (404, dead data URI, offline blob) otherwise renders the
+// browser's raw broken-image glyph, which is exactly the kind of
+// unpolished detail the design system exists to prevent (user direction
+// 2026-09-13: ship the invalid-image re-render as a global hook, the same
+// way the tooltip bridge replaces native tooltips). Mechanics:
+//
+//   error (capture-phase delegated — resource errors do NOT bubble)
+//     → the img gains the `hk-img-broken` class (muted surface treatment
+//       in imageFallback.scss)
+//     → its src swaps to the bundled inline-SVG placeholder (a quiet
+//       broken-image glyph on a rounded muted tile), keeping the element,
+//       its layout box and its alt text intact — no DOM surgery, no
+//       layout shift
+//   load (capture-phase delegated)
+//     → a previously-broken img whose src later resolves (retry, upload
+//       finished, URL repaired) drops the class and renders normally.
+//
+// The swap is one-shot per element (`data-hk-img-fallback`): a fallback
+// that itself fails (hostile custom fallbackSrc) can never loop.
+//
+// Escape hatches:
+//   - `[data-hk-img-native]` keeps the raw browser broken-image rendering
+//   - `selector` / `exclude` options scope the hook further
+//   - `fallbackSrc` overrides the bundled placeholder ("" = class only,
+//     no src swap — for hosts that style the class themselves)
+import "./imageFallback.scss";
+
+export interface HkImageFallbackOptions {
+  /** Which images are covered. Default: `img`. */
+  selector?: string;
+  /** Images matching this keep raw browser rendering. */
+  exclude?: string;
+  /** Placeholder src override. `""` marks the img but keeps its src. */
+  fallbackSrc?: string;
+}
+
+/** The bundled placeholder: quiet broken-image glyph on a muted tile. */
+const PLACEHOLDER_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" role="img" aria-hidden="true">
+  <rect width="48" height="48" rx="8" fill="#888f9b" fill-opacity="0.14"/>
+  <g fill="none" stroke="#888f9b" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" opacity="0.85">
+    <rect x="12" y="10" width="24" height="28" rx="3"/>
+    <circle cx="20" cy="18" r="2.5"/>
+    <path d="M15 33l7-8 5 6 3.5-3.5L36 33"/>
+    <path d="M9 39L39 9"/>
+  </g>
+</svg>`;
+
+const DEFAULT_FALLBACK_SRC = `data:image/svg+xml,${encodeURIComponent(PLACEHOLDER_SVG)}`;
+
+const APPLIED_FLAG = "hkImgFallback" as const;
+
+interface FallbackState {
+  root: Document;
+  listeners: Array<[type: string, fn: EventListener]>;
+  selector: string;
+  exclude: string;
+  fallbackSrc: string;
+}
+
+const INSTALLS = new WeakMap<Document, FallbackState>();
+
+function onError(state: FallbackState, e: Event) {
+  const target = e.target;
+  if (!target || !(target instanceof HTMLImageElement)) return;
+  if (!target.matches(state.selector)) return;
+  if (state.exclude && target.matches(state.exclude)) return;
+  if (target.dataset[APPLIED_FLAG] === "1") return; // already marked — never loop
+  target.dataset[APPLIED_FLAG] = "1";
+  target.classList.add("hk-img-broken");
+  if (state.fallbackSrc && target.getAttribute("src") !== state.fallbackSrc) {
+    target.src = state.fallbackSrc;
+  }
+}
+
+function onLoad(state: FallbackState, e: Event) {
+  const target = e.target;
+  if (!target || !(target instanceof HTMLImageElement)) return;
+  if (!target.classList.contains("hk-img-broken")) return;
+  // The swapped placeholder fires its own load — the class comes off only
+  // for an image that RESOLVED with real content again (src repaired,
+  // retry succeeded). A load OF the placeholder keeps the treatment.
+  if (state.fallbackSrc && target.getAttribute("src") === state.fallbackSrc) return;
+  target.classList.remove("hk-img-broken");
+  delete target.dataset[APPLIED_FLAG]; // a later breakage can re-mark it
+}
+
+function uninstall(state: FallbackState) {
+  if (INSTALLS.get(state.root) === state) INSTALLS.delete(state.root);
+  for (const [type, fn] of state.listeners.splice(0)) {
+    state.root.removeEventListener(type, fn, true);
+  }
+}
+
+/**
+ * Install the document-level broken-image re-render. Returns the
+ * uninstaller (removes listeners; already-marked images keep their
+ * placeholder). Idempotent per document.
+ */
+export function installHkImageFallback(options: HkImageFallbackOptions = {}): () => void {
+  if (typeof document === "undefined") return () => undefined;
+  const existing = INSTALLS.get(document);
+  if (existing) return () => uninstall(existing);
+
+  const state: FallbackState = {
+    root: document,
+    listeners: [],
+    selector: options.selector ?? "img",
+    exclude: options.exclude ?? "[data-hk-img-native]",
+    fallbackSrc: options.fallbackSrc !== undefined ? options.fallbackSrc : DEFAULT_FALLBACK_SRC,
+  };
+
+  // Resource errors never bubble — capture phase is the only delegation
+  // point that sees them from the document.
+  const on = (type: string, fn: EventListener) => {
+    document.addEventListener(type, fn, true);
+    state.listeners.push([type, fn]);
+  };
+  on("error", (e) => onError(state, e));
+  on("load", (e) => onLoad(state, e));
+
+  INSTALLS.set(document, state);
+  return () => uninstall(state);
+}

package/src/runtime/index.ts

@@ -3,6 +3,19 @@ export * from "./cronBus";
 export * from "./intervalBus";
 export * from "./pageLifecycle";
 export * from "./mobileViewport";
+export {
+  installHkTooltipBridge,
+  type HkTooltipBridgeOptions,
+} from "./tooltipBridge";
+export {
+  installHkImageFallback,
+  type HkImageFallbackOptions,
+} from "./imageFallback";
+export {
+  tooltipPositionStyle,
+  TOOLTIP_GAP_PX,
+  type TooltipPlacement,
+} from "./tooltipPosition";
 export {
   sanitizeHistoryUrl,
   installHistorySafetyNet,

package/src/runtime/tooltipBridge.test.ts

@@ -0,0 +1,213 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { installHkTooltipBridge, type HkTooltipBridgeOptions } from "./tooltipBridge";
+import { usePopupManager } from "./usePopupManager";
+
+/**
+ * installHkTooltipBridge contract tests:
+ * - engage: hovering/focusing a [title] element REMOVES the attribute
+ *   (native tooltip cannot appear), stashes it in data-hk-title, and
+ *   shows the shared `.hk-tooltip-popup` after the delay with the text
+ *   + aria-describedby on the trigger
+ * - disengage: the title attribute is restored exactly when WE removed
+ *   it; fresher writers (host re-set, HkPopover's `title=""` blanking,
+ *   Vue undefined-removal) always win
+ * - escape hatches: empty titles, [data-hk-tooltip-native], elements
+ *   inside an HkTooltip wrapper — never engage
+ * - pointerdown hides but stays engaged; scroll/resize and Esc disengage
+ * - idempotent install per document; uninstall tears everything down
+ */
+
+const manager = usePopupManager();
+
+function install(options: HkTooltipBridgeOptions = {}) {
+  const uninstall = installHkTooltipBridge(options);
+  uninstalls.push(uninstall);
+  return uninstall;
+}
+
+const uninstalls: Array<() => void> = [];
+
+function trigger(title: string): HTMLElement {
+  const el = document.createElement("button");
+  el.setAttribute("title", title);
+  el.textContent = "probe";
+  document.body.appendChild(el);
+  return el;
+}
+
+function hover(el: Element) {
+  el.dispatchEvent(new MouseEvent("pointerover", { bubbles: true }));
+}
+
+function unhover(el: Element) {
+  el.dispatchEvent(new MouseEvent("pointerout", { bubbles: true }));
+}
+
+function bridgePopup(): HTMLElement | null {
+  return document.querySelector<HTMLElement>(".hk-tooltip-popup.hk-tooltip-bridge");
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const u of uninstalls.splice(0)) u();
+  for (const entry of [...manager.registry.value.values()]) {
+    manager.unregister(entry.id);
+  }
+  document.querySelectorAll(".hk-tooltip-popup").forEach((el) => el.remove());
+  document.querySelectorAll<HTMLElement>("[data-hk-title]").forEach((el) => {
+    delete el.dataset.hkTitle;
+  });
+});
+
+describe("installHkTooltipBridge", () => {
+  it("engages on hover: removes the title, shows the popup after the delay", () => {
+    vi.useFakeTimers();
+    install({ delay: 300 });
+    const el = trigger("Hello world");
+    hover(el);
+    expect(el.hasAttribute("title")).toBe(false);
+    expect(el.dataset.hkTitle).toBe("Hello world");
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+    vi.advanceTimersByTime(300);
+    const popup = bridgePopup()!;
+    expect(popup.classList.contains("hk-tooltip-visible")).toBe(true);
+    expect(popup.querySelector(".hk-tooltip-content")?.textContent).toBe("Hello world");
+    expect(el.getAttribute("aria-describedby")).toBe(popup.id);
+  });
+
+  it("restores the title and hides the popup on leave", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Back soon");
+    hover(el);
+    vi.advanceTimersByTime(300);
+    unhover(el);
+    expect(el.getAttribute("title")).toBe("Back soon");
+    expect(el.hasAttribute("aria-describedby")).toBe(false);
+    expect(el.dataset.hkTitle).toBeUndefined();
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+  });
+
+  it("cancels a pending show when the pointer leaves before the delay", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Never shown");
+    hover(el);
+    unhover(el);
+    vi.advanceTimersByTime(1000);
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+    expect(el.getAttribute("title")).toBe("Never shown");
+  });
+
+  it("engages on keyboard focus too and disengages on blur", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Focused");
+    el.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    vi.advanceTimersByTime(300);
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(true);
+    el.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    expect(el.getAttribute("title")).toBe("Focused");
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+  });
+
+  it("never engages on empty titles, native escape hatches or HkTooltip-managed triggers", () => {
+    vi.useFakeTimers();
+    install();
+    const blank = trigger("");
+    hover(blank);
+    expect(blank.hasAttribute("title")).toBe(true);
+    const native = trigger("Native");
+    native.setAttribute("data-hk-tooltip-native", "");
+    hover(native);
+    expect(native.getAttribute("title")).toBe("Native");
+    const wrapped = trigger("Managed");
+    const wrapper = document.createElement("span");
+    wrapper.className = "hk-tooltip-wrapper";
+    wrapper.appendChild(wrapped);
+    document.body.appendChild(wrapper);
+    hover(wrapped);
+    expect(wrapped.getAttribute("title")).toBe("Managed");
+    vi.advanceTimersByTime(1000);
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+  });
+
+  it("honors the exclude option", () => {
+    vi.useFakeTimers();
+    install({ exclude: ".quiet" });
+    const el = trigger("Excluded");
+    el.className = "quiet";
+    hover(el);
+    expect(el.getAttribute("title")).toBe("Excluded");
+  });
+
+  it("never restores over a fresher writer while engaged", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Old");
+    hover(el);
+    // The host (or a Vue binding) re-set the title mid-hover.
+    el.setAttribute("title", "New");
+    unhover(el);
+    expect(el.getAttribute("title")).toBe("New");
+  });
+
+  it("leaves a blanked title alone (HkPopover open-state suppression)", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Suppressed");
+    hover(el);
+    // HkPopover blanks titles via `title=""` while a popover is open.
+    el.setAttribute("title", "");
+    unhover(el);
+    expect(el.getAttribute("title")).toBe("");
+  });
+
+  it("hides on pointerdown but stays engaged until the pointer leaves", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Stays");
+    hover(el);
+    vi.advanceTimersByTime(300);
+    el.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true }));
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+    expect(el.hasAttribute("title")).toBe(false); // still engaged — no native flash
+    unhover(el);
+    expect(el.getAttribute("title")).toBe("Stays");
+  });
+
+  it("disengages on Escape", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Escaped");
+    hover(el);
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    expect(el.getAttribute("title")).toBe("Escaped");
+  });
+
+  it("disengages on scroll and resize (restores the title, drops the hold)", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Scrolled");
+    hover(el);
+    document.dispatchEvent(new Event("scroll"));
+    expect(el.getAttribute("title")).toBe("Scrolled");
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+    hover(el);
+    window.dispatchEvent(new Event("resize"));
+    expect(el.getAttribute("title")).toBe("Scrolled");
+  });
+
+  it("is idempotent per document and uninstallable", () => {
+    vi.useFakeTimers();
+    install();
+    const second = installHkTooltipBridge();
+    // The duplicate install reuses the first bridge: still one popup.
+    expect(document.querySelectorAll(".hk-tooltip-bridge").length).toBe(1);
+    second();
+    const el = trigger("After uninstall");
+    hover(el);
+    expect(el.getAttribute("title")).toBe("After uninstall");
+  });
+});

package/src/runtime/tooltipBridge.ts

@@ -0,0 +1,292 @@
+// installHkTooltipBridge — document-level replacement for NATIVE tooltips.
+//
+// Hover/focus on ANY element carrying a `title` attribute shows an
+// HkTooltip-styled popup instead of the browser's built-in one, so every
+// existing `title=` call site in a host app upgrades to the house tooltip
+// look with zero per-component migration. The mechanics:
+//
+//   engage (pointerover / focusin, delegated)
+//     → 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
+//   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
+//       view-source fidelity and non-pointer readers keep the original
+//       markup (screen readers announce the title on focus as before;
+//       while the popup is up it carries aria-describedby instead).
+//
+// Escape hatches:
+//   - `[data-hk-tooltip-native]` keeps its native browser tooltip
+//   - elements inside an `.hk-tooltip-wrapper` are already HkTooltip-
+//     managed and are skipped (no double popups)
+//   - empty / whitespace-only titles never engage
+//
+// The bridge holds one popup-manager handle (kind "tooltip"), so its
+// 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 { usePopupManager, type PopupHandle } from "./usePopupManager";
+// The popup reuses HkTooltip's popup classes — carry the sheet so a host
+// that installs the bridge without mounting HkTooltip still renders the
+// house look (scss imports are deduped, so double-import is free).
+import "../components/HkTooltip.scss";
+
+export interface HkTooltipBridgeOptions {
+  /** Hover/focus → popup delay in ms (HkTooltip parity: 300). */
+  delay?: number;
+  /** Popup side relative to the trigger. */
+  placement?: TooltipPlacement;
+  /** Popup max-width (the shared SCSS caps at 280px by default). */
+  maxWidth?: string;
+  /** Which elements carry tooltip text. Default: `[title]`. */
+  selector?: string;
+  /** Elements matching this never engage (their title stays native). */
+  exclude?: string;
+}
+
+interface BridgeState {
+  root: Document;
+  popup: HTMLDivElement;
+  content: HTMLDivElement;
+  handle: PopupHandle | null;
+  listeners: Array<{ target: EventTarget; type: string; fn: EventListener; opts?: AddEventListenerOptions }>;
+  active: Element | null;
+  savedTitle: string | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  delay: number;
+  placement: TooltipPlacement;
+  maxWidth: string | undefined;
+  selector: string;
+  exclude: string;
+  describedBy: string;
+}
+
+const INSTALLS = new WeakMap<Document, BridgeState>();
+let bridgeSeq = 0;
+
+function stopTimer(state: BridgeState) {
+  if (state.timer !== null) {
+    clearTimeout(state.timer);
+    state.timer = null;
+  }
+}
+
+/** Fade the popup out without touching the held title. */
+function hidePopup(state: BridgeState) {
+  stopTimer(state);
+  state.popup.classList.remove("hk-tooltip-visible");
+  if (state.active) {
+    // Hand the description relationship back: once the popup is gone the
+    // restored title attribute speaks for itself again.
+    state.active.removeAttribute("aria-describedby");
+  }
+}
+
+/** Restore the title attribute stashed at engage time and drop the hold. */
+function restoreTitle(state: BridgeState) {
+  const el = state.active;
+  const saved = state.savedTitle;
+  state.active = null;
+  state.savedTitle = null;
+  if (!el) return;
+  // Write back ONLY into the exact state WE created (attr removed).
+  // Anything else is a fresher writer that must win:
+  //   - a host re-set a title while we held it removed → theirs;
+  //   - HkPopover's open-state suppression blanks titles via `title=""`
+  //     and restores its own snapshots on close — resurrecting ours over
+  //     its blank would defeat it (engage already skips empty titles, so
+  //     blanked elements can never be the engaged ones);
+  //   - a Vue binding flipped to `undefined` → Vue REMOVES the attr, and
+  //     a stale resurrection would keep showing dead text.
+  // Vue never re-adds an attr it saw removed while its vnode value stayed
+  // unchanged, so this restore is what keeps static titles alive after a
+  // plain hover.
+  if (saved !== null && !el.hasAttribute("title")) {
+    el.setAttribute("title", saved);
+  }
+  delete (el as HTMLElement).dataset.hkTitle;
+}
+
+function disengage(state: BridgeState) {
+  stopTimer(state);
+  hidePopup(state);
+  restoreTitle(state);
+}
+
+function showPopup(state: BridgeState, el: Element) {
+  const text = state.savedTitle;
+  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(
+    el.getBoundingClientRect(),
+    state.placement,
+    state.maxWidth,
+  ));
+  state.popup.classList.add("hk-tooltip-visible");
+  el.setAttribute("aria-describedby", state.describedBy);
+}
+
+function engage(state: BridgeState, el: Element) {
+  if (state.active === el) return; // moving across the trigger's children
+  if (state.active) disengage(state);
+  const title = el.getAttribute("title");
+  if (!title || !title.trim()) return;
+  state.active = el;
+  state.savedTitle = title;
+  (el as HTMLElement).dataset.hkTitle = title;
+  el.removeAttribute("title");
+  stopTimer(state);
+  state.timer = setTimeout(() => {
+    state.timer = null;
+    showPopup(state, el);
+  }, state.delay);
+}
+
+function shouldEngage(state: BridgeState, target: EventTarget | null): Element | null {
+  if (!target || !(target instanceof Element)) return null;
+  // Skip HkTooltip-managed triggers and the bridge's own popup.
+  if (target.closest(".hk-tooltip-wrapper") || target.closest(".hk-tooltip-popup")) return null;
+  if (target.closest("[data-hk-tooltip-native]")) return null;
+  if (state.exclude && target.closest(state.exclude)) return null;
+  const el = target.closest(state.selector);
+  // HTML and SVG elements both carry dataset/getBoundingClientRect/attrs —
+  // an <svg title=...> gets the house popup just like a <button>.
+  return el instanceof HTMLElement || el instanceof SVGElement ? el : null;
+}
+
+function uninstall(state: BridgeState) {
+  if (INSTALLS.get(state.root) === state) INSTALLS.delete(state.root);
+  disengage(state);
+  for (const { target, type, fn, opts } of state.listeners.splice(0)) {
+    target.removeEventListener(type, fn, opts);
+  }
+  if (state.handle) {
+    try {
+      usePopupManager().unregister(state.handle.id);
+    } catch {
+      /* handle already gone */
+    }
+    state.handle = null;
+  }
+  state.popup.remove();
+}
+
+/**
+ * Install the document-level native-tooltip replacement. Returns the
+ * uninstaller (removes listeners, restores any held title, drops the
+ * popup element). Idempotent per document.
+ */
+export function installHkTooltipBridge(options: HkTooltipBridgeOptions = {}): () => void {
+  if (typeof document === "undefined") return () => undefined;
+  const existing = INSTALLS.get(document);
+  if (existing) return () => uninstall(existing);
+
+  const popup = document.createElement("div");
+  popup.className = "hk-tooltip-popup hk-tooltip-bridge";
+  const content = document.createElement("div");
+  content.className = "hk-tooltip-content";
+  popup.appendChild(content);
+  document.body.appendChild(popup);
+
+  const state: BridgeState = {
+    root: document,
+    popup,
+    content,
+    handle: null,
+    listeners: [],
+    active: null,
+    savedTitle: null,
+    timer: null,
+    delay: options.delay ?? 300,
+    placement: options.placement ?? "top",
+    maxWidth: options.maxWidth,
+    selector: options.selector ?? "[title]",
+    exclude: options.exclude ?? "",
+    describedBy: `hk-tooltip-bridge-${++bridgeSeq}`,
+  };
+  popup.id = state.describedBy;
+
+  // One popup-manager handle for the bridge's lifetime: its popups hold
+  // the tooltip band (above overlays, below toasts) exactly like
+  // component tooltips do.
+  try {
+    state.handle = usePopupManager().register("tooltip", false);
+    popup.style.zIndex = String(state.handle.zIndex);
+  } catch {
+    state.handle = null; // popup manager unavailable — CSS fallback z-index
+  }
+
+  const on = (type: string, fn: EventListener, opts?: AddEventListenerOptions) => {
+    document.addEventListener(type, fn, opts);
+    state.listeners.push({ target: document, type, fn, opts });
+  };
+
+  on("pointerover", (e) => {
+    const el = shouldEngage(state, e.target);
+    if (el) engage(state, el);
+  }, { capture: true, passive: true });
+
+  on("pointerout", (e) => {
+    if (!state.active) return;
+    const target = e.target instanceof Element ? e.target : null;
+    if (!target) return;
+    // Only leave when the pointer exited the engaged element entirely.
+    // Containment — NOT the selector: engagement removed the title
+    // attribute, so the engaged element no longer matches `[title]`.
+    const related = (e as MouseEvent).relatedTarget;
+    if ((target === state.active || state.active.contains(target))
+      && !(related instanceof Element && state.active.contains(related))) {
+      disengage(state);
+    }
+  }, { capture: true, passive: true });
+
+  on("pointerdown", () => {
+    if (state.active) hidePopup(state); // native also hides on press; stay engaged
+  }, { capture: true, passive: true });
+
+  on("focusin", (e) => {
+    const el = shouldEngage(state, e.target);
+    if (el) engage(state, el);
+  }, { capture: true });
+
+  on("focusout", (e) => {
+    if (!state.active) return;
+    if (e.target instanceof Element
+      && (e.target === state.active || state.active.contains(e.target))) {
+      disengage(state);
+    }
+  }, { capture: true });
+
+  // Any scroll/resize anywhere invalidates the fixed-position geometry —
+  // DISCONNECT entirely (restore the title, drop the hold), not just hide:
+  // a hide-only path would leave the trigger with its title attribute
+  // removed and no aria-describedby while the pointer rests on it. The
+  // popup re-arms through a fresh engage on the next pointer move.
+  // NOTE: resize fires at WINDOW (never routed through document capture),
+  // so it binds there explicitly; element scrolls are capture-reachable
+  // from the document.
+  on("scroll", () => {
+    if (state.active) disengage(state);
+  }, { capture: true, passive: true });
+  const view = document.defaultView;
+  if (view) {
+    const onResize = () => {
+      if (state.active) disengage(state);
+    };
+    view.addEventListener("resize", onResize);
+    state.listeners.push({ target: view, type: "resize", fn: onResize });
+  }
+
+  on("keydown", (e) => {
+    if ((e as KeyboardEvent).key === "Escape" && state.active) disengage(state);
+  }, { capture: true });
+
+  INSTALLS.set(document, state);
+  return () => uninstall(state);
+}

package/src/runtime/tooltipPosition.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOLTIP_GAP_PX, tooltipPositionStyle } from "./tooltipPosition";
+
+/** A 100x40 rect at (200,100) — big enough for every placement side. */
+function rect(): DOMRect {
+  return {
+    left: 200, top: 100, right: 300, bottom: 140,
+    width: 100, height: 40, x: 200, y: 100,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+describe("tooltipPositionStyle", () => {
+  it("pins the popup 8px outside the rect with per-placement transforms", () => {
+    expect(TOOLTIP_GAP_PX).toBe(8);
+    const top = tooltipPositionStyle(rect(), "top");
+    expect(top.top).toBe("92px"); // 100 - 8
+    expect(top.left).toBe("250px"); // hcenter
+    expect(top.transform).toBe("translate(-50%, -100%)");
+
+    const bottom = tooltipPositionStyle(rect(), "bottom");
+    expect(bottom.top).toBe("148px"); // 140 + 8
+    expect(bottom.transform).toBe("translate(-50%, 0)");
+
+    const left = tooltipPositionStyle(rect(), "left");
+    expect(left.left).toBe("192px"); // 200 - 8
+    expect(left.top).toBe("120px"); // vcenter
+    expect(left.transform).toBe("translate(-100%, -50%)");
+
+    const right = tooltipPositionStyle(rect(), "right");
+    expect(right.left).toBe("308px"); // 300 + 8
+    expect(right.transform).toBe("translate(0, -50%)");
+  });
+
+  it("carries the maxWidth override onto the popup style", () => {
+    const style = tooltipPositionStyle(rect(), "top", "180px");
+    expect(style.maxWidth).toBe("180px");
+    expect(tooltipPositionStyle(rect(), "top").maxWidth).toBeUndefined();
+  });
+});