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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(window): signal the renderer when the main window is hidden or shown
reviewb50292bcd7aa
diff --git a/src/main/index.ts b/src/main/index.tsindex b23ed71b1..cc0e4b420 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -185,6 +185,7 @@ import {import { answerHeldPermission, isStructuredTicket, type HeldPermissionIo } from '../core/agents/permission-decision'import type { AnswerPermissionPayload } from '../shared/agents/permission-answer'import { setMainWindow, getMainWindow, sendToMain, closeAction, createCrashReloadPolicy } from './main-window'+import { WINDOW_VISIBILITY_EVENTS, windowVisibilitySignal } from './window-visibility'import {MENU_ITEM_ID_CLOSE,MENU_ITEM_ID_KANBAN,@@ -1364,6 +1365,15 @@ function createWindow(): BrowserWindow {// The main window is a regular app window; establishing its Dock presence explicitly means the// later focusable:false Notch HUD panel can never leave the app looking like an accessory.win.on('show', () => assertRegularDockPresence())+ // Tell the renderer when the window is put away / brought back, so a tray-hidden (Windows+ // default), hide-on-close (macOS) or minimized window lets its terminals count as offscreen and+ // the existing reclaim levers give memory back (renderer/terminal/window-backgrounded.ts). Every+ // platform; the mapping is the pure main/window-visibility.ts.+ for (const ev of WINDOW_VISIBILITY_EVENTS) {+ win.on(ev as 'hide', () => {+ if (!win.isDestroyed()) win.webContents.send(IPC.appWindowVisibility, windowVisibilitySignal(ev))+ })+ }// Windows: the taskbar flash raised by an unread rise (appSetBadge) ends when the user comes back.if (process.platform === 'win32') win.on('focus', () => win.flashFrame(false))diff --git a/src/main/window-visibility.test.ts b/src/main/window-visibility.test.tsnew file mode 100644index 000000000..24d35ac1e--- /dev/null+++ b/src/main/window-visibility.test.ts@@ -0,0 +1,15 @@+import { describe, expect, it } from 'vitest'+import { WINDOW_VISIBILITY_EVENTS, windowVisibilitySignal } from './window-visibility'++describe('windowVisibilitySignal', () => {+ it('maps hide and minimize to hidden, show and restore to shown', () => {+ expect(windowVisibilitySignal('hide')).toBe('hidden')+ expect(windowVisibilitySignal('minimize')).toBe('hidden')+ expect(windowVisibilitySignal('show')).toBe('shown')+ expect(windowVisibilitySignal('restore')).toBe('shown')+ })++ it('covers exactly the four window events the shell subscribes to', () => {+ expect([...WINDOW_VISIBILITY_EVENTS].sort()).toEqual(['hide', 'minimize', 'restore', 'show'])+ })+})diff --git a/src/main/window-visibility.ts b/src/main/window-visibility.tsnew file mode 100644index 000000000..e6f524ed6--- /dev/null+++ b/src/main/window-visibility.ts@@ -0,0 +1,28 @@+// Main-window visibility → the renderer's "backgrounded" signal (renderer/terminal/+// window-backgrounded.ts). Pure + Electron-free so the mapping is pressable on any CI box.+//+// Why an explicit signal and not `document.visibilityState`: Chromium's occlusion tracking also+// flips that to `hidden` for a window that is merely COVERED by another app, and a covered window+// must keep its terminals warm — the user is one ⌘Tab away. Only a window the user actually put+// away (close-to-tray / macOS hide-on-close / minimize) is backgrounded.++/** The BrowserWindow events that change whether the user can see the window at all. */+export type WindowVisibilityEvent = 'hide' | 'show' | 'minimize' | 'restore'++export type WindowVisibilitySignal = 'hidden' | 'shown'++export const WINDOW_VISIBILITY_EVENTS: readonly WindowVisibilityEvent[] = [+ 'hide',+ 'show',+ 'minimize',+ 'restore'+]++/**+ * Map one window event to the signal the renderer gets. `restore` can also arrive for a window+ * that was never minimized (some Linux window managers emit it on un-maximize); that maps to+ * `'shown'`, which the renderer treats idempotently — "shown" while shown changes nothing.+ */+export function windowVisibilitySignal(event: WindowVisibilityEvent): WindowVisibilitySignal {+ return event === 'hide' || event === 'minimize' ? 'hidden' : 'shown'+}diff --git a/src/preload/index.ts b/src/preload/index.tsindex 04964624e..29c8af081 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -862,6 +862,11 @@ const api: NodeTerminalApi = {ipcRenderer.on(IPC.appMemoryPressure, handler)return () => ipcRenderer.removeListener(IPC.appMemoryPressure, handler)},+ onWindowVisibility: (listener) => {+ const handler = (_e: unknown, state: 'hidden' | 'shown') => listener(state)+ ipcRenderer.on(IPC.appWindowVisibility, handler)+ return () => ipcRenderer.removeListener(IPC.appWindowVisibility, handler)+ },onPtyPressure: (listener) => {const handler = (_e: unknown, reading: PtyPressure) => listener(reading)ipcRenderer.on(IPC.ptyPressure, handler)diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.tsindex b450be182..199aca748 100644--- a/src/renderer/bridge/stubs.ts+++ b/src/renderer/bridge/stubs.ts@@ -608,6 +608,12 @@ export function buildStubApi(): Omit<// on its own terms; pushing our levers over the wire would fight it, not help it. Deliberate// no-op, not an oversight.onMemoryPressure: noopUnsub,+ // Deliberate no-op, not an oversight. The desktop signal means "the user put the app away"+ // (tray / hide / minimize). The browser's nearest analogue, `visibilitychange`, fires on every+ // tab switch AND on occlusion — wiring it here would release every terminal of a user who+ // glanced at another tab for two minutes. The browser throttles and discards a hidden tab on+ // its own terms; the viewport-driven levers keep working unchanged.+ onWindowVisibility: noopUnsub,// Same asymmetry, one step further: the desktop's pty-pressure banner exists to offer "Fix// automatically…", which ends in macOS's admin-password dialog on the HOST's physical display.// A browser tab cannot answer that prompt, so the host keeps the reaper leg and says nothingdiff --git a/src/shared/ipc.ts b/src/shared/ipc.tsindex 60d0b0d4c..2e463b610 100644--- a/src/shared/ipc.ts+++ b/src/shared/ipc.ts@@ -164,6 +164,12 @@ export const IPC = {* so the renderer should run its reclaim levers now (hidden WebGL contexts, parked terminals).* Payload: `'warning' | 'critical'`. Re-fired at most once a minute — see core/memory-pressure. */appMemoryPressure: 'app:memory-pressure',+ /** Main → renderer: the main window was put away (`'hidden'` — close-to-tray, macOS+ * hide-on-close, minimize) or brought back (`'shown'`). The renderer then treats every terminal+ * as offscreen so the existing reclaim levers run on their timers (see+ * renderer/terminal/window-backgrounded.ts). Explicit, not `visibilitychange`: an occluded window+ * must not release. Mapping: main/window-visibility.ts. */+ appWindowVisibility: 'app:window-visibility',/** Main → renderer: a macOS trackpad gesture (two-finger scroll or pinch) opened or closed on* the main window — edge transitions from main/trackpad-gesture.ts, a handful per physical* gesture. Payload: `boolean` (active). The canvas wheel router uses this as ground-truthdiff --git a/src/shared/types.ts b/src/shared/types.tsindex 771ee3cd3..bc5888030 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -4392,6 +4392,12 @@ export interface NodeTerminalApi {* need only be idempotent, not cheap. Returns unsubscribe. Server Edition: never fires (the* pressure levers run host-side there; a browser tab's memory belongs to the browser). */onMemoryPressure(listener: (severity: 'warning' | 'critical') => void): () => void+ /** Fires when the main window is put away (`'hidden'`: close-to-tray, macOS hide-on-close,+ * minimize) or brought back (`'shown'`). The renderer answers by treating every terminal as+ * offscreen while hidden (renderer/terminal/window-backgrounded.ts). Returns unsubscribe.+ * Server Edition: never fires — a browser tab being hidden is a routine tab switch, not the app+ * being put away, so the levers stay on their viewport-only behaviour there. */+ onWindowVisibility(listener: (state: 'hidden' | 'shown') => void): () => void/** Fires when THIS MACHINE's pty-device pressure band changes (core/pty-pressure.ts): the* renderer raises/lowers the banner that warns before `kern.tty.ptmx_max` stops every new* terminal from opening. Band changes only, re-sent for a held band at most once every five