From 5cdc2ea233b2c2d4cf07e88f83b50a83bb038e58 Mon Sep 17 00:00:00 2001
From: Valerio Coltre <colthreepv@gmail.com>
Date: Wed, 30 Sep 2026 08:56:22 +0700
Subject: [PATCH 1/3] fix(gui): keep quota popovers reachable and link account
 management

---
 .../src/content/docs/guides/web-dashboard.md  |   7 +-
 gui/README.md                                 |  19 ++
 gui/package.json                              |   3 +-
 .../quota-summary-bar/QuotaSummaryBar.tsx     |  39 +++-
 .../quota-summary-bar/quota-summary-bar.css   |  22 +++
 gui/tests/quota-summary-bar.test.tsx          |  96 +++++++++-
 gui/tests/quota-summary-hover-browser.ts      | 174 ++++++++++++++++++
 structure/dashboard-and-usage.md              |   4 +-
 8 files changed, 345 insertions(+), 19 deletions(-)
 create mode 100644 gui/tests/quota-summary-hover-browser.ts

diff --git a/docs-site/src/content/docs/guides/web-dashboard.md b/docs-site/src/content/docs/guides/web-dashboard.md
index 3645ae7c1d3..7af6c4dc4c9 100644
--- a/docs-site/src/content/docs/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/guides/web-dashboard.md
@@ -87,9 +87,12 @@ is visible) and never forces an upstream refresh.
   provider-named window or prepaid credits.
 - A chip turns amber at 70% used and red at 90% used.
 - Hover or keyboard-focus a chip to see every reported window with its reset time and the time the
-  reading was taken. On a touch screen, the first tap shows those details.
+  reading was taken. The details stay open as the pointer moves from the chip into the popover,
+  including across the small visual gap. On a touch screen, the first tap shows those details.
 - Click a chip (or tap it a second time) to open that provider's Accounts tab in Providers, where
-  its accounts or API keys are managed.
+  its accounts or API keys are managed. The popover's **Open account management** link opens the
+  same tab; keyboard users can Tab from the chip to this link and press Enter. Escape closes the
+  popover and returns focus to the chip when focus was inside the popover.
 - The bar always stays on one line. When the chips do not fit, scroll it sideways or use the « and
   » buttons at either end.
 - Providers that report no quota window are left out. The bar is hidden when no provider reports one.
diff --git a/gui/README.md b/gui/README.md
index e55b038fb64..d15f4432feb 100644
--- a/gui/README.md
+++ b/gui/README.md
@@ -53,6 +53,25 @@ bun run setup:hooks             # pre-push runs doctor when gui/ changed
 
 Fix ESLint errors first. Use `doctor` / `doctor:full` for deeper React triage.
 
+## Quota popover hover browser regression
+
+```bash
+cd gui
+bun run build
+bun run test:quota-hover
+```
+
+Rebuild after changing CSS: this opt-in check combines the current React quota component with
+the production CSS in `dist`. It uses an installed Chrome/Chromium (`CHROME_BIN` when not on PATH)
+and never connects to the proxy or provider accounts. Across 48 cases it moves a real pointer
+through the chip-to-popover gap, clicks the account-management link, returns to the chip, and
+checks dismissal outside. It also verifies keyboard Tab, Enter, and Escape. Cases cover light/dark themes, mobile and desktop widths, fractional
+placement, display scaling, and the last chip after horizontal scrolling. Results and a screenshot
+are written to `.tmp/quota-summary-hover-browser/`. This browser check is manual, not part of CI;
+happy-dom unit tests do not perform CSS hit-testing. To prove the guard detects the original gap,
+run `bun tests/quota-summary-hover-browser.ts .tmp/quota-hover-without-bridge --without-bridge`;
+that run must fail while crossing the gap.
+
 ## Sidebar version browser regression
 
 ```bash
diff --git a/gui/package.json b/gui/package.json
index cd9d7fcf917..d7000ade3d2 100644
--- a/gui/package.json
+++ b/gui/package.json
@@ -12,7 +12,8 @@
     "doctor": "npx --yes react-doctor@0.9.11 --verbose --scope changed --base origin/main --no-telemetry",
     "doctor:full": "npx --yes react-doctor@0.9.11 --verbose --scope full --no-telemetry",
     "preview": "vite preview",
-    "test:sidebar-version": "bun tests/sidebar-version-browser.ts"
+    "test:sidebar-version": "bun tests/sidebar-version-browser.ts",
+    "test:quota-hover": "bun tests/quota-summary-hover-browser.ts"
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.9",
diff --git a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
index 957694475f6..eec82276599 100644
--- a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
+++ b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
@@ -83,6 +83,8 @@ function usePopoverPlacement(open: boolean, anchorRef: RefObject<HTMLElement | n
       // Unitless: the stylesheet multiplies by 1px.
       popover.style.setProperty("--qs-pop-top", String(Math.round(rect.bottom + POPOVER_GAP)));
       popover.style.setProperty("--qs-pop-left", String(Math.round(left)));
+      // Share the measured gap with the hover bridge, including fractional-pixel rounding.
+      popover.style.setProperty("--qs-pop-gap", String(Math.round(rect.bottom + POPOVER_GAP) - rect.bottom));
     };
     place();
     window.addEventListener("scroll", place, { capture: true, passive: true });
@@ -124,7 +126,14 @@ function QuotaSummaryItem({ row, t, locale }: { row: QuotaSummaryRow; t: TFn; lo
       if (rootRef.current && !rootRef.current.contains(event.target as Node)) setTapped(false);
     };
     const onKey = (event: KeyboardEvent) => {
-      if (event.key === "Escape") close();
+      if (event.key === "Escape") {
+        const returnFocus = popoverRef.current?.contains(document.activeElement);
+        close();
+        if (returnFocus) {
+          chipRef.current?.focus();
+          setSuppressed(true);
+        }
+      }
     };
     document.addEventListener("pointerdown", onPointer);
     document.addEventListener("keydown", onKey);
@@ -169,19 +178,22 @@ function QuotaSummaryItem({ row, t, locale }: { row: QuotaSummaryRow; t: TFn; lo
       className={`quota-summary-item quota-summary-item--${row.severity}`}
       onPointerEnter={onPointerEnter}
       onPointerLeave={onPointerLeave}
+      onFocus={event => {
+        if (!isKeyboardFocus(event.target)) return;
+        setSuppressed(false);
+        setFocused(true);
+      }}
+      onBlur={event => {
+        if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
+      }}
     >
       <a
         ref={chipRef}
         href={`#${providerAccountsHash(row.provider)}`}
         className={`quota-summary-chip${open ? " quota-summary-chip--open" : ""}`}
