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.

perf(kanban): pause the canvas's animations while the board covers it

enesd891c5221ecd
diff --git a/CLAUDE.md b/CLAUDE.md
index 564744e1c..5821d4c03 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3843,6 +3843,28 @@ callbacks — the default renderer path has no self-perpetuating rAF loop (glyph
idle frames and is opt-in; the dino game's is focus-gated). Before adding a timer gate for energy
reasons, measure: at these frequencies a JS wakeup is nothing beside one frame of compositing.
+**The board is the second gate, and it is a SEPARATE attribute on purpose.** The canvas stays
+mounted under the kanban overlay (`display: none` would 0x0-resize every terminal into a tmux
+SIGWINCH), so its glows and pulses keep animating under something nobody can see through — 12.8 %
+in the table above. `renderer/lib/canvasCovered.ts` marks `data-nt-canvas="covered"` for as long as
+a full-page board view is MOUNTED (mount is the signal: both board views are conditionally
+rendered, so it cannot drift from the view state the way a recomputed `kanbanOpen` flag can, and it
+needs nothing from Canvas), and `:root[data-nt-canvas='covered'] .react-flow` overrides
+`--nt-anim-state` on that subtree alone — the variable INHERITS, so that one declaration is the
+whole gate for every animation reading it. It is not a second writer of `data-nt-window` because
+the two facts are independent (a board on a focused window; an unfocused window with no board) and
+one attribute with two owners is a race over who clears it. The claim is refcounted: React can
+mount the incoming view before unmounting the outgoing one, and a plain set/clear pair would let
+that unmount erase the live view's claim.
+
+**Specificity is the quiet failure mode in all of this, and it has already happened twice.** The
+three glows carry their own `animation:` shorthand, which RESETS `animation-play-state` — so
+inheriting the variable does nothing for them and every gate has to name them explicitly. A first
+draft of the covered rule used `.react-flow__node::after`, lost to
+`.react-flow__node:has(.term-node.working)::after` on specificity, and measured EXACTLY the
+unpatched number while looking correct in the diff. When you add a gate, verify the COMPUTED
+`animation-play-state` on a real element, not the presence of the declaration.
+
The gate itself: `renderer/lib/windowActivity.ts` sets `data-nt-window="idle"` on the document
element when the window loses focus or the page hides, `:root[data-nt-window='idle']` flips
`--nt-anim-state` to `paused`, and the three per-node glows take a static-lit rule instead of the
diff --git a/src/renderer/components/kanban/GlobalKanbanView.tsx b/src/renderer/components/kanban/GlobalKanbanView.tsx
index f01b9e4b8..73dbdbd8d 100644
--- a/src/renderer/components/kanban/GlobalKanbanView.tsx
+++ b/src/renderer/components/kanban/GlobalKanbanView.tsx
@@ -12,6 +12,7 @@ import { KanbanColumn, type KanbanLane } from './KanbanColumn'
import { SessionCard } from './SessionCard'
import { toKanbanSessionState } from '../../canvas/toKanbanSessionState'
import { createAgentNode, createBrowserNode, createStickyNode, createTerminalNode, flowToNodeStates, resolveNewNodeAccount } from '../../state/workspace'
+import { markCanvasCovered } from '../../lib/canvasCovered'
import { useViewMode } from '../../state/viewMode'
import { useSession } from '../../session/session'
import { activePermissionMode } from '../../state/permissionMode'
@@ -287,6 +288,8 @@ const Swimlane = memo(function Swimlane({
})
export const GlobalKanbanView = memo(function GlobalKanbanView() {
+ // Same rule as the per-project board: the canvas is covered but mounted underneath.
+ useEffect(() => markCanvasCovered(document.documentElement), [])
const projects = useProjects(s => s.projects.filter(p => !p.closed))
const { api } = useSession()
const modalRef = useRef<string | null>(null)
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index 179a08414..f8e0a716c 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -10,6 +10,7 @@ import {
deleteColumn, labelsForCard, moveColumn,
nextColumnColor, pruneAssignments, recolorColumn, renameColumn, unassigned
} from '../../lib/kanban'
+import { markCanvasCovered } from '../../lib/canvasCovered'
import { labelSwatch } from '../../lib/kanbanLabelColors'
import { CardModal } from './CardModal'
import { KanbanColumn, type KanbanLane } from './KanbanColumn'
@@ -123,10 +124,20 @@ const NO_CARDS: KanbanSession[] = []
* memo: Canvas re-renders on plenty the board doesn't care about (agent signatures, camera
* banners…); with every prop stable (Canvas useCallbacks + memoized board/sessions) those
* renders stop at this boundary. */
+/**
+ * While this board is on screen the canvas underneath is fully covered but still mounted, so its
+ * node glows and status pulses keep the compositor producing frames for something nobody can see.
+ * Mount is the signal (see lib/canvasCovered.ts for the measurements).
+ */
+function useCanvasCovered(): void {
+ useEffect(() => markCanvasCovered(document.documentElement), [])
+}
+
export const KanbanView = memo(function KanbanView({
board, sessions, onChange, onOpenNode, onCreateNode, onRenameNode, onEditSticky, onDeleteNode,
onModalNodeChange, onBrowserNav, onSetIcon
}: KanbanViewProps) {
+ useCanvasCovered()
const { api } = useSession()
const dragRef = useRef<Drag>(null)
// One card modal at a time; a deleted node closes it via the byId.has render guard.
diff --git a/src/renderer/lib/canvasCovered.test.ts b/src/renderer/lib/canvasCovered.test.ts
new file mode 100644
index 000000000..f7e29df20
--- /dev/null
+++ b/src/renderer/lib/canvasCovered.test.ts
@@ -0,0 +1,118 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+ CANVAS_COVERED_ATTR,
+ canvasCoveredDepth,
+ markCanvasCovered,
+ resetCanvasCoveredForTest,
+ type CoveredRoot
+} from './canvasCovered'
+
+function fakeRoot() {
+ const attrs = new Map<string, string>()
+ const writes: string[] = []
+ const root: CoveredRoot = {
+ setAttribute: (n, v) => {
+ attrs.set(n, v)
+ writes.push('set:' + v)
+ },
+ removeAttribute: (n) => {
+ attrs.delete(n)
+ writes.push('remove')
+ }
+ }
+ return { root, writes, value: () => attrs.get(CANVAS_COVERED_ATTR) }
+}
+
+beforeEach(() => resetCanvasCoveredForTest())
+
+describe('markCanvasCovered', () => {
+ it('marks and unmarks around one surface', () => {
+ const h = fakeRoot()
+ const release = markCanvasCovered(h.root)
+ expect(h.value()).toBe('covered')
+ release()
+ expect(h.value()).toBeUndefined()
+ })
+
+ it('survives an overlapping view switch', () => {
+ // React can mount the incoming surface before unmounting the outgoing one. A plain set/clear
+ // pair would let that unmount erase the live surface's claim, leaving the canvas animating
+ // under a board that is very much on screen.
+ const h = fakeRoot()
+ const outgoing = markCanvasCovered(h.root)
+ const incoming = markCanvasCovered(h.root)
+ outgoing()
+ expect(h.value()).toBe('covered')
+ incoming()
+ expect(h.value()).toBeUndefined()
+ })
+
+ it('writes the attribute once per covered period, not once per surface', () => {
+ const h = fakeRoot()
+ const a = markCanvasCovered(h.root)
+ const b = markCanvasCovered(h.root)
+ b()
+ a()
+ expect(h.writes).toEqual(['set:covered', 'remove'])
+ })
+
+ it('ignores a repeated release rather than driving the count negative', () => {
+ // A double-invoked effect cleanup would otherwise leave the depth at -1, and the NEXT board
+ // open would not reach 1 — the attribute would silently never be set again.
+ const h = fakeRoot()
+ const release = markCanvasCovered(h.root)
+ release()
+ release()
+ expect(canvasCoveredDepth()).toBe(0)
+
+ const again = markCanvasCovered(h.root)
+ expect(h.value()).toBe('covered')
+ again()
+ expect(h.value()).toBeUndefined()
+ })
+})
+
+/**
+ * Source-level pin, in the shape of `hook-verified-parity.test.ts`. Both board views cover the
+ * canvas and BOTH must claim it; wiring one leaves the other silently without the gate, and the
+ * failure is invisible — the board looks identical either way, and only a power measurement on a
+ * machine nobody is watching would ever show it.
+ */
+describe('both full-page board views claim the canvas', () => {
+ const views = ['KanbanView.tsx', 'GlobalKanbanView.tsx']
+
+ it.each(views)('%s calls markCanvasCovered', (file) => {
+ const src = fs
+ .readFileSync(path.join(__dirname, '..', 'components', 'kanban', file), 'utf8')
+ .replace(/\r\n/g, '\n')
+ expect(src).toContain('markCanvasCovered')
+ })
+})
+
+/** And the CSS has to act on the attribute, or the claim is bookkeeping nobody reads. */
+describe('the covered attribute is wired to the stylesheet', () => {
+ const css = fs
+ .readFileSync(path.join(__dirname, '..', 'styles.css'), 'utf8')
+ .replace(/\r\n/g, '\n')
+
+ it('pauses the variable-gated animations on the canvas subtree', () => {
+ expect(css).toMatch(
+ /:root\[data-nt-canvas='covered'\]\s+\.react-flow\s*\{\s*--nt-anim-state:\s*paused/
+ )
+ })
+
+ it.each(['unread', 'working', 'attention'])(
+ 'pauses the %s glow, which is not in the variable scheme',
+ (state) => {
+ // The three glows carry their own `animation:` shorthand, which RESETS play-state — so
+ // inheriting the variable does nothing for them and they need naming here. A rule that
+ // loses on specificity is the quiet version of this bug: it is present in the diff and
+ // has no effect.
+ expect(css).toContain(
+ `:root[data-nt-canvas='covered'] .react-flow__node:has(.term-node.${state})::after`
+ )
+ }
+ )
+})
diff --git a/src/renderer/lib/canvasCovered.ts b/src/renderer/lib/canvasCovered.ts
new file mode 100644
index 000000000..e9511aeb2
--- /dev/null
+++ b/src/renderer/lib/canvasCovered.ts
@@ -0,0 +1,63 @@
+/**
+ * Is the canvas currently hidden behind a full-page surface?
+ *
+ * The canvas stays MOUNTED under the kanban board on purpose — `display: none` would resize every
+ * terminal to 0x0 and fire a tmux SIGWINCH (see the kanban section of CLAUDE.md) — so every node
+ * glow, status pulse and minimap dot on it keeps animating under an opaque overlay nobody can see
+ * through. Chromium culls most of that work but not all of it: MEASURED on the Server Edition with
+ * twenty pulsing nodes, covering the canvas with an opaque full-screen div took total browser CPU
+ * from 101 % to 12.8 %, against an idle floor of 1.5 %. Pausing the canvas's animations underneath
+ * takes it the rest of the way, to 1.5 %.
+ *
+ * This is the same gate as `windowActivity.ts` and deliberately a SEPARATE attribute rather than a
+ * second writer of that one: the two facts are independent (a board can be open on a focused
+ * window, and a window can be unfocused with no board), and one attribute written by two owners is
+ * a race over who clears it.
+ *
+ * **Mount is the signal, not a derived boolean.** Both board views are conditionally rendered, so
+ * "this component exists" already means "the canvas is covered" — it cannot drift from the view
+ * state the way a `kanbanOpen` flag recomputed somewhere else can, and it needs nothing from
+ * Canvas.
+ */
+
+/** The attribute this module writes on the document element. */
+export const CANVAS_COVERED_ATTR = 'data-nt-canvas'
+
+/** Minimal surface of the element the attribute lives on, so the unit test needs no DOM. */
+export interface CoveredRoot {
+ setAttribute(name: string, value: string): void
+ removeAttribute(name: string): void
+}
+
+let depth = 0
+
+/**
+ * Declare the canvas covered, and return the release.
+ *
+ * Refcounted because a view switch can legitimately overlap: React may mount the incoming surface
+ * before it unmounts the outgoing one, and a plain set/clear pair would then have the outgoing
+ * unmount erase the incoming mount's claim — leaving the canvas animating under a board that is
+ * very much on screen. Releasing twice is a no-op, so a double-invoked cleanup cannot drive the
+ * count negative and strand the attribute.
+ */
+export function markCanvasCovered(root: CoveredRoot): () => void {
+ depth += 1
+ if (depth === 1) root.setAttribute(CANVAS_COVERED_ATTR, 'covered')
+ let released = false
+ return () => {
+ if (released) return
+ released = true
+ depth -= 1
+ if (depth === 0) root.removeAttribute(CANVAS_COVERED_ATTR)
+ }
+}
+
+/** Test seam: the module-level count is a singleton, so a suite has to be able to reset it. */
+export function resetCanvasCoveredForTest(): void {
+ depth = 0
+}
+
+/** How many surfaces currently claim the canvas is covered. Test seam. */
+export function canvasCoveredDepth(): number {
+ return depth
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index c81c57788..7850d116b 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -1504,6 +1504,32 @@ body,
will-change: auto;
}
+/* ---- Covered-canvas animation gate -----------------------------------------------------------
+ The kanban board is an opaque overlay and the canvas stays MOUNTED underneath it, because
+ `display: none` would resize every terminal to 0x0 and fire a tmux SIGWINCH. So every glow and
+ pulse on that canvas keeps the compositor producing frames for something nobody can see through.
+ MEASURED with twenty pulsing nodes: 101 % total browser CPU uncovered, 12.8 % under an opaque
+ full-screen div (Chromium culls a lot of it, but not the frame loop), 1.5 % with this rule.
+
+ `--nt-anim-state` INHERITS, so overriding it on the canvas subtree is the whole gate for every
+ animation that reads it — no second list of selectors to keep in step. The three node glows are
+ not in that scheme (see the idle rules above) and take an explicit pause here; under an opaque
+ board there is no readability argument for freezing them lit, so they simply stop.
+
+ A SEPARATE attribute from `data-nt-window` on purpose: the two facts are independent (a board on
+ a focused window, an unfocused window with no board), and one attribute with two writers is a
+ race over who clears it. Scoped to the canvas and nothing else — the controls cluster and the
+ pills sit ABOVE the board (z 26) and are genuinely on screen, so they keep animating. */
+:root[data-nt-canvas='covered'] .react-flow {
+ --nt-anim-state: paused;
+}
+
+:root[data-nt-canvas='covered'] .react-flow__node:has(.term-node.unread)::after,
+:root[data-nt-canvas='covered'] .react-flow__node:has(.term-node.working)::after,
+:root[data-nt-canvas='covered'] .react-flow__node:has(.term-node.attention)::after {
+ animation-play-state: paused;
+}
+
/* Bridge link handles (Claude nodes): dots on the header row, on top of the node so they're
never buried under the terminal body. Subtle until you hover the node, then prominent.
Never set `transform` on a React Flow handle: the side classes (.react-flow__handle-left/right/