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
perf(kanban): pause the canvas's animations while the board covers it
enesd891c5221ecd
diff --git a/CLAUDE.md b/CLAUDE.mdindex 564744e1c..5821d4c03 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3843,6 +3843,28 @@ callbacks — the default renderer path has no self-perpetuating rAF loop (glyphidle frames and is opt-in; the dino game's is focus-gated). Before adding a timer gate for energyreasons, 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 documentelement 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 thediff --git a/src/renderer/components/kanban/GlobalKanbanView.tsx b/src/renderer/components/kanban/GlobalKanbanView.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.cssindex 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'renever 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/