-        aria-describedby={open ? popoverId : undefined}
+        aria-expanded={open}
+        aria-controls={open ? popoverId : undefined}
         onPointerDown={event => { pointerTypeRef.current = event.pointerType; }}
-        onFocus={event => {
-          if (!isKeyboardFocus(event.currentTarget)) return;
-          setSuppressed(false);
-          setFocused(true);
-        }}
-        onBlur={() => setFocused(false)}
         onClick={onClick}
       >
         <span className="quota-summary-name">{row.label}</span>
@@ -191,7 +203,7 @@ function QuotaSummaryItem({ row, t, locale }: { row: QuotaSummaryRow; t: TFn; lo
         <span className="sr-only">{t("quotaSummary.openAccounts")}</span>
       </a>
       {open && (
-        <div ref={popoverRef} id={popoverId} className="quota-summary-popover" role="tooltip">
+        <div ref={popoverRef} id={popoverId} className="quota-summary-popover" role="group" aria-label={row.label}>
           <div className="quota-summary-popover-head">
             <strong>{row.label}</strong>
             {warning && <span className={`quota-summary-badge quota-summary-badge--${row.severity}`}>{warning}</span>}
@@ -213,7 +225,14 @@ function QuotaSummaryItem({ row, t, locale }: { row: QuotaSummaryRow; t: TFn; lo
             {row.updatedAt !== undefined && (
               <span>{t(row.observed ? "quotaSummary.observedAt" : "quotaSummary.dataAt", { time: formatClock(row.updatedAt, locale) })}</span>
             )}
-            <span className="quota-summary-popover-hint">{t("quotaSummary.openAccounts")}</span>
+            <a
+              href={`#${providerAccountsHash(row.provider)}`}
+              className="quota-summary-popover-link"
+              onPointerDown={event => { pointerTypeRef.current = event.pointerType; }}
+              onClick={onClick}
+            >
+              {t("quotaSummary.openAccounts")}
+            </a>
           </div>
         </div>
       )}
diff --git a/gui/src/components/quota-summary-bar/quota-summary-bar.css b/gui/src/components/quota-summary-bar/quota-summary-bar.css
index 120a14512d3..118a854f54c 100644
--- a/gui/src/components/quota-summary-bar/quota-summary-bar.css
+++ b/gui/src/components/quota-summary-bar/quota-summary-bar.css
@@ -171,6 +171,17 @@
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.14);
 }
 
+/* Keep the pointer inside the item while crossing the visual gap to its fixed popover. */
+.quota-summary-popover::before {
+  content: "";
+  position: absolute;
+  left: -1px;
+  right: -1px;
+  bottom: 100%;
+  /* The containing block starts inside the border; cover it as well as the measured gap. */
+  height: calc((var(--qs-pop-gap, 4) + 1) * 1px);
+}
+
 .quota-summary-popover-head {
   display: flex;
   align-items: center;
@@ -257,6 +268,17 @@
   white-space: nowrap;
 }
 
+.quota-summary-popover-link {
+  color: var(--text);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.quota-summary-popover-link:focus-visible {
+  outline: 2px solid var(--text);
+  outline-offset: 1px;
+}
+
 .quota-summary-updated--stale {
   color: var(--amber);
 }
diff --git a/gui/tests/quota-summary-bar.test.tsx b/gui/tests/quota-summary-bar.test.tsx
index b3f8b1f7c09..5a9f1ece6f3 100644
--- a/gui/tests/quota-summary-bar.test.tsx
+++ b/gui/tests/quota-summary-bar.test.tsx
@@ -74,7 +74,30 @@ test("every chip is a link to its provider's Accounts tab, and a click follows i
   expect(view.chip("xAI Grok").getAttribute("href")).toBe("#providers?provider=xai&tab=accounts");
   await click(view.chip("xAI Grok"));
   expect(testWindow.location.hash).toBe("#providers?provider=xai&tab=accounts");
-  expect(view.container.querySelector("[role=tooltip]")).toBeNull();
+  expect(view.container.querySelector(".quota-summary-popover")).toBeNull();
+  await view.unmount();
+});
+
+test("popover placement shares the rounded gap with its hover bridge and updates on scroll", async () => {
+  const view = await mount();
+  const chip = view.chip("xAI Grok");
+  let bottom = 28.25;
+  Object.defineProperty(chip, "getBoundingClientRect", {
+    configurable: true,
+    value: () => new testWindow.DOMRect(10, bottom - 27, 150, 27),
+  });
+  await act(async () => {
+    chip.dispatchEvent(new testWindow.PointerEvent("pointerover", {
+      bubbles: true, pointerType: "mouse", relatedTarget: document.body,
+    } as never) as unknown as Event);
+  });
+  const popover = view.container.querySelector<HTMLElement>(".quota-summary-popover")!;
+  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("32");
+  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("3.75");
+  bottom = 28.75;
+  await act(async () => { window.dispatchEvent(new testWindow.Event("scroll") as unknown as Event); });
+  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("33");
+  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("4.25");
   await view.unmount();
 });
 
@@ -92,6 +115,71 @@ test("following the link that is already current re-announces it", async () => {
   await view.unmount();
 });
 
+test("the popover account link navigates and preserves modified clicks", async () => {
+  const view = await mount();
+  await act(async () => {
+    view.chip("Kimi").dispatchEvent(new testWindow.PointerEvent("pointerover", {
+      bubbles: true, pointerType: "mouse", relatedTarget: document.body,
+    } as never) as unknown as Event);
+  });
+  const popover = view.container.querySelector(".quota-summary-popover")!;
+  expect(popover.getAttribute("role")).toBe("group");
+  expect(popover.getAttribute("aria-label")).toBe("Kimi");
+  const link = popover.querySelector("a")!;
+  expect(link.getAttribute("href")).toBe("#providers?provider=kimi&tab=accounts");
+  await act(async () => {
+    const modified = new testWindow.MouseEvent("click", { bubbles: true, cancelable: true, ctrlKey: true });
+    link.dispatchEvent(modified as unknown as Event);
+    expect(modified.defaultPrevented).toBe(false);
+  });
+  expect(view.container.querySelector(".quota-summary-popover")).not.toBeNull();
+  await click(link);
+  expect(testWindow.location.hash).toBe("#providers?provider=kimi&tab=accounts");
+  expect(view.container.querySelector(".quota-summary-popover")).toBeNull();
+  await view.unmount();
+});
+
+test("keyboard focus reaches the account link, Escape restores the chip, and outside blur dismisses", async () => {
+  const view = await mount();
+  const chip = view.chip("Kimi");
+  // happy-dom has no input modality: emulate :focus-visible for keyboard focus only.
+  Object.defineProperty(chip, "matches", { configurable: true, value: () => true });
+  await act(async () => { chip.focus(); });
+  const link = view.container.querySelector<HTMLAnchorElement>(".quota-summary-popover-link")!;
+  Object.defineProperty(link, "matches", { configurable: true, value: () => true });
+  await act(async () => { link.focus(); });
+  expect(document.activeElement).toBe(link);
+  expect(view.container.querySelector(".quota-summary-popover")).not.toBeNull();
+  await act(async () => {
+    document.dispatchEvent(new testWindow.KeyboardEvent("keydown", { key: "Escape", bubbles: true }) as unknown as Event);
+  });
+  expect(document.activeElement).toBe(chip);
+  expect(chip.getAttribute("aria-expanded")).toBe("false");
+  expect(view.container.querySelector(".quota-summary-popover")).toBeNull();
+  await act(async () => { chip.blur(); chip.focus(); });
+  expect(view.container.querySelector(".quota-summary-popover")).not.toBeNull();
+  await act(async () => { chip.blur(); });
+  expect(view.container.querySelector(".quota-summary-popover")).toBeNull();
+  await view.unmount();
+});
+
+test("a touch user can follow the popover account link with one tap", async () => {
+  const view = await mount();
+  const chip = view.chip("Kimi");
+  await act(async () => {
+    chip.dispatchEvent(new testWindow.PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" } as never) as unknown as Event);
+  });
+  await click(chip);
+  const link = view.container.querySelector(".quota-summary-popover-link")!;
+  await act(async () => {
+    link.dispatchEvent(new testWindow.PointerEvent("pointerdown", { bubbles: true, pointerType: "touch" } as never) as unknown as Event);
+  });
+  await click(link);
+  expect(testWindow.location.hash).toBe("#providers?provider=kimi&tab=accounts");
+  expect(view.container.querySelector(".quota-summary-popover")).toBeNull();
+  await view.unmount();
+});
+
 test("the scroll buttons appear only when the chips overflow, and page the one row", async () => {
   const view = await mount();
   await scrollMetrics(view.list, { scrollWidth: 300, clientWidth: 300, scrollLeft: 0 });
@@ -135,7 +223,7 @@ test("on touch the first tap shows the detail, the second follows the link, and
     });
     await click(chip);
   };
-  const tooltip = () => view.container.querySelector("[role=tooltip]");
+  const tooltip = () => view.container.querySelector(".quota-summary-popover");
 
   await tap("Kimi");
   expect(tooltip()?.textContent).toContain("Kimi");
@@ -173,11 +261,11 @@ test("a clicked chip keeps its detail closed under the resting pointer until the
       item.dispatchEvent(new testWindow.PointerEvent(type, { bubbles: true, pointerType: "mouse", relatedTarget } as never) as unknown as Event);
     });
   };
-  const tooltip = () => view.container.querySelector("[role=tooltip]");
+  const tooltip = () => view.container.querySelector(".quota-summary-popover");
 
   await pointer("pointerover", document.body);
   expect(tooltip()?.textContent).toContain("xAI Grok");
-  expect(view.chip("xAI Grok").getAttribute("aria-describedby")).toBe(tooltip()?.id ?? "missing");
+  expect(view.chip("xAI Grok").getAttribute("aria-controls")).toBe(tooltip()?.id ?? "missing");
 
   await click(view.chip("xAI Grok"));
   expect(tooltip()).toBeNull();
diff --git a/gui/tests/quota-summary-hover-browser.ts b/gui/tests/quota-summary-hover-browser.ts
new file mode 100644
index 00000000000..24eca82f88a
--- /dev/null
+++ b/gui/tests/quota-summary-hover-browser.ts
@@ -0,0 +1,174 @@
+/** Real-pointer regression for the quota popover gap. Run after `bun run build`.
+ * Uses the actual React component and production CSS in isolated Chromium; no live API. */
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const gui = resolve(import.meta.dir, "..");
+const output = resolve(process.argv[2] ?? join(gui, ".tmp/quota-summary-hover-browser"));
+const chrome = process.env.CHROME_BIN || ["chromium", "chromium-browser", "google-chrome", "chrome"]
+  .map(name => Bun.which(name)).find(Boolean);
+if (!chrome) throw new Error("Set CHROME_BIN to Chrome/Chromium, then run bun run test:quota-hover.");
+const assets = join(gui, "dist/assets");
+const styles = await Promise.all((await readdir(assets)).filter(name => name.endsWith(".css"))
+  .map(name => readFile(join(assets, name), "utf8")));
+await mkdir(join(gui, ".tmp"), { recursive: true });
+await mkdir(output, { recursive: true });
+const fixture = await mkdtemp(join(gui, ".tmp/quota-hover-fixture-"));
+const profile = await mkdtemp(join(tmpdir(), "ocx-quota-hover-chrome-"));
+let browser: ReturnType<typeof Bun.spawn> | undefined;
+let socket: WebSocket | undefined;
+const delay = (ms: number) => new Promise<void>(done => setTimeout(done, ms));
+try {
+  const entry = join(fixture, "entry.tsx");
+  await writeFile(entry, `
+    import { createRoot } from "react-dom/client";
+    import { QuotaSummaryChips } from "../../src/components/quota-summary-bar/QuotaSummaryBar";
+    const t = key => ({ "quotaSummary.openAccounts": "Open account management", "quotaSummary.critical": "90%+ used" })[key] ?? key;
+    const rows = Array.from({ length: 8 }, (_, i) => ({
+      provider: "fixture-" + i, label: i ? "Provider " + i : "opencode go", severity: "critical",
+      headline: { id: "weekly", label: "Weekly limit", percent: 90, severity: "critical" },
+      windows: [{ id: "weekly", label: "Weekly limit", percent: 90, severity: "critical" }],
+    }));
+    createRoot(document.getElementById("root")).render(
+      <section className="quota-summary-bar"><QuotaSummaryChips rows={rows} t={t} locale="en" /></section>
+    );
+  `);
+  const build = await Bun.build({ entrypoints: [entry], target: "browser", minify: true });
+  if (!build.success) throw new AggregateError(build.logs, "Browser fixture failed to bundle");
+  const js = await build.outputs.find(file => file.path.endsWith(".js"))!.text();
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>${styles.join("\n")}</style>
+    <style>body{margin:0;padding-top:40px}${process.argv.includes("--without-bridge") ? ".quota-summary-popover::before{content:none}" : ""}</style></head>
+    <body><div id="root"></div><script type="module">${js.replaceAll("</script", "<\\/script")}</script></body></html>`;
+  browser = Bun.spawn([chrome, "--headless", "--disable-gpu", "--disable-background-networking",
+    "--no-first-run", "--no-default-browser-check", "--remote-debugging-address=127.0.0.1",
+    "--remote-debugging-port=0", `--user-data-dir=${profile}`,
+    ...(process.env.CHROME_NO_SANDBOX === "1" ? ["--no-sandbox"] : []), "about:blank"],
+  { stdout: "ignore", stderr: "ignore" });
+  let port = "";
+  const deadline = Date.now() + 10_000;
+  while (!port && Date.now() < deadline) {
+    try { port = (await readFile(join(profile, "DevToolsActivePort"), "utf8")).split("\n")[0]; }
+    catch { await delay(50); }
+  }
+  if (!/^\d+$/.test(port)) throw new Error("Chrome did not expose its debugging port");
+  const response = await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: "PUT" });
+  const target = await response.json() as { webSocketDebuggerUrl: string };
+  socket = new WebSocket(target.webSocketDebuggerUrl);
+  const ws = socket;
+  await new Promise<void>((done, fail) => {
+    ws.addEventListener("open", () => done(), { once: true });
+    ws.addEventListener("error", () => fail(new Error("CDP connection failed")), { once: true });
+  });
+  let id = 0;
+  const pending = new Map<number, { resolve: (value: unknown) => void; reject: (reason: Error) => void }>();
+  ws.addEventListener("message", event => {
+    const message = JSON.parse(String(event.data)) as { id?: number; result?: unknown; error?: unknown };
+    if (!message.id) return;
+    const request = pending.get(message.id);
+    pending.delete(message.id);
+    if (message.error) request?.reject(new Error(JSON.stringify(message.error)));
+    else request?.resolve(message.result);
+  });
+  const cdp = <T = unknown>(method: string, params: Record<string, unknown> = {}) => new Promise<T>((resolve, reject) => {
+    const next = ++id;
+    pending.set(next, { resolve: value => resolve(value as T), reject });
+    ws.send(JSON.stringify({ id: next, method, params }));
+  });
+  const evaluate = async <T>(expression: string): Promise<T> => {
+    const result = await cdp<{ result: { value: T }; exceptionDetails?: unknown }>("Runtime.evaluate", { expression, returnByValue: true });
+    if (result.exceptionDetails) throw new Error(JSON.stringify(result.exceptionDetails));
+    return result.result.value;
+  };
+  const move = async (x: number, y: number) => {
+    await cdp("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    // Let React commit before the next real hit test.
+    await delay(20);
+  };
+  const box = (selector: string) => evaluate<{ left: number; right: number; top: number; bottom: number }>(`(() => {
+    const r = document.querySelector(${JSON.stringify(selector)}).getBoundingClientRect();
+    return {left:r.left,right:r.right,top:r.top,bottom:r.bottom};
+  })()`);
+  const assertOpen = async (stage: string) => {
+    if (!await evaluate('!!document.querySelector(".quota-summary-popover")')) throw new Error(`Popover closed ${stage}`);
+  };
+  await cdp("Page.enable");
+  const { frameTree } = await cdp<{ frameTree: { frame: { id: string } } }>("Page.getFrameTree");
+  await cdp("Page.setDocumentContent", { frameId: frameTree.frame.id, html });
+  for (let attempt = 0; !await evaluate('!!document.querySelector(".quota-summary-chip")'); attempt++) {
+    if (attempt === 100) throw new Error("React fixture did not mount");
+    await delay(25);
+  }
+  const cases: unknown[] = [];
+  for (const theme of ["light", "dark"]) for (const width of [375, 760, 761, 1280]) for (const scale of [1, 1.25, 1.5]) {
+    await cdp("Emulation.setDeviceMetricsOverride", { width, height: 800, deviceScaleFactor: scale, mobile: false });
+    // A fractional layout origin exercises placement rounding as well as display scaling.
+    await evaluate(`document.documentElement.dataset.theme=${JSON.stringify(theme)}; document.body.style.paddingTop=${JSON.stringify(`${40 + scale % 1}px`)};`);
+    const chips = await evaluate<number>('document.querySelectorAll(".quota-summary-chip").length');
+    for (const index of [0, chips - 1]) {
+      await move(width / 2, 500);
+      const selector = `.quota-summary-item:nth-child(${index + 1}) .quota-summary-chip`;
+      await evaluate(`document.querySelector(${JSON.stringify(selector)}).scrollIntoView({block:"nearest",inline:"nearest"})`);
+      const chip = await box(selector);
+      const x = (chip.left + chip.right) / 2;
+      await move(x, (chip.top + chip.bottom) / 2);
+      await assertOpen(`on chip (${theme}/${width}/${scale}/${index})`);
+      const popover = await box(".quota-summary-popover");
+      for (let y = chip.bottom - 0.5; y <= popover.top + 1; y += 0.5) {
+        await move(x, y);
+        await assertOpen(`crossing gap (${theme}/${width}/${scale}/${index}, y=${y})`);
+      }
+      const foot = await box(".quota-summary-popover-foot");
+      await move((foot.left + foot.right) / 2, (foot.top + foot.bottom) / 2);
+      await assertOpen("at account-management link");
+      if (theme === "dark" && width === 1280 && scale === 1 && index === 0) {
+        const screenshot = await cdp<{ data: string }>("Page.captureScreenshot", { format: "png", clip: { x:0, y:35, width:500, height:180, scale:1 } });
+        await writeFile(join(output, "quota-hover-fixed.png"), Buffer.from(screenshot.data, "base64"));
+      }
+      await move(x, (chip.top + chip.bottom) / 2);
+      await assertOpen("returning to chip");
+      const link = await box(".quota-summary-popover-link");
+      await move((link.left + link.right) / 2, (link.top + link.bottom) / 2);
+      for (const type of ["mousePressed", "mouseReleased"]) {
+        await cdp("Input.dispatchMouseEvent", { type, x:(link.left + link.right) / 2, y:(link.top + link.bottom) / 2, button:"left", clickCount:1 });
+      }
+      await delay(20);
+      if (await evaluate('location.hash') !== `#providers?provider=fixture-${index}&tab=accounts`) throw new Error("Account link did not navigate");
+      if (await evaluate('!!document.querySelector(".quota-summary-popover")')) throw new Error("Navigation did not close the popover");
+      await move(x, (chip.top + chip.bottom) / 2);
+      // A resting pointer stays suppressed after navigation; leave and re-enter to reopen.
+      await move(width / 2, 500);
+      await move(x, (chip.top + chip.bottom) / 2);
+      await assertOpen("after re-entering chip");
+      await move(width / 2, 500);
+      if (await evaluate('!!document.querySelector(".quota-summary-popover")')) throw new Error("Popover stayed open outside item");
+      cases.push({ theme, width, scale, index, gap: popover.top - chip.bottom });
+    }
+  }
+  const key = async (key: string, code: number) => {
+    for (const type of ["keyDown", "keyUp"]) await cdp("Input.dispatchKeyEvent", { type, key, windowsVirtualKeyCode: code });
+    await delay(20);
+  };
+  await key("Tab", 9);
+  await evaluate('document.querySelector(".quota-summary-chip").focus()');
+  await delay(20);
+  await assertOpen("on keyboard-focused chip");
+  await key("Tab", 9);
+  if (!await evaluate('document.activeElement.matches(".quota-summary-popover-link")')) throw new Error("Tab did not reach account link");
+  await assertOpen("on keyboard-focused link");
+  await key("Escape", 27);
+  if (!await evaluate('document.activeElement.matches(".quota-summary-chip") && !document.querySelector(".quota-summary-popover")')) throw new Error("Escape did not restore chip focus and dismiss");
+  await key("Tab", 9);
+  await key("Tab", 9);
+  if (!await evaluate('document.activeElement.matches(".quota-summary-popover-link")')) throw new Error("Next chip's account link is unreachable");
+  await key("Enter", 13);
+  if (await evaluate('location.hash') !== "#providers?provider=fixture-1&tab=accounts") throw new Error("Keyboard account navigation failed");
+  await writeFile(join(output, "results.json"), JSON.stringify({ browser: await cdp("Browser.getVersion"), cases }, null, 2));
+  console.log(`PASS: ${cases.length} real-pointer cases, account navigation, gap traversal and dismissal; keyboard Tab/Enter/Escape.`);
+} finally {
+  socket?.close();
+  browser?.kill();
+  if (browser) await browser.exited;
+  await rm(profile, { recursive: true, force: true });
+  await rm(fixture, { recursive: true, force: true });
+}
diff --git a/structure/dashboard-and-usage.md b/structure/dashboard-and-usage.md
index 29ddb52d626..1eb1f306b8c 100644
--- a/structure/dashboard-and-usage.md
+++ b/structure/dashboard-and-usage.md
@@ -96,11 +96,11 @@ Deep links (`gui/src/protocol-deep-links.ts`) carry their target in the hash que
 and drops elsewhere. Each plan candidate links to `#providers?provider=<name>` (`gui/src/pages/providers-deep-link.ts` selects that provider and opens its Settings tab, and drops
 the query once another provider is chosen) and to `#models/compatibility?inbound=…&upstream=…`; a traced Logs row links to the compatibility pair it took. Each chip of the header quota strip
 (`gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx`, one scrolling row with « / » paging) links to `#providers?provider=<name>&tab=accounts`, which opens that provider's
