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
feat(wallpaper): macOS Aerial video wallpapers, single and Shuffle <category>
iceclatterWT095cf3968e6e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 3e8e3bdaa..2a77ea762 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -7094,6 +7094,21 @@ glass never sits over plain black; a wallpaper the user chose is never replaced.ops, Windows lists `%WINDIR%\Web\Wallpaper` stills as `win:` ids (same re-resolve-against-a-scanjail as `mac:`). nativeImage decodes no HEIC (`canHeic:false`, still refused) and cannot measureWebP, so an unmeasurable file is COPIED there (`convertUnknownSize:false`), never handed to it.+- **macOS Aerials are `aerial:<asset UUID>` / `aerial-shuffle:<category UUID>` presets** (UUID-only+ after the prefix, else `none`). Core reads `~/Library/Application Support/com.apple.wallpaper/aerials`+ (`manifest/entries.json`, `videos/<id>.mov` = only what macOS downloaded, `thumbnails/<id>.png`)+ with a FRESH scan per call and allowlists only those two shapes built from manifest UUIDs found as+ 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 %.- **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 1425ea1b5..908aa22b1 100644--- a/src/core/wallpaper.test.ts+++ b/src/core/wallpaper.test.ts@@ -5,7 +5,12 @@ import { afterEach, describe, expect, it } from 'vitest'import { existsSync, readdirSync } from 'node:fs'import { wallpapersToKeep } from '../shared/wallpaper'import {+ aerialClips,cachedImagePath,+ listAerials,+ parseAerialManifest,+ scanAerials,+ setWallpaperMediaUrl,importWallpaper,listStills,loadWallpaper,@@ -232,3 +237,108 @@ describe('sipsImageOps', () => {expect(sipsImageOps.convertUnknownSize).toBe(true)})})++describe('macOS aerials', () => {+ const L = 'A33A55D9-EDEA-4596-A850-6C10B54FBBB5' // Landscapes+ const C = '5EF41171-4862-4F93-800C-AD86CE5E6891' // Cities+ const [A1, A2, A3, B1] = [+ '11111111-1111-4111-8111-111111111111',+ '22222222-2222-4222-8222-222222222222',+ '33333333-3333-4333-8333-333333333333',+ '44444444-4444-4444-8444-444444444444'+ ]+ const manifest = {+ categories: [+ { id: C, localizedNameKey: 'AerialCategoryCities', preferredOrder: 1 },+ { id: L, localizedNameKey: 'AerialCategoryLandscapes', preferredOrder: 0 },+ { id: 'not-a-uuid', localizedNameKey: 'AerialCategoryBad', preferredOrder: 2 }+ ],+ assets: [+ { id: A1, accessibilityLabel: 'Tahoe Night', categories: [L], includeInShuffle: true, preferredOrder: 5 },+ { id: A2, accessibilityLabel: 'Tahoe Day', categories: [L], includeInShuffle: true, preferredOrder: 1 },+ { id: A3, accessibilityLabel: 'Hidden Gem', categories: [L], includeInShuffle: false, preferredOrder: 3 },+ { id: B1, accessibilityLabel: 'Dubai', categories: [C], includeInShuffle: true, preferredOrder: 2 },+ { id: '../../etc/passwd', accessibilityLabel: 'Evil', categories: [L], includeInShuffle: true, preferredOrder: 0 }+ ]+ }+ const url = (p: string): string => `nt-media://media${p}`+ const fixture = (): string => {+ root = mkdtempSync(path.join(tmpdir(), 'aerials-'))+ put('manifest/entries.json', 0)+ writeFileSync(path.join(root, 'manifest/entries.json'), JSON.stringify(manifest))+ for (const id of [A1, A3, B1]) put(`videos/${id}.mov`, 10)+ put(`videos/${A2}.mov.download`, 10) // a partial download is not a clip+ put('videos/notes.txt', 10)+ for (const id of [A1, A2, A3, B1]) put(`thumbnails/${id}.png`, 10)+ setWallpaperHostForTests({ platform: 'darwin', aerialsRoot: root })+ setWallpaperMediaUrl(url)+ return root+ }+ afterEach(() => setWallpaperHostForTests(null))++ it('parses categories and assets by preferredOrder; malformed ids drop', () => {+ const m = parseAerialManifest(manifest)+ expect(m.categories.map((c) => c.label)).toEqual(['Landscapes', 'Cities'])+ expect(m.assets.map((a) => a.label)).toEqual(['Tahoe Day', 'Dubai', 'Hidden Gem', 'Tahoe Night'])+ expect(parseAerialManifest(null)).toEqual({ categories: [], assets: [] })+ })++ it('scan: only <UUID>.mov regular files count as downloaded', async () => {+ const r = fixture()+ const scan = await scanAerials(r)+ expect([...scan!.downloaded].sort()).toEqual([A1, A3, B1].sort())+ expect(scan!.thumbs.size).toBe(4)+ expect(await scanAerials(path.join(r, 'missing'))).toBeNull()+ })++ it('lists a shuffle per category (still = first by preferredOrder), then each downloaded aerial', async () => {+ const r = fixture()+ const list = await listAerials()+ expect(list.map((t) => [t.id, t.label])).toEqual([+ [`aerial-shuffle:${L}`, 'Shuffle Landscapes'],+ [`aerial-shuffle:${C}`, 'Shuffle Cities'],+ [`aerial:${A3}`, 'Hidden Gem'],+ [`aerial:${A1}`, 'Tahoe Night'],+ [`aerial:${B1}`, 'Dubai']+ ])+ expect(list[0].thumb).toBe(url(path.join(r, 'thumbnails', `${A2}.png`)))+ })++ it('shuffle clips: downloaded AND includeInShuffle, re-scanned per call; single = that clip', async () => {+ const r = fixture()+ const video = (id: string): string => url(path.join(r, 'videos', `${id}.mov`))+ expect(await aerialClips({ kind: 'preset', id: `aerial-shuffle:${L}` })).toEqual([video(A1)])+ expect(await aerialClips({ kind: 'preset', id: `aerial:${A3}` })).toEqual([video(A3)])+ put(`videos/${A2}.mov`, 10) // macOS downloaded another one+ expect(await aerialClips({ kind: 'preset', id: `aerial-shuffle:${L}` })).toEqual([video(A2), video(A1)])+ })++ it('the still is the first member thumbnail; unknown ids load nothing', async () => {+ const r = fixture()+ expect(await loadWallpaper({ kind: 'preset', id: `aerial-shuffle:${C}` })).toBe(+ url(path.join(r, 'thumbnails', `${B1}.png`))+ )+ const unknown = { kind: 'preset', id: 'aerial-shuffle:99999999-9999-4999-8999-999999999999' }+ expect(await loadWallpaper(unknown)).toBeNull()+ })++ 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`))+ rmSync(path.join(r, 'videos', `${B1}.mov`)) // Cities now has nothing downloaded+ expect(await aerialClips({ kind: 'preset', id: `aerial-shuffle:${C}` })).toEqual([video(A3), video(A1)])+ expect(await aerialClips({ kind: 'preset', id: `aerial:${A2}` })).toEqual([video(A3), video(A1)])+ rmSync(path.join(r, 'videos'), { recursive: true, force: true })+ expect(await aerialClips({ kind: 'preset', id: `aerial-shuffle:${L}` })).toEqual([])+ })++ it('off macOS, or with no media URL minter (the Server Edition), there are no aerials', async () => {+ fixture()+ setWallpaperMediaUrl(null)+ expect(await listAerials()).toEqual([])+ expect(await aerialClips({ kind: 'preset', id: `aerial:${A1}` })).toEqual([])+ setWallpaperHostForTests({ platform: 'linux', aerialsRoot: root! })+ setWallpaperMediaUrl(url)+ expect(await listAerials()).toEqual([])+ })+})diff --git a/src/core/wallpaper.ts b/src/core/wallpaper.tsindex ab9fb1409..1a8f3a085 100644--- a/src/core/wallpaper.ts+++ b/src/core/wallpaper.ts@@ -1,11 +1,16 @@import { execFile } from 'node:child_process'import { createHash } from 'node:crypto'-import { copyFile, mkdir, open, readdir, stat, unlink } from 'node:fs/promises'+import { copyFile, mkdir, open, readdir, readFile, stat, unlink } from 'node:fs/promises'+import { homedir } from 'node:os'import path from 'node:path'import { promisify } from 'node:util'import { IPC } from '../shared/ipc'import {+ AERIAL_SHUFFLE_PREFIX,+ AERIAL_PREFIX,+ isAerialUuid,normalizeWallpaper,+ parseAerialId,wallpapersToKeep,type DesktopWallpaper,type WallpaperStill@@ -81,7 +86,10 @@ export interface WallpaperHost {env: Record<string, string | undefined>/** Tests only: the Windows stills root, bypassing `windowsWallpaperRoot(env)`. */windowsStillsRoot?: string+ /** Tests only: the macOS Aerials root, bypassing the real `~/Library/...` one. */+ aerialsRoot?: string}+let mediaUrl: ((absPath: string) => string) | null = nulllet host: () => WallpaperHost = () => ({ platform: process.platform, env: process.env })let registeredOps: WallpaperImageOps | null = null@@ -91,16 +99,27 @@ export function setWallpaperImageOps(ops: WallpaperImageOps | null): void {stillScan = null}+/**+ * The shell's way to hand the page a local file by URL: Electron's `allowMediaPath` (nt-media://,+ * streamed with Range so a 400 MB clip is never read whole). Core may not import electron. With+ * none (the Server Edition) there are no aerials — the viewer's browser could not reach the files.+ */+export function setWallpaperMediaUrl(fn: ((absPath: string) => string) | null): void {+ mediaUrl = fn+}+/** Tests only: pretend to be another OS / environment, and forget the memoized scan. */export function setWallpaperHostForTests(next: Partial<WallpaperHost> | null): void {host = next? () => ({platform: next.platform ?? process.platform,env: next.env ?? process.env,- windowsStillsRoot: next.windowsStillsRoot+ windowsStillsRoot: next.windowsStillsRoot,+ aerialsRoot: next.aerialsRoot}): () => ({ platform: process.platform, env: process.env })registeredOps = null+ mediaUrl = nullstillScan = null}@@ -324,6 +343,7 @@ export async function loadWallpaper(value: unknown): Promise<string | null> {.then(toDataUrl).catch(() => null)}+ if (w.kind === 'preset' && parseAerialId(w.id)) return aerialStill(w.id)return null}@@ -417,6 +437,170 @@ export async function pruneWallpaperCache(keep: unknown[], dir = wallpaperCacheD}}+/*+ * macOS Aerials (the moving wallpapers). macOS 26 keeps them under one root:+ * `manifest/entries.json` (every asset and category Apple offers), `videos/<asset UUID>.mov` (ONLY+ * what macOS has downloaded — the user downloads more in System Settings → Wallpaper) and+ * `thumbnails/<asset UUID>.png` (small stills, present for all). We never download anything.+ *+ * The jail is the same shape as the stills': the page names an aerial by `aerial:` /+ * `aerial-shuffle:` + UUID, core re-resolves it against a FRESH manifest scan, and the only paths+ * ever allowlisted are `<root>/videos/<id>.mov` and `<root>/thumbnails/<id>.png` built from a+ * UUID-shaped manifest id and found as a regular file by `readdir` (a symlink is not a file there,+ * and nt-media refuses one at serve time anyway). The pre-Sonoma `idleassetsd` layout has no+ * thumbnails, so it is not read (ponytail: add it as a second root if anyone runs an older macOS).+ */++export function aerialsRoot(): string {+ return host().aerialsRoot ?? path.join(homedir(), 'Library', 'Application Support', 'com.apple.wallpaper', 'aerials')+}++export interface AerialAsset {+ id: string+ label: string+ categories: string[]+ includeInShuffle: boolean+ order: number+}++export interface AerialCategory {+ id: string+ /** `AerialCategoryLandscapes` → `Landscapes`. */+ label: string+ order: number+}++export interface AerialScan {+ categories: AerialCategory[]+ assets: AerialAsset[]+ /** Asset ids with a `videos/<id>.mov` on disk. */+ downloaded: Set<string>+ /** Asset ids with a `thumbnails/<id>.png` on disk. */+ thumbs: Set<string>+}++const orderOf = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : Number.MAX_SAFE_INTEGER)++/** The parts of `entries.json` we use, both lists sorted by `preferredOrder`. Malformed rows drop. */+export function parseAerialManifest(json: unknown): Pick<AerialScan, 'categories' | 'assets'> {+ const o = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>+ const rows = (v: unknown): Record<string, unknown>[] =>+ Array.isArray(v) ? v.filter((r): r is Record<string, unknown> => !!r && typeof r === 'object') : []+ const categories = rows(o.categories)+ .filter((c) => typeof c.id === 'string' && isAerialUuid(c.id) && typeof c.localizedNameKey === 'string')+ .map((c) => ({+ id: c.id as string,+ label: (c.localizedNameKey as string).replace(/^AerialCategory/, ''),+ order: orderOf(c.preferredOrder)+ }))+ .filter((c) => c.label.length > 0)+ .sort((a, b) => a.order - b.order)+ const assets = rows(o.assets)+ .filter((a) => typeof a.id === 'string' && isAerialUuid(a.id))+ .map((a) => ({+ id: a.id as string,+ label: typeof a.accessibilityLabel === 'string' && a.accessibilityLabel ? a.accessibilityLabel : 'Aerial',+ categories: Array.isArray(a.categories) ? a.categories.filter((c): c is string => typeof c === 'string') : [],+ includeInShuffle: a.includeInShuffle === true,+ order: orderOf(a.preferredOrder)+ }))+ .sort((a, b) => a.order - b.order)+ return { categories, assets }+}++/** The UUIDs of the regular files `<dir>/<UUID><ext>`. A missing dir is an empty set. */+async function uuidFiles(dir: string, ext: string): Promise<Set<string>> {+ const out = new Set<string>()+ try {+ for (const e of await readdir(dir, { withFileTypes: true })) {+ const id = e.name.endsWith(ext) ? e.name.slice(0, -ext.length) : ''+ if (e.isFile() && isAerialUuid(id)) out.add(id)+ }+ } catch {+ // not there: nothing downloaded / no thumbnails+ }+ return out+}++/** A fresh scan, every call: one small JSON read and two readdirs (macOS downloads clips at will). */+export async function scanAerials(root = aerialsRoot()): Promise<AerialScan | null> {+ let manifest+ try {+ manifest = parseAerialManifest(JSON.parse(await readFile(path.join(root, 'manifest', 'entries.json'), 'utf8')))+ } catch {+ return null+ }+ const [downloaded, thumbs] = await Promise.all([+ uuidFiles(path.join(root, 'videos'), '.mov'),+ uuidFiles(path.join(root, 'thumbnails'), '.png')+ ])+ return { ...manifest, downloaded, thumbs }+}++/** A shuffle's category members (by preferredOrder), or the one asset an `aerial:` id names. */+function aerialMembers(scan: AerialScan, id: string): AerialAsset[] {+ const a = parseAerialId(id)+ if (!a) return []+ if (!a.shuffle) return scan.assets.filter((x) => x.id === a.uuid)+ if (!scan.categories.some((c) => c.id === a.uuid)) return []+ return scan.assets.filter((x) => x.categories.includes(a.uuid))+}++/** The scan, when this host can serve aerials at all (macOS desktop with a media URL minter). */+async function aerialScan(): Promise<{ scan: AerialScan; root: string; url: (p: string) => string } | null> {+ const url = mediaUrl+ if (host().platform !== 'darwin' || !url) return null+ const root = aerialsRoot()+ const scan = await scanAerials(root)+ return scan ? { scan, root, url } : null+}++function thumbUrl(s: { scan: AerialScan; root: string; url: (p: string) => string }, id: string | undefined) {+ return id && s.scan.thumbs.has(id) ? s.url(path.join(s.root, 'thumbnails', `${id}.png`)) : null+}++/** One "Shuffle <category>" tile per category with any asset, then one tile per downloaded aerial. */+export async function listAerials(): Promise<WallpaperStill[]> {+ const s = await aerialScan()+ if (!s) return []+ const shuffles: WallpaperStill[] = []+ const singles: WallpaperStill[] = []+ for (const c of s.scan.categories) {+ const members = aerialMembers(s.scan, `${AERIAL_SHUFFLE_PREFIX}${c.id}`)+ if (!members.length) continue+ shuffles.push({ id: `${AERIAL_SHUFFLE_PREFIX}${c.id}`, label: `Shuffle ${c.label}`, thumb: thumbUrl(s, members[0].id) })+ for (const a of members) {+ if (s.scan.downloaded.has(a.id) && !singles.some((x) => x.id === `${AERIAL_PREFIX}${a.id}`)) {+ singles.push({ id: `${AERIAL_PREFIX}${a.id}`, label: a.label, thumb: thumbUrl(s, a.id) })+ }+ }+ }+ return [...shuffles, ...singles]+}++/**+ * 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+ * 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).+ */+export async function aerialClips(value: unknown): Promise<string[]> {+ const w = normalizeWallpaper(value)+ 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))+ return clips.map((a) => s.url(path.join(s.root, 'videos', `${a.id}.mov`)))+}++/** The still under (and instead of) the video: the first member's thumbnail, by preferredOrder. */+async function aerialStill(id: string): Promise<string | null> {+ const s = await aerialScan()+ return s ? thumbUrl(s, aerialMembers(s.scan, id)[0]?.id) : null+}+let currentKeep: () => unknown[] = () => []/**@@ -445,4 +629,6 @@ export function registerWallpaperIpc(settings: {platform().handle(IPC.wallpaperListStills, () => listStills())platform().handle(IPC.wallpaperLoad, (value: unknown) => loadWallpaper(value))platform().handle(IPC.wallpaperImport, (sourcePath: unknown) => importWallpaper(sourcePath))+ platform().handle(IPC.wallpaperListAerials, () => listAerials())+ platform().handle(IPC.wallpaperAerialClips, (value: unknown) => aerialClips(value))}diff --git a/src/main/index.ts b/src/main/index.tsindex d8348a63c..0c1766240 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -375,7 +375,7 @@ import { registerGrokCliIpc } from '../core/grok-cli'import { registerCursorCliIpc } from '../core/cursor-cli'import { refreshCodexIdentityCaps, registerCodexIdentityIpc } from '../core/codex-identity-caps'import { codexCliCaps, registerCodexCliIpc } from '../core/codex-cli'-import { registerWallpaperIpc, setWallpaperImageOps } from '../core/wallpaper'+import { registerWallpaperIpc, setWallpaperImageOps, setWallpaperMediaUrl } from '../core/wallpaper'import { nativeImageWallpaperOps } from './wallpaper-native-image'import { registerRunConfigIpc, stopAllRunWatches } from '../core/run-service'import { registerSimulatorIpc, setSimulatorNodeRefusal, shutdownOwnedSimulators, stopAllSimulators } from '../core/simulator/simulator-service'@@ -1732,6 +1732,9 @@ app.whenReady().then(async () => {// Windows has no sips: convert (thumbnails, Windows stills, oversized imports) with Chromium's// own decoder. macOS keeps sips and Linux keeps no converter, byte for byte.if (process.platform === 'win32') setWallpaperImageOps(nativeImageWallpaperOps)+ // Aerial wallpapers (macOS) stream through nt-media://; core allowlists only the clips and+ // thumbnails its own manifest scan found.+ setWallpaperMediaUrl(allowMediaPath)registerWallpaperIpc(settingsStore)registerRunConfigIpc()registerSimulatorIpc()diff --git a/src/preload/index.ts b/src/preload/index.tsindex bb08a0483..6dc9cdc67 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -584,7 +584,9 @@ const api: NodeTerminalApi = {wallpaper: {listStills: () => ipcRenderer.invoke(IPC.wallpaperListStills),load: (w) => ipcRenderer.invoke(IPC.wallpaperLoad, w),- importImage: (p) => ipcRenderer.invoke(IPC.wallpaperImport, p)+ importImage: (p) => ipcRenderer.invoke(IPC.wallpaperImport, p),+ listAerials: () => ipcRenderer.invoke(IPC.wallpaperListAerials),+ aerialClips: (w) => ipcRenderer.invoke(IPC.wallpaperAerialClips, w)},simulator: {devices: (refresh) => ipcRenderer.invoke(IPC.simulatorDevices, refresh === true),diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.tsindex 713a19808..d8a4ee53f 100644--- a/src/renderer/bridge/stubs.ts+++ b/src/renderer/bridge/stubs.ts@@ -343,7 +343,9 @@ export function buildStubApi(): Omit<// are pure CSS and need no bridge), and import refuses.listStills: () => Promise.resolve([]),load: () => Promise.resolve(null),- importImage: U('wallpaper.importImage')+ importImage: U('wallpaper.importImage'),+ listAerials: () => Promise.resolve([]),+ aerialClips: () => Promise.resolve([])},simulator: {devices: () => Promise.resolve({ devices: [] }),diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.tsindex 494de01a7..33826af11 100644--- a/src/renderer/bridge/ws-bridge.ts+++ b/src/renderer/bridge/ws-bridge.ts@@ -1121,7 +1121,9 @@ export function buildWallpaperApi(client: RpcClient): Pick<NodeTerminalApi, 'walwallpaper: {listStills: () => client.request(IPC.wallpaperListStills) as Promise<WallpaperStill[]>,load: (w: DesktopWallpaper) => client.request(IPC.wallpaperLoad, w) as Promise<string | null>,- importImage: (p: string) => client.request(IPC.wallpaperImport, p) as Promise<DesktopWallpaper>+ importImage: (p: string) => client.request(IPC.wallpaperImport, p) as Promise<DesktopWallpaper>,+ listAerials: () => client.request(IPC.wallpaperListAerials) as Promise<WallpaperStill[]>,+ aerialClips: (w: DesktopWallpaper) => client.request(IPC.wallpaperAerialClips, w) as Promise<string[]>}}}diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex e077f0137..67b8539c0 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -976,6 +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 { showCanvasDots } from '../lib/canvasDots'import { PROJECT_NAME_MAX, clampProjectName } from '@shared/project-name'@@ -19259,6 +19260,7 @@ export function Canvas() {return (<div className="canvas-root" style={wallpaperStyle}>+ <AerialWallpaper /><TabBaronSwitch={switchProject}onReconnect={reconnectRelay}diff --git a/src/renderer/components/AerialWallpaper.tsx b/src/renderer/components/AerialWallpaper.tsxnew file mode 100644index 000000000..e29e96790--- /dev/null+++ b/src/renderer/components/AerialWallpaper.tsx@@ -0,0 +1,116 @@+import { useEffect, useRef, useState, useSyncExternalStore } from 'react'+import { nextShuffleClip, normalizeWallpaper, parseAerialId } from '@shared/wallpaper'+import { CANVAS_COVERED_ATTR } from '../lib/canvasCovered'+import { useSettings } from '../state/settings'++const REDUCED_MOTION = '(prefers-reduced-motion: reduce)'+const motionQuery = (): MediaQueryList | null =>+ typeof window !== 'undefined' && typeof window.matchMedia === 'function' ? window.matchMedia(REDUCED_MOTION) : null++function useReducedMotion(): boolean {+ return useSyncExternalStore(+ (onChange) => {+ const q = motionQuery()+ q?.addEventListener('change', onChange)+ return () => q?.removeEventListener('change', onChange)+ },+ () => motionQuery()?.matches ?? false+ )+}++/**+ * 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.+ *+ * 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.+ *+ * `board`: the kanban overlay's layer, fixed to the viewport so it lines up with the canvas's.+ */+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 [clip, setClip] = useState<{ id: string; src: string } | null>(null)+ const ref = useRef<HTMLVideoElement>(null)++ useEffect(() => {+ if (!id) return+ let live = true+ window.nodeTerminal.wallpaper+ .aerialClips({ kind: 'preset', id })+ .then((clips) => {+ const src = nextShuffleClip(clips, null)+ if (live) setClip(src ? { id, src } : null)+ })+ .catch(() => live && setClip(null))+ return () => {+ live = false+ }+ }, [id])++ const src = clip?.id === id ? clip.src : null++ useEffect(() => {+ const el = ref.current+ if (!el) return+ const root = document.documentElement+ const sync = (): void => {+ if (reduced || document.hidden || (!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] })+ return () => {+ document.removeEventListener('visibilitychange', sync)+ covered?.disconnect()+ }+ }, [src, board, reduced])++ if (!id || !src) return null++ const onEnded = (): void => {+ const playing = id+ void window.nodeTerminal.wallpaper+ .aerialClips({ kind: 'preset', id: playing })+ .catch(() => [] as string[])+ .then((clips) => {+ const next = nextShuffleClip(clips, src)+ if (next === src && ref.current) {+ ref.current.currentTime = 0+ void ref.current.play().catch(() => {})+ } else {+ setClip((c) => (c?.id === playing ? (next ? { id: playing, src: next } : null) : c))+ }+ })+ }++ return (+ <video+ ref={ref}+ key={src}+ src={src}+ className={board ? 'aerial-wallpaper aerial-wallpaper--board' : 'aerial-wallpaper'}+ aria-hidden+ tabIndex={-1}+ muted+ autoPlay={!reduced}+ preload="auto"+ playsInline+ loop={!shuffle}+ onEnded={shuffle ? onEnded : undefined}+ onError={() => setClip(null)}+ />+ )+}diff --git a/src/renderer/components/kanban/GlobalKanbanView.tsx b/src/renderer/components/kanban/GlobalKanbanView.tsxindex 373efcebc..99c6d2205 100644--- a/src/renderer/components/kanban/GlobalKanbanView.tsx+++ b/src/renderer/components/kanban/GlobalKanbanView.tsx@@ -4,6 +4,7 @@ import { AGENT_CONFIG, BUILTIN_AGENT_IDS, type AgentId } from '@shared/agents/coimport { useProjects } from '../../state/projects'import { useSettings } from '../../state/settings'import { useBoardWallpaperStyle } from '../../state/wallpaper'+import { AerialWallpaper } from '../AerialWallpaper'import {addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,deleteColumn, labelsForCard, moveColumn,@@ -519,6 +520,7 @@ export const GlobalKanbanView = memo(function GlobalKanbanView({ live = null, onif (projects.length === 0) {return (<div className="kanban-overlay global-kanban" style={boardStyle}>+ {boardStyle && <AerialWallpaper board />}<div className="kanban-header"><span className="kanban-header__name">All Projects</span><KanbanScopeSwitch scope="all" /></div><div className="kanban-empty">No projects yet. Create a project to see its swimlane.</div></div>@@ -527,6 +529,7 @@ export const GlobalKanbanView = memo(function GlobalKanbanView({ live = null, onreturn (<div className="kanban-overlay global-kanban" ref={containerRef} style={boardStyle}>+ {boardStyle && <AerialWallpaper board />}<div className="kanban-header"><span className="kanban-header__name">All Projects</span><KanbanScopeSwitch scope="all" />diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsxindex 1a2aef40f..18d7fefef 100644--- a/src/renderer/components/kanban/KanbanView.tsx+++ b/src/renderer/components/kanban/KanbanView.tsx@@ -17,6 +17,7 @@ import { useViewMode } from '../../state/viewMode'import { useProjects } from '../../state/projects'import { useSettings } from '../../state/settings'import { useBoardWallpaperStyle } from '../../state/wallpaper'+import { AerialWallpaper } from '../AerialWallpaper'import {AT_COLUMN_END, addColumn, assignNode, assignedTo, boardLabels, cardAssignees, cardMatchesLabelFilter, cardMeta, columnForNode,deleteColumn, labelsForCard, moveColumn,@@ -1051,6 +1052,7 @@ export const KanbanView = memo(function KanbanView({return (<div className="kanban-overlay" style={boardStyle}>+ {boardStyle && <AerialWallpaper board />}{/* Title strip: names the board's project AND pushes the columns below the top-rightcontrols cluster, so column headers never sit under its icons. */}<div className="kanban-header">diff --git a/src/renderer/components/settings/sections/AppearanceSection.tsx b/src/renderer/components/settings/sections/AppearanceSection.tsxindex 838309f44..3507b4bad 100644--- a/src/renderer/components/settings/sections/AppearanceSection.tsx+++ b/src/renderer/components/settings/sections/AppearanceSection.tsx@@ -90,7 +90,7 @@ const ROWS = {accent: { title: 'Accent', keywords: ['accent', 'color', 'theme', 'appearance'] },wallpaper: {title: 'Desktop wallpaper',- keywords: ['wallpaper', 'background', 'desktop', 'image', 'picture', 'gradient', 'sonoma', 'canvas']+ keywords: ['wallpaper', 'background', 'desktop', 'image', 'picture', 'gradient', 'sonoma', 'canvas', 'aerial', 'aerials', 'video', 'shuffle', 'moving']},windowTitle: {title: 'Window title',@@ -393,6 +393,7 @@ function WallpaperPicker(): React.JSX.Element {const yourImageBg = useWallpaperBackgroundFor(yourImage)const update = useSettings((s) => s.update)const [stills, setStills] = useState<WallpaperStill[] | null>(null)+ const [aerials, setAerials] = useState<WallpaperStill[]>([])const [error, setError] = useState<string | null>(null)useEffect(() => {let live = true@@ -400,6 +401,11 @@ function WallpaperPicker(): React.JSX.Element {.listStills().then((list) => live && setStills(list)).catch(() => live && setStills([]))+ // Empty off macOS, in the Server Edition and on a relay tab: the group then does not render.+ window.nodeTerminal.wallpaper+ .listAerials()+ .then((list) => live && setAerials(list))+ .catch(() => {})return () => {live = false}@@ -469,6 +475,25 @@ function WallpaperPicker(): React.JSX.Element {)}</div>{error && <p className="mt-2 text-[12px] text-danger">{error}</p>}+ {aerials.length > 0 && (+ <>+ <h4 className="mt-4 text-[13px] font-medium text-text">Aerials</h4>+ <div className="mt-3 flex flex-wrap gap-2">+ {aerials.map((a) => (+ <WallpaperTile+ key={a.id}+ label={a.label}+ selected={is({ kind: 'preset', id: a.id })}+ background={a.thumb ? `center / cover no-repeat url("${a.thumb}")` : undefined}+ onClick={() => pick({ kind: 'preset', id: a.id })}+ >+ {a.thumb ? null : a.label}+ </WallpaperTile>+ ))}+ </div>+ <p className="mt-2 text-[12px] text-muted">Download more aerials in System Settings → Wallpaper.</p>+ </>+ )}</div>)}diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex 657eb3e36..55b55f5ff 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -4368,6 +4368,26 @@ 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. */+.aerial-wallpaper {+ position: absolute;+ inset: 0;+ width: 100%;+ height: 100%;+ object-fit: cover;+ z-index: -1;+ pointer-events: none;+}+.aerial-wallpaper--board {+ position: fixed;+}+.canvas-root:has(> .aerial-wallpaper) {+ isolation: isolate;+}.flow-wrap {flex: 1;diff --git a/src/shared/ipc.ts b/src/shared/ipc.tsindex 86249e1a2..b2f0b9313 100644--- a/src/shared/ipc.ts+++ b/src/shared/ipc.ts@@ -403,6 +403,8 @@ export const IPC = {wallpaperListStills: 'wallpaper:list-stills',wallpaperLoad: 'wallpaper:load',wallpaperImport: 'wallpaper:import',+ wallpaperListAerials: 'wallpaper:list-aerials',+ wallpaperAerialClips: 'wallpaper:aerial-clips',// Run node (core/run-service.ts): launch.json entries, devices, launcher, status, stop, signals.runEntries: 'run:entries',runDevices: 'run:devices',diff --git a/src/shared/wallpaper.test.ts b/src/shared/wallpaper.test.tsindex 41e411a1f..94a291947 100644--- a/src/shared/wallpaper.test.ts+++ b/src/shared/wallpaper.test.ts@@ -2,7 +2,9 @@ import { describe, expect, it } from 'vitest'import {defaultWallpaper,GRADIENT_WALLPAPERS,+ nextShuffleClip,normalizeWallpaper,+ parseAerialId,recentWallpaperImage,wallpaperChoice,wallpapersToKeep@@ -50,3 +52,37 @@ describe('normalizeWallpaper system-still prefixes', () => {expect(normalizeWallpaper({ kind: 'preset', id: 'windows:x.jpg' })).toEqual({ kind: 'none' })})})++describe('aerial ids', () => {+ const U = '00BA71CD-2C54-415A-A68A-8358E677D750'+ it('accepts aerial: and aerial-shuffle: with a UUID', () => {+ expect(normalizeWallpaper({ kind: 'preset', id: `aerial:${U}` })).toEqual({ kind: 'preset', id: `aerial:${U}` })+ expect(normalizeWallpaper({ kind: 'preset', id: `aerial-shuffle:${U}` })).toEqual({+ kind: 'preset',+ id: `aerial-shuffle:${U}`+ })+ expect(parseAerialId(`aerial-shuffle:${U}`)).toEqual({ uuid: U, shuffle: true })+ })+ it('rejects anything but a UUID after the prefix (paths included)', () => {+ for (const bad of ['aerial:', 'aerial:Dubai', `aerial:${U}.mov`, `aerial:../${U}`, `aerial-shuffle:${U}/x`, 'aerial-x:' + U]) {+ expect(normalizeWallpaper({ kind: 'preset', id: bad })).toEqual({ kind: 'none' })+ }+ })+})++describe('nextShuffleClip', () => {+ it('never repeats the current clip while another is available', () => {+ const clips = ['a', 'b', 'c']+ for (let i = 0; i < 50; i++) {+ const r = i / 50+ expect(nextShuffleClip(clips, 'b', () => r)).not.toBe('b')+ }+ expect(nextShuffleClip(['a', 'b'], 'a', () => 0.99)).toBe('b')+ expect(nextShuffleClip(clips, 'a', () => 1)).not.toBe('a') // random() === 1 stays in range+ })+ it('a single clip repeats itself; none is null', () => {+ expect(nextShuffleClip(['a'], 'a')).toBe('a')+ expect(nextShuffleClip([], 'a')).toBeNull()+ expect(nextShuffleClip(['a', 'b'], null, () => 0)).toBe('a')+ })+})diff --git a/src/shared/wallpaper.ts b/src/shared/wallpaper.tsindex 3453d9c18..d12f7863e 100644--- a/src/shared/wallpaper.ts+++ b/src/shared/wallpaper.ts@@ -13,6 +13,11 @@* core, since Chromium cannot decode HEIC.* - `win:<path under %WINDIR%\\Web\\Wallpaper>` presets are the stock Windows stills, read and* converted the same way through Electron's `nativeImage` (desktop only).+ * - `aerial:<asset UUID>` / `aerial-shuffle:<category UUID>` presets are the macOS Aerial videos+ * macOS itself has downloaded (one clip looped, or a category shuffled), read from+ * `~/Library/Application Support/com.apple.wallpaper/aerials` at runtime and never bundled or+ * downloaded by us. Core resolves the UUID against a fresh manifest scan; the still behind the+ * video (and the fallback when nothing can play) is the asset's thumbnail.* - `image` is a picture the user chose, COPIED into `<userData>/wallpapers/` on import so moving* the original does not break it. `path` names that copy; core refuses to read anything else.*/@@ -84,10 +89,46 @@ export interface WallpaperApi {load(wallpaper: DesktopWallpaper): Promise<string | null>/** Copy (converting HEIC) a picked image into the wallpaper cache; resolves the value to store. */importImage(sourcePath: string): Promise<DesktopWallpaper>+ /** The aerial tiles: one shuffle per category, then each downloaded aerial. Empty off macOS and in+ * the Server Edition. `thumb` is an nt-media: URL. */+ listAerials(): Promise<WallpaperStill[]>+ /** nt-media: URLs of the downloaded clips an aerial wallpaper plays, re-scanned on every call+ * (macOS downloads more over time); empty when none can play — the still then shows. */+ aerialClips(wallpaper: DesktopWallpaper): Promise<string[]>}const MAX_FIELD = 4096+export const AERIAL_PREFIX = 'aerial:'+export const AERIAL_SHUFFLE_PREFIX = 'aerial-shuffle:'+/** Apple's asset and category ids are upper-case UUIDs; accept either case, nothing else. */+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i++export function isAerialUuid(s: string): boolean {+ return UUID.test(s)+}++/** 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)+ if (!shuffle && !id.startsWith(AERIAL_PREFIX)) return null+ const uuid = id.slice(shuffle ? AERIAL_SHUFFLE_PREFIX.length : AERIAL_PREFIX.length)+ return isAerialUuid(uuid) ? { uuid, shuffle } : null+}++/**+ * The shuffle's next clip: a random one, never `current` again while there is any other. A single+ * clip (or none) is simply itself.+ */+export function nextShuffleClip(+ clips: readonly string[],+ current: string | null,+ random: () => number = Math.random+): string | null {+ const pool = clips.length > 1 ? clips.filter((c) => c !== current) : clips+ return pool.length ? pool[Math.floor(random() * pool.length) % pool.length] : null+}+/** Re-validate a hand-editable value. Anything unrecognised is `none`. */export function normalizeWallpaper(v: unknown): DesktopWallpaper {if (!v || typeof v !== 'object') return NO_WALLPAPER@@ -96,7 +137,10 @@ export function normalizeWallpaper(v: unknown): DesktopWallpaper {if (o.id.startsWith('gradient:') && !gradientCss(o.id)) return NO_WALLPAPER// `mac:` / `win:` name a system still; core re-resolves it against its OWN fresh scan, so an id// from the other OS (a settings.json synced across machines) simply loads nothing there.- if (!o.id.startsWith('gradient:') && !o.id.startsWith('mac:') && !o.id.startsWith('win:')) {+ // `aerial:` / `aerial-shuffle:` likewise, and only with a UUID after the prefix.+ const aerial = o.id.startsWith(AERIAL_PREFIX) || o.id.startsWith(AERIAL_SHUFFLE_PREFIX)+ if (aerial && !parseAerialId(o.id)) return NO_WALLPAPER+ if (!aerial && !o.id.startsWith('gradient:') && !o.id.startsWith('mac:') && !o.id.startsWith('win:')) {return NO_WALLPAPER}return { kind: 'preset', id: o.id }