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.

fix(wallpaper): aerial layer without a new stacking context; pause when idle

iceclatterWT43879adf5a4d
diff --git a/CLAUDE.md b/CLAUDE.md
index 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, so
it 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 the
image the user chose. Only hash-named full-size files are candidates; thumbnails, temps and
diff --git a/src/core/wallpaper.test.ts b/src/core/wallpaper.test.ts
index 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.ts
index 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() : null
if (!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.tsx
index 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 />
<TabBar
onSwitch={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.tsx
index 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 : null
const shuffle = !!id && parseAerialId(id)!.shuffle
const 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) return
let live = true
+ failedRef.current = new Set()
window.nodeTerminal.wallpaper
.aerialClips({ kind: 'preset', id })
.then((clips) => {
+ clipsRef.current = clips
const 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.J
if (!el) return
const root = document.documentElement
const 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 = 0
void 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}
+ <div
className={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.css
index 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.ts
index 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)