@runtypelabs/persona 4.17.0 → 4.18.0

package/src/utils/tokens.ts

@@ -280,9 +280,10 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     },
   },
   launcher: {
-    background: 'palette.colors.primary.500',
-    foreground: 'palette.colors.primary.50',
-    border: 'palette.colors.gray.200',
+    // Launcher pill role: shared surface/primary tones until a host overrides.
+    background: 'semantic.colors.surface',
+    foreground: 'semantic.colors.primary',
+    border: 'semantic.colors.border',
     size: '60px',
     iconSize: '28px',
     borderRadius: 'palette.radius.full',
@@ -299,16 +300,14 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     canvasBackground: DEFAULT_PANEL_CANVAS_BACKGROUND,
   },
   header: {
-    // Header role: solid primary
+    // Header role: solid primary. Border, subtitle, and action icons stay
+    // unset so they derive from this background/foreground pair.
     background: 'palette.colors.primary.500',
-    border: 'palette.colors.primary.600',
+    foreground: 'palette.colors.primary.50',
     borderRadius: 'palette.radius.xl palette.radius.xl 0 0',
     padding: 'semantic.spacing.md',
     iconBackground: 'palette.colors.primary.600',
     iconForeground: 'palette.colors.primary.50',
-    titleForeground: 'palette.colors.primary.50',
-    subtitleForeground: 'palette.colors.primary.200',
-    actionIconForeground: 'palette.colors.primary.200',
   },
   message: {
     user: {
@@ -729,6 +728,9 @@ export function createTheme(
   return theme;
 }
 
+/** Coerce a unitless "0" to "0px" for vars consumed inside length calc()s. */
+const zeroLength = (value: string): string => (value.trim() === '0' ? '0px' : value);
+
 export function themeToCssVariables(theme: PersonaTheme): Record<string, string> {
   const resolved = resolveTokens(theme);
   const cssVars: Record<string, string> = {};
@@ -787,10 +789,20 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     '9999px';
   cssVars['--persona-launcher-bg'] =
     cssVars['--persona-components-launcher-background'] ??
-    cssVars['--persona-primary'];
+    cssVars['--persona-surface'];
   cssVars['--persona-launcher-fg'] =
     cssVars['--persona-components-launcher-foreground'] ??
-    cssVars['--persona-text-inverse'];
+    cssVars['--persona-primary'];
+  // Subtitle keeps the shared muted tone while the foreground is stock (it
+  // resolves to primary); a custom foreground washes to 70% so both pill
+  // text lines recolor together. Compared by resolved value, not key
+  // presence: DEFAULT_COMPONENTS materializes launcher.foreground into
+  // every theme.
+  const launcherFg = cssVars['--persona-components-launcher-foreground'];
+  cssVars['--persona-launcher-fg-muted'] =
+    launcherFg && launcherFg !== cssVars['--persona-primary']
+      ? `color-mix(in srgb, ${launcherFg} 70%, transparent)`
+      : cssVars['--persona-muted'];
   cssVars['--persona-launcher-border'] =
     cssVars['--persona-components-launcher-border'] ??
     cssVars['--persona-border'];
@@ -853,8 +865,15 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   // dedicated CSS variables that the widget CSS reads for individual elements.
   cssVars['--persona-header-bg'] =
     cssVars['--persona-components-header-background'] ?? cssVars['--persona-surface'];
+  // The background/foreground pair anchors every other header color: unset
+  // text and border keys mix the two rather than falling back to page chrome.
+  const headerBg = cssVars['--persona-header-bg'];
+  const headerFg = cssVars['--persona-components-header-foreground'];
+  const headerMutedFg = headerFg ? `color-mix(in srgb, ${headerFg} 72%, ${headerBg})` : undefined;
   cssVars['--persona-header-border'] =
-    cssVars['--persona-components-header-border'] ?? cssVars['--persona-divider'];
+    cssVars['--persona-components-header-border'] ??
+    (headerFg ? `color-mix(in srgb, ${headerFg} 14%, ${headerBg})` : undefined) ??
+    cssVars['--persona-divider'];
   cssVars['--persona-header-icon-bg'] =
     cssVars['--persona-components-header-iconBackground'] ?? cssVars['--persona-primary'];
   cssVars['--persona-header-icon-fg'] =
@@ -863,17 +882,133 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   cssVars['--persona-header-title-fg'] =
     cssVars['--persona-components-header-title-color'] ??
     cssVars['--persona-components-header-titleForeground'] ??
+    headerFg ??
     cssVars['--persona-primary'];
   cssVars['--persona-header-subtitle-fg'] =
     cssVars['--persona-components-header-subtitle-color'] ??
     cssVars['--persona-components-header-subtitleForeground'] ??
+    headerMutedFg ??
     cssVars['--persona-text-muted'];
   cssVars['--persona-header-action-icon-fg'] =
-    cssVars['--persona-components-header-actionIconForeground'] ?? cssVars['--persona-muted'];
+    cssVars['--persona-components-header-actionIconForeground'] ??
+    headerMutedFg ??
+    cssVars['--persona-muted'];
+  // Unified header control box. Every header icon button reads these two from
+  // the stylesheet; per-control config keys stay inline and win. The third
+  // control token, `header.controlStrokeWidth`, needs no alias: widget.css
+  // reads its auto-emitted `--persona-components-header-controlStrokeWidth`
+  // directly and carries the 1.5 default in the var() fallback.
+  cssVars['--persona-header-control-size'] =
+    cssVars['--persona-components-header-controlSize'] ?? '32px';
+  cssVars['--persona-header-control-icon-size'] =
+    cssVars['--persona-components-header-controlIconSize'] ?? '20px';
 
   const headerTokens = theme.components?.header;
   if (headerTokens?.shadow) cssVars['--persona-header-shadow'] = headerTokens.shadow;
   if (headerTokens?.borderBottom) cssVars['--persona-header-border-bottom'] = headerTokens.borderBottom;
+  // Conditional: the stylesheet carries `auto` / the rail's own fallback chain,
+  // so an unset token must leave the variable undefined.
+  if (headerTokens?.minHeight) cssVars['--persona-header-min-height'] = headerTokens.minHeight;
+
+  // Messages rail header strip. Same conditional rule: the chunk's CSS carries
+  // the surface/border/height fallback chain when a theme says nothing.
+  const railHeaderBg = cssVars['--persona-components-history-railHeader-background'];
+  if (railHeaderBg) cssVars['--persona-history-rail-header-bg'] = railHeaderBg;
+  const railHeaderBorder = cssVars['--persona-components-history-railHeader-border'];
+  if (railHeaderBorder) cssVars['--persona-history-rail-header-border'] = railHeaderBorder;
+  const railHeaderMinHeight = cssVars['--persona-components-history-railHeader-minHeight'];
+  if (railHeaderMinHeight)
+    cssVars['--persona-history-rail-header-min-height'] = railHeaderMinHeight;
+
+  // Floating (overlay-collapsed) rail. Same conditional rule: the host's
+  // inline styles carry every default in their var() fallback.
+  for (const [token, alias] of [
+    ['margin', 'margin'],
+    ['borderRadius', 'radius'],
+    ['shadow', 'shadow'],
+    ['background', 'bg'],
+  ] as const) {
+    const value = cssVars[`--persona-components-history-overlay-${token}`];
+    if (value) cssVars[`--persona-history-overlay-${alias}`] = value;
+  }
+
+  // Row overflow menu. Same conditional rule: the chunk's CSS carries the
+  // elevated color-mix default in its var() fallback.
+  for (const [token, alias] of [
+    ['background', 'bg'],
+    ['borderRadius', 'radius'],
+  ] as const) {
+    const value = cssVars[`--persona-components-history-menu-${token}`];
+    if (value) cssVars[`--persona-history-menu-${alias}`] = value;
+  }
+  // Messages enter/exit motion. Read straight off the theme: durations are
+  // authored as bare millisecond NUMBERS, and resolveTokens collects only
+  // string leaves, so these never reach the flattened vars. A unitless value
+  // gains "ms" for the CSS animation shorthand; 0 emits "0ms" (leg disabled).
+  const historyMotion = theme.components?.history?.motion;
+  if (historyMotion) {
+    const asTime = (value: number | string | undefined): string | undefined => {
+      if (value === undefined) return undefined;
+      const s = String(value).trim();
+      return /^\d+(\.\d+)?$/.test(s) ? `${s}ms` : s;
+    };
+    const enterMs = asTime(historyMotion.enterDurationMs);
+    if (enterMs !== undefined) cssVars['--persona-history-enter-ms'] = enterMs;
+    const exitMs = asTime(historyMotion.exitDurationMs);
+    if (exitMs !== undefined) cssVars['--persona-history-exit-ms'] = exitMs;
+    if (historyMotion.enterEasing)
+      cssVars['--persona-history-enter-easing'] = historyMotion.enterEasing;
+    if (historyMotion.exitEasing)
+      cssVars['--persona-history-exit-easing'] = historyMotion.exitEasing;
+  }
+  // Destructive action text. The chunk falls back to the light-surface
+  // error-600; the built-in dark theme sets this to a passing lighter red.
+  const historyDangerFg = cssVars['--persona-components-history-dangerForeground'];
+  if (historyDangerFg) cssVars['--persona-history-danger-fg'] = historyDangerFg;
+  // Confirmation dialog. The danger fill/label pair is always emitted so the
+  // dialog follows the error palette; scrim and shadow stay conditional with
+  // the dialog's inline fallbacks as the defaults.
+  cssVars['--persona-danger'] =
+    cssVars['--persona-components-history-confirm-dangerBackground'] ??
+    cssVars['--persona-palette-colors-error-700'] ??
+    '#b42318';
+  cssVars['--persona-danger-fg'] =
+    cssVars['--persona-components-history-confirm-dangerForeground'] ?? '#ffffff';
+  for (const token of ['scrim', 'shadow'] as const) {
+    const value = cssVars[`--persona-components-history-confirm-${token}`];
+    if (value) cssVars[`--persona-history-confirm-${token}`] = value;
+  }
+
+  // Portaled control tooltip. Same conditional rule: widget.css carries the
+  // built-in look in every var() fallback, so an unset token stays undefined.
+  for (const [token, alias] of [
+    ['background', 'background'],
+    ['foreground', 'foreground'],
+    ['hintForeground', 'hint-fg'],
+    ['borderRadius', 'radius'],
+    ['fontSize', 'font-size'],
+    ['padding', 'padding'],
+    ['maxWidth', 'max-width'],
+    ['shadow', 'shadow'],
+  ]) {
+    const value = cssVars[`--persona-components-tooltip-${token}`];
+    if (value) cssVars[`--persona-tooltip-${alias}`] = value;
+  }
+  // Booleans never resolve into a token, so the arrow reads off the theme.
+  if (theme.components?.tooltip?.arrow === false)
+    cssVars['--persona-tooltip-arrow-display'] = 'none';
+
+  // Per-message action row (copy, vote, read aloud). Same conditional rule:
+  // widget.css falls back to the scheme-aware ghost wash and semantic text, so
+  // an unset token must leave the variable undefined.
+  for (const [token, alias] of [
+    ['hoverBackground', 'hover-bg'],
+    ['hoverForeground', 'hover-fg'],
+    ['borderRadius', 'radius'],
+  ] as const) {
+    const value = cssVars[`--persona-components-messageActions-${token}`];
+    if (value) cssVars[`--persona-message-action-${alias}`] = value;
+  }
 
   // Intro card aliases: short names the panel inline-styles read directly.
   // The full-path `--persona-components-introCard-*` variables auto-emit above.
@@ -1102,16 +1237,19 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     if (t.iconPadding) cssVars['--persona-artifact-toolbar-icon-padding'] = t.iconPadding;
     if (t.iconBorderRadius) cssVars['--persona-artifact-toolbar-icon-radius'] = t.iconBorderRadius;
     if (t.iconBorder) cssVars['--persona-artifact-toolbar-icon-border'] = t.iconBorder;
-    if (t.toggleGroupGap) cssVars['--persona-artifact-toolbar-toggle-group-gap'] = t.toggleGroupGap;
+    // A bare "0" is a <number> in calc(), not a <length>; gap/padding feed the
+    // toggle thumb's width calc, so a unitless zero would zero out the thumb.
+    if (t.toggleGroupGap) cssVars['--persona-artifact-toolbar-toggle-group-gap'] = zeroLength(t.toggleGroupGap);
     if (t.toggleBorderRadius) cssVars['--persona-artifact-toolbar-toggle-radius'] = t.toggleBorderRadius;
-    if (t.toggleGroupPadding) cssVars['--persona-artifact-toolbar-toggle-group-padding'] = t.toggleGroupPadding;
+    if (t.toggleGroupPadding) cssVars['--persona-artifact-toolbar-toggle-group-padding'] = zeroLength(t.toggleGroupPadding);
     if (t.toggleGroupBorder) cssVars['--persona-artifact-toolbar-toggle-group-border'] = t.toggleGroupBorder;
     if (t.toggleGroupBorderRadius) cssVars['--persona-artifact-toolbar-toggle-group-radius'] = t.toggleGroupBorderRadius;
     if (t.toggleGroupBackground) cssVars['--persona-artifact-toolbar-toggle-group-bg'] = resolveTokenValue(theme, t.toggleGroupBackground) ?? t.toggleGroupBackground;
     if (t.copyBackground) cssVars['--persona-artifact-toolbar-copy-bg'] = t.copyBackground;
     if (t.copyBorder) cssVars['--persona-artifact-toolbar-copy-border'] = t.copyBorder;
     if (t.copyColor) cssVars['--persona-artifact-toolbar-copy-color'] = t.copyColor;
-    if (t.copyBorderRadius) cssVars['--persona-artifact-toolbar-copy-radius'] = t.copyBorderRadius;
+    // Feeds the split-button halves' inner-radius calc; must stay a <length>.
+    if (t.copyBorderRadius) cssVars['--persona-artifact-toolbar-copy-radius'] = zeroLength(t.copyBorderRadius);
     if (t.copyPadding) cssVars['--persona-artifact-toolbar-copy-padding'] = t.copyPadding;
     if (t.copyMenuBackground) {
       cssVars['--persona-artifact-toolbar-copy-menu-bg'] = t.copyMenuBackground;

package/src/utils/tooltip-timing.ts

@@ -0,0 +1,4 @@
+/** First-hover wait. Matches ChatGPT and Claude. */
+export const DEFAULT_TOOLTIP_DELAY_MS = 200;
+/** After one tooltip, later ones in this window open immediately. */
+export const DEFAULT_TOOLTIP_SKIP_DELAY_MS = 300;

package/src/utils/tooltip.test.ts

@@ -1,7 +1,23 @@
 // @vitest-environment jsdom
 
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { attachTooltip } from "./tooltip";
+import {
+  attachTooltip,
+  DEFAULT_TOOLTIP_DELAY_MS,
+  resetTooltipTiming,
+} from "./tooltip";
+
+/**
+ * Focus with a pinned keyboard-visible verdict. jsdom implements the spec's
+ * focus-visible propagation, so a bare focus() verdict depends on what ran
+ * before it; tests that open via focus must not be order-dependent.
+ */
+const focusVisible = (button: HTMLElement): void => {
+  vi.spyOn(button, "matches").mockImplementation(
+    (selector: string) => selector === ":focus-visible"
+  );
+  button.focus();
+};
 
 const rect = (
   left: number,
@@ -98,7 +114,7 @@ describe("attachTooltip", () => {
     );
 
     attachTooltip({ anchor: button, text: "Close chat" });
-    button.focus();
+    focusVisible(button);
 
     const tooltip = document.body.querySelector<HTMLElement>(
       ".persona-control-tooltip"
@@ -110,12 +126,26 @@ describe("attachTooltip", () => {
     expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
   });
 
-  it("dismisses an open tooltip with Escape", () => {
+  it("stays closed on focus that is not focus-visible", () => {
     const button = document.createElement("button");
     document.body.appendChild(button);
+    // jsdom reports every focus as :focus-visible; model a browser's
+    // programmatic-focus-after-mouse verdict instead.
+    vi.spyOn(button, "matches").mockImplementation(
+      (selector: string) => selector !== ":focus-visible"
+    );
 
     attachTooltip({ anchor: button, text: "Close chat" });
     button.focus();
+    expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
+  });
+
+  it("dismisses an open tooltip with Escape", () => {
+    const button = document.createElement("button");
+    document.body.appendChild(button);
+
+    attachTooltip({ anchor: button, text: "Close chat" });
+    focusVisible(button);
     expect(document.body.querySelector(".persona-control-tooltip")).not.toBeNull();
 
     button.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
@@ -123,6 +153,47 @@ describe("attachTooltip", () => {
     expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
   });
 
+  it("dismisses on activation and reopens with the label the control now has", () => {
+    const button = document.createElement("button");
+    button.setAttribute("aria-label", "Collapse conversation list");
+    document.body.appendChild(button);
+    const tip = () =>
+      document.body.querySelector<HTMLElement>(".persona-control-tooltip");
+
+    attachTooltip({
+      anchor: button,
+      text: () => button.getAttribute("aria-label") ?? "",
+    });
+    button.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(tip()?.textContent).toContain("Collapse conversation list");
+
+    // The pointer never left, so nothing but the activation closes it.
+    button.click();
+    expect(tip()).toBeNull();
+
+    button.setAttribute("aria-label", "Expand conversation list");
+    button.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(tip()?.textContent).toContain("Expand conversation list");
+  });
+
+  it("dismisses a keyboard-opened tooltip on activation until focus returns", () => {
+    const button = document.createElement("button");
+    document.body.appendChild(button);
+    const tip = () => document.body.querySelector(".persona-control-tooltip");
+
+    attachTooltip({ anchor: button, text: "Close chat" });
+    focusVisible(button);
+    expect(tip()).not.toBeNull();
+
+    // Space/Enter activates without moving focus off the control.
+    button.click();
+    expect(tip()).toBeNull();
+
+    button.blur();
+    focusVisible(button);
+    expect(tip()).not.toBeNull();
+  });
+
   it("suppresses hover tooltips when the device has no hover capability", () => {
     vi.stubGlobal(
       "matchMedia",
@@ -166,7 +237,7 @@ describe("attachTooltip", () => {
     );
 
     attachTooltip({ anchor: button, text: "Add context" });
-    button.focus();
+    focusVisible(button);
     const tooltip = document.body.querySelector<HTMLElement>(
       ".persona-control-tooltip"
     );
@@ -186,7 +257,7 @@ describe("attachTooltip", () => {
     document.body.appendChild(button);
 
     attachTooltip({ anchor: button, text: "Add context" });
-    button.focus();
+    focusVisible(button);
     expect(document.body.querySelector(".persona-control-tooltip")).not.toBeNull();
 
     button.remove();
@@ -203,11 +274,101 @@ describe("attachTooltip", () => {
     const next = attachTooltip({ anchor: button, text: "New", enabled: false });
 
     expect(old.isOpen).toBe(false);
-    button.focus();
+    focusVisible(button);
     expect(next.isOpen).toBe(false);
     expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
   });
 
+  it("renders a shortcut hint chip and refreshes it alongside the label", () => {
+    const button = document.createElement("button");
+    button.setAttribute("aria-label", "New conversation");
+    document.body.appendChild(button);
+    let hint = "⌘K";
+
+    attachTooltip({
+      anchor: button,
+      text: () => button.getAttribute("aria-label") ?? "",
+      hint: () => hint,
+    });
+    focusVisible(button);
+
+    const chip = () =>
+      document.body.querySelector<HTMLElement>(
+        ".persona-control-tooltip__hint"
+      );
+    expect(chip()?.textContent).toBe("⌘K");
+
+    hint = "⌘⇧K";
+    window.dispatchEvent(new Event("resize"));
+    expect(chip()?.textContent).toBe("⌘⇧K");
+  });
+
+  it("renders no hint chip when the hint is absent or empty", () => {
+    const bare = document.createElement("button");
+    const blank = document.createElement("button");
+    document.body.append(bare, blank);
+
+    attachTooltip({ anchor: bare, text: "Close chat" });
+    focusVisible(bare);
+    expect(
+      document.body.querySelector(".persona-control-tooltip__hint")
+    ).toBeNull();
+    bare.blur();
+
+    attachTooltip({ anchor: blank, text: "Close chat", hint: () => "  " });
+    focusVisible(blank);
+    expect(
+      document.body.querySelector(".persona-control-tooltip__hint")
+    ).toBeNull();
+  });
+
+  it("copies the anchor's resolved theme variables onto a body-portaled tooltip", () => {
+    const mount = document.createElement("div");
+    const button = document.createElement("button");
+    mount.appendChild(button);
+    document.body.appendChild(mount);
+
+    // The mount carries the theme; jsdom does not inherit custom properties,
+    // so the anchor's computed style is stubbed the way a browser resolves it.
+    vi.spyOn(window, "getComputedStyle").mockImplementation(
+      (element: Element) =>
+        ({
+          fontFamily: element === button ? "Geist, sans-serif" : "serif",
+          getPropertyValue: (name: string) =>
+            element === button
+              ? ({
+                  "--persona-tooltip-background": "#1d4ed8",
+                  "--persona-tooltip-hint-fg": "rgba(255,255,255,0.6)",
+                  "--persona-tooltip-arrow-display": "none",
+                  "--persona-radius-sm": "0.5rem",
+                })[name] ?? ""
+              : "",
+        }) as CSSStyleDeclaration
+    );
+
+    attachTooltip({ anchor: button, text: "Close chat", hint: "Esc" });
+    focusVisible(button);
+
+    const tooltip = document.body.querySelector<HTMLElement>(
+      ".persona-control-tooltip"
+    );
+    expect(tooltip!.style.getPropertyValue("--persona-tooltip-background")).toBe(
+      "#1d4ed8"
+    );
+    expect(tooltip!.style.getPropertyValue("--persona-tooltip-hint-fg")).toBe(
+      "rgba(255,255,255,0.6)"
+    );
+    // arrow: false rides along, so a themed tooltip hides the caret off-mount.
+    expect(
+      tooltip!.style.getPropertyValue("--persona-tooltip-arrow-display")
+    ).toBe("none");
+    expect(tooltip!.style.getPropertyValue("--persona-radius-sm")).toBe("0.5rem");
+    // The body portal inherits the page font; the anchor's family wins instead.
+    expect(tooltip!.style.fontFamily).toBe("Geist, sans-serif");
+    // Unresolved variables are never written as empty declarations.
+    expect(tooltip!.style.getPropertyValue("--persona-tooltip-padding")).toBe("");
+  });
+
   it("portals into the anchor's shadow root so widget styles still apply", () => {
     const host = document.createElement("div");
     const shadow = host.attachShadow({ mode: "open" });
@@ -216,7 +377,7 @@ describe("attachTooltip", () => {
     document.body.appendChild(host);
 
     attachTooltip({ anchor: button, text: "Shadow tooltip" });
-    button.focus();
+    focusVisible(button);
 
     expect(shadow.querySelector(".persona-control-tooltip")?.textContent).toContain(
       "Shadow tooltip"
@@ -224,3 +385,84 @@ describe("attachTooltip", () => {
     expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
   });
 });
+
+describe("attachTooltip hover delay", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    resetTooltipTiming({ delayMs: 0, skipDelayMs: 0 });
+  });
+
+  const tip = () => document.body.querySelector(".persona-control-tooltip");
+
+  const hoverButton = (label: string): HTMLButtonElement => {
+    const button = document.createElement("button");
+    button.setAttribute("aria-label", label);
+    document.body.appendChild(button);
+    attachTooltip({
+      anchor: button,
+      text: () => button.getAttribute("aria-label") ?? "",
+    });
+    return button;
+  };
+
+  it("waits the product default before showing on hover", () => {
+    resetTooltipTiming();
+    vi.useFakeTimers();
+    const button = hoverButton("Close chat");
+
+    button.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(tip()).toBeNull();
+
+    vi.advanceTimersByTime(DEFAULT_TOOLTIP_DELAY_MS - 1);
+    expect(tip()).toBeNull();
+
+    vi.advanceTimersByTime(1);
+    expect(tip()?.textContent).toContain("Close chat");
+  });
+
+  it("cancels a pending hover if the pointer leaves before the delay", () => {
+    resetTooltipTiming();
+    vi.useFakeTimers();
+    const button = hoverButton("Close chat");
+
+    button.dispatchEvent(new MouseEvent("mouseenter"));
+    vi.advanceTimersByTime(100);
+    button.dispatchEvent(new MouseEvent("mouseleave"));
+    vi.advanceTimersByTime(DEFAULT_TOOLTIP_DELAY_MS);
+    expect(tip()).toBeNull();
+  });
+
+  it("opens the next tooltip immediately inside the skip-delay window", () => {
+    resetTooltipTiming();
+    vi.useFakeTimers();
+    const first = hoverButton("New conversation");
+    const second = hoverButton("Close chat");
+
+    first.dispatchEvent(new MouseEvent("mouseenter"));
+    vi.advanceTimersByTime(DEFAULT_TOOLTIP_DELAY_MS);
+    expect(tip()?.textContent).toContain("New conversation");
+
+    first.dispatchEvent(new MouseEvent("mouseleave"));
+    expect(tip()).toBeNull();
+
+    second.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(tip()?.textContent).toContain("Close chat");
+  });
+
+  it("opens immediately on keyboard-visible focus even when hover is delayed", () => {
+    resetTooltipTiming();
+    const button = hoverButton("Close chat");
+    focusVisible(button);
+    expect(tip()?.textContent).toContain("Close chat");
+  });
+
+  it("honors delayMs: 0 for instant hover", () => {
+    const button = document.createElement("button");
+    document.body.appendChild(button);
+    attachTooltip({ anchor: button, text: "Close chat", delayMs: 0 });
+    button.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(tip()?.textContent).toContain("Close chat");
+  });
+});