-Accounts tab through `revealProviderAccounts` instead; following the same link again re-dispatches `hashchange` so it re-applies. Links push history, the matrix replaces
+Accounts tab through `revealProviderAccounts` instead; following the same link again re-dispatches `hashchange` so it re-applies. A transparent hit area above the fixed quota popover bridges its measured gap to the chip, keeping details open during pointer travel. The popover is a named group with an account-management link; focus stays open between its chip and link, and Escape restores focus to the chip. Links push history, the matrix replaces
 the entry when its filter is edited, and both targets re-read the hash on `hashchange`/`popstate`,
 so Back and Forward restore the prefilter. Tests live in `gui/tests/provider-protocol-panel.test.tsx`,
 `gui/tests/compatibility-protocol-filter.test.tsx`, `gui/tests/protocol-deep-links.test.ts`, `gui/tests/providers-deep-link.test.tsx`,
-`gui/tests/quota-summary-bar.test.tsx` and `gui/tests/combo-protocol-plan.test.tsx`.
+`gui/tests/quota-summary-bar.test.tsx` and `gui/tests/combo-protocol-plan.test.tsx`; `gui/tests/quota-summary-hover-browser.ts` checks real pointer travel across the quota popover gap with production CSS.
 
 The API workspace gives `gui/src/components/section-tabs.tsx` its mobile reading
 line so scroll-spy and the top-bar offset agree; other consumers keep their

From 4b40f1d38a6bfdee85fbf8fc95a1322790209581 Mon Sep 17 00:00:00 2001
From: Valerio Coltre <colthreepv@gmail.com>
Date: Thu, 1 Oct 2026 06:17:16 +0700
Subject: [PATCH 2/3] fix(gui): use the verified 7px quota popover spacing

---
 gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx | 2 +-
 gui/tests/quota-summary-bar.test.tsx                     | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
index eec82276599..0e59ccaa394 100644
--- a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
+++ b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
@@ -28,7 +28,7 @@ interface QuotaSummaryData {
 
 const POLL_MS = 60_000;
 /** Gap between the chip and its fixed-position popover, and the popover's viewport margin. */
-const POPOVER_GAP = 4;
+const POPOVER_GAP = 7;
 const VIEWPORT_MARGIN = 8;
 /** A « / » press pages the strip by this share of its visible width. */
 const PAGE_FRACTION = 0.8;
diff --git a/gui/tests/quota-summary-bar.test.tsx b/gui/tests/quota-summary-bar.test.tsx
index 5a9f1ece6f3..238d3169ce5 100644
--- a/gui/tests/quota-summary-bar.test.tsx
+++ b/gui/tests/quota-summary-bar.test.tsx
@@ -92,12 +92,12 @@ test("popover placement shares the rounded gap with its hover bridge and updates
     } as never) as unknown as Event);
   });
   const popover = view.container.querySelector<HTMLElement>(".quota-summary-popover")!;
-  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("32");
-  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("3.75");
+  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("35");
+  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("6.75");
   bottom = 28.75;
   await act(async () => { window.dispatchEvent(new testWindow.Event("scroll") as unknown as Event); });
-  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("33");
-  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("4.25");
+  expect(popover.style.getPropertyValue("--qs-pop-top")).toBe("36");
+  expect(popover.style.getPropertyValue("--qs-pop-gap")).toBe("7.25");
   await view.unmount();
 });
 

From 87eaf88150d60d604396a5deb7c32dbae4539f3d Mon Sep 17 00:00:00 2001
From: Valerio Coltre <colthreepv@gmail.com>
Date: Thu, 1 Oct 2026 06:34:32 +0700
Subject: [PATCH 3/3] fix(gui): describe quota chips by their popover and trim
 the hover check notes

---
 gui/README.md                                       | 13 +++----------
 .../quota-summary-bar/QuotaSummaryBar.tsx           |  1 +
 gui/tests/quota-summary-bar.test.tsx                |  1 +
 structure/dashboard-and-usage.md                    |  2 +-
 4 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/gui/README.md b/gui/README.md
index d15f4432feb..6029356e5e5 100644
--- a/gui/README.md
+++ b/gui/README.md
@@ -61,16 +61,9 @@ bun run build
 bun run test:quota-hover
 ```
 
-Rebuild after changing CSS: this opt-in check combines the current React quota component with
-the production CSS in `dist`. It uses an installed Chrome/Chromium (`CHROME_BIN` when not on PATH)
-and never connects to the proxy or provider accounts. Across 48 cases it moves a real pointer
-through the chip-to-popover gap, clicks the account-management link, returns to the chip, and
-checks dismissal outside. It also verifies keyboard Tab, Enter, and Escape. Cases cover light/dark themes, mobile and desktop widths, fractional
-placement, display scaling, and the last chip after horizontal scrolling. Results and a screenshot
-are written to `.tmp/quota-summary-hover-browser/`. This browser check is manual, not part of CI;
-happy-dom unit tests do not perform CSS hit-testing. To prove the guard detects the original gap,
-run `bun tests/quota-summary-hover-browser.ts .tmp/quota-hover-without-bridge --without-bridge`;
-that run must fail while crossing the gap.
+This opt-in check is not part of CI. It moves a real pointer from a quota chip into its popover in an
+installed Chrome/Chromium (`CHROME_BIN` when not on PATH), which happy-dom unit tests cannot hit-test.
+Rebuild after changing CSS: it uses the production CSS in `dist`.
 
 ## Sidebar version browser regression
 
diff --git a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
index 0e59ccaa394..b66ad55bbeb 100644
--- a/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
+++ b/gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx
@@ -193,6 +193,7 @@ function QuotaSummaryItem({ row, t, locale }: { row: QuotaSummaryRow; t: TFn; lo
         className={`quota-summary-chip${open ? " quota-summary-chip--open" : ""}`}
         aria-expanded={open}
         aria-controls={open ? popoverId : undefined}
+        aria-describedby={open ? popoverId : undefined}
         onPointerDown={event => { pointerTypeRef.current = event.pointerType; }}
         onClick={onClick}
       >
diff --git a/gui/tests/quota-summary-bar.test.tsx b/gui/tests/quota-summary-bar.test.tsx
index 238d3169ce5..dc4413167a7 100644
--- a/gui/tests/quota-summary-bar.test.tsx
+++ b/gui/tests/quota-summary-bar.test.tsx
@@ -266,6 +266,7 @@ test("a clicked chip keeps its detail closed under the resting pointer until the
   await pointer("pointerover", document.body);
   expect(tooltip()?.textContent).toContain("xAI Grok");
   expect(view.chip("xAI Grok").getAttribute("aria-controls")).toBe(tooltip()?.id ?? "missing");
+  expect(view.chip("xAI Grok").getAttribute("aria-describedby")).toBe(tooltip()?.id ?? "missing");
 
   await click(view.chip("xAI Grok"));
   expect(tooltip()).toBeNull();
diff --git a/structure/dashboard-and-usage.md b/structure/dashboard-and-usage.md
index 1eb1f306b8c..17d29c6d794 100644
--- a/structure/dashboard-and-usage.md
+++ b/structure/dashboard-and-usage.md
@@ -96,7 +96,7 @@ Deep links (`gui/src/protocol-deep-links.ts`) carry their target in the hash que
 and drops elsewhere. Each plan candidate links to `#providers?provider=<name>` (`gui/src/pages/providers-deep-link.ts` selects that provider and opens its Settings tab, and drops
 the query once another provider is chosen) and to `#models/compatibility?inbound=…&upstream=…`; a traced Logs row links to the compatibility pair it took. Each chip of the header quota strip
 (`gui/src/components/quota-summary-bar/QuotaSummaryBar.tsx`, one scrolling row with « / » paging) links to `#providers?provider=<name>&tab=accounts`, which opens that provider's
-Accounts tab through `revealProviderAccounts` instead; following the same link again re-dispatches `hashchange` so it re-applies. A transparent hit area above the fixed quota popover bridges its measured gap to the chip, keeping details open during pointer travel. The popover is a named group with an account-management link; focus stays open between its chip and link, and Escape restores focus to the chip. Links push history, the matrix replaces
+Accounts tab through `revealProviderAccounts` instead; following the same link again re-dispatches `hashchange` so it re-applies. A transparent hit area above the fixed quota popover bridges its measured gap to the chip, keeping details open during pointer travel. The popover is a named group that also describes its chip, with an account-management link; focus stays open between its chip and link, and Escape restores focus to the chip. Links push history, the matrix replaces
 the entry when its filter is edited, and both targets re-read the hash on `hashchange`/`popstate`,
 so Back and Forward restore the prefilter. Tests live in `gui/tests/provider-protocol-panel.test.tsx`,
 `gui/tests/compatibility-protocol-filter.test.tsx`, `gui/tests/protocol-deep-links.test.ts`, `gui/tests/providers-deep-link.test.tsx`,