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
fix(wallpaper): aerial layer without a new stacking context; pause when idle
iceclatterWT43879adf5a4d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2a77ea762..2691497d0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -7101,14 +7101,18 @@ glass never sits over plain black; a wallpaper the user chose is never replaced.regular files; the renderer never names a path. Videos stream through nt-media:// via the`setWallpaperMediaUrl` seam (main registers `allowMediaPath`; the Server Edition registers none, soit lists no aerials). Never downloaded, never bundled. `load` returns the 214×130 thumbnail as the- CSS still; `AerialWallpaper.tsx` puts a muted `<video>` above it (z-index −1; `.canvas-root`- isolates only while it holds one) on the canvas and, under Liquid Glass, the boards. A category or- aerial with no downloaded clip of its own plays ANY downloaded aerial — the upscaled thumbnail read- as a blurry regression in live review — so the thumbnail is the picture only with nothing- downloaded at all or a load error. Reduce Motion mounts the video paused (a full-resolution frame).- Paused while `document.hidden` and, for the canvas layer, while a board covers it. MEASURED (4K- 240 fps HEVC Dubai clip, M-series, Liquid Glass + one terminal): GPU process ~72 % vs ~0 % on a- still, renderer ~3 % vs ~0 %.+ still; `AerialWallpaper.tsx` paints still + muted `<video>` on a `position: fixed`, z-index auto+ layer rendered as the SIBLING before `.canvas-root` (which then paints no background), so NO new+ stacking context is created and every panel/portal stacks exactly as over a still — an earlier+ `isolation: isolate` on the root changed portal-vs-chrome order (review of 095cf396). Under Liquid+ Glass each board renders its own layer (z −1 inside the overlay) and picks its own clip. Clip+ choice: the category's shuffle clips, else its other downloaded clips, else ANY downloaded aerial+ — the upscaled thumbnail read as a blurry regression in live review — so the thumbnail is the+ picture only with nothing downloaded at all or every clip failing. Reduce Motion mounts the video+ paused (a full-resolution frame). Paused while `data-nt-window="idle"` (unfocused or hidden — the+ CSS animation gate's signal) and, for the canvas layer, while a board covers it. MEASURED (4K+ 240 fps HEVC Dubai clip, M-series, Liquid Glass + one terminal): GPU process ~70 % playing, ~0.1 %+ idle-paused or on a still; renderer ~3 % vs ~0 %.- **The cache is pruned on a SAVED change and on import, never at boot.** `SettingsStore.init`answers an unreadable settings.json with the defaults, and pruning against that would delete theimage the user chose. Only hash-named full-size files are candidates; thumbnails, temps anddiff --git a/src/core/wallpaper.test.ts b/src/core/wallpaper.test.tsindex 908aa22b1..2b1daf335 100644--- a/src/core/wallpaper.test.ts+++ b/src/core/wallpaper.test.ts@@ -322,6 +322,13 @@ describe('macOS aerials', () => {expect(await loadWallpaper(unknown)).toBeNull()})+ it('a shuffle with no includeInShuffle clip downloaded plays its own category before any other', async () => {+ const r = fixture()+ const video = (id: string): string => url(path.join(r, 'videos', `${id}.mov`))+ rmSync(path.join(r, 'videos', `${A1}.mov`)) // Landscapes' only shuffle clip; A3 is not in shuffle+ expect(await aerialClips({ kind: 'preset', id: `aerial-shuffle:${L}` })).toEqual([video(A3)])+ })+it('with none of its own downloaded, any downloaded aerial plays; nothing at all = empty', async () => {const r = fixture()const video = (id: string): string => url(path.join(r, 'videos', `${id}.mov`))diff --git a/src/core/wallpaper.ts b/src/core/wallpaper.tsindex 1a8f3a085..49f3d5c85 100644--- a/src/core/wallpaper.ts+++ b/src/core/wallpaper.ts@@ -580,7 +580,7 @@ export async function listAerials(): Promise<WallpaperStill[]> {/*** The clips an aerial wallpaper plays: its own downloaded ones (a shuffle's only if- * `includeInShuffle`). When it has none — a category macOS has not downloaded anything for, or a+ * `includeInShuffle`, else any of the category's downloaded ones). When it has none — a category macOS has not downloaded anything for, or a* single aerial macOS has since deleted — ANY downloaded aerial plays instead: the thumbnail is a* 214×130 PNG, and stretched over the window it reads as a blurry regression, not a wallpaper. Only* with nothing downloaded at all is the list empty (the thumbnail then shows).@@ -590,8 +590,12 @@ export async function aerialClips(value: unknown): Promise<string[]> {const s = w.kind === 'preset' && parseAerialId(w.id) ? await aerialScan() : nullif (!s || w.kind !== 'preset') return []const shuffle = parseAerialId(w.id)!.shuffle- const own = aerialMembers(s.scan, w.id).filter((a) => s.scan.downloaded.has(a.id) && (!shuffle || a.includeInShuffle))- const clips = own.length ? own : s.scan.assets.filter((a) => s.scan.downloaded.has(a.id))+ const downloaded = aerialMembers(s.scan, w.id).filter((a) => s.scan.downloaded.has(a.id))+ const own = shuffle ? downloaded.filter((a) => a.includeInShuffle) : downloaded+ // A category whose downloaded clips are all left out of macOS's shuffle still plays its own+ // before anything from another category.+ const fallback = own.length ? own : downloaded+ const clips = fallback.length ? fallback : s.scan.assets.filter((a) => s.scan.downloaded.has(a.id))return clips.map((a) => s.url(path.join(s.root, 'videos', `${a.id}.mov`)))}diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 67b8539c0..f41ef84c6 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -976,7 +976,7 @@ import type { TeamStation } from '../lib/teamProgress'import { canvasTeamStations, useTeamStations } from '../state/teamStations'import { applyPullAutoMove } from '../lib/pullAutoMove'import { useWallpaperBackground, wallpaperLayers } from '../state/wallpaper'-import { AerialWallpaper } from '../components/AerialWallpaper'+import { AerialWallpaper, useIsAerialWallpaper } from '../components/AerialWallpaper'import { showCanvasDots } from '../lib/canvasDots'import { PROJECT_NAME_MAX, clampProjectName } from '@shared/project-name'@@ -1402,12 +1402,16 @@ export function Canvas() {// transformed, so it stays fixed while the canvas pans and zooms. React Flow's own root goes// transparent over it (`.react-flow.has-wallpaper`).const wallpaperBg = useWallpaperBackground()+ // An aerial paints its still and video on its own layer before the root (AerialWallpaper), so the+ // root paints nothing — and it is a wallpaper even when its thumbnail is missing.+ const aerialWallpaper = useIsAerialWallpaper()+ const hasWallpaper = !!wallpaperBg || aerialWallpaper// Memoised: Canvas re-renders on every drag frame, and a fresh style object would make React// re-diff (and a multi-MB data: URL re-compare) the root's style each time.const wallpaperStyle = useMemo<React.CSSProperties | undefined>(() =>- wallpaperBg ? wallpaperLayers(wallpaperBg) : undefined,- [wallpaperBg]+ wallpaperBg && !aerialWallpaper ? wallpaperLayers(wallpaperBg) : undefined,+ [wallpaperBg, aerialWallpaper])const [nodes, setNodes, onNodesChange] = useNodesState<CanvasNode>([])// Persistent context links between Claude nodes (separate from ephemeral subagent/loop edges).@@ -19259,8 +19263,11 @@ export function Canvas() {const paletteChip = chipFor('app.commandPalette')return (+ <>+ {/* An aerial wallpaper paints as a fixed layer BEFORE the root (the root then paints no+ background), so it needs no stacking context of its own — see AerialWallpaper. */}+ <AerialWallpaper /><div className="canvas-root" style={wallpaperStyle}>- <AerialWallpaper /><TabBaronSwitch={switchProject}onReconnect={reconnectRelay}@@ -19639,7 +19646,7 @@ export function Canvas() {the key is always 'local', so this never remounts — zero behavior change. */}<SessionProvider session={sessionForProject(activeProjectId || '')} key={sessionForProject(activeProjectId || '').id}><ReactFlow- className={wallpaperBg ? 'has-wallpaper' : undefined}+ className={hasWallpaper ? 'has-wallpaper' : undefined}nodes={allNodes}edges={displayEdges}nodeTypes={nodeTypes}@@ -20576,5 +20583,6 @@ export function Canvas() {)}</div></div>+ </>)}diff --git a/src/renderer/components/AerialWallpaper.tsx b/src/renderer/components/AerialWallpaper.tsxindex e29e96790..4163cb2f1 100644--- a/src/renderer/components/AerialWallpaper.tsx+++ b/src/renderer/components/AerialWallpaper.tsx@@ -1,7 +1,9 @@-import { useEffect, useRef, useState, useSyncExternalStore } from 'react'-import { nextShuffleClip, normalizeWallpaper, parseAerialId } from '@shared/wallpaper'+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'+import { isAerialWallpaper, nextShuffleClip, normalizeWallpaper, parseAerialId } from '@shared/wallpaper'import { CANVAS_COVERED_ATTR } from '../lib/canvasCovered'+import { WINDOW_ACTIVITY_ATTR } from '../lib/windowActivity'import { useSettings } from '../state/settings'+import { useWallpaperBackground, wallpaperLayers } from '../state/wallpaper'const REDUCED_MOTION = '(prefers-reduced-motion: reduce)'const motionQuery = (): MediaQueryList | null =>@@ -19,42 +21,58 @@ function useReducedMotion(): boolean {}/**- * The moving half of an aerial wallpaper (`aerial:` / `aerial-shuffle:`): a muted `<video>` layer- * right above the wallpaper's CSS background (which holds the aerial's thumbnail still) and below- * everything else, so the glass and tint layers sit on it exactly as they sit on a still. Renders- * nothing for any other wallpaper, before the first clip resolves, with no downloaded clip at all,- * or after a load error — in those cases the thumbnail still shows, never black. Under Reduce- * Motion the video is mounted but never played: its first frame is a full-resolution still, where- * the thumbnail is a 214×130 PNG.+ * An aerial wallpaper (`aerial:` / `aerial-shuffle:`): the aerial's thumbnail still with a muted+ * `<video>` over it. Renders nothing for any other wallpaper.+ *+ * Canvas layer (`board` false): a `position: fixed` layer rendered as the SIBLING right before+ * `.canvas-root`, which then paints no background of its own. It has `z-index: auto`, so it creates+ * no stacking context and everything inside `.canvas-root` paints over it exactly as it painted over+ * the root's own background — the stacking of every panel, portal and the tab bar is identical to a+ * still wallpaper's. The layer carries the still (and the `--canvas-bg` colour under it), so a clip+ * that is loading, failed, or never existed leaves the still on screen, never black.+ *+ * Board layer (`board` true, Liquid Glass only): fixed to the viewport at `z-index: -1` inside the+ * kanban overlay, which is a stacking context already (fixed, z 25) and paints the still itself.+ * The board picks its OWN clip and starts it from the beginning; it does not continue the canvas+ * layer's clip or position (the canvas layer is paused while a board covers it).** The clips are nt-media: URLs core minted from its own manifest scan (`wallpaper.aerialClips`).- * A single aerial loops; a shuffle asks core again when a clip ends (macOS downloads more over- * time) and plays a random other one. Paused while the document is hidden, and the canvas's layer- * also while a board covers the canvas — the board plays its own (`board`), and two 4K HEVC- * decodes for one visible picture is pure waste.+ * A single aerial loops; a shuffle asks core again when a clip ends (macOS downloads more over time)+ * and plays a random other one. A clip that fails to load is skipped once for another clip; with+ * none left, the still shows. Under Reduce Motion the video is mounted but never played: its first+ * frame is a full-resolution still, where the thumbnail is a 214×130 PNG.*- * `board`: the kanban overlay's layer, fixed to the viewport so it lines up with the canvas's.+ * Paused whenever nobody is looking: the window is hidden or unfocused (`data-nt-window="idle"`,+ * the same gate that freezes every CSS animation — a decoding 4K clip keeps the GPU busy like one),+ * and the canvas layer also while a board covers the canvas.*/export function AerialWallpaper({ board = false }: { board?: boolean }): React.JSX.Element | null {const w = normalizeWallpaper(useSettings((s) => s.settings.desktopWallpaper))const id = w.kind === 'preset' && parseAerialId(w.id) ? w.id : nullconst shuffle = !!id && parseAerialId(id)!.shuffleconst reduced = useReducedMotion()+ const still = useWallpaperBackground()const [clip, setClip] = useState<{ id: string; src: string } | null>(null)const ref = useRef<HTMLVideoElement>(null)+ // The last clip list core answered, and the clips that failed to load this episode.+ const clipsRef = useRef<string[]>([])+ const failedRef = useRef<Set<string>>(new Set())useEffect(() => {if (!id) returnlet live = true+ failedRef.current = new Set()window.nodeTerminal.wallpaper.aerialClips({ kind: 'preset', id }).then((clips) => {+ clipsRef.current = clipsconst src = nextShuffleClip(clips, null)if (live) setClip(src ? { id, src } : null)}).catch(() => live && setClip(null))return () => {live = false+ setClip(null)}}, [id])@@ -65,29 +83,54 @@ export function AerialWallpaper({ board = false }: { board?: boolean }): React.Jif (!el) returnconst root = document.documentElementconst sync = (): void => {- if (reduced || document.hidden || (!board && root.hasAttribute(CANVAS_COVERED_ATTR))) el.pause()+ const away = document.hidden || root.getAttribute(WINDOW_ACTIVITY_ATTR) === 'idle'+ if (reduced || away || (!board && root.hasAttribute(CANVAS_COVERED_ATTR))) el.pause()else void el.play().catch(() => {})}sync()document.addEventListener('visibilitychange', sync)- const covered = board ? null : new MutationObserver(sync)- covered?.observe(root, { attributes: true, attributeFilter: [CANVAS_COVERED_ATTR] })+ const watch = new MutationObserver(sync)+ watch.observe(root, {+ attributes: true,+ attributeFilter: board ? [WINDOW_ACTIVITY_ATTR] : [WINDOW_ACTIVITY_ATTR, CANVAS_COVERED_ATTR]+ })return () => {document.removeEventListener('visibilitychange', sync)- covered?.disconnect()+ watch.disconnect()}}, [src, board, reduced])- if (!id || !src) return null+ // Release the decoder when the clip changes or the layer goes: a detached <video> keeps its+ // media resource (and a hardware HEVC decoder) until its src is dropped and it reloads.+ useEffect(() => {+ const el = ref.current+ return () => {+ if (!el) return+ el.pause()+ el.removeAttribute('src')+ el.load()+ }+ }, [src])- const onEnded = (): void => {+ const layerStyle = useMemo<React.CSSProperties | undefined>(+ () => (board ? undefined : still ? wallpaperLayers(still) : { backgroundColor: 'var(--canvas-bg)' }),+ [board, still]+ )++ if (!id) return null++ /** Move on from `from` (ended, or failed): the next clip core lists, else the still. */+ const advance = (from: string, failed: boolean): void => {const playing = id+ if (failed) failedRef.current.add(from)void window.nodeTerminal.wallpaper.aerialClips({ kind: 'preset', id: playing })- .catch(() => [] as string[])+ .catch(() => clipsRef.current).then((clips) => {- const next = nextShuffleClip(clips, src)- if (next === src && ref.current) {+ clipsRef.current = clips+ const usable = clips.filter((c) => !failedRef.current.has(c))+ const next = nextShuffleClip(usable, from)+ if (next === from && ref.current) {ref.current.currentTime = 0void ref.current.play().catch(() => {})} else {@@ -97,20 +140,31 @@ export function AerialWallpaper({ board = false }: { board?: boolean }): React.J}return (- <video- ref={ref}- key={src}- src={src}+ <divclassName={board ? 'aerial-wallpaper aerial-wallpaper--board' : 'aerial-wallpaper'}+ style={layerStyle}aria-hidden- tabIndex={-1}- muted- autoPlay={!reduced}- preload="auto"- playsInline- loop={!shuffle}- onEnded={shuffle ? onEnded : undefined}- onError={() => setClip(null)}- />+ >+ {src && (+ <video+ ref={ref}+ key={src}+ src={src}+ tabIndex={-1}+ muted+ autoPlay={!reduced}+ preload="auto"+ playsInline+ loop={!shuffle}+ onEnded={shuffle ? () => advance(src, false) : undefined}+ onError={() => (shuffle ? advance(src, true) : setClip(null))}+ />+ )}+ </div>)}++/** Whether the setting names an aerial, for callers that only need to know (the canvas root). */+export function useIsAerialWallpaper(): boolean {+ return isAerialWallpaper(useSettings((s) => s.settings.desktopWallpaper))+}diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex 55b55f5ff..f9a38f536 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -4368,25 +4368,25 @@ body,.react-flow.has-wallpaper .react-flow__background {opacity: 0.3;}-/* An aerial wallpaper's <video> (AerialWallpaper.tsx): z-index -1 paints it ABOVE its host's- background (the aerial's still) and BELOW all the host's content. `.canvas-root` is no stacking- context of its own, so it becomes one only while it holds the layer — every other wallpaper- leaves the root exactly as before. `.kanban-overlay` is one already (fixed, z-index 25); its layer- is fixed to the viewport so it lines up with the canvas's, like the board's still. */+/* An aerial wallpaper's layer (AerialWallpaper.tsx). The canvas layer is a fixed SIBLING before+ `.canvas-root` with z-index auto: it creates no stacking context, and the root (positioned, later+ in tree order) paints all of its content over it, exactly as over its own background. The board+ layer sits inside `.kanban-overlay` (a stacking context already: fixed, z 25) at z-index -1, above+ the overlay's still and below its content, fixed to the viewport like the board's still. */.aerial-wallpaper {- position: absolute;+ position: fixed;inset: 0;- width: 100%;- height: 100%;- object-fit: cover;- z-index: -1;pointer-events: none;}.aerial-wallpaper--board {- position: fixed;+ z-index: -1;}-.canvas-root:has(> .aerial-wallpaper) {- isolation: isolate;+.aerial-wallpaper > video {+ position: absolute;+ inset: 0;+ width: 100%;+ height: 100%;+ object-fit: cover;}.flow-wrap {diff --git a/src/shared/wallpaper.ts b/src/shared/wallpaper.tsindex d12f7863e..6c3f4aef8 100644--- a/src/shared/wallpaper.ts+++ b/src/shared/wallpaper.ts@@ -108,6 +108,12 @@ export function isAerialUuid(s: string): boolean {return UUID.test(s)}+/** Does this (hand-editable) setting name an aerial wallpaper? */+export function isAerialWallpaper(raw: unknown): boolean {+ const w = normalizeWallpaper(raw)+ return w.kind === 'preset' && parseAerialId(w.id) !== null+}+/** The UUID an aerial id names and whether it is a shuffle, or null for any other id. */export function parseAerialId(id: string): { uuid: string; shuffle: boolean } | null {const shuffle = id.startsWith(AERIAL_SHUFFLE_PREFIX)