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): serve macOS stills and imported images from a core cache

iceclatterWT7b7664dd404a
diff --git a/src/core/wallpaper.test.ts b/src/core/wallpaper.test.ts
new file mode 100644
index 000000000..fc8f5118a
--- /dev/null
+++ b/src/core/wallpaper.test.ts
@@ -0,0 +1,63 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { cachedImagePath, importWallpaper, scanStills } from './wallpaper'
+
+const HASH = 'a'.repeat(40)
+let root: string | null = null
+afterEach(() => {
+ if (root) rmSync(root, { recursive: true, force: true })
+ root = null
+})
+
+function put(rel: string, bytes: number): void {
+ const p = path.join(root!, rel)
+ mkdirSync(path.dirname(p), { recursive: true })
+ writeFileSync(p, Buffer.alloc(bytes))
+}
+
+describe('scanStills', () => {
+ it('finds >1MB stills incl. .wallpapers/*, skips thumbnails/placeholders, scenic first', async () => {
+ root = mkdtempSync(path.join(tmpdir(), 'wp-'))
+ put('Mac Blue.heic', 2_000_000)
+ put('Sonoma.heic', 2_000_000)
+ put('.wallpapers/Sonoma Horizon/Sonoma Horizon.heic', 2_000_000)
+ put('.wallpapers/Sonoma Horizon/Sonoma Horizon.madesktop', 2_000_000)
+ put('.thumbnails/Big.heic', 2_000_000)
+ put('Tiny.heic', 1000)
+ put('notes.txt', 2_000_000)
+ const list = await scanStills(root)
+ expect(list.map((s) => s.label)).toEqual(['Sonoma Horizon', 'Sonoma', 'Mac Blue'])
+ expect(list[0].id).toBe('mac:.wallpapers/Sonoma Horizon/Sonoma Horizon.heic')
+ })
+
+ it('a missing root is an empty list', async () => {
+ expect(await scanStills(path.join(tmpdir(), 'no-such-wallpaper-dir-xyz'))).toEqual([])
+ })
+})
+
+describe('cachedImagePath (the read jail)', () => {
+ const cache = path.resolve('/data/wallpapers')
+ it('accepts only a hash-named direct child of the cache dir', () => {
+ expect(cachedImagePath(path.join(cache, `${HASH}.jpg`), cache)).toBe(path.join(cache, `${HASH}.jpg`))
+ expect(cachedImagePath(path.join(cache, `${HASH}-t.jpg`), cache)).not.toBeNull()
+ })
+ it.each([
+ ['traversal', path.join(cache, '..', `${HASH}.jpg`)],
+ ['nested', path.join(cache, 'x', `${HASH}.jpg`)],
+ ['non-hash name', path.join(cache, 'id_rsa.jpg')],
+ ['wrong extension', path.join(cache, `${HASH}.txt`)],
+ ['windows-shaped', `C:\\Users\\me\\${HASH}.jpg`],
+ ['empty', '']
+ ])('refuses %s', (_label, p) => {
+ expect(cachedImagePath(p, cache)).toBeNull()
+ })
+})
+
+describe('importWallpaper', () => {
+ it('refuses a file that is not a supported image', async () => {
+ await expect(importWallpaper('/etc/passwd')).rejects.toThrow(/JPEG, PNG, WebP or HEIC/)
+ await expect(importWallpaper(42)).rejects.toThrow()
+ })
+})
diff --git a/src/core/wallpaper.ts b/src/core/wallpaper.ts
new file mode 100644
index 000000000..53f94efd1
--- /dev/null
+++ b/src/core/wallpaper.ts
@@ -0,0 +1,224 @@
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { copyFile, mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { IPC } from '../shared/ipc'
+import {
+ normalizeWallpaper,
+ type DesktopWallpaper,
+ type WallpaperStill
+} from '../shared/wallpaper'
+import { renameAtomic, tempNameFor } from './fs-atomic'
+import { platform } from './platform'
+
+/**
+ * Wallpaper files for the canvas background (Liquid Glass appearance). Core, so both shells serve
+ * it: on the Server Edition (Linux) the stills list is simply empty and gradients need no files.
+ *
+ * Every file the renderer can get bytes for lives in ONE directory, `<userData>/wallpapers/`, under
+ * a hash name this module minted. The renderer never names a path to read: a still is named by its
+ * `mac:` id and re-resolved against a fresh scan, and an imported image's path must be a direct
+ * child of the cache dir with a hash-shaped name (`cachedImagePath`). So a hand-edited
+ * settings.json cannot aim `load` at anything else, and there is no traversal to reject because
+ * no caller-supplied segment is ever joined.
+ */
+
+const run = promisify(execFile)
+
+export const SYSTEM_WALLPAPER_DIR = '/System/Library/Desktop Pictures'
+const SIPS = '/usr/bin/sips'
+/** Real stills are several MB; the 356px `.madesktop` placeholders and thumbnails are not. */
+const MIN_STILL_BYTES = 1_000_000
+const STILL_EXT = /\.(heic|jpe?g|png)$/i
+const IMPORT_EXT = /\.(heic|jpe?g|png|webp)$/i
+/** Shown first, in this order: the scenic ones. */
+const SCENIC_FIRST = ['Sonoma Horizon', 'Sonoma']
+const FULL_PX = 3840
+const THUMB_PX = 320
+/** Refuse to ship anything bigger over IPC as a data: URL. */
+const MAX_LOAD_BYTES = 25 * 1024 * 1024
+const CACHED_NAME = /^[0-9a-f]{40}(-t)?\.(jpg|jpeg|png|webp)$/
+
+export interface ScannedStill {
+ id: string
+ label: string
+ path: string
+}
+
+export function wallpaperCacheDir(): string {
+ return path.join(platform().userDataDir, 'wallpapers')
+}
+
+/**
+ * The stock macOS stills under `root`, scenic first. Recurses into `.wallpapers/<name>/`, skips
+ * `.thumbnails` and anything under 1 MB (which is what drops the `.madesktop` placeholders' tiny
+ * siblings). A missing root is an empty list, which is the answer everywhere but macOS.
+ */
+export async function scanStills(root = SYSTEM_WALLPAPER_DIR, depth = 3): Promise<ScannedStill[]> {
+ const found: ScannedStill[] = []
+ const walk = async (dir: string, left: number): Promise<void> => {
+ let entries
+ try {
+ entries = await readdir(dir, { withFileTypes: true })
+ } catch {
+ return
+ }
+ for (const e of entries) {
+ const p = path.join(dir, e.name)
+ if (e.isDirectory()) {
+ if (e.name !== '.thumbnails' && left > 0) await walk(p, left - 1)
+ } else if (e.isFile() && STILL_EXT.test(e.name)) {
+ try {
+ if ((await stat(p)).size < MIN_STILL_BYTES) continue
+ } catch {
+ continue
+ }
+ const rel = path.relative(root, p).split(path.sep).join('/')
+ found.push({ id: `mac:${rel}`, label: e.name.replace(STILL_EXT, ''), path: p })
+ }
+ }
+ }
+ await walk(root, depth)
+ const seen = new Set<string>()
+ const rank = (label: string): number => {
+ const i = SCENIC_FIRST.indexOf(label)
+ return i === -1 ? SCENIC_FIRST.length : i
+ }
+ return found
+ .sort((a, b) => rank(a.label) - rank(b.label) || a.label.localeCompare(b.label))
+ .filter((s) => (seen.has(s.label) ? false : (seen.add(s.label), true)))
+}
+
+/** A cached file's name: stable per source file version and output size. */
+async function cacheKey(src: string, variant: string): Promise<string> {
+ const st = await stat(src)
+ return createHash('sha1').update(`${src}\x00${st.mtimeMs}\x00${st.size}\x00${variant}`).digest('hex')
+}
+
+/** In-flight conversions, so two callers asking for the same file share one `sips`. */
+const inflight = new Map<string, Promise<string>>()
+
+/** Publish `produce(tmp)` at `target` through a unique temp, unless it is already there. */
+function publishOnce(target: string, produce: (tmp: string) => Promise<void>): Promise<string> {
+ const pending = inflight.get(target)
+ if (pending) return pending
+ const job = (async () => {
+ try {
+ await stat(target)
+ return target
+ } catch {
+ // not cached yet
+ }
+ await mkdir(path.dirname(target), { recursive: true })
+ const tmp = tempNameFor(target)
+ try {
+ await produce(tmp)
+ await renameAtomic(tmp, target)
+ } catch (err) {
+ await unlink(tmp).catch(() => {})
+ throw err
+ }
+ return target
+ })().finally(() => inflight.delete(target))
+ inflight.set(target, job)
+ return job
+}
+
+/** HEIC/JPEG/PNG → JPEG no larger than `px` on its long edge, via macOS's built-in `sips`. */
+async function convertWithSips(src: string, px: number, suffix: string): Promise<string> {
+ const target = path.join(wallpaperCacheDir(), `${await cacheKey(src, `sips${px}`)}${suffix}.jpg`)
+ return publishOnce(target, async (tmp) => {
+ await run(SIPS, ['-s', 'format', 'jpeg', '-Z', String(px), src, '--out', tmp], {
+ timeout: 60_000
+ })
+ })
+}
+
+let stillScan: Promise<ScannedStill[]> | null = null
+function stills(): Promise<ScannedStill[]> {
+ if (process.platform !== 'darwin') return Promise.resolve([])
+ // One scan per app run: the system stills only change with an OS update.
+ stillScan ??= scanStills().catch(() => [])
+ return stillScan
+}
+
+async function toDataUrl(file: string): Promise<string | null> {
+ try {
+ const st = await stat(file)
+ if (st.size > MAX_LOAD_BYTES) return null
+ const ext = path.extname(file).slice(1).toLowerCase()
+ const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'
+ return `data:${mime};base64,${(await readFile(file)).toString('base64')}`
+ } catch {
+ return null
+ }
+}
+
+/**
+ * The cache file an `image` wallpaper names, or null when the value names anything else. Only a
+ * DIRECT child of the cache dir with a hash-shaped name qualifies — that is the whole jail.
+ */
+export function cachedImagePath(p: string, cacheDir = wallpaperCacheDir()): string | null {
+ if (typeof p !== 'string' || p.length === 0) return null
+ const resolved = path.resolve(p)
+ if (path.dirname(resolved) !== path.resolve(cacheDir)) return null
+ if (!CACHED_NAME.test(path.basename(resolved))) return null
+ return resolved
+}
+
+export async function listStills(): Promise<WallpaperStill[]> {
+ const list = await stills()
+ const out: WallpaperStill[] = []
+ // Sequential on purpose: a fresh cache runs one `sips` per still, and a dozen at once is a burst
+ // of CPU for a grid of 320px thumbnails. Cached, each is a stat plus a small read.
+ for (const s of list) {
+ const thumb = await convertWithSips(s.path, THUMB_PX, '-t')
+ .then(toDataUrl)
+ .catch(() => null)
+ out.push({ id: s.id, label: s.label, thumb })
+ }
+ return out
+}
+
+export async function loadWallpaper(value: unknown): Promise<string | null> {
+ const w = normalizeWallpaper(value)
+ if (w.kind === 'image') {
+ const file = cachedImagePath(w.path)
+ return file ? toDataUrl(file) : null
+ }
+ if (w.kind === 'preset' && w.id.startsWith('mac:')) {
+ const still = (await stills()).find((s) => s.id === w.id)
+ if (!still) return null
+ return convertWithSips(still.path, FULL_PX, '')
+ .then(toDataUrl)
+ .catch(() => null)
+ }
+ return null
+}
+
+/**
+ * Copy a picked image into the cache (HEIC is converted, since Chromium cannot decode it) and
+ * return the value to store. The copy is what keeps the wallpaper when the original moves.
+ */
+export async function importWallpaper(sourcePath: unknown): Promise<DesktopWallpaper> {
+ if (typeof sourcePath !== 'string' || !IMPORT_EXT.test(sourcePath)) {
+ throw new Error('Choose a JPEG, PNG, WebP or HEIC image.')
+ }
+ const src = path.resolve(sourcePath)
+ if (/\.heic$/i.test(src)) {
+ if (process.platform !== 'darwin') throw new Error('HEIC images can only be converted on macOS.')
+ return { kind: 'image', path: await convertWithSips(src, FULL_PX, '') }
+ }
+ const ext = path.extname(src).toLowerCase().replace('.jpeg', '.jpg')
+ const target = path.join(wallpaperCacheDir(), `${await cacheKey(src, 'copy')}${ext}`)
+ await publishOnce(target, (tmp) => copyFile(src, tmp))
+ return { kind: 'image', path: target }
+}
+
+/** Wire onto the platform's RPC surface (Electron ipcMain / server WS-RPC alike). */
+export function registerWallpaperIpc(): void {
+ platform().handle(IPC.wallpaperListStills, () => listStills())
+ platform().handle(IPC.wallpaperLoad, (value: unknown) => loadWallpaper(value))
+ platform().handle(IPC.wallpaperImport, (sourcePath: unknown) => importWallpaper(sourcePath))
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index 346328472..347401922 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -268,6 +268,7 @@ import type { CodexCliCaps } from '../shared/types'
import { registerGrokCliIpc } from '../core/grok-cli'
import { refreshCodexIdentityCaps, registerCodexIdentityIpc } from '../core/codex-identity-caps'
import { codexCliCaps, registerCodexCliIpc } from '../core/codex-cli'
+import { registerWallpaperIpc } from '../core/wallpaper'
import {
bindCodexThreadIdentity,
setCodexThreadIdentityAuthSecret,
@@ -1400,6 +1401,7 @@ app.whenReady().then(async () => {
// What THIS machine's codex accepts for `--ask-for-approval`. Lazy + memoized inside the probe,
// so registering it costs nothing until the first Codex launch line asks.
registerCodexCliIpc()
+ registerWallpaperIpc()
// Warm the `claude --version` probe now (it spawns a login shell + node, ~sub-second) so the
// renderer's first `claude.cliCaps()` — awaited on the launch path of a cold-restored agent
// node — resolves from cache instead of racing the probe into a conservative "no auto".
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 1008e8cdd..cd48f2837 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -491,6 +491,11 @@ const api: NodeTerminalApi = {
read: (q?: SessionMemoryQuery) => ipcRenderer.invoke(IPC.sessionMemory, q),
host: (q?: SessionMemoryQuery) => ipcRenderer.invoke(IPC.sessionMemoryHost, q)
},
+ wallpaper: {
+ listStills: () => ipcRenderer.invoke(IPC.wallpaperListStills),
+ load: (w) => ipcRenderer.invoke(IPC.wallpaperLoad, w),
+ importImage: (p) => ipcRenderer.invoke(IPC.wallpaperImport, p)
+ },
triggers: {
arm: (projectId, nodeId, spec) => ipcRenderer.invoke(IPC.triggersArm, { projectId, nodeId, spec }),
disarm: (projectId, nodeId) => ipcRenderer.invoke(IPC.triggersDisarm, { projectId, nodeId }),
diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.ts
index 2b4858a5a..bab26986d 100644
--- a/src/renderer/bridge/stubs.ts
+++ b/src/renderer/bridge/stubs.ts
@@ -283,6 +283,15 @@ export function buildStubApi(): Omit<
read: () => Promise.resolve({ ok: false, rows: [], mem: null }),
host: () => Promise.resolve(null)
},
+ wallpaper: {
+ // Superseded by the real WS-backed namespace in ws-bridge (registerWallpaperIpc runs in the
+ // server shell). A RELAY tab keeps this: the wallpaper is this window's own appearance, and
+ // the peer's disk has nothing to say about it. No stills, nothing to load (gradient presets
+ // are pure CSS and need no bridge), and import refuses.
+ listStills: () => Promise.resolve([]),
+ load: () => Promise.resolve(null),
+ importImage: U('wallpaper.importImage')
+ },
triggers: {
// Superseded by the real WS-backed namespace in ws-bridge (startTriggerService registers the
// handlers in the server shell). On the RELAY tab this stub stays in force and REFUSES: the
diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.ts
index 004b9f5c3..5f6781cee 100644
--- a/src/renderer/bridge/ws-bridge.ts
+++ b/src/renderer/bridge/ws-bridge.ts
@@ -1,5 +1,6 @@
import type { NormalizedAgentEvent } from '../../shared/agents/normalize'
import { subscribeAgentReplay } from '../../shared/agent-replay-subscription'
+import type { DesktopWallpaper, WallpaperStill } from '../../shared/wallpaper'
// WebSocket bridge that reconstructs `window.nodeTerminal` in the browser (Server Edition).
//
// Under Electron the preload already defines `window.nodeTerminal`; this module only runs when
@@ -852,6 +853,16 @@ export function buildSessionMemoryApi(client: RpcClient): Pick<NodeTerminalApi,
}
}
+export function buildWallpaperApi(client: RpcClient): Pick<NodeTerminalApi, 'wallpaper'> {
+ return {
+ 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>
+ }
+ }
+}
+
/**
* Build the `claude` namespace over an RpcClient. `cliCaps` is a REAL handler on the server
* (`registerClaudeCliIpc` runs in the server shell too), so the browser resolves the very same
@@ -1133,6 +1144,7 @@ export async function installWsBridge(): Promise<boolean> {
...buildSpeechApi(client),
...buildUsageApi(client),
...buildSessionMemoryApi(client),
+ ...buildWallpaperApi(client),
...buildTriggersApi(client),
...buildGitHubApi(client),
...buildClaudeAccountsApi(client),
diff --git a/src/server/handlers/index.ts b/src/server/handlers/index.ts
index 9235be14c..3e484099c 100644
--- a/src/server/handlers/index.ts
+++ b/src/server/handlers/index.ts
@@ -10,6 +10,7 @@ import { claudeCliCaps, registerClaudeCliIpc } from '../../core/claude-cli'
import { registerGrokCliIpc } from '../../core/grok-cli'
import { registerCodexIdentityIpc } from '../../core/codex-identity-caps'
import { registerCodexCliIpc } from '../../core/codex-cli'
+import { registerWallpaperIpc } from '../../core/wallpaper'
import { startUsageService } from '../../core/usage/usage-service'
import { registerClaudeAccountsIpc } from '../../core/claude-accounts-service'
import { codexUsageAccounts } from '../../core/codex-accounts-core'
@@ -83,6 +84,7 @@ export function registerCoreHandlers(
// hand a later codex a value it removed: exactly the "a stub compiles fine while doing nothing"
// failure the three-surfaces rule warns about.
registerCodexCliIpc()
+ registerWallpaperIpc()
void claudeCliCaps()
// The answer is populated after server node identity is armed. Early browser callers wait for
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index f422db2b3..2c21a5e07 100644
--- a/src/shared/ipc.ts
+++ b/src/shared/ipc.ts
@@ -287,6 +287,10 @@ export const IPC = {
/** The scoped machine's RAM (available/total) — the cheap read behind the system-resource
* pill. Safe to poll locally; NOT polled for an SSH scope. */
sessionMemoryHost: 'session-memory:host',
+ // Canvas wallpaper (core/wallpaper.ts): macOS stills, cached image reads, image import.
+ wallpaperListStills: 'wallpaper:list-stills',
+ wallpaperLoad: 'wallpaper:load',
+ wallpaperImport: 'wallpaper:import',
// Trigger nodes (issue #493): machine-local arm/disarm + the card's status/run-now.
triggersArm: 'triggers:arm',
triggersDisarm: 'triggers:disarm',
diff --git a/src/shared/types.ts b/src/shared/types.ts
index a596ab5cd..aa1b7d90b 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -3548,6 +3548,7 @@ export interface NodeTerminalApi {
githubControl: import('./github-issues').GitHubControlApi
usage: UsageApi
sessionMemory: SessionMemoryApi
+ wallpaper: import('./wallpaper').WallpaperApi
triggers: TriggersApi
context: ContextApi
canvas: CanvasApi