Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(usage): reserve dock space and keep refresh reachable

review17e6bb4d565c
diff --git a/CLAUDE.md b/CLAUDE.md
index f108819c7..5f1e6ea85 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2947,6 +2947,13 @@ else, and its context links must keep classifying across restarts).
tooltip pointing at Settings → Accounts, where **Detected config dirs** lists it for one-click
linking. Mobile: N/A (additive mirror fields).
+- **Bottom chrome shares a measured width budget** (issue #853). `CanvasPills` observes the canvas
+ wrapper and actual dock, bounds the left row with an 8px gap, and uses a row above the dock when
+ fewer than 200 CSS pixels remain. Rects are converted back through UI scale. Usage summary text
+ ellipsizes; refresh never shrinks. Do not clip the whole row or give it a stacking context:
+ usage/RAM popovers must escape independently above the sidebar and board. Desktop and Server
+ share this renderer. The real-browser regression is `scripts/usage-layout.test.ts` (`CHROME_BIN`).
+
- **The usage indicator is scoped to the ACTIVE project** (`renderer/lib/usageScope.ts`, pure +
unit-tested) — it describes **the machine that project runs on**, and nothing else. A local
project shows this machine (system + managed local accounts + the billing providers, whose
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..642594541 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -107,6 +107,12 @@ lane unaffected.
PR; copy that really is macOS-specific (the ptmx-limit banner, the notch step) is exempt by name
with its reason. Comments are not scanned.
+- **Bottom canvas pills must leave room for the measured dock.** `CanvasPills` bounds their row
+ and moves it above the dock when the side budget is too small. Only usage summary text may
+ truncate; keep refresh outside that overflow and keep the row free of stacking contexts so
+ popovers can still clear the sidebar/board. `scripts/usage-layout.test.ts` verifies real Chrome
+ layout and hit targets (set `CHROME_BIN` when Chrome is not at the Linux default path).
+
- **An overlay you lay over a live terminal steals its wheel — give it `pointer-events: none`.**
Wheel routing is a per-packet hit test on `closest('.nowheel')` (ours in `Canvas.tsx`, and React
Flow's own `panOnScroll` independently), so the element under the pointer decides, not the node.
diff --git a/scripts/usage-layout.test.ts b/scripts/usage-layout.test.ts
new file mode 100644
index 000000000..ea92841dd
--- /dev/null
+++ b/scripts/usage-layout.test.ts
@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import WebSocket from 'ws'
+import { build } from 'esbuild'
+import { expect, it } from 'vitest'
+
+// Real layout + hit testing, not jsdom's zero rectangles. CI/device runs can supply CHROME_BIN.
+const chrome = process.env.CHROME_BIN ?? '/usr/bin/google-chrome'
+it.skipIf(!existsSync(chrome))('keeps refresh clickable beside/above the real dock at laptop and phone widths', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'usage-layout-'))
+ try {
+ const bundle = await build({
+ entryPoints: ['test/fixtures/usage-layout.tsx'], bundle: true, write: false,
+ loader: { '.svg': 'dataurl' }, tsconfig: 'tsconfig.web.json', define: { 'process.env.NODE_ENV': '"production"' }
+ })
+ const css = readFileSync('src/renderer/styles.css', 'utf8')
+ writeFileSync(join(dir, 'index.html'), `<style>${css}</style><div id="root"></div><pre id="result">WAIT</pre><script>${bundle.outputFiles[0].text}</script>`)
+ const browser = spawn(chrome, [
+ '--headless', '--no-sandbox', '--disable-gpu', `--user-data-dir=${join(dir, 'profile')}`,
+ '--window-size=1800,1100', '--remote-debugging-port=0', 'about:blank'
+ ])
+ try {
+ const endpoint = await new Promise<string>((resolve, reject) => {
+ let output = ''
+ browser.stderr.on('data', chunk => {
+ output += chunk
+ const match = output.match(/DevTools listening on (ws:\/\/[^\s]+)/)
+ if (match) resolve(match[1])
+ })
+ browser.on('error', reject)
+ browser.on('exit', code => reject(new Error(`Chrome exited: ${code}`)))
+ })
+ const ws = new WebSocket(endpoint)
+ await new Promise(resolve => ws.once('open', resolve))
+ let id = 0
+ const call = (method: string, params = {}, sessionId?: string): Promise<any> => {
+ const next = ++id
+ return new Promise((resolve, reject) => {
+ const onMessage = (raw: WebSocket.RawData): void => {
+ const message = JSON.parse(raw.toString())
+ if (message.id !== next) return
+ ws.off('message', onMessage)
+ if (message.error) reject(new Error(JSON.stringify(message.error)))
+ else resolve(message.result)
+ }
+ ws.on('message', onMessage)
+ ws.send(JSON.stringify({ id: next, method, params, sessionId }))
+ })
+ }
+ try {
+ const { targetId } = await call('Target.createTarget', { url: 'about:blank' })
+ const { sessionId } = await call('Target.attachToTarget', { targetId, flatten: true })
+ await call('Page.enable', {}, sessionId)
+ const loaded = new Promise<void>(resolve => {
+ const listener = (raw: WebSocket.RawData): void => {
+ const msg = JSON.parse(raw.toString())
+ if (msg.sessionId === sessionId && msg.method === 'Page.loadEventFired') {
+ ws.off('message', listener)
+ resolve()
+ }
+ }
+ ws.on('message', listener)
+ })
+ await call('Page.navigate', { url: `file://${resolve(dir, 'index.html')}` }, sessionId)
+ await loaded
+ const value = await call('Runtime.evaluate', {
+ expression: `new Promise(resolve => { const timer = setInterval(() => {
+ const text = document.getElementById('result')?.textContent;
+ if (text && text !== 'WAIT') { clearInterval(timer); resolve(text); }
+ }, 50); setTimeout(() => { clearInterval(timer); resolve('TIMEOUT'); }, 15000); })`,
+ awaitPromise: true, returnByValue: true
+ }, sessionId)
+ const result = value.result.value
+ expect(result).toMatch(/^PASS /)
+ console.log(result)
+ } finally { ws.close() }
+ } finally {
+ browser.kill()
+ await new Promise(resolve => browser.once('exit', resolve))
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+}, 40000)
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 9cbed6b7a..27eb88934 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -241,6 +241,7 @@ import {
noteTerminalCapture,
terminalShortcutPolicy
} from '../lib/keybindingOverrides'
+import { CanvasPills } from '../components/CanvasPills'
import { UsageIndicator } from '../components/UsageIndicator'
import { SystemResourcePill } from '../components/SystemResourcePill'
import { PresenceLayer } from '../components/PresenceLayer'
@@ -14603,7 +14604,7 @@ export function Canvas() {
`data-canvas-chrome` is fit-view's own documented opt-in: it makes the whole cluster ONE
obstacle rect (instead of one per pill, overlapping after inflation), so fitView never
parks a node underneath either pill. */}
- <div className="canvas-pills" data-canvas-chrome>
+ <CanvasPills>
{/* `travelToNode`, not `focusNodeById`: the panel resolves sessions in CLOSED projects
too (their tmux sessions keep running), and reaching one means reopening its tab
first — the same path a notification click and a peer jump take. */}
@@ -14618,7 +14619,7 @@ export function Canvas() {
{/* Same write path as the TabBar caret menu (project.defaultAccountId + persist) — the
popover row is a second, better-placed entrance to the same action (issue #142). */}
<UsageIndicator overBoard={kanbanOpen} onSetDefaultAccount={setProjectDefaultAccount} />
-</div>
+ </CanvasPills>
{/* Canvas-mounted, deliberately NOT in the .top-banners column: this is about THIS canvas,
not an app-wide message. Opening a row records a new breadcrumb through goToNode — which
diff --git a/src/renderer/components/CanvasPills.tsx b/src/renderer/components/CanvasPills.tsx
new file mode 100644
index 000000000..9e7ee050d
--- /dev/null
+++ b/src/renderer/components/CanvasPills.tsx
@@ -0,0 +1,37 @@
+import { useLayoutEffect, useRef, type ReactNode } from 'react'
+
+/** Keep the ambient pills outside the dock's measured footprint, without creating a stacking
+ * context (their popovers still need to rise above the sidebar/board independently). */
+export function CanvasPills({ children }: { children: ReactNode }): JSX.Element {
+ const ref = useRef<HTMLDivElement>(null)
+ useLayoutEffect(() => {
+ const row = ref.current!
+ const wrap = row.parentElement!
+ const dock = wrap.closest('.canvas-root')?.querySelector<HTMLElement>('.dock')
+ if (!dock) return
+ const measure = (): void => {
+ const bounds = wrap.getBoundingClientRect()
+ if (!wrap.offsetWidth || !bounds.width) return
+ // DOMRects include UI zoom; CSS lengths do not.
+ const scale = bounds.width / wrap.offsetWidth
+ const left = (row.getBoundingClientRect().left - bounds.left) / scale
+ const dockBounds = dock.getBoundingClientRect()
+ const gap = 8
+ const edge = parseFloat(getComputedStyle(row).getPropertyValue('--float-gap')) || 22
+ const beside = (dockBounds.left - bounds.left) / scale - left - gap
+ // Below this budget, even a short usage summary becomes hard to read. Use a second row
+ // above the dock, still bounded by the canvas, instead of covering either control.
+ const above = beside < 200
+ row.style.maxWidth = `${Math.max(0, above ? wrap.offsetWidth - left - edge : beside)}px`
+ row.style.bottom = above
+ ? `${Math.max(0, (bounds.bottom - dockBounds.top) / scale) + gap}px`
+ : ''
+ }
+ measure()
+ const observer = new ResizeObserver(measure)
+ observer.observe(wrap)
+ observer.observe(dock)
+ return () => observer.disconnect()
+ }, [])
+ return <div ref={ref} className="canvas-pills" data-canvas-chrome>{children}</div>
+}
diff --git a/src/renderer/components/UsageIndicator.tsx b/src/renderer/components/UsageIndicator.tsx
index 7599233e9..0cc00592e 100644
--- a/src/renderer/components/UsageIndicator.tsx
+++ b/src/renderer/components/UsageIndicator.tsx
@@ -604,7 +604,7 @@ export function UsageIndicator({
title={scope.kind === 'ssh' ? `Agent usage on ${scope.hostKey}` : 'Agent usage'}
>
<span className="usage-pill__icon">✦</span>
- {pillBody}
+ <span className="usage-pill__summary">{pillBody}</span>
</button>
<button
className={`usage-refresh${fetching ? ' spin' : ''}`}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index caec75eb2..73593f770 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -6904,6 +6904,7 @@ button.group-node__setup:disabled {
The left offset clears the controls column, which shares this corner: --controls-w plus the 12px
the other chrome already uses between two adjacent clusters (see .resume-card). */
.canvas-pills {
+ width: max-content;
position: absolute;
left: calc(var(--float-gap) + var(--controls-w) + 12px);
bottom: var(--float-gap);
@@ -7017,6 +7018,19 @@ button.group-node__setup:disabled {
align-items: center;
gap: 4px;
}
+/* Only summary text may overflow: refresh and the usage opener remain reachable. Never clip
+ the indicator/row itself, since the popover must escape it. */
+.canvas-pills > .sysres-indicator { flex: 0 0 auto; }
+.usage-indicator { min-width: 0; }
+.usage-pill { min-width: 0; }
+.usage-pill__icon, .usage-refresh { flex: 0 0 auto; }
+.usage-pill__summary {
+ min-width: 0;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.usage-pill__summary > span + span { margin-left: 6px; }
/* While the popover is open, rise above the sessions sidebar (z-index 12) — a tall sidebar
reaches the bottom-left corner and would cover the panel. Closed pill keeps its low layer so
it never draws over the sidebar itself.
diff --git a/test/fixtures/usage-layout.tsx b/test/fixtures/usage-layout.tsx
new file mode 100644
index 000000000..b795fc1d7
--- /dev/null
+++ b/test/fixtures/usage-layout.tsx
@@ -0,0 +1,63 @@
+import { createRoot } from 'react-dom/client'
+import { CanvasPills } from '../../src/renderer/components/CanvasPills'
+import { UsageIndicator } from '../../src/renderer/components/UsageIndicator'
+import type { ClaudeUsage, UsageLimit } from '../../src/shared/types'
+import { useSettings } from '../../src/renderer/state/settings'
+import { Dock } from '../../src/renderer/components/Dock'
+
+const limit = (kind: string, usedPercent: number, scopeLabel: string | null = null): UsageLimit => ({ kind, usedPercent, scopeLabel, severity: 'warning', resetsAt: null, group: null, windowMinutes: null, isActive: false })
+const usage: ClaudeUsage = { session: null, weekly: null, email: null, status: 'ok', limits: [limit('session', 96), limit('weekly_all', 52), limit('weekly_scoped', 82, 'Fable')], updatedAt: Date.now() }
+useSettings.setState(s => ({ settings: { ...s.settings, usagePercentMode: 'used' } }))
+let refreshes = 0
+window.nodeTerminal = { usage: {
+ fetch: async () => usage,
+ refresh: async () => { refreshes++; return usage },
+ onUpdate: () => () => {},
+ providers: async () => ['codex', 'grok'].map(provider => ({ provider, status: 'ok', account: null, updatedAt: Date.now(), limits: [limit('session', provider === 'codex' ? 42 : 84)] }))
+} }
+createRoot(document.getElementById('root')!).render(
+ <div className="canvas-root" style={{ width: 1470, height: 862 }}>
+ <div className="flow-wrap">
+ <CanvasPills>
+ <div className="sysres-indicator"><button className="sysres-pill">M</button></div>
+ <UsageIndicator />
+ </CanvasPills>
+ </div>
+ <Dock zoomPct={100} />
+ </div>
+)
+const pause = () => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(resolve, 80))))
+async function check() {
+ await pause()
+ const root = document.querySelector<HTMLElement>('.canvas-root')!
+ const dock = document.querySelector<HTMLElement>('.dock')!
+ const results = []
+ for (const [width, zoom, expanded] of [[1470, 1, false], [1280, 1, true], [900, 1, false], [390, 1, false], [1470, 1.5, false], [1470, 0.8, false], [1470, 1, false]] as const) {
+ root.style.width = `${width / zoom}px`
+ root.style.height = `${862 / zoom}px`
+ root.style.zoom = `${zoom}`
+ document.querySelector<HTMLElement>('.sysres-pill')!.style.width = expanded ? '180px' : '26px'
+ // Dock growth (e.g. zoom readout / font changes) must also remeasure without window resize.
+ dock.style.paddingRight = expanded ? '70px' : ''
+ await pause()
+ const refresh = document.querySelector<HTMLButtonElement>('.usage-refresh')!
+ const r = refresh.getBoundingClientRect()
+ const d = dock.getBoundingClientRect()
+ const hit = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2)
+ if (!refresh.contains(hit)) throw Error(`refresh covered at ${width}/${zoom}/${expanded}: ${hit?.className} row=${document.querySelector(".canvas-pills")?.getAttribute("style")} refresh=${JSON.stringify(r)} dock=${JSON.stringify(d)}`)
+ if (r.right > width + 1 || r.width < 23 * zoom) throw Error('refresh clipped/shrunk')
+ if (!(r.right <= d.left - 7 * zoom || r.bottom <= d.top - 7 * zoom)) throw Error('dock overlap')
+ hit!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+ await pause()
+ const pill = document.querySelector<HTMLButtonElement>('.usage-pill')!
+ pill.focus()
+ await pause()
+ if (!document.querySelector('.usage-popover')?.textContent?.includes('Grok')) throw Error('full provider details inaccessible')
+ pill.click()
+ pill.blur()
+ results.push({ width, zoom, expanded, right: r.right, dockLeft: d.left, above: r.bottom < d.top })
+ }
+ if (refreshes !== results.length) throw Error(`refresh calls: ${refreshes}`)
+ document.getElementById('result')!.textContent = `PASS ${JSON.stringify(results)}`
+}
+check().catch(error => { document.getElementById('result')!.textContent = `FAIL ${error.stack}` })