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(browser): page zoom for web and browser nodes

Fabricio Casalid73aa27a4166
diff --git a/CLAUDE.md b/CLAUDE.md
index 6dbd15e6d..604ff8880 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1246,6 +1246,18 @@ session.
- **browser** (`BrowserNode.tsx`) — a navigable Chromium browser wrapping the shared
`BrowserSurface` (webview + toolbar); the last top-level URL persists to `data.url`, and the same
surface backs the kanban card modal's browser popup.
+ **Page zoom is owned by the GUEST boundary, not the canvas DOM** (`@shared/webview-zoom` +
+ `main/webview-zoom.ts`, 2026-09-20). Measured on Electron 42.10.1 with a physical wheel injection:
+ Ctrl+wheel over the page arrived in its OOPIF with `ctrl=true`, the host received NO `wheel`
+ event, and Electron left the factor at 1 until the guest `WebContents`'s `zoom-changed` handler
+ called `setZoomLevel` (one level produced 1.2). So `.browser-node__view` / the web node body KEEP
+ `nowheel` — it prevents React Flow from taking a wheel packet over the page, and removing it
+ cannot make an OOPIF event bubble. Main's one `web-contents-created` listener installs wheel and
+ Cmd/Ctrl +/-/0 zoom only for `getType() === 'webview'`; the shared `WebviewZoomControls` calls the
+ same 50%–300% policy for `WebNode` and `BrowserSurface`, which also covers the card modal. The app
+ does NOT persist zoom in `project.json`: Electron propagates a zoom level by origin, so a per-node
+ persisted value would make two nodes for one origin fight. Desktop: full; Server Edition:
+ controls hidden (no Electron guest); Mobile: N/A (no canvas).
- **files** (`FilesNode.tsx`) — a file-manager node: ONE directory listing (`data.cwd`, persisted),
pinned to the canvas beside the terminals working in it. Deliberately not a second Explorer: the
drawer is a single tree rooted at the project cwd that covers the canvas, so it gives you one
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..29860f7f4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -298,6 +298,13 @@ lane unaffected.
unmounting. `display:none` is safe (measured: state, scroll and viewport size survive); a reorder
or unmount reloads the user's page and loses their in-page state.
+- **A `<webview>` page's wheel never reaches the host DOM.** The guest is an out-of-process frame:
+ measured on Electron 42, physical Ctrl/Cmd+wheel reached the page and emitted `zoom-changed` on
+ the guest `WebContents`, while no host `wheel` listener fired. Keep `nowheel` on the webview host
+ (it protects React Flow routing) and install page zoom in main through `installWebviewZoom`;
+ removing the class or adding a renderer wheel handler cannot implement guest zoom. The shared
+ renderer controls call the same `@shared/webview-zoom` policy directly on the attached guest.
+
These are the ones that come up in review most often. Each exists because its absence caused a real
bug.
diff --git a/src/main/index.ts b/src/main/index.ts
index 5d8a5bc1f..075ddb3a1 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -18,6 +18,7 @@ installLogSink(logBuffer)
import { writeFilesToClipboard } from './clipboard-files'
import { pickProjectIcon } from './project-icon-upload'
import { allowGuestNavigation } from './webview-nav'
+import { installWebviewZoom } from './webview-zoom'
import { hostOsFromPlatform, sshServerCopy } from '../shared/ssh-server'
import { macTitleBarOptions, trafficLightPositionFor } from './window-chrome'
import { resolveTabBarHeight } from '@shared/window-chrome-metrics'
@@ -1258,6 +1259,7 @@ app.whenReady().then(async () => {
/* logging must never break a page */
}
})
+ installWebviewZoom(contents, process.platform === 'darwin')
if (contents.getType() !== 'webview') return
// Web nodes may only show http(s) pages, jailed nt-media:// content, or origin-gated
// local file:// pages (policy + tests in webview-nav.ts).
diff --git a/src/main/webview-zoom.test.ts b/src/main/webview-zoom.test.ts
new file mode 100644
index 000000000..fa8b99bf9
--- /dev/null
+++ b/src/main/webview-zoom.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { WebContents } from 'electron'
+import { installWebviewZoom } from './webview-zoom'
+
+type Handler = (event: { preventDefault(): void }, value: never) => void
+
+function fakeContents(type = 'webview') {
+ const handlers = new Map<string, Handler>()
+ let level = 0
+ const contents = {
+ getType: () => type,
+ getZoomLevel: () => level,
+ setZoomLevel: vi.fn((next: number) => {
+ level = next
+ }),
+ on: vi.fn((event: string, handler: Handler) => {
+ handlers.set(event, handler)
+ })
+ }
+ return { contents, handlers }
+}
+
+describe('installWebviewZoom', () => {
+ it('ignores non-webview contents', () => {
+ const { contents } = fakeContents('window')
+ expect(installWebviewZoom(contents as unknown as WebContents, false)).toBe(false)
+ expect(contents.on).not.toHaveBeenCalled()
+ })
+
+ it('applies a wheel zoom request from the guest', () => {
+ const { contents, handlers } = fakeContents()
+ installWebviewZoom(contents as unknown as WebContents, false)
+ const preventDefault = vi.fn()
+ handlers.get('zoom-changed')?.({ preventDefault }, 'in' as never)
+ expect(preventDefault).toHaveBeenCalledOnce()
+ expect(contents.setZoomLevel).toHaveBeenCalledWith(1)
+ })
+
+ it('claims browser zoom shortcuts and leaves ordinary guest input alone', () => {
+ const { contents, handlers } = fakeContents()
+ installWebviewZoom(contents as unknown as WebContents, false)
+ const shortcutEvent = { preventDefault: vi.fn() }
+ handlers.get('before-input-event')?.(
+ shortcutEvent,
+ { type: 'keyDown', code: 'Minus', control: true, meta: false, shift: false, alt: false } as never
+ )
+ expect(shortcutEvent.preventDefault).toHaveBeenCalledOnce()
+ expect(contents.setZoomLevel).toHaveBeenCalledWith(-1)
+
+ const ordinaryEvent = { preventDefault: vi.fn() }
+ handlers.get('before-input-event')?.(
+ ordinaryEvent,
+ { type: 'keyDown', code: 'KeyA', control: false, meta: false, shift: false, alt: false } as never
+ )
+ expect(ordinaryEvent.preventDefault).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/main/webview-zoom.ts b/src/main/webview-zoom.ts
new file mode 100644
index 000000000..5193839db
--- /dev/null
+++ b/src/main/webview-zoom.ts
@@ -0,0 +1,21 @@
+import type { WebContents } from 'electron'
+import { applyWebviewZoom, webviewZoomShortcut } from '../shared/webview-zoom'
+
+/** Installs browser-like page zoom only on Electron webview guests. */
+export function installWebviewZoom(contents: WebContents, isMac: boolean): boolean {
+ if (contents.getType() !== 'webview') return false
+
+ contents.on('zoom-changed', (event, direction) => {
+ event.preventDefault()
+ applyWebviewZoom(contents, direction)
+ })
+
+ contents.on('before-input-event', (event, input) => {
+ const action = webviewZoomShortcut(input, isMac)
+ if (!action) return
+ event.preventDefault()
+ applyWebviewZoom(contents, action)
+ })
+
+ return true
+}
diff --git a/src/renderer/components/WebviewZoomControls.test.tsx b/src/renderer/components/WebviewZoomControls.test.tsx
new file mode 100644
index 000000000..76bac4f34
--- /dev/null
+++ b/src/renderer/components/WebviewZoomControls.test.tsx
@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { act, createRef } from 'react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { ZoomableWebview } from '@shared/webview-zoom'
+
+const runtime = vi.hoisted(() => ({ browser: false }))
+vi.mock('../bridge/runtime', () => ({ isBrowserRuntime: () => runtime.browser }))
+
+import { WebviewZoomControls } from './WebviewZoomControls'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+afterEach(() => {
+ document.body.innerHTML = ''
+ runtime.browser = false
+})
+
+describe('WebviewZoomControls', () => {
+ it('applies zoom out, reset, and zoom in to the mounted guest', () => {
+ let level = 1
+ const target: { current: ZoomableWebview | null } = {
+ current: {
+ getZoomLevel: () => level,
+ setZoomLevel: (next: number) => {
+ level = next
+ }
+ }
+ }
+ const host = document.createElement('div')
+ document.body.append(host)
+ const root = createRoot(host)
+ act(() => root.render(<WebviewZoomControls target={target} />))
+
+ const click = (label: string): void => {
+ const button = host.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`)
+ expect(button).not.toBeNull()
+ act(() => button?.click())
+ }
+
+ click('Zoom out')
+ expect(level).toBe(0)
+ click('Zoom in')
+ expect(level).toBe(1)
+ click('Reset page zoom to 100%')
+ expect(level).toBe(0)
+
+ act(() => root.unmount())
+ })
+
+ it('renders no Electron-only controls in the Server Edition browser', () => {
+ runtime.browser = true
+ const host = document.createElement('div')
+ document.body.append(host)
+ const root = createRoot(host)
+ act(() => root.render(<WebviewZoomControls target={createRef()} />))
+ expect(host.querySelector('.webview-zoom')).toBeNull()
+ act(() => root.unmount())
+ })
+})
diff --git a/src/renderer/components/WebviewZoomControls.tsx b/src/renderer/components/WebviewZoomControls.tsx
new file mode 100644
index 000000000..f0f0c9379
--- /dev/null
+++ b/src/renderer/components/WebviewZoomControls.tsx
@@ -0,0 +1,58 @@
+import type { RefObject } from 'react'
+import { IconMinus, IconPlus } from './icons'
+import { applyWebviewZoom, type ZoomableWebview } from '@shared/webview-zoom'
+import { isBrowserRuntime } from '../bridge/runtime'
+
+interface WebviewZoomControlsProps {
+ target: RefObject<ZoomableWebview | null>
+ disabled?: boolean
+}
+
+export function WebviewZoomControls({ target, disabled = false }: WebviewZoomControlsProps) {
+ if (isBrowserRuntime()) return null
+
+ const zoom = (action: 'in' | 'out' | 'reset'): void => {
+ const webview = target.current
+ if (!webview) return
+ try {
+ applyWebviewZoom(webview, action)
+ } catch {
+ // A webview exists before its guest is attached. The next click can retry once it is ready.
+ }
+ }
+
+ return (
+ <span className="webview-zoom" aria-label="Page zoom controls">
+ <button
+ className="webview-zoom__button"
+ type="button"
+ disabled={disabled}
+ title="Zoom out"
+ aria-label="Zoom out"
+ onClick={() => zoom('out')}
+ >
+ <IconMinus />
+ </button>
+ <button
+ className="webview-zoom__button webview-zoom__reset"
+ type="button"
+ disabled={disabled}
+ title="Reset page zoom to 100%"
+ aria-label="Reset page zoom to 100%"
+ onClick={() => zoom('reset')}
+ >
+ 100%
+ </button>
+ <button
+ className="webview-zoom__button"
+ type="button"
+ disabled={disabled}
+ title="Zoom in"
+ aria-label="Zoom in"
+ onClick={() => zoom('in')}
+ >
+ <IconPlus />
+ </button>
+ </span>
+ )
+}
diff --git a/src/renderer/nodes/BrowserSurface.tsx b/src/renderer/nodes/BrowserSurface.tsx
index 44a46ebae..b6d83ce71 100644
--- a/src/renderer/nodes/BrowserSurface.tsx
+++ b/src/renderer/nodes/BrowserSurface.tsx
@@ -9,9 +9,11 @@ import { reloadWebview, type ReloadableWebview } from './webviewReload'
import { describeLoadFailure, isReportableFailure, type WebviewLoadFailure } from './webviewError'
import { WebviewErrorPlate } from './WebviewErrorPlate'
import { WebviewLoadingBar } from './WebviewLoadingBar'
+import { WebviewZoomControls } from '../components/WebviewZoomControls'
+import type { ZoomableWebview } from '@shared/webview-zoom'
// Minimal typing for the Electron <webview> element methods/events we use.
-type WebviewEl = HTMLElement & {
+type WebviewEl = HTMLElement & ZoomableWebview & {
goBack(): void
goForward(): void
reload(): void
@@ -293,6 +295,7 @@ export function BrowserSurface({
if (e.key === 'Enter') go()
}}
/>
+ <WebviewZoomControls target={ref} disabled={discarded || !src} />
</div>
<div className="browser-node__view nodrag nowheel">
{/* The element is UNMOUNTED while discarded — that is what ends the guest process; an
diff --git a/src/renderer/nodes/WebNode.tsx b/src/renderer/nodes/WebNode.tsx
index 6714b0b25..9da9b81d1 100644
--- a/src/renderer/nodes/WebNode.tsx
+++ b/src/renderer/nodes/WebNode.tsx
@@ -12,6 +12,8 @@ import { describeLoadFailure, isReportableFailure, type WebviewLoadFailure } fro
import { WebviewErrorPlate } from './WebviewErrorPlate'
import { WebviewLoadingBar } from './WebviewLoadingBar'
import { useWebviewKeepAlive } from '../state/webviewKeepAlive'
+import { WebviewZoomControls } from '../components/WebviewZoomControls'
+import type { ZoomableWebview } from '@shared/webview-zoom'
/**
* A web view node. When `data.url` is set it loads that live URL; otherwise it serves the
@@ -32,7 +34,7 @@ export default function WebNode({ id, data, selected }: NodeProps<CanvasNode>) {
const title = (data.title as string) || url || filePath.split('/').pop() || 'web'
const rootRef = useRef<HTMLDivElement | null>(null)
/** The guest, for the audible check only — a local html page can hold a playing <video>. */
- const wvRef = useRef<(AudibleWebview & ReloadableWebview) | null>(null)
+ const wvRef = useRef<(AudibleWebview & ReloadableWebview & ZoomableWebview) | null>(null)
// Memory saver — the same shared hook {@link BrowserSurface} uses: hidden long enough, the
// <webview> is unmounted (its Chromium process exits) and rebuilt on reveal. `revive` is what
// re-runs the source effect below, so the `nt-media://` grant is re-issued for a local file
@@ -183,6 +185,7 @@ export default function WebNode({ id, data, selected }: NodeProps<CanvasNode>) {
{title}
</span>
<span className="term-node__spacer" />
+ {live && <WebviewZoomControls target={wvRef} />}
{live && (
<button
className="term-node__close"
@@ -226,7 +229,7 @@ export default function WebNode({ id, data, selected }: NodeProps<CanvasNode>) {
{/* eslint-disable-next-line react/no-unknown-property */}
<webview
ref={(el) => {
- wvRef.current = el as unknown as (AudibleWebview & ReloadableWebview) | null
+ wvRef.current = el as unknown as (AudibleWebview & ReloadableWebview & ZoomableWebview) | null
}}
src={src}
style={{ width: '100%', height: '100%' }}
diff --git a/src/renderer/nodes/webview-zoom-parity.test.ts b/src/renderer/nodes/webview-zoom-parity.test.ts
new file mode 100644
index 000000000..5696c2ff4
--- /dev/null
+++ b/src/renderer/nodes/webview-zoom-parity.test.ts
@@ -0,0 +1,19 @@
+import { readFileSync } from 'fs'
+import { describe, expect, it } from 'vitest'
+
+const source = (file: string): string =>
+ readFileSync(new URL(file, import.meta.url), 'utf8').replace(/\r\n/g, '\n')
+
+describe('webview zoom surface parity', () => {
+ it('keeps the shared controls on web nodes and browser surfaces', () => {
+ const webNode = source('./WebNode.tsx')
+ const browserSurface = source('./BrowserSurface.tsx')
+ expect(webNode).toContain('<WebviewZoomControls target={wvRef}')
+ expect(browserSurface).toContain('<WebviewZoomControls target={ref}')
+ })
+
+ it('keeps browser nodes and the kanban modal on the shared BrowserSurface', () => {
+ expect(source('./BrowserNode.tsx')).toContain('<BrowserSurface')
+ expect(source('../components/kanban/CardModal.tsx')).toContain('<BrowserSurface')
+ })
+})
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index caec75eb2..7a4852502 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -8410,6 +8410,47 @@ button.group-node__setup:disabled {
opacity: 0.35;
cursor: default;
}
+.webview-zoom {
+ display: inline-flex;
+ align-items: center;
+ flex-shrink: 0;
+ gap: 1px;
+ padding: 1px;
+ border: 1px solid var(--border, #333);
+ border-radius: 5px;
+}
+.webview-zoom__button {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 22px;
+ height: 20px;
+ padding: 0;
+ border: none;
+ border-radius: 3px;
+ background: transparent;
+ color: var(--muted);
+ cursor: pointer;
+}
+.webview-zoom__button:hover:not(:disabled) {
+ background: rgba(var(--tint-rgb), 0.1);
+ color: var(--text);
+}
+.webview-zoom__button:disabled {
+ opacity: 0.35;
+ cursor: default;
+}
+.webview-zoom__button svg {
+ width: 13px;
+ height: 13px;
+}
+.webview-zoom__reset {
+ width: auto;
+ min-width: 34px;
+ padding: 0 3px;
+ font-size: 9px;
+ font-variant-numeric: tabular-nums;
+}
.browser-node__address {
flex: 1;
min-width: 0;
diff --git a/src/shared/webview-zoom.test.ts b/src/shared/webview-zoom.test.ts
new file mode 100644
index 000000000..7f8bdd9ad
--- /dev/null
+++ b/src/shared/webview-zoom.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ applyWebviewZoom,
+ nextWebviewZoomLevel,
+ WEBVIEW_ZOOM_MAX_LEVEL,
+ WEBVIEW_ZOOM_MIN_LEVEL,
+ webviewZoomShortcut,
+ type WebviewZoomShortcutInput
+} from './webview-zoom'
+
+const input = (over: Partial<WebviewZoomShortcutInput> = {}): WebviewZoomShortcutInput => ({
+ type: 'keyDown',
+ code: 'Equal',
+ meta: false,
+ control: true,
+ shift: false,
+ alt: false,
+ ...over
+})
+
+describe('webview page zoom', () => {
+ it('steps by one Electron zoom level and clamps both ends', () => {
+ expect(nextWebviewZoomLevel(0, 'in')).toBe(1)
+ expect(nextWebviewZoomLevel(0, 'out')).toBe(-1)
+ expect(nextWebviewZoomLevel(5, 'reset')).toBe(0)
+ expect(nextWebviewZoomLevel(WEBVIEW_ZOOM_MAX_LEVEL, 'in')).toBe(WEBVIEW_ZOOM_MAX_LEVEL)
+ expect(nextWebviewZoomLevel(WEBVIEW_ZOOM_MIN_LEVEL, 'out')).toBe(WEBVIEW_ZOOM_MIN_LEVEL)
+ })
+
+ it('falls back to 100 percent when the current level is invalid', () => {
+ expect(nextWebviewZoomLevel(Number.NaN, 'in')).toBe(1)
+ })
+
+ it('writes only when the resulting level changes', () => {
+ const setZoomLevel = vi.fn()
+ expect(applyWebviewZoom({ getZoomLevel: () => 0, setZoomLevel }, 'in')).toBe(1)
+ expect(setZoomLevel).toHaveBeenCalledWith(1)
+
+ setZoomLevel.mockClear()
+ applyWebviewZoom(
+ { getZoomLevel: () => WEBVIEW_ZOOM_MAX_LEVEL, setZoomLevel },
+ 'in'
+ )
+ expect(setZoomLevel).not.toHaveBeenCalled()
+ })
+
+ it('maps the platform primary modifier plus +/-/0 and refuses unrelated chords', () => {
+ expect(webviewZoomShortcut(input(), false)).toBe('in')
+ expect(webviewZoomShortcut(input({ code: 'Minus' }), false)).toBe('out')
+ expect(webviewZoomShortcut(input({ code: 'Digit0' }), false)).toBe('reset')
+ expect(webviewZoomShortcut(input({ code: 'NumpadAdd' }), false)).toBe('in')
+ expect(webviewZoomShortcut(input({ shift: true }), false)).toBe('in')
+ expect(webviewZoomShortcut(input({ control: false, meta: true }), true)).toBe('in')
+ expect(webviewZoomShortcut(input({ code: 'KeyA' }), false)).toBeNull()
+ expect(webviewZoomShortcut(input({ alt: true }), false)).toBeNull()
+ expect(webviewZoomShortcut(input({ type: 'keyUp' }), false)).toBeNull()
+ expect(webviewZoomShortcut(input({ code: 'Digit0', shift: true }), false)).toBeNull()
+ })
+
+ it('does not treat the non-primary modifier as page zoom on either platform', () => {
+ expect(webviewZoomShortcut(input({ control: false, meta: true }), false)).toBeNull()
+ expect(webviewZoomShortcut(input({ control: true, meta: false }), true)).toBeNull()
+ expect(webviewZoomShortcut(input({ control: true, meta: true }), true)).toBeNull()
+ })
+})
diff --git a/src/shared/webview-zoom.ts b/src/shared/webview-zoom.ts
new file mode 100644
index 000000000..53fffa913
--- /dev/null
+++ b/src/shared/webview-zoom.ts
@@ -0,0 +1,48 @@
+const ELECTRON_ZOOM_FACTOR_PER_LEVEL = 1.2
+export const WEBVIEW_ZOOM_MIN_LEVEL = Math.log(0.5) / Math.log(ELECTRON_ZOOM_FACTOR_PER_LEVEL)
+export const WEBVIEW_ZOOM_MAX_LEVEL = Math.log(3) / Math.log(ELECTRON_ZOOM_FACTOR_PER_LEVEL)
+
+export type WebviewZoomAction = 'in' | 'out' | 'reset'
+
+export interface ZoomableWebview {
+ getZoomLevel(): number
+ setZoomLevel(level: number): void
+}
+
+export interface WebviewZoomShortcutInput {
+ type: string
+ code: string
+ meta: boolean
+ control: boolean
+ shift: boolean
+ alt: boolean
+}
+
+export function nextWebviewZoomLevel(current: number, action: WebviewZoomAction): number {
+ const level = Number.isFinite(current) ? current : 0
+ if (action === 'reset') return 0
+ const next = level + (action === 'in' ? 1 : -1)
+ return Math.min(WEBVIEW_ZOOM_MAX_LEVEL, Math.max(WEBVIEW_ZOOM_MIN_LEVEL, next))
+}
+
+export function applyWebviewZoom(target: ZoomableWebview, action: WebviewZoomAction): number {
+ const current = target.getZoomLevel()
+ const next = nextWebviewZoomLevel(current, action)
+ if (next !== current) target.setZoomLevel(next)
+ return next
+}
+
+export function webviewZoomShortcut(
+ input: WebviewZoomShortcutInput,
+ isMac: boolean
+): WebviewZoomAction | null {
+ if (input.type !== 'keyDown' || input.alt) return null
+ const primary = isMac ? input.meta && !input.control : input.control && !input.meta
+ if (!primary) return null
+ // Equal is the physical +/- key on common layouts, so Shift is valid only for zooming in.
+ if (input.code === 'Equal' || (!input.shift && input.code === 'NumpadAdd')) return 'in'
+ if (input.shift) return null
+ if (input.code === 'Minus' || input.code === 'NumpadSubtract') return 'out'
+ if (input.code === 'Digit0' || input.code === 'Numpad0') return 'reset'
+ return null
+}