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.

feat(wallpaper): macOS Aerial video wallpapers, single and Shuffle <category>

iceclatterWT095cf3968e6e
diff --git a/CLAUDE.md b/CLAUDE.md
index 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-scan
jail as `mac:`). nativeImage decodes no HEIC (`canHeic:false`, still refused) and cannot measure
WebP, 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 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 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.ts
index 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 = null
let 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 = null
stillScan = 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, 'wal
wallpaper: {
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.tsx
index 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 />
<TabBar
onSwitch={switchProject}
onReconnect={reconnectRelay}
diff --git a/src/renderer/components/AerialWallpaper.tsx b/src/renderer/components/AerialWallpaper.tsx
new file mode 100644
index 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.tsx
index 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/co
import { 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, on
if (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, on
return (
<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.tsx
index 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-right
controls 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.tsx
index 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.css
index 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.ts
index 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.ts
index 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.ts
index 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 }