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(renderer): hold decorative animations still while nobody is looking

enesa3240e4242e0
diff --git a/CLAUDE.md b/CLAUDE.md
index 61577c10c..564744e1c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3788,6 +3788,69 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
- **Theme**: macOS dark palette as CSS tokens in `styles.css` `:root` (`--accent` = systemBlue,
label/separator opacities, SF font stack). Canvas background is black with dot grid.
+## Idle energy: an animation is a frame loop, not a decoration
+
+**A running CSS animation obliges the compositor to produce a frame every vsync — on a ProMotion
+display 120 of them a second — for as long as it runs, and each of those frames re-rasters and
+re-composites the whole window.** That cost is paid once for the WINDOW, not once per animation, and
+it does not care whether anybody is looking: an unfocused window that is still visible (a second
+monitor, half behind an editor) is not `document.hidden` by any definition Chromium uses, so it
+keeps producing frames at full display rate.
+
+MEASURED on the Server Edition, 40 terminal nodes on one canvas, headless Chrome, 25 s idle windows,
+total CPU across every Chrome process (`/proc/<pid>/stat`):
+
+| state | CPU |
+|---|---|
+| idle, nothing animating | **1.5 %** |
+| **one** visible node with the `working` glow | **33 %** |
+| five | 66 % |
+| twenty | 101 % |
+| twenty, but all panned OFF screen | 2.2 % |
+| twenty, under an opaque full-screen overlay | 12.8 % |
+| twenty, `animation-play-state: paused` | **1.6 %** |
+| twenty, `animation: none` + a static opacity | 1.9 % |
+| first-run mobile-launch card open (5 animations, no node glows) | 97 % |
+
+Four things to take from that table, because each one contradicts a reasonable guess:
+
+- **The step is at the FIRST animation, not the twentieth.** What costs is that frames are produced
+ at all. So a gate that covers most of the app's animations buys nothing — one that keeps running
+ holds the frame loop open, while everything the gate DOES cover still looks correctly frozen. That
+ is why `--nt-anim-state` is applied to EVERY `infinite` animation in `styles.css` and enforced by
+ scan (`styles.animation-gate.test.ts`) rather than applied to the worst few by hand.
+- **Offscreen nodes are already free** (2.2 %): Chromium skips raster and compositing for layers
+ fully outside the viewport. There is nothing to fix there, and a viewport-gated animation would be
+ work with no measurable return. A canvas of 119 nodes costs what its VISIBLE animated nodes cost.
+- **`paused` is as cheap as `none`** (1.6 % vs 1.9 %), so the gate freezes each animation where it
+ stands instead of snapping it to a resting frame — nothing MOVES at the moment focus is lost, and
+ refocusing resumes rather than restarts.
+- **The renderer's MAIN thread is idle throughout.** Over the 25 s window with one node pulsing,
+ `Performance.getMetrics` reported 0.15 s of `TaskDuration`, 1 layout and 51 style recalcs, while
+ the renderer PROCESS burned 14.8 % and the GPU process 17.9 %. This is compositor and raster work,
+ invisible to every JS-level profiler and to a timer census.
+
+**What the numbers are NOT.** Headless Chrome here rasters in software (SwiftShader), so the
+absolute percentages are inflated relative to a real GPU and none of them is a prediction about
+macOS. What the A/B establishes is the MECHANISM and its direction; the magnitude on a given machine
+has to be measured there (`powermetrics --samplers gpu_power,tasks`, and Activity Monitor's Energy
+Impact, which weights GPU use and wakeups heavily).
+
+**Timers are not the problem, and the census that said so is worth not repeating.** Over the same
+idle window the renderer fired **56 timer callbacks in 30 s** (~1.9/s: 40 per-node liveness polls at
+1/30 Hz, the 2 s terminal-focus mirror, the 30 s host-RAM read) and **zero** `requestAnimationFrame`
+callbacks — the default renderer path has no self-perpetuating rAF loop (glyphgrid's parks after 30
+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 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
+shared pause — `nt-unread-glow` rests at `opacity: 0`, so pausing it is a coin flip on whether the
+glow that says "this agent finished while you were away" is still on screen when you come back to
+look for it. `hud.css` is deliberately excluded: the notch HUD's window is never focused, so the
+shared gate would freeze it permanently rather than while nobody is looking.
+
## Remote access (phone relay) — free, not Pro
- Phone relay remote access ("Reach this Mac from anywhere") is a **Core (free) feature** as of
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d8eead2e9..7977574bd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -543,6 +543,17 @@ tmux without carrying `TMUX_TMPDIR` into it, which is the one way left to escape
`src/core/tmux-socket-isolation.guard.test.ts` holds the short allowlist of suites that name a
production socket on purpose; adding a third is a review conversation, not a checkbox.
+**An `infinite` CSS animation is a frame loop, and it runs whether or not anyone is looking.** A
+running animation makes the compositor produce a frame every vsync — 120/s on a ProMotion display —
+and re-raster the window each time; measured on a 40-terminal canvas, ONE visible pulsing node took
+idle CPU from 1.5 % to 33 %, and twenty took it to 101 %. The cost is paid once for the window, so
+the step is at the FIRST animation, not the twentieth. Two consequences when you add one: give it
+`animation-play-state: var(--nt-anim-state);` right after the shorthand so it joins the idle-window
+gate (`src/renderer/styles.animation-gate.test.ts` fails if you forget, because one ungated
+animation takes the whole win back), and prefer a static state to a pulse wherever the pulse is not
+carrying information the user needs at a glance. The full measurement table and the reasoning are
+in CLAUDE.md § Idle energy.
+
## Pull requests
- Branch from `main`. CI runs `quality`, `CodeQL` and `Dependency review`; all three are required.
diff --git a/src/renderer/App.tsx b/src/renderer/App.tsx
index e120725d8..ca8e15c9c 100644
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -17,6 +17,7 @@ import { resolveTerminalRenderer } from '../shared/webgl'
import { resolveTerminalTheme } from './terminal/themes'
import { resolveUiScale } from '../shared/ui-scale'
import { useAppTheme } from './state/useAppTheme'
+import { installWindowActivityOnDocument } from './lib/windowActivity'
export default function App() {
// Apply the terminal-rendering setting to the two GPU coordinators, live. 'auto' is
@@ -44,6 +45,14 @@ export default function App() {
if (background) document.documentElement.style.setProperty('--term-bg', background)
}, [terminalTheme])
+ // Hold every infinite CSS animation still while nobody is looking at this window (the gate is
+ // `--nt-anim-state` / `[data-nt-window]` in styles.css, where the measurements live). Installed
+ // here rather than in Canvas because the surfaces that animate outside the canvas — the
+ // onboarding scenes, the settings spinners, the sessions sidebar — are mounted here too, and a
+ // gate that covers most of the animations buys nothing: one that keeps running keeps the
+ // compositor producing frames, which is the entire cost.
+ useEffect(() => installWindowActivityOnDocument(), [])
+
// Publish the resolved appearance as `data-theme` on <html> — what the light palette in
// styles.css keys off. Absent, or 'dark', leaves every token at its original value, so this one
// attribute is all that stands between an existing install and the chrome it has always had.
diff --git a/src/renderer/lib/windowActivity.test.ts b/src/renderer/lib/windowActivity.test.ts
new file mode 100644
index 000000000..64ff93f2e
--- /dev/null
+++ b/src/renderer/lib/windowActivity.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest'
+import {
+ installWindowActivity,
+ resolveWindowActivity,
+ WINDOW_ACTIVITY_ATTR,
+ type WindowActivityDeps
+} from './windowActivity'
+
+function harness(init: { focused: boolean; hidden: boolean }) {
+ const attrs = new Map<string, string>()
+ const listeners = new Map<string, Set<() => void>>()
+ const state = { ...init }
+ const deps: WindowActivityDeps = {
+ root: {
+ setAttribute: (n, v) => void attrs.set(n, v),
+ removeAttribute: (n) => void attrs.delete(n)
+ },
+ hasFocus: () => state.focused,
+ isHidden: () => state.hidden,
+ addEventListener: (type, l) => {
+ if (!listeners.has(type)) listeners.set(type, new Set())
+ listeners.get(type)!.add(l)
+ },
+ removeEventListener: (type, l) => void listeners.get(type)?.delete(l)
+ }
+ return {
+ deps,
+ state,
+ attr: () => attrs.get(WINDOW_ACTIVITY_ATTR),
+ fire: (type: string) => {
+ for (const l of listeners.get(type) ?? []) l()
+ },
+ listenerCount: () => [...listeners.values()].reduce((n, s) => n + s.size, 0)
+ }
+}
+
+describe('resolveWindowActivity', () => {
+ it('is active only when focused AND visible', () => {
+ expect(resolveWindowActivity(true, false)).toBe('active')
+ expect(resolveWindowActivity(false, false)).toBe('idle')
+ expect(resolveWindowActivity(true, true)).toBe('idle')
+ expect(resolveWindowActivity(false, true)).toBe('idle')
+ })
+
+ it('treats a VISIBLE but unfocused window as idle — the case the gate exists for', () => {
+ // A nodeterm window sitting on a second monitor while its owner works elsewhere is not hidden
+ // by any definition Chromium uses, and composites at full display rate. If this ever flips to
+ // 'active' the feature is inert on the only scenario that motivated it.
+ expect(resolveWindowActivity(false, false)).toBe('idle')
+ })
+})
+
+describe('installWindowActivity', () => {
+ it('leaves NO attribute while active, so a never-blurred window is unchanged', () => {
+ const h = harness({ focused: true, hidden: false })
+ installWindowActivity(h.deps)
+ expect(h.attr()).toBeUndefined()
+ })
+
+ it('marks idle on blur and clears it again on focus', () => {
+ const h = harness({ focused: true, hidden: false })
+ installWindowActivity(h.deps)
+
+ h.state.focused = false
+ h.fire('blur')
+ expect(h.attr()).toBe('idle')
+
+ h.state.focused = true
+ h.fire('focus')
+ expect(h.attr()).toBeUndefined()
+ })
+
+ it('marks idle when the page is hidden even though it still has focus', () => {
+ const h = harness({ focused: true, hidden: false })
+ installWindowActivity(h.deps)
+ h.state.hidden = true
+ h.fire('visibilitychange')
+ expect(h.attr()).toBe('idle')
+ })
+
+ it('applies the initial state at install time, not only on the first event', () => {
+ // The page can be restored into an unfocused window (a reload while the user is in another
+ // app); waiting for an event would leave every animation running until they came back.
+ const h = harness({ focused: false, hidden: false })
+ installWindowActivity(h.deps)
+ expect(h.attr()).toBe('idle')
+ })
+
+ it('resolves blur+hide landing in the same tick to one value, whichever event ran last', () => {
+ // ⌘H fires both. Each listener re-reads BOTH facts rather than asserting the one it knows
+ // about, so the second listener to run cannot undo the first.
+ const h = harness({ focused: true, hidden: false })
+ installWindowActivity(h.deps)
+ h.state.focused = false
+ h.state.hidden = true
+ h.fire('blur')
+ h.fire('visibilitychange')
+ expect(h.attr()).toBe('idle')
+ })
+
+ it('falls back to active when the environment cannot answer', () => {
+ // Fail-safe direction: a wrong answer costs a running animation, never a frozen one.
+ const h = harness({ focused: true, hidden: false })
+ h.deps.hasFocus = () => {
+ throw new Error('no focus API')
+ }
+ installWindowActivity(h.deps)
+ expect(h.attr()).toBeUndefined()
+ })
+
+ it('removes every listener on teardown', () => {
+ const h = harness({ focused: true, hidden: false })
+ const stop = installWindowActivity(h.deps)
+ expect(h.listenerCount()).toBeGreaterThan(0)
+ stop()
+ expect(h.listenerCount()).toBe(0)
+ })
+
+ it('writes only on a change', () => {
+ const writes: string[] = []
+ const h = harness({ focused: true, hidden: false })
+ h.deps.root = {
+ setAttribute: (_n, v) => void writes.push('set:' + v),
+ removeAttribute: () => void writes.push('remove')
+ }
+ installWindowActivity(h.deps)
+ h.state.focused = false
+ h.fire('blur')
+ h.fire('blur')
+ h.fire('visibilitychange')
+ // The leading removal is the install seeding a known state (it clears a stale value left by a
+ // previous install); after that only real transitions reach the DOM.
+ expect(writes).toEqual(['remove', 'set:idle'])
+ })
+})
diff --git a/src/renderer/lib/windowActivity.ts b/src/renderer/lib/windowActivity.ts
new file mode 100644
index 000000000..beec16b98
--- /dev/null
+++ b/src/renderer/lib/windowActivity.ts
@@ -0,0 +1,108 @@
+/**
+ * Is anybody looking at this window right now?
+ *
+ * The one consumer is the CSS animation gate (`--nt-anim-state` / `[data-nt-window]` near the top
+ * of styles.css): every `infinite` animation the app draws — pulsing status dots, node glows,
+ * spinners, the walking mascots — is held still while the answer is no. See that block for the
+ * measurements; the short version is that one running animation obliges the compositor to produce
+ * a frame every vsync for as long as it runs, and a canvas full of agent nodes does that forever.
+ *
+ * "Looking at it" is deliberately the STRICTER of two facts, and each covers a case the other
+ * misses:
+ *
+ * - `document.hidden` is the browser's own answer, and it is the weaker one. It goes true for a
+ * background tab or a minimised/fully-occluded window — Chromium then stops producing frames
+ * by itself, so on its own it would gate nothing we are not already getting for free.
+ * - Window FOCUS is the case that actually costs: a nodeterm window sitting visible on a second
+ * monitor, or behind a half-width editor, while its owner works in another app. It is not
+ * hidden by any definition Chromium uses, it composites at full display rate, and nobody is
+ * watching a dot pulse. That is the state this module exists to name.
+ *
+ * The fail-safe direction is `active`. Everything here is decoration, so being wrong costs a
+ * needlessly running animation, never a hidden one — an environment with no `hasFocus` (a test
+ * DOM, an exotic embedder) therefore reads as active and the app animates exactly as it did
+ * before this file existed.
+ */
+
+/** What the gate reports. `idle` is "no one is looking", not "the machine is idle". */
+export type WindowActivity = 'active' | 'idle'
+
+/** The attribute `installWindowActivity` writes on the document element. */
+export const WINDOW_ACTIVITY_ATTR = 'data-nt-window'
+
+/**
+ * The whole decision, as a pure function of the two facts above.
+ *
+ * Note `focused` is asked for as a value rather than read here: the caller reads it from the
+ * event that woke it (a `blur` means unfocused even in the tick before `document.hasFocus()`
+ * agrees), which is what keeps the attribute in step with what the user just did.
+ */
+export function resolveWindowActivity(focused: boolean, hidden: boolean): WindowActivity {
+ return focused && !hidden ? 'active' : 'idle'
+}
+
+export interface WindowActivityDeps {
+ /** The element carrying the attribute. Defaults to `document.documentElement`. */
+ root: { setAttribute(name: string, value: string): void; removeAttribute(name: string): void }
+ /** Focus/visibility sources, injected so the unit test can drive them without a real window. */
+ hasFocus(): boolean
+ isHidden(): boolean
+ addEventListener(type: string, listener: () => void): void
+ removeEventListener(type: string, listener: () => void): void
+}
+
+/**
+ * Start reflecting window activity onto the document element, and return the teardown.
+ *
+ * The attribute is only written when the value CHANGES, and `active` removes it rather than
+ * writing `active`: the default state should leave no trace in the DOM, so a page that never
+ * loses focus is byte-identical to one from before this module existed.
+ */
+export function installWindowActivity(deps: WindowActivityDeps): () => void {
+ let current: WindowActivity | null = null
+
+ const apply = (): void => {
+ // `hasFocus` is read fresh each time rather than inferred from which event fired: a window can
+ // lose focus and be hidden in the same tick (⌘H), and two listeners racing to write opposite
+ // values would leave whichever landed second in charge.
+ let next: WindowActivity
+ try {
+ next = resolveWindowActivity(deps.hasFocus(), deps.isHidden())
+ } catch {
+ next = 'active'
+ }
+ if (next === current) return
+ current = next
+ if (next === 'active') deps.root.removeAttribute(WINDOW_ACTIVITY_ATTR)
+ else deps.root.setAttribute(WINDOW_ACTIVITY_ATTR, next)
+ }
+
+ const events = ['focus', 'blur', 'visibilitychange', 'pageshow']
+ for (const e of events) deps.addEventListener(e, apply)
+ apply()
+
+ return () => {
+ for (const e of events) deps.removeEventListener(e, apply)
+ }
+}
+
+/** The browser wiring, kept apart from the logic above so the logic stays testable. */
+export function installWindowActivityOnDocument(): () => void {
+ if (typeof document === 'undefined' || typeof window === 'undefined') return () => {}
+ return installWindowActivity({
+ root: document.documentElement,
+ // A document that cannot answer (no `hasFocus`) reads as focused — see the fail-safe note above.
+ hasFocus: () => (typeof document.hasFocus === 'function' ? document.hasFocus() : true),
+ isHidden: () => document.visibilityState === 'hidden',
+ addEventListener: (type, listener) => {
+ // `visibilitychange` is a document event; focus/blur are read off the window, because a
+ // window `blur` is the event Electron forwards when the user switches apps.
+ const target: EventTarget = type === 'visibilitychange' ? document : window
+ target.addEventListener(type, listener)
+ },
+ removeEventListener: (type, listener) => {
+ const target: EventTarget = type === 'visibilitychange' ? document : window
+ target.removeEventListener(type, listener)
+ }
+ })
+}
diff --git a/src/renderer/styles.animation-gate.test.ts b/src/renderer/styles.animation-gate.test.ts
new file mode 100644
index 000000000..3a71474f8
--- /dev/null
+++ b/src/renderer/styles.animation-gate.test.ts
@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The animation gate is an ALL-OR-NOTHING fix, which is why it is enforced by scan rather than by
+ * review.
+ *
+ * A running CSS animation obliges the compositor to produce a frame every vsync, and that cost is
+ * paid once for the window, not once per animation. Measured on the Server Edition with a
+ * 40-terminal canvas idling for 25 s under headless Chrome: 1.5 % total browser CPU with nothing
+ * animating, 33 % with ONE node pulsing, 101 % with twenty, and 1.6 % with the same twenty paused.
+ * The step is at the first animation. So a single `infinite` animation added later without the
+ * gate does not make the feature 1/56th worse — it holds the frame loop open and takes the whole
+ * win back, while every animation the gate DOES cover still looks correctly frozen, which is
+ * exactly the kind of regression nobody notices by looking.
+ *
+ * Joining the gate means one of two things, and the allowlist below is for neither:
+ * - `animation-play-state: var(--nt-anim-state);` after the shorthand (the shorthand resets
+ * play-state, so it must come after), or
+ * - an explicit `:root[data-nt-window='idle']` rule that gives the element a static state.
+ */
+
+const STYLES = path.join(__dirname, 'styles.css')
+const PLAY_STATE = 'animation-play-state: var(--nt-anim-state)'
+
+/**
+ * Animations that deliberately stay out of the shared play-state property because an idle-window
+ * rule handles them by hand. Keyed by keyframe name, with the reason, so removing the hand-written
+ * rule without removing the entry fails below.
+ */
+const STATIC_WHEN_IDLE: Record<string, string> = {
+ 'nt-unread-glow': 'rests at opacity 0; pausing could hide the "finished while you were away" glow',
+ 'nt-working-glow': 'held lit rather than frozen mid-cycle, alongside its two siblings',
+ 'nt-attention-glow': 'held lit rather than frozen mid-cycle, alongside its two siblings'
+}
+
+function readStyles(): string {
+ // Normalized per the repo's line-endings rule: `.gitattributes` only applies on re-checkout, so
+ // a tree cloned before it still has CRLF working files and every `\n` slice below would miss.
+ return fs.readFileSync(STYLES, 'utf8').replace(/\r\n/g, '\n')
+}
+
+/** Every `animation:` shorthand in the file that runs forever, with its line number. */
+function infiniteAnimationLines(css: string): { line: number; text: string }[] {
+ return css
+ .split('\n')
+ .map((text, i) => ({ line: i + 1, text }))
+ .filter((l) => l.text.includes('animation:') && /\binfinite\b/.test(l.text))
+}
+
+describe('idle-window animation gate', () => {
+ const css = readStyles()
+
+ it('defines the variable and the idle state that drive it', () => {
+ expect(css).toContain('--nt-anim-state: running')
+ expect(css).toMatch(/:root\[data-nt-window='idle'\]\s*\{\s*--nt-anim-state:\s*paused/)
+ })
+
+ it('finds the infinite animations at all (a passing scan over nothing proves nothing)', () => {
+ expect(infiniteAnimationLines(css).length).toBeGreaterThan(20)
+ })
+
+ it('gates every infinite animation, or names it in the static-when-idle allowlist', () => {
+ const lines = css.split('\n')
+ const ungated: string[] = []
+
+ for (const { line, text } of infiniteAnimationLines(css)) {
+ const keyframe = Object.keys(STATIC_WHEN_IDLE).find((k) => text.includes(k))
+ if (keyframe) continue
+
+ // The property is either on the same line (single-line rule) or on the next non-blank one.
+ const sameLine = text.includes(PLAY_STATE)
+ const next = (lines[line] ?? '').trim()
+ if (sameLine || next.startsWith(PLAY_STATE)) continue
+
+ ungated.push(`styles.css:${line} ${text.trim()}`)
+ }
+
+ expect(
+ ungated,
+ 'These infinite animations keep the compositor producing frames while nobody is looking at\n' +
+ 'the window, which takes back the whole win of the gate (see the header of this file).\n' +
+ `Add "${PLAY_STATE};" directly after the shorthand, or give the element an explicit\n` +
+ "`:root[data-nt-window='idle']` rule and list its keyframe in STATIC_WHEN_IDLE.\n"
+ ).toEqual([])
+ })
+
+ it('backs every static-when-idle entry with a real idle rule', () => {
+ for (const [keyframe, reason] of Object.entries(STATIC_WHEN_IDLE)) {
+ // The keyframe still has to exist, or the entry is stale and is silently excusing nothing.
+ expect(css, `${keyframe} is allowlisted (${reason}) but has no @keyframes`).toContain(
+ `@keyframes ${keyframe}`
+ )
+ // And the animation it drives must be turned off — not merely paused — while idle.
+ const selector = css.match(
+ new RegExp(`:root\\[data-nt-window='idle'\\][^{]*\\{[^}]*animation:\\s*none[^}]*\\}`, 'g')
+ )
+ expect(selector, `${keyframe} is allowlisted (${reason}) but nothing sets animation: none`)
+ .not.toBeNull()
+ }
+ })
+
+ it('never pauses the notch HUD, whose window is never focused', () => {
+ // hud.css belongs to a separate always-on-top panel window that by design never takes focus,
+ // so the shared gate would freeze it permanently rather than while nobody is looking.
+ const hud = path.join(__dirname, 'hud', 'hud.css')
+ if (!fs.existsSync(hud)) return
+ expect(fs.readFileSync(hud, 'utf8')).not.toContain('--nt-anim-state')
+ })
+})
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 745518432..c81c57788 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -98,6 +98,34 @@
color-scheme: dark;
}
+/* ---- Idle-window animation gate --------------------------------------------------------------
+ Every `infinite` animation in this file is a STATUS or DECORATION — a pulsing dot, a glow, a
+ spinner, a walking mascot. None of them settles, so none of them carries state that is lost by
+ being held still; they exist to catch the eye of somebody who is looking at this window.
+
+ While nobody is (the window is not focused, or the page is hidden), they are pure battery. A
+ running CSS animation obliges the compositor to produce a frame every vsync — 120/s on a
+ ProMotion display — for as long as it runs, and each of those frames re-rasters and re-composites
+ the window. MEASURED on the Server Edition with a 40-terminal canvas, idling for 25 s under
+ headless Chrome: 1.5 % total browser CPU with nothing animating, 33 % with ONE node pulsing,
+ 101 % with twenty. The same twenty with `animation-play-state: paused`: 1.6 %. The step happens
+ at the FIRST animation — what costs is that frames are produced at all — which is why this is
+ applied to every infinite animation in the file rather than to the worst few: one that keeps
+ running holds the frame loop open and the rest of the fix buys nothing. `lib/windowActivity.ts`
+ sets the attribute; `styles.animation-gate.test.ts` fails if a new `infinite` animation is added
+ without joining in.
+
+ `paused` is deliberately not `none`: it freezes each animation where it stands instead of
+ snapping it to its resting frame, so nothing MOVES at the moment the window loses focus, and
+ refocusing resumes rather than restarts. The three node glows below are the one exception. */
+:root {
+ --nt-anim-state: running;
+}
+
+:root[data-nt-window='idle'] {
+ --nt-anim-state: paused;
+}
+
/* ---- Light appearance ----------------------------------------------------------------------
Set by App.tsx from `settings.appTheme` (see lib/appTheme.ts); absent = dark, so an install
that never picks one is byte-for-byte unchanged.
@@ -1059,6 +1087,7 @@ body,
border-color: rgba(255, 69, 58, 0.5);
color: var(--danger);
animation: dictation-pulse 1.4s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.dictation__mic--small {
@@ -1127,6 +1156,7 @@ body,
border-top-color: transparent;
opacity: 0.85;
animation: ui-spin 0.8s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes ui-spin {
to {
@@ -1141,6 +1171,7 @@ body,
border: 2px solid var(--border);
border-top-color: var(--accent);
animation: dictation-spin 0.8s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes dictation-spin {
@@ -1443,6 +1474,36 @@ body,
}
}
+/* The three glows above, while the window is idle (see the animation gate near the top of the
+ file). They do NOT take the shared `--nt-anim-state: paused`, because pausing freezes an
+ animation wherever its clock happened to stop and `nt-unread-glow` rests at `opacity: 0` — a
+ coin flip on whether the glow that says "this agent finished while you were away" is still on
+ screen when you come back to look for it. So each one goes STATIC-LIT instead: no frames, and
+ the state reads at a glance from across the room, which is the whole job of a glow you are not
+ in front of. The value sits between each keyframe's floor and its peak, so the node neither
+ flashes brighter nor drops out at the moment focus leaves.
+
+ `will-change` is dropped with the animation: it is a promise about a property that is about to
+ change, and nothing is about to change any more — holding the compositor layer for every idle
+ working/unread/attention node on a 100-node canvas is exactly the cost this block is removing. */
+:root[data-nt-window='idle'] .react-flow__node:has(.term-node.unread)::after {
+ animation: none;
+ opacity: 0.85;
+ will-change: auto;
+}
+
+:root[data-nt-window='idle'] .react-flow__node:has(.term-node.working)::after {
+ animation: none;
+ opacity: 0.7;
+ will-change: auto;
+}
+
+:root[data-nt-window='idle'] .react-flow__node:has(.term-node.attention)::after {
+ animation: none;
+ opacity: 0.8;
+ will-change: auto;
+}
+
/* 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/
@@ -1664,6 +1725,7 @@ body,
.term-node__status--busy .term-node__status-dot {
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* DRIVING: an agent holds a control lease on this browser node (S8 PR 6). Same clay as RUNNING so
@@ -1677,6 +1739,7 @@ body,
.term-node__status--driven .term-node__status-dot {
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.browser-driving__label {
@@ -1734,6 +1797,7 @@ body,
height: var(--mascot-h);
background-size: calc(var(--mascot-w) * 2) var(--mascot-h);
animation: mascot-walk-claude 0.8s steps(1) infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* Grok, gemini and opencode have no critter: their RUNNING indicator is the brand mark itself,
@@ -1746,6 +1810,7 @@ body,
Agent-neutral by design: no rule below names an agent. */
.term-node__mascot--pulse {
animation: mascot-pulse-brand 1.6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes mascot-pulse-brand {
@@ -1795,6 +1860,7 @@ body,
background-position: 0 0;
background-size: var(--cmascot-sheet-w) var(--cmascot-sheet-h);
animation: mascot-walk-codex 0.96s steps(8) infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes mascot-walk-codex {
@@ -1878,6 +1944,7 @@ body,
.term-node__status--attention .term-node__status-dot {
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.term-node__status--unread {
@@ -2289,6 +2356,7 @@ body,
border: 2px solid var(--border);
border-top-color: var(--accent);
animation: dictation-spin 0.8s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* Drop-target hint while dragging a file from Finder into the terminal. */
@@ -4685,6 +4753,7 @@ body,
.scm-gen.is-generating {
animation: scm-gen-pulse 0.9s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes scm-gen-pulse {
@@ -4876,6 +4945,7 @@ body,
border-top-color: var(--accent);
border-radius: 50%;
animation: ex-dls-spin 0.8s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* Download strip: pinned under the tree, one row per transfer. */
@@ -4947,6 +5017,7 @@ body,
border-top-color: var(--accent);
border-radius: 50%;
animation: ex-dls-spin 0.8s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes ex-dls-spin {
@@ -6286,6 +6357,7 @@ button.group-node__setup:disabled {
.subagent-node.working .subagent-node__dot {
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.subagent-node.done .subagent-node__dot {
@@ -6401,6 +6473,7 @@ button.group-node__setup:disabled {
.loop-node.working .loop-node__dot {
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.loop-node__type {
@@ -6595,10 +6668,12 @@ button.group-node__setup:disabled {
.minimap .mm-working {
filter: drop-shadow(0 0 3px rgba(255, 214, 10, 0.8));
animation: mm-pulse-soft 2.6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.minimap .mm-attention {
filter: drop-shadow(0 0 3px rgba(255, 69, 58, 0.9));
animation: mm-pulse 1.8s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* Unread = clay, the agent-hook colour (RUNNING badge, working glow). Its own keyframes: at
minimap scale a node is a few pixels tall, so opacity alone reads as a faint flicker — the
@@ -6606,6 +6681,7 @@ button.group-node__setup:disabled {
.minimap .mm-unread {
filter: drop-shadow(0 0 4px rgba(217, 119, 87, 0.95));
animation: mm-pulse-unread 1.6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes mm-pulse-unread {
0%,
@@ -6834,7 +6910,7 @@ button.group-node__setup:disabled {
.usage-pill__dim,
.sysres-pill__dim { color: rgba(var(--tint-rgb), 0.5); }
.usage-pill__pulse,
-.sysres-pill__pulse { animation: usage-pulse 1.2s ease-in-out infinite; }
+.sysres-pill__pulse { animation: usage-pulse 1.2s ease-in-out infinite; animation-play-state: var(--nt-anim-state); }
@keyframes usage-pulse { 0%, 100% { opacity: 0.4; } 50% { opacity: 1; } }
/* Expanded: hover, keyboard focus, or an open panel. `width: auto` cannot be transitioned, so the
@@ -6924,7 +7000,7 @@ button.group-node__setup:disabled {
width: 14px;
height: 14px;
}
-.usage-refresh.spin svg { animation: usage-spin 0.9s linear infinite; }
+.usage-refresh.spin svg { animation: usage-spin 0.9s linear infinite; animation-play-state: var(--nt-anim-state); }
@keyframes usage-spin { to { transform: rotate(360deg); } }
.usage-popover {
@@ -7145,6 +7221,7 @@ button.group-node__setup:disabled {
background: var(--success);
/* Reuse the terminal-header badge pulse rather than a bespoke keyframe. */
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.sessmem-row__dot--attention { background: var(--warn); }
.sessmem-row__dot--idle { background: rgba(var(--tint-rgb), 0.3); }
@@ -7267,7 +7344,7 @@ button.group-node__setup:disabled {
.sessmem-panel__refresh:hover { color: var(--text-strong); background: rgba(var(--tint-rgb), 0.08); }
.sessmem-panel__refresh:disabled { opacity: 0.4; cursor: default; }
/* Same spin as the usage panel's refresh. */
-.sessmem-panel__refresh.spin svg { animation: usage-spin 0.9s linear infinite; }
+.sessmem-panel__refresh.spin svg { animation: usage-spin 0.9s linear infinite; animation-play-state: var(--nt-anim-state); }
/* ---- Claude context-window meter (per-node header pill + popover) ---- */
.ctx-meter {
@@ -7615,17 +7692,18 @@ button.group-node__setup:disabled {
.ss-dot--done { background: var(--success); }
.ss-check { color: var(--success); margin-top: 2px; flex: 0 0 auto; line-height: 0; }
/* Unread: the same check, accent-blue and pulsing until the user visits the node. */
-.ss-check--unread { color: var(--accent); animation: nt-pulse 1.1s ease-in-out infinite; }
+.ss-check--unread { color: var(--accent); animation: nt-pulse 1.1s ease-in-out infinite; animation-play-state: var(--nt-anim-state); }
.ss-check svg { width: 13px; height: 13px; }
/* attention renders as a red bell (ss-bell) — "it's ringing for you". Gentle pulse,
same cadence as the header badge dot. */
-.ss-bell { color: var(--danger); margin-top: 2px; flex: 0 0 auto; line-height: 0; animation: nt-pulse 1.1s ease-in-out infinite; }
+.ss-bell { color: var(--danger); margin-top: 2px; flex: 0 0 auto; line-height: 0; animation: nt-pulse 1.1s ease-in-out infinite; animation-play-state: var(--nt-anim-state); }
.ss-bell svg { width: 13px; height: 13px; }
.ss-dot--working {
background: transparent;
border: 2px solid var(--agent-working);
border-top-color: transparent;
animation: nt-spin 1s steps(12, end) infinite;
+ animation-play-state: var(--nt-anim-state);
}
.ss-row__body { min-width: 0; flex: 1; display: flex; flex-direction: column; gap: 2px; }
@@ -7920,6 +7998,7 @@ button.group-node__setup:disabled {
border: 1.5px solid var(--agent-working);
border-top-color: transparent;
animation: nt-spin 1s steps(12, end) infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* Respect the OS setting: spinning ring/arc badges freeze in place rather than
keep animating forever. */
@@ -8204,6 +8283,7 @@ button.group-node__setup:disabled {
width: 35%;
background: var(--accent);
animation: webview-progress-slide 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes webview-progress-slide {
from {
@@ -8403,12 +8483,14 @@ button.group-node__setup:disabled {
color: #d97757;
background: rgba(217, 119, 87, 0.15);
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
/* NEEDS YOU is red everywhere (same as the terminal attention badge). */
.chat-node__badge--needs {
color: var(--danger);
background: rgba(255, 69, 58, 0.15);
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.chat-node__cost {
flex: 0 0 auto;
@@ -8441,6 +8523,7 @@ button.group-node__setup:disabled {
border-radius: 50%;
background: rgba(var(--tint-rgb), 0.55);
animation: chat-typing 1.2s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.chat-node__typing span:nth-child(2) {
animation-delay: 0.15s;
@@ -8899,6 +8982,7 @@ button.group-node__setup:disabled {
warning. It decays ~2s after the last keystroke (TYPING_DECAY_MS, swept in state/presence.ts). */
.presence-chip--typing {
animation: nt-typing-pulse 1.1s ease-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes nt-typing-pulse {
@@ -9824,6 +9908,7 @@ button.group-node__setup:disabled {
background: rgba(50, 215, 75, 0.12);
/* reuse the terminal-header badge pulse (nt-pulse) rather than a bespoke keyframe */
animation: nt-pulse 1.1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.kanban-badge--needs {
color: var(--warn);
@@ -11032,6 +11117,7 @@ button.group-node__setup:disabled {
border-radius: 10px;
background: rgba(163, 141, 255, 0.045);
animation: onb-float 9s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-ghost--a { top: 14%; left: 12%; }
.onb-ghost--b { top: 22%; right: 14%; width: 180px; animation-delay: -3s; }
@@ -11049,6 +11135,7 @@ button.group-node__setup:disabled {
stroke-width: 1.5;
stroke-dasharray: 6 7;
animation: onb-dash 14s linear infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-float {
0%, 100% { transform: translateY(0); }
@@ -11369,6 +11456,7 @@ button.group-node__setup:disabled {
left: 30px;
top: 200px;
animation: onb-cursor-path 7s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.6));
}
@keyframes onb-cursor-path {
@@ -11386,6 +11474,7 @@ button.group-node__setup:disabled {
border: 1.5px solid rgba(163, 141, 255, 0.8);
opacity: 0;
animation: onb-ripple 7s ease-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-ripple {
0%, 16% { opacity: 0; transform: scale(0.3); }
@@ -11404,6 +11493,7 @@ button.group-node__setup:disabled {
opacity: 0;
transform-origin: top left;
animation: onb-menu 7s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-menu {
0%, 19% { opacity: 0; transform: scale(0.92); }
@@ -11416,6 +11506,7 @@ button.group-node__setup:disabled {
}
.onb-menu__hl {
animation: onb-menu-hl 7s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-menu-hl {
0%, 30% { background: transparent; }
@@ -11436,6 +11527,7 @@ button.group-node__setup:disabled {
box-shadow: 0 8px 28px rgba(0, 0, 0, calc(0.4 * var(--shadow-k)));
opacity: 0;
animation: onb-node-pop 7s cubic-bezier(0.34, 1.4, 0.5, 1) infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-node-pop {
0%, 56% { opacity: 0; transform: scale(0.7); }
@@ -11510,6 +11602,7 @@ button.group-node__setup:disabled {
font-size: 15px;
font-weight: 600;
animation: onb-keypress 8s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-kbd--hold {
animation-name: onb-keyhold;
@@ -11530,6 +11623,7 @@ button.group-node__setup:disabled {
margin-left: 4px;
opacity: 0;
animation: onb-holdhint 8s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-holdhint {
0%, 5% { opacity: 0; }
@@ -11540,6 +11634,7 @@ button.group-node__setup:disabled {
.onb-mic-wrap {
opacity: 0;
animation: onb-micgate 8s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-micgate {
0%, 6% { opacity: 0; transform: scale(0.9); }
@@ -11562,6 +11657,7 @@ button.group-node__setup:disabled {
border-radius: 50%;
border: 1.5px solid rgba(255, 55, 95, 0.5);
animation: onb-ring 2.4s ease-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-mic__ring--late {
animation-delay: 1.2s;
@@ -11582,6 +11678,7 @@ button.group-node__setup:disabled {
border-radius: 2px;
background: rgba(255, 55, 95, 0.85);
animation: onb-wave 1s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-wave {
0%, 100% { height: 6px; }
@@ -11608,6 +11705,7 @@ button.group-node__setup:disabled {
white-space: nowrap;
max-width: 0;
animation: onb-type 8s steps(32) infinite;
+ animation-play-state: var(--nt-anim-state);
color: rgba(235, 235, 245, 0.85);
}
/* types only AFTER the release (58%) — the transcription arrives when you let go */
@@ -11620,6 +11718,7 @@ button.group-node__setup:disabled {
height: 13px;
background: rgba(235, 235, 245, 0.8);
animation: onb-caret 1s steps(1) infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-caret {
50% { opacity: 0; }
@@ -11742,6 +11841,7 @@ button.group-node__setup:disabled {
background: var(--canvas-bg);
border-radius: 0 0 10px 10px;
animation: onb-capsule 6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-capsule__left {
display: flex;
@@ -11759,6 +11859,7 @@ button.group-node__setup:disabled {
border-radius: 50%;
background: rgb(48, 209, 88);
animation: onb-blob 1.6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-capsule {
0%, 10% { padding-right: 8px; }
@@ -11781,6 +11882,7 @@ button.group-node__setup:disabled {
border-radius: 0 0 12px 12px;
transform-origin: top center;
animation: onb-notchpanel 6s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-notchpanel__row {
display: flex;
@@ -11813,6 +11915,7 @@ button.group-node__setup:disabled {
color: rgba(235, 235, 245, 0.45);
transform-origin: top center;
animation: onb-bell 5s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-bell {
0%, 8% { transform: rotate(0); }
@@ -11832,6 +11935,7 @@ button.group-node__setup:disabled {
padding: 10px 12px;
box-shadow: 0 14px 36px rgba(0, 0, 0, calc(0.5 * var(--shadow-k)));
animation: onb-notif 5s ease infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-notif {
0%, 6% { opacity: 0; transform: translateX(60px); }
@@ -11882,6 +11986,7 @@ button.group-node__setup:disabled {
box-shadow: 0 18px 50px rgba(0, 0, 0, calc(0.55 * var(--shadow-k)));
padding: 28px 10px 12px;
animation: onb-float 7s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
.onb-phone__notch {
position: absolute;
@@ -11943,6 +12048,7 @@ button.group-node__setup:disabled {
border-radius: 999px;
box-shadow: 0 8px 20px rgba(0, 0, 0, calc(0.4 * var(--shadow-k)));
animation: onb-soon 3.2s ease-in-out infinite;
+ animation-play-state: var(--nt-anim-state);
}
@keyframes onb-soon {
0%, 100% { transform: rotate(8deg) scale(1); }