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(canvas): draw the desktop wallpaper behind the canvas

iceclatterWT3ff78ae55e2d
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 96ef668ae..548f97594 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -645,6 +645,7 @@ import {
import type { CodexAccount } from '@shared/codex-account'
import { useSystemCodexAccount } from '../state/systemCodexAccount'
import { toKanbanSession } from './toKanbanSession'
+import { useWallpaperBackground } from '../state/wallpaper'
const isMac = /Mac/i.test(navigator.platform || navigator.userAgent)
@@ -1033,6 +1034,9 @@ export function Canvas() {
// For the local session it IS window.nodeTerminal, so every call resolves identically.
const session = useSession()
const { api } = session
+ // Desktop wallpaper (Settings → Appearance): painted on the React Flow root, which is
+ // viewport-sized and never transformed, so it stays fixed while the canvas pans and zooms.
+ const wallpaperBg = useWallpaperBackground()
const [nodes, setNodes, onNodesChange] = useNodesState<CanvasNode>([])
// Persistent context links between Claude nodes (separate from ephemeral subagent/loop edges).
const [linkEdges, setLinkEdges, onLinkEdgesChange] = useEdgesState<Edge>([])
@@ -14796,6 +14800,8 @@ export function Canvas() {
the key is always 'local', so this never remounts — zero behavior change. */}
<SessionProvider session={sessionForProject(activeProjectId || '')} key={sessionForProject(activeProjectId || '').id}>
<ReactFlow
+ className={wallpaperBg ? 'has-wallpaper' : undefined}
+ style={wallpaperBg ? { background: `${wallpaperBg}, var(--canvas-bg)` } : undefined}
nodes={allNodes}
edges={displayEdges}
nodeTypes={nodeTypes}
diff --git a/src/renderer/state/wallpaper.ts b/src/renderer/state/wallpaper.ts
new file mode 100644
index 000000000..ecab8a28d
--- /dev/null
+++ b/src/renderer/state/wallpaper.ts
@@ -0,0 +1,57 @@
+import { useEffect, useState } from 'react'
+import { gradientCss, normalizeWallpaper, type DesktopWallpaper } from '@shared/wallpaper'
+import { useSettings } from './settings'
+
+/**
+ * The canvas background for the current `desktopWallpaper` setting, as a CSS `background` value,
+ * or null for none (the canvas then draws exactly as before).
+ *
+ * A gradient preset is CSS and resolves synchronously. A still or an imported image is a data:
+ * URL from core (`wallpaper.load`), cached here by value so a re-render or a round trip through
+ * Settings never re-reads a multi-MB file. A load that fails resolves to null — degrade to the
+ * plain canvas, never to a stale picture.
+ */
+const loaded = new Map<string, Promise<string | null>>()
+
+function cacheKey(w: DesktopWallpaper): string {
+ return JSON.stringify(w)
+}
+
+function load(w: DesktopWallpaper): Promise<string | null> {
+ const key = cacheKey(w)
+ let p = loaded.get(key)
+ if (!p) {
+ // ponytail: keep only the latest image; a picker session that flips through ten stills would
+ // otherwise pin ten data: URLs in memory for the app run.
+ loaded.clear()
+ p = window.nodeTerminal.wallpaper
+ .load(w)
+ .then((url) => (url ? `center / cover no-repeat url("${url}")` : null))
+ .catch(() => null)
+ loaded.set(key, p)
+ }
+ return p
+}
+
+export function useWallpaperBackground(): string | null {
+ const raw = useSettings((s) => s.settings.desktopWallpaper)
+ const w = normalizeWallpaper(raw)
+ const key = cacheKey(w)
+ // null = no wallpaper, a string = a gradient, undefined = a file that has to be loaded.
+ const sync = w.kind === 'none' ? null : w.kind === 'preset' ? gradientCss(w.id) : undefined
+ const [async, setAsync] = useState<{ key: string; bg: string | null } | null>(null)
+ useEffect(() => {
+ if (sync !== undefined) return
+ let live = true
+ void load(w).then((bg) => {
+ if (live) setAsync({ key, bg })
+ })
+ return () => {
+ live = false
+ }
+ // `key` carries `w`'s identity; `w` itself is rebuilt every render.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [key, sync])
+ if (sync !== undefined) return sync
+ return async?.key === key ? async.bg : null
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index dfc26e513..89708bd39 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -3204,6 +3204,11 @@ body,
.react-flow {
background: var(--canvas-bg);
}
+/* A desktop wallpaper (Settings → Appearance) is set inline on this element by Canvas. The dot grid
+ stays — it is what snapping aligns to — but faded, so the picture reads as the background. */
+.react-flow.has-wallpaper .react-flow__background {
+ opacity: 0.3;
+}
.flow-wrap {
flex: 1;