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.

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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 nothing
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index 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-truth
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 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