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): give a session an emoji or picture icon

Lorenzo Albanese (alblor)a2ce6d689af7
diff --git a/CLAUDE.md b/CLAUDE.md
index 7e3596bd7..cf6051550 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -171,7 +171,8 @@ Fire-time `TriggerArmStore.isArmed` re-ask everywhere; every rule test-pinned. T
machine-local, content-bound `core/trigger-arm-store.ts` (a spec that arrives or CHANGES via git
reads as disarmed until armed on this machine). A node's `data`
carries `title, color, group, tags, collapsed, expandedHeight, shell, cwd, text,
-initialCommand, filePath, diffStaged`, `agentId` (which agent CLI a terminal node runs —
+initialCommand, filePath, diffStaged`, `icon` (a user-chosen emoji or picture — see **Node icons**
+below), `agentId` (which agent CLI a terminal node runs —
persisted), and `accountId` (which managed Claude account a terminal node runs under — immutable,
resolved at creation, persisted; see **Managed Claude accounts**). `nodeStatesToFlow` defaults a
missing `kind` to `terminal` for backward compat and migrates the legacy `tags:['claude']` marker
@@ -1988,6 +1989,56 @@ disappearing" rather than as an occasional cull. The `vm_stat` reader is what ma
again; the grace window was never the thing that was wrong.
+## Node icons (emoji or picture)
+
+A node may carry `data.icon` (`NodeIcon` in `@shared/node-icon`): `{type:'emoji', value}` or
+`{type:'image', path}`. Absent = the node draws exactly as it did before the feature, which is the
+degrade every failure path falls back to. Set from the node right-click menu ("Set icon…", hideable
+like Colors — id `icon`), from the icon itself in the terminal node header, and from the kanban card
+modal's header slot; drawn by the one `NodeIconView` on all four surfaces that list a node (canvas
+header, kanban card, card modal, sessions sidebar row), because a session seen in four places must
+not look like four sessions. **Terminal (session) nodes only in v1** — the menu row is gated on the
+kind, deliberately: offering it on an editor or a group frame would persist a value nothing draws,
+which is the "looks like it worked" failure this file warns about elsewhere. Extending it to sticky
+or browser nodes means adding the draw and the set together, in one change.
+
+- **`.nodeterm/project.json` is hostile input, so the icon is validated at BOTH serializer seams.**
+ `normalizeNodeIcon` runs in `nodeStatesToFlow` (a cloned file becoming live state) *and* in
+ `flowToNodeStates` (live state becoming the next reader's file — live node data is reachable by a
+ peer canvas mutation, and whatever we write is what the next machine trusts). One-sided validation
+ passes every round-trip test while leaving the other direction open; both seams are mutation-pinned
+ in `workspace.test.ts`.
+- **An emoji is ONE grapheme** (`Intl.Segmenter`, with a UTF-16 cap as the fallback, never as the
+ primary rule — slicing units cuts a ZWJ sequence into a fragment). Uncapped, a shared file could
+ put a 40 kB "emoji" into every header, card and sidebar row.
+- **An image path must LOOK like an image** (extension → MIME). That gate is what stops a hand-edited
+ project file from aiming `fs.readBinary` at `~/.ssh/id_rsa`. It is not a full jail — the path can
+ still name any `*.png` on the machine, exactly as an editor node's `filePath` always could — but
+ the bytes only ever become an `<img>` under a `'self'` CSP with no network, so the reachable
+ outcome is "an icon fails to draw". A `./` path may not traverse (same rule as
+ `isSafeQuickOpenRelPath`).
+- **The bytes are COPIED, not referenced.** The picker reads the chosen file and writes it through
+ `files.saveCanvasImage` — the same seam canvas image nodes use — so it lands in the project's
+ git-shared `.nodeterm/images/`. A path inside the project cwd is then stored `./`-relative
+ (`portableIconPath`) and resolved on read (`resolveIconPath`), which is the convention
+ `toPortableNodes` already set for node cwds. **This is the one place that convention is applied to
+ a `filePath`-like field**: canvas image nodes still store theirs absolutely, so their file travels
+ with the repo while the node naming it does not — an existing gap, not one this introduced.
+ A cwd-less canvas, an SSH project (its cwd is on the host; the image is written app-locally) and
+ the app-local fallback all keep an absolute path and simply do not travel. Not an error.
+- **A relay tab is refused** (`canvasImportRefusal`, the same message and the same reason as canvas
+ image import): the write is this machine's preload while the read is the peer's core, so the node
+ would name a file only this machine has. Reads otherwise go through the PROJECT's session api, not
+ `window.nodeTerminal` — which is what makes a peer-authored `./` icon resolve on the peer.
+- Image reads are cached per `(projectId, absPath)` in `lib/nodeIconImage.ts`, because four surfaces
+ mount independently and a thirty-card board would otherwise re-read the same bytes thirty times per
+ open. Caching by path is safe: `saveCanvasImage` creates exclusively, so re-picking yields
+ `logo (2).png` rather than overwriting.
+- **Surfaces.** Desktop: full. **Server Edition**: full — every leg is already core (`fs.readBinary`,
+ `files.saveCanvasImage`) or has a real browser implementation (`dialog.selectFile` → the web
+ picker), so no new IPC was added and nothing is stubbed. **Mobile**: N/A for v1 — *nodeterm mobile*
+ attaches to tmux sessions over the transport protocol and carries no per-node icon concept;
+ surfacing one means extending that protocol (follow-up in the iOS repo).
## Keybindings (registry, overrides, dispatch)
Every user-facing chord is a registry command, and the whole engine is **one module**:
diff --git a/src/renderer/App.tsx b/src/renderer/App.tsx
index dcaf01fb7..e120725d8 100644
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -2,6 +2,7 @@ import { useEffect } from 'react'
import { ReactFlowProvider } from '@xyflow/react'
import { Canvas } from './canvas/Canvas'
import { PromptDialogHost } from './components/promptDialog'
+import { NodeIconDialogHost } from './components/NodeIconPicker'
import { SessionProvider } from './session/session'
import { localSession } from './session/localSession'
import { useSettings } from './state/settings'
@@ -75,6 +76,9 @@ export default function App() {
<Canvas />
{/* In-app window.prompt replacement (Electron has no prompt); driven by promptDialog(). */}
<PromptDialogHost />
+ {/* The node-icon picker, opened from the node menu, a node header and the kanban card
+ modal — one dialog for all three, driven by nodeIconDialog(). */}
+ <NodeIconDialogHost />
</ReactFlowProvider>
</SessionProvider>
)
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 1cb4e2c7f..5dc855634 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -106,6 +106,7 @@ import {
IconLock,
IconMarkdown,
IconReload,
+ IconSmiley,
IconPower,
IconNote,
IconPhone,
@@ -385,6 +386,9 @@ import { promptFilePathError } from '@shared/agents/launch'
import { parseTeamSpec } from '../lib/teamSpec'
import { relativeTime } from '../lib/relativeTime'
import { AgentIcon } from '../lib/agentIcons'
+import { nodeIconDialog } from '../components/NodeIconPicker'
+import { applyIconChoice } from '../lib/nodeIconChoice'
+import type { NodeIcon } from '@shared/node-icon'
import { branchClaudeSession } from '../lib/claudeBranch'
import {
useSession,
@@ -2091,6 +2095,7 @@ export function Canvas() {
title: n.data.title ?? n.id,
color: n.data.color ?? '#888',
agentId: n.data.agentId,
+ icon: n.data.icon as NodeIcon | undefined,
cwd: n.data.cwd,
ssh: n.data.ssh,
parentId: n.parentId
@@ -6193,6 +6198,35 @@ export function Canvas() {
[setNodes, markDirty]
)
+ /** Write a node's icon (`undefined` clears it). The single funnel for every surface that sets
+ * one — the node menu, the node header and the kanban card modal — so the canvas is marked
+ * dirty exactly once per change and in one place. */
+ const setNodeIcon = useCallback(
+ (nodeId: string, icon: NodeIcon | undefined) => {
+ setNodes((ns) => ns.map((n) => (n.id === nodeId ? { ...n, data: { ...n.data, icon } } : n)))
+ markDirty()
+ },
+ [setNodes, markDirty]
+ )
+
+ /**
+ * Open the icon picker for ONE node and apply the answer. Single-target on purpose: an icon is
+ * how you tell two sessions apart, so setting the same one across a multi-selection is the
+ * opposite of what the feature is for — the menu row is offered only for a single node.
+ */
+ const pickNodeIcon = useCallback(
+ (nodeId: string) => {
+ const node = nodesRef.current.find((n) => n.id === nodeId)
+ if (!node) return
+ void nodeIconDialog({
+ nodeId,
+ title: (node.data.title as string) ?? '',
+ icon: node.data.icon as NodeIcon | undefined
+ }).then((choice) => applyIconChoice(choice, (icon) => setNodeIcon(nodeId, icon)))
+ },
+ [setNodeIcon]
+ )
+
const alignToGrid = useCallback(
(ids: string[]) => {
const g = useSettings.getState().settings.gridSize || GRID
@@ -7216,6 +7250,23 @@ export function Canvas() {
...(isHidden('colors', hidden)
? []
: ([{ type: 'colors', onPick: (c) => setNodesColor(ids, c) }] as MenuItem[])),
+ // Single target, and only a SESSION node: an icon is how you tell two sessions apart, so
+ // setting one across a multi-selection is the opposite of the point — and offering it on a
+ // kind that draws no icon (an editor, a diff, a group frame) would be a row that persists a
+ // value nothing ever shows, which is worse than no row at all.
+ ...(ids.length === 1 &&
+ !isHidden('icon', hidden) &&
+ nodesRef.current.find((n) => n.id === ids[0])?.type === 'terminal'
+ ? ([
+ {
+ label: nodesRef.current.find((n) => n.id === ids[0])?.data.icon
+ ? 'Change icon…'
+ : 'Set icon…',
+ icon: <IconSmiley />,
+ onClick: () => pickNodeIcon(ids[0])
+ }
+ ] as MenuItem[])
+ : []),
{ type: 'separator' },
...(isHidden('duplicate', hidden)
? []
@@ -12162,6 +12213,7 @@ export function Canvas() {
onDeleteNode={deleteNodeFromKanban}
onModalNodeChange={setKanbanModalNode}
onBrowserNav={browserNavFromKanban}
+ onSetIcon={setNodeIcon}
/>
)}
<UpdateCard />
diff --git a/src/renderer/canvas/toKanbanSession.ts b/src/renderer/canvas/toKanbanSession.ts
index 854945134..57db91a68 100644
--- a/src/renderer/canvas/toKanbanSession.ts
+++ b/src/renderer/canvas/toKanbanSession.ts
@@ -1,4 +1,5 @@
import type { SshConnection } from '@shared/ssh'
+import type { NodeIcon } from '@shared/node-icon'
import { NODE_COLORS, type CanvasNode } from '../state/workspace'
import type { KanbanSession } from '../components/kanban/KanbanView'
@@ -44,6 +45,7 @@ export function toKanbanSession(n: CanvasNode): KanbanSession | null {
color: (n.data.color as string) ?? NODE_COLORS[0],
kind: 'terminal',
agentId: n.data.agentId as string | undefined,
+ icon: n.data.icon as NodeIcon | undefined,
// What the card modal's co-attach terminal needs to join THIS node's session the same way the
// canvas TerminalNode does.
spawn: {
diff --git a/src/renderer/components/NodeIcon.tsx b/src/renderer/components/NodeIcon.tsx
new file mode 100644
index 000000000..7fdd2936a
--- /dev/null
+++ b/src/renderer/components/NodeIcon.tsx
@@ -0,0 +1,52 @@
+/**
+ * Drawing a node's icon. One component, used by every surface that lists a node — the canvas
+ * header, the kanban card, the card modal and the sessions sidebar — so an icon cannot look like
+ * four different things depending on where you happen to be looking at the session.
+ *
+ * Renders NOTHING (not a placeholder, not an empty box) when the node has no icon, when the icon
+ * is an image that is still loading, and when that image could not be read. All three are the same
+ * thing from the user's side: the node looks exactly as it did before the feature. An icon is
+ * decoration — it must never occupy space it cannot fill, and it must never announce its own
+ * failure in a header that is already carrying six chips.
+ */
+import type { NodeIcon } from '@shared/node-icon'
+import { useNodeIconSrc } from '../lib/nodeIconImage'
+
+export interface NodeIconViewProps {
+ icon?: NodeIcon
+ /** Rendered box in px. The emoji's font-size is derived from it so both forms agree optically. */
+ size?: number
+ /** Extra class for surface-specific spacing (the card and the header sit differently). */
+ className?: string
+ /** The node's project, for surfaces that list nodes across projects. See `useNodeIconSrc`. */
+ projectId?: string
+}
+
+export function NodeIconView({
+ icon,
+ size = 14,
+ className,
+ projectId
+}: NodeIconViewProps): React.JSX.Element | null {
+ // Called unconditionally (hook rules) — it answers null for an emoji icon and for no icon.
+ const src = useNodeIconSrc(icon, projectId)
+ if (!icon) return null
+ const cls = `node-icon${className ? ` ${className}` : ''}`
+ if (icon.type === 'emoji') {
+ return (
+ <span
+ className={cls}
+ style={{ width: size, height: size, fontSize: Math.round(size * 0.92) }}
+ aria-hidden
+ >
+ {icon.value}
+ </span>
+ )
+ }
+ if (!src) return null
+ return (
+ <span className={cls} style={{ width: size, height: size }} aria-hidden>
+ <img src={src} alt="" draggable={false} />
+ </span>
+ )
+}
diff --git a/src/renderer/components/NodeIconPicker.tsx b/src/renderer/components/NodeIconPicker.tsx
new file mode 100644
index 000000000..38eccd6ac
--- /dev/null
+++ b/src/renderer/components/NodeIconPicker.tsx
@@ -0,0 +1,229 @@
+/**
+ * Choosing a node's icon: an emoji from a small palette, any character typed by hand, or an image
+ * file from disk.
+ *
+ * Driven by the promise-based singleton `nodeIconDialog()` — the same shape as `promptDialog()` —
+ * so every surface that can set an icon (the node context menu, the node header, the kanban card
+ * modal) opens the SAME dialog and none of them has to own its state.
+ *
+ * The three outcomes are distinct on purpose, and the caller must keep them distinct:
+ * `NodeIcon` → set this icon. `null` → remove the icon. `undefined` → cancelled, change nothing.
+ * Collapsing "remove" into "cancel" is how a Remove button silently does nothing.
+ *
+ * **Where an image goes.** Not where the user picked it from: a path outside the project would
+ * break for everyone who clones the repo, and would break here the moment the file moves. The
+ * bytes are copied through `files.saveCanvasImage`, the same seam canvas image nodes use, which
+ * puts them in the project's git-shared `.nodeterm/images/` (or a durable app-local folder when
+ * the project has no local cwd). The stored path is then made `./`-relative by `portableIconPath`
+ * so the icon travels with the canvas that names it.
+ *
+ * **Relay tabs are refused**, with the same message and for the same reason canvas image import
+ * is: the write is this machine's preload while the read is the peer's core, so the node would end
+ * up naming a file only this machine has. A clear refusal beats an icon that can never draw.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { create } from 'zustand'
+import { type NodeIcon, normalizeNodeIcon, portableIconPath } from '@shared/node-icon'
+import { canvasImportRefusal } from '../canvas/canvas-image-import'
+import { useProjects } from '../state/projects'
+import { sessionForProject } from '../session/session'
+import { useDialogStack } from './dialog-stack'
+
+/**
+ * A small, deliberately opinionated palette rather than a full emoji keyboard. Grouped by what
+ * people actually label a terminal with — state, kind of work, subject matter — because the point
+ * is to tell twelve sessions apart at a glance, not to browse Unicode. Anything not here is one
+ * keystroke away in the input beside it, which is also where every platform's own emoji picker
+ * lands its result.
+ */
+const PALETTE: readonly string[] = [
+ '\u{1F680}', '\u{1F525}', '\u{2B50}', '\u{26A1}', '\u{1F41B}', '\u{1F527}',
+ '\u{1F9EA}', '\u{1F4E6}', '\u{1F310}', '\u{1F512}', '\u{1F5C4}', '\u{1F4CA}',
+ '\u{1F3AF}', '\u{1F4DD}', '\u{1F4DA}', '\u{1F9E0}', '\u{1F916}', '\u{1F441}',
+ '\u{1F3D7}', '\u{1F9F9}', '\u{1F6A8}', '\u{1F6A7}', '\u{2705}', '\u{1F534}',
+ '\u{1F7E2}', '\u{1F535}', '\u{1F7E1}', '\u{1F7E3}', '\u{1F3A8}', '\u{1F3B5}',
+ '\u{2615}', '\u{1F31E}', '\u{1F319}', '\u{1F332}', '\u{1F433}', '\u{1F431}'
+]
+
+/** `undefined` = cancelled (change nothing); `null` = remove the icon; a value = set it. */
+export type NodeIconChoice = NodeIcon | null | undefined
+
+interface DialogState {
+ current: {
+ nodeId: string
+ title: string
+ icon?: NodeIcon
+ resolve: (choice: NodeIconChoice) => void
+ } | null
+}
+
+const useStore = create<DialogState>(() => ({ current: null }))
+
+/**
+ * Open the icon dialog for one node and resolve with the user's choice. Opening a second one
+ * cancels the first (resolving `undefined`), matching `promptDialog`.
+ */
+export function nodeIconDialog(opts: {
+ nodeId: string
+ title: string
+ icon?: NodeIcon
+}): Promise<NodeIconChoice> {
+ return new Promise((resolve) => {
+ const prev = useStore.getState().current
+ if (prev) {
+ useStore.setState({ current: null })
+ prev.resolve(undefined)
+ }
+ useStore.setState({ current: { ...opts, resolve } })
+ })
+}
+
+/** Mount once, at the app root. Renders the active icon dialog, if any. */
+export function NodeIconDialogHost(): React.JSX.Element | null {
+ const current = useStore((s) => s.current)
+ if (!current) return null
+ const finish = (choice: NodeIconChoice): void => {
+ useStore.setState({ current: null })
+ current.resolve(choice)
+ }
+ return <NodeIconPicker title={current.title} icon={current.icon} onDone={finish} />
+}
+
+function NodeIconPicker({
+ title,
+ icon,
+ onDone
+}: {
+ title: string
+ icon?: NodeIcon
+ onDone: (choice: NodeIconChoice) => void
+}): React.JSX.Element {
+ const [typed, setTyped] = useState(icon?.type === 'emoji' ? icon.value : '')
+ const [busy, setBusy] = useState(false)
+ const [error, setError] = useState('')
+ const inputRef = useRef<HTMLInputElement>(null)
+ useDialogStack()
+
+ useEffect(() => {
+ inputRef.current?.focus()
+ }, [])
+
+ const commitTyped = (raw: string): void => {
+ // The same validator the persisted file goes through, so what the picker accepts and what a
+ // reload accepts cannot drift: type three characters, keep the first grapheme.
+ const next = normalizeNodeIcon({ type: 'emoji', value: raw })
+ onDone(next ?? null)
+ }
+
+ /**
+ * Copy the chosen file into the project and hand back a portable path. Every failure resolves to
+ * a message rather than a thrown error or a silently-missing icon: the user picked a file and is
+ * owed an answer about it.
+ */
+ const chooseImage = async (): Promise<void> => {
+ setError('')
+ const { activeProjectId, getProject } = useProjects.getState()
+ const project = activeProjectId ? getProject(activeProjectId) : undefined
+ if (!project) return
+ const refusal = canvasImportRefusal(!!project.remote)
+ if (refusal) {
+ setError(refusal)
+ return
+ }
+ const api = sessionForProject(project.id).api
+ const picked = await api.dialog.selectFile()
+ if (!picked) return
+ setBusy(true)
+ try {
+ const b64 = await api.fs.readBinary(picked)
+ if (!b64) {
+ setError('Could not read that file.')
+ return
+ }
+ const name = picked.split('/').pop() || 'icon.png'
+ const saved = await api.files.saveCanvasImage(project.id, name, b64)
+ if (!saved) {
+ setError('Could not save the image — check that this project’s folder is writable.')
+ return
+ }
+ // An SSH project writes app-locally (its cwd is on another machine), so `portableIconPath`
+ // is handed the LOCAL cwd only — for an SSH project that is undefined and the path stays
+ // absolute, which is exactly the non-travelling icon that case can honestly offer.
+ const stored = portableIconPath(saved, project.ssh ? undefined : project.cwd)
+ const next = normalizeNodeIcon({ type: 'image', path: stored })
+ if (!next) {
+ // Reachable when the picked file has an extension we do not render (a .heic, say). Saying
+ // which formats work is more use than "invalid".
+ setError('That file type cannot be used as an icon. Try PNG, JPEG, GIF, WEBP or SVG.')
+ return
+ }
+ onDone(next)
+ } finally {
+ setBusy(false)
+ }
+ }
+
+ return createPortal(
+ <div className="confirm-overlay" onClick={() => onDone(undefined)}>
+ <div className="confirm node-icon-dialog" onClick={(e) => e.stopPropagation()}>
+ <p className="confirm__msg">Icon for {title || 'this node'}</p>
+ <div className="node-icon-dialog__grid">
+ {PALETTE.map((e) => (
+ <button
+ key={e}
+ type="button"
+ className={`node-icon-dialog__swatch${
+ icon?.type === 'emoji' && icon.value === e ? ' is-current' : ''
+ }`}
+ onClick={() => onDone({ type: 'emoji', value: e })}
+ >
+ {e}
+ </button>
+ ))}
+ </div>
+ <div className="node-icon-dialog__row">
+ <input
+ ref={inputRef}
+ className="confirm__input node-icon-dialog__input"
+ value={typed}
+ placeholder="Or type any emoji or character"
+ spellCheck={false}
+ onChange={(e) => setTyped(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === 'Enter') {
+ e.preventDefault()
+ commitTyped(typed)
+ } else if (e.key === 'Escape') {
+ e.preventDefault()
+ onDone(undefined)
+ }
+ }}
+ />
+ <button
+ type="button"
+ className="confirm__btn"
+ disabled={busy}
+ onClick={() => void chooseImage()}
+ >
+ {busy ? 'Copying…' : 'Choose image…'}
+ </button>
+ </div>
+ {error && <p className="node-icon-dialog__error">{error}</p>}
+ <div className="confirm__actions">
+ {/* Distinct from Cancel: one clears the icon, the other leaves it alone. */}
+ <button type="button" className="confirm__btn" disabled={!icon} onClick={() => onDone(null)}>
+ Remove icon
+ </button>
+ <button type="button" className="confirm__btn" onClick={() => onDone(undefined)}>
+ Cancel
+ </button>
+ <button type="button" className="confirm__btn primary" onClick={() => commitTyped(typed)}>
+ Use
+ </button>
+ </div>
+ </div>
+ </div>,
+ document.body
+ )
+}
diff --git a/src/renderer/components/SessionRow.tsx b/src/renderer/components/SessionRow.tsx
index bdc7dd214..d141a8d90 100644
--- a/src/renderer/components/SessionRow.tsx
+++ b/src/renderer/components/SessionRow.tsx
@@ -1,5 +1,6 @@
import { useState } from 'react'
import { IconBellFilled, IconCircleCheck } from './icons'
+import { NodeIconView } from './NodeIcon'
import { ProjectGlyph } from './ProjectGlyph'
import type { SessionRowVM } from '../lib/sessionList'
import { useContextWindow } from '../state/contextWindow'
@@ -98,6 +99,11 @@ export function SessionRow({
)}
<div className="ss-row__body">
<div className="ss-row__titleline">
+ {/* Ahead of the project monogram: the icon identifies the SESSION, and a row that is
+ already carrying a status dot, a monogram and a context pill needs its most specific
+ mark first. `projectId` is passed because status mode flattens rows across projects,
+ so the active project is not necessarily this row's. */}
+ <NodeIconView icon={row.icon} size={13} className="ss-row__icon" projectId={row.projectId} />
{row.projectColor ? (
// Status mode: rows are flattened across projects, so each row shows its project's
// icon (or, absent one, the monogram — colored circle with the project initial)
diff --git a/src/renderer/components/icons.tsx b/src/renderer/components/icons.tsx
index 2e511fb0f..99e17a575 100644
--- a/src/renderer/components/icons.tsx
+++ b/src/renderer/components/icons.tsx
@@ -85,6 +85,17 @@ export const IconColor = () => (
</svg>
)
+/** "Set icon" — a face, for the emoji-or-picture the row actually sets. Deliberately unlike
+ * IconColor (a palette of dots), which sits directly above it in the same menu. */
+export const IconSmiley = () => (
+ <svg {...S}>
+ <circle cx="12" cy="12" r="8.5" />
+ <circle cx="9.2" cy="10" r="1.1" fill="currentColor" stroke="none" />
+ <circle cx="14.8" cy="10" r="1.1" fill="currentColor" stroke="none" />
+ <path d="M8.4 14.2a4.4 4.4 0 0 0 7.2 0" />
+ </svg>
+)
+
export const IconGrid = () => (
<svg {...S}>
<path d="M4 9h16M4 15h16M9 4v16M15 4v16" />
diff --git a/src/renderer/components/kanban/CardModal.test.tsx b/src/renderer/components/kanban/CardModal.test.tsx
index 64afefe73..92d0d64d8 100644
--- a/src/renderer/components/kanban/CardModal.test.tsx
+++ b/src/renderer/components/kanban/CardModal.test.tsx
@@ -92,6 +92,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={onEditSticky}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -172,6 +173,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -214,6 +216,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={onRename}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -289,6 +292,7 @@ describe('CardModal', () => {
onOpenCanvas={onOpenCanvas}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -342,6 +346,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -383,6 +388,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
@@ -436,6 +442,7 @@ describe('CardModal', () => {
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
diff --git a/src/renderer/components/kanban/CardModal.tsx b/src/renderer/components/kanban/CardModal.tsx
index 5d8019863..283a2bc63 100644
--- a/src/renderer/components/kanban/CardModal.tsx
+++ b/src/renderer/components/kanban/CardModal.tsx
@@ -1,7 +1,11 @@
import { useEffect, useRef, useState } from 'react'
import { createPortal } from 'react-dom'
import { isTopDialog, nextDialogId, popDialog, pushDialog } from '../dialog-stack'
-import { IconChat, IconMic, IconSearch } from '../icons'
+import { IconChat, IconMic, IconSearch, IconSmiley } from '../icons'
+import { NodeIconView } from '../NodeIcon'
+import { nodeIconDialog } from '../NodeIconPicker'
+import { applyIconChoice } from '../../lib/nodeIconChoice'
+import type { NodeIcon } from '@shared/node-icon'
import { ContextMeter } from '../ContextMeter'
import { useAgentStatus } from '../../state/agentStatus'
import { useCardPanel } from '../../state/cardPanel'
@@ -45,12 +49,14 @@ interface CardModalProps {
onEditSticky: (text: string) => void
/** Browser navigation write-through (only called for kind 'browser'). */
onBrowserNav: (patch: { url?: string; title?: string }) => void
+ /** Icon write-through. `undefined` clears it — the dialog's cancel never reaches here. */
+ onSetIcon: (icon: NodeIcon | undefined) => void
}
/** Trello-style card popup over the board. Scrim click / Esc close it; the board (and the
* canvas under it) stay mounted. Terminal cards carry the node header's actions too:
* search / dictate / AI-name / markdown view (the node itself is hidden under the board). */
-export function CardModal({ session, columnTitle, board, onChangeBoard, onClose, onOpenCanvas, onRename, onEditSticky, onBrowserNav }: CardModalProps) {
+export function CardModal({ session, columnTitle, board, onChangeBoard, onClose, onOpenCanvas, onRename, onEditSticky, onBrowserNav, onSetIcon }: CardModalProps) {
const { api } = useSession()
const idRef = useRef<string>()
if (!idRef.current) idRef.current = nextDialogId()
@@ -230,6 +236,19 @@ export function CardModal({ session, columnTitle, board, onChangeBoard, onClose,
}}
>
<span className="kanban-card__nodedot" style={{ background: session.color }} />
+ <button
+ className={`kanban-modal__icon${session.icon ? '' : ' kanban-modal__icon--empty'}`}
+ title={session.icon ? 'Change icon' : 'Set icon'}
+ onClick={() =>
+ void nodeIconDialog({
+ nodeId: session.id,
+ title: session.title,
+ icon: session.icon
+ }).then((choice) => applyIconChoice(choice, onSetIcon))
+ }
+ >
+ {session.icon ? <NodeIconView icon={session.icon} size={16} /> : <IconSmiley />}
+ </button>
{editingTitle ? (
<input
className="kanban-modal__rename"
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index 9ea6987a1..179a08414 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -1,5 +1,6 @@
import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
import type { KanbanLabel, ProjectKanban } from '@shared/types'
+import type { NodeIcon } from '@shared/node-icon'
import { AGENT_CONFIG, BUILTIN_AGENT_IDS, type AgentId } from '@shared/agents/config'
import { useViewMode } from '../../state/viewMode'
import { useProjects } from '../../state/projects'
@@ -50,6 +51,11 @@ export interface KanbanSession {
/** Browser node session partition (kind 'browser' only) — threaded to the modal webview so it
* shares the canvas node's jar (`browser-partition-parity.test.tsx`). Absent = default session. */
partition?: string
+ /** The node's user-chosen icon (see @shared/node-icon). The board is the canvas's other view of
+ * the same session, so a session the user marked with an icon carries it here too. Terminal
+ * cards only in v1 — that is the only kind whose canvas node offers the action, and a card
+ * showing an icon its node cannot set would be a dead end on the board. */
+ icon?: NodeIcon
/** The subset of the node's `data` the card modal's co-attach terminal needs to spawn/join the
* same session (kind 'terminal' only; sticky passes `{}`). */
spawn: ModalSpawn
@@ -89,6 +95,8 @@ export interface KanbanViewProps {
onModalNodeChange: (nodeId: string | null) => void
/** Persist a browser card's navigation (url/title) from the modal webview to the node. */
onBrowserNav: (nodeId: string, patch: { url?: string; title?: string }) => void
+ /** Set (or clear, with `undefined`) a node's icon — the card modal's icon button. */
+ onSetIcon: (nodeId: string, icon: NodeIcon | undefined) => void
}
type Drag =
@@ -117,7 +125,7 @@ const NO_CARDS: KanbanSession[] = []
* renders stop at this boundary. */
export const KanbanView = memo(function KanbanView({
board, sessions, onChange, onOpenNode, onCreateNode, onRenameNode, onEditSticky, onDeleteNode,
- onModalNodeChange, onBrowserNav
+ onModalNodeChange, onBrowserNav, onSetIcon
}: KanbanViewProps) {
const { api } = useSession()
const dragRef = useRef<Drag>(null)
@@ -663,6 +671,7 @@ export const KanbanView = memo(function KanbanView({
onRename={(t) => onRenameNode(modalNodeId, t)}
onEditSticky={(t) => onEditSticky(modalNodeId, t)}
onBrowserNav={(patch) => onBrowserNav(modalNodeId, patch)}
+ onSetIcon={(icon) => onSetIcon(modalNodeId, icon)}
/>
)}
{modalIssue && (
diff --git a/src/renderer/components/kanban/SessionCard.tsx b/src/renderer/components/kanban/SessionCard.tsx
index 48a571809..3502b90db 100644
--- a/src/renderer/components/kanban/SessionCard.tsx
+++ b/src/renderer/components/kanban/SessionCard.tsx
@@ -2,6 +2,7 @@ import { memo, useState } from 'react'
import type { KanbanCardMeta, KanbanLabel, KanbanPriority } from '@shared/types'
import { useAgentStatus } from '../../state/agentStatus'
import { ContextMeter } from '../ContextMeter'
+import { NodeIconView } from '../NodeIcon'
import { LabelChips } from './LabelChips'
import type { KanbanSession } from './KanbanView'
@@ -105,6 +106,7 @@ export const SessionCard = memo(function SessionCard({
>
<div className="kanban-card__row">
<span className="kanban-card__nodedot" style={{ background: session.color }} />
+ <NodeIconView icon={session.icon} size={14} className="kanban-card__icon" />
<span className="kanban-card__title">{session.title}</span>
{session.kind === 'sticky' && <span className="kanban-card__kind">note</span>}
{session.kind === 'browser' && <span className="kanban-card__kind">web</span>}
diff --git a/src/renderer/lib/nodeIconChoice.test.ts b/src/renderer/lib/nodeIconChoice.test.ts
new file mode 100644
index 000000000..98102ea24
--- /dev/null
+++ b/src/renderer/lib/nodeIconChoice.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest'
+import { applyIconChoice } from './nodeIconChoice'
+
+describe('applyIconChoice', () => {
+ it('sets the chosen icon', () => {
+ const apply = vi.fn()
+ applyIconChoice({ type: 'emoji', value: '\u{1F680}' }, apply)
+ expect(apply).toHaveBeenCalledWith({ type: 'emoji', value: '\u{1F680}' })
+ })
+
+ // The distinction the whole module exists for: `if (!choice) return` passes every test above
+ // and breaks exactly this one.
+ it('clears the icon on remove', () => {
+ const apply = vi.fn()
+ applyIconChoice(null, apply)
+ expect(apply).toHaveBeenCalledTimes(1)
+ expect(apply).toHaveBeenCalledWith(undefined)
+ })
+
+ it('does nothing at all on cancel, so a cancel cannot mark the canvas dirty', () => {
+ const apply = vi.fn()
+ applyIconChoice(undefined, apply)
+ expect(apply).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/renderer/lib/nodeIconChoice.ts b/src/renderer/lib/nodeIconChoice.ts
new file mode 100644
index 000000000..085c0ce08
--- /dev/null
+++ b/src/renderer/lib/nodeIconChoice.ts
@@ -0,0 +1,29 @@
+/**
+ * What the icon dialog's answer MEANS, in one place.
+ *
+ * The dialog has three outcomes and two of them are easy to confuse, because JavaScript makes
+ * `null` and `undefined` look interchangeable right up until they are not:
+ *
+ * a `NodeIcon` → set this icon
+ * `null` → remove the icon the node has
+ * `undefined` → cancelled; the node keeps whatever it had
+ *
+ * Written inline at each call site, "remove" and "cancel" collapse the moment someone writes
+ * `if (!choice) return` — which reads as obviously correct and silently turns the Remove button
+ * into a second Cancel. Three surfaces open this dialog, so the rule lives here once and is
+ * pinned by a test rather than by three identical conditionals.
+ */
+import type { NodeIcon } from '@shared/node-icon'
+import type { NodeIconChoice } from '../components/NodeIconPicker'
+
+/**
+ * Apply a dialog answer. `apply` is called with the new icon, or with `undefined` to clear it —
+ * and is NOT called at all when the user cancelled, so a cancel never marks the canvas dirty.
+ */
+export function applyIconChoice(
+ choice: NodeIconChoice,
+ apply: (icon: NodeIcon | undefined) => void
+): void {
+ if (choice === undefined) return
+ apply(choice ?? undefined)
+}
diff --git a/src/renderer/lib/nodeIconImage.ts b/src/renderer/lib/nodeIconImage.ts
new file mode 100644
index 000000000..b92c687c6
--- /dev/null
+++ b/src/renderer/lib/nodeIconImage.ts
@@ -0,0 +1,112 @@
+/**
+ * Turning a node's icon IMAGE into something an `<img>` can show, once per file rather than once
+ * per place it is drawn.
+ *
+ * The same icon appears on the canvas node header, on its kanban card, in the card modal and in
+ * the sessions sidebar — four components that mount and unmount independently. Read per component
+ * and a board of thirty sessions issues thirty duplicate `readBinary` round trips on every open,
+ * for bytes that have not changed. So the promise is cached by absolute path and every caller
+ * awaits the same one.
+ *
+ * Caching by PATH is safe because a picked image is never overwritten in place: `saveCanvasImage`
+ * creates exclusively (`wx`) and walks `candidateName`, so re-picking produces `logo (2).png`, a
+ * different key. An icon the user points at an arbitrary file they later edit is the one case a
+ * stale entry could survive, and it costs an app restart — the trade a per-render re-read is not
+ * worth.
+ *
+ * Reads go through the PROJECT's own session api, not `window.nodeTerminal`: a relay tab's project
+ * lives on a peer's core, and its `./`-relative icon resolves against the peer's cwd. Reading it
+ * locally would ask this machine for a path only that one has.
+ */
+import { useEffect, useState } from 'react'
+import type { FsApi } from '@shared/types'
+import { type NodeIcon, nodeIconMime, resolveIconPath } from '@shared/node-icon'
+import { sessionForProject } from '../session/session'
+import { useProjects } from '../state/projects'
+
+/**
+ * Bounded so a long session that visits many projects cannot grow it without limit. Icons are
+ * small and few per canvas; 128 is far above any real board and still a fixed ceiling.
+ */
+const CACHE_MAX = 128
+
+/**
+ * An icon big enough to be worth refusing. `readBinary` already returns a sentinel STRING above
+ * its own cap rather than base64, and that sentinel is not valid base64 — an `<img>` fed it shows
+ * a broken-image glyph on every surface, which is worse than no icon. This bound catches both
+ * that case and a merely huge file, and its unit is base64 characters (~3/4 of a byte each).
+ */
+const SRC_MAX_CHARS = 4_000_000
+
+const cache = new Map<string, Promise<string | null>>()
+
+/** The cache key includes the reader: two projects can resolve the same `./` path against
+ * different roots, and a relay project's read lands on another machine entirely. */
+const keyFor = (projectId: string, absPath: string): string => `${projectId}\x00${absPath}`
+
+/** Test seam, and the escape hatch for "I replaced the file on disk". */
+export function clearNodeIconCache(): void {
+ cache.clear()
+}
+
+/**
+ * Read `absPath` as a data URL, or null when it could not be read. Never rejects: an icon that
+ * cannot be drawn falls back to no icon, which is the pre-feature node.
+ */
+export function loadNodeIconSrc(
+ fs: FsApi,
+ projectId: string,
+ absPath: string
+): Promise<string | null> {
+ const key = keyFor(projectId, absPath)
+ const hit = cache.get(key)
+ if (hit) return hit
+ const mime = nodeIconMime(absPath)
+ // Unreachable through `normalizeNodeIcon` (which already refuses a non-image extension), and
+ // deliberately still checked: this function is exported and the next caller may not have gone
+ // through it.
+ if (!mime) return Promise.resolve(null)
+ const pending = Promise.resolve()
+ .then(() => fs.readBinary(absPath))
+ .then((b64) => (b64 && b64.length < SRC_MAX_CHARS ? `data:${mime};base64,${b64}` : null))
+ .catch(() => null)
+ if (cache.size >= CACHE_MAX) cache.delete(cache.keys().next().value as string)
+ cache.set(key, pending)
+ return pending
+}
+
+/**
+ * The `src` for an icon image, or null while it loads / when it cannot be read. `projectId`
+ * defaults to the active project — pass it explicitly from any surface that lists nodes across
+ * projects (the sessions sidebar's status mode does), or the icon resolves against the wrong root.
+ */
+export function useNodeIconSrc(icon: NodeIcon | undefined, projectId?: string): string | null {
+ const activeProjectId = useProjects((s) => s.activeProjectId)
+ const pid = projectId ?? activeProjectId
+ const storedPath = icon?.type === 'image' ? icon.path : null
+ const cwd = useProjects((s) => (pid ? s.getProject(pid)?.cwd : undefined))
+ const [src, setSrc] = useState<string | null>(null)
+
+ useEffect(() => {
+ if (!storedPath || !pid) {
+ setSrc(null)
+ return
+ }
+ const abs = resolveIconPath(storedPath, cwd)
+ if (!abs) {
+ // A `./` icon on a project with no local cwd: the file belongs to a checkout this machine
+ // does not have. Nothing to read, and nothing worth guessing at.
+ setSrc(null)
+ return
+ }
+ let live = true
+ void loadNodeIconSrc(sessionForProject(pid).api.fs, pid, abs).then((v) => {
+ if (live) setSrc(v)
+ })
+ return () => {
+ live = false
+ }
+ }, [storedPath, pid, cwd])
+
+ return src
+}
diff --git a/src/renderer/lib/sessionList.ts b/src/renderer/lib/sessionList.ts
index 83617f3b4..67c0da14c 100644
--- a/src/renderer/lib/sessionList.ts
+++ b/src/renderer/lib/sessionList.ts
@@ -1,6 +1,7 @@
import type { AgentNodeStatus } from '../state/agentStatus'
import type { AgentId } from '@shared/agents/config'
import type { NodeKind } from '@shared/types'
+import type { NodeIcon } from '@shared/node-icon'
import { hasUsage } from '@shared/agents/config'
import type { SshConnection } from '@shared/ssh'
import type { ProjectIcon } from '@shared/project-icon'
@@ -16,6 +17,8 @@ export interface SessionNodeInput {
ssh?: SshConnection
/** Parent group node id when this node lives inside a canvas group frame. */
parentId?: string
+ /** The node's user-chosen icon (see @shared/node-icon). */
+ icon?: NodeIcon
}
export interface ProjectInput {
@@ -223,6 +226,7 @@ export interface SessionRowVM {
title: string
color: string
agentId?: AgentId
+ icon?: NodeIcon
isAgent: boolean
statusKind: StatusKind
stateLabel: string
@@ -292,6 +296,7 @@ function toRow(
title: n.title,
color: n.color,
agentId: n.agentId,
+ icon: n.icon,
isAgent: !!n.agentId,
statusKind,
stateLabel: STATE_LABEL[statusKind],
diff --git a/src/renderer/lib/ui-visibility.test.ts b/src/renderer/lib/ui-visibility.test.ts
index 3ee97190d..0db7422ad 100644
--- a/src/renderer/lib/ui-visibility.test.ts
+++ b/src/renderer/lib/ui-visibility.test.ts
@@ -23,7 +23,7 @@ describe('isHidden', () => {
describe('hideable inventories', () => {
it('list the agreed ids and nothing destructive', () => {
expect(HIDEABLE_MENU_ITEMS.map((r) => r.id)).toEqual([
- 'group', 'remove-from-group', 'colors', 'duplicate', 'snap-zone', 'collapse',
+ 'group', 'remove-from-group', 'colors', 'icon', 'duplicate', 'snap-zone', 'collapse',
'markdown-view', 'refresh-terminal'
])
expect(HIDEABLE_HEADER_BUTTONS.map((r) => r.id)).toEqual([
diff --git a/src/renderer/lib/ui-visibility.ts b/src/renderer/lib/ui-visibility.ts
index abd14f970..c846e5fe8 100644
--- a/src/renderer/lib/ui-visibility.ts
+++ b/src/renderer/lib/ui-visibility.ts
@@ -22,6 +22,7 @@ export const HIDEABLE_MENU_ITEMS: readonly HideableRow[] = [
{ id: 'group', label: 'Group node / Group selection' },
{ id: 'remove-from-group', label: 'Remove from group' },
{ id: 'colors', label: 'Colors' },
+ { id: 'icon', label: 'Set icon' },
{ id: 'duplicate', label: 'Duplicate' },
{ id: 'snap-zone', label: 'Snap to zone' },
{ id: 'collapse', label: 'Collapse / Expand' },
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 651da8ba5..be88035e3 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -191,6 +191,10 @@ import { ColumnPill } from '../components/kanban/ColumnPill'
import { BoardLogPanel } from '../components/kanban/BoardLogPanel'
import { AgentMascot } from './AgentMascot'
import { MaximizeButton } from './MaximizeButton'
+import { NodeIconView } from '../components/NodeIcon'
+import { nodeIconDialog } from '../components/NodeIconPicker'
+import { applyIconChoice } from '../lib/nodeIconChoice'
+import type { NodeIcon } from '@shared/node-icon'
import { connectHostAttachment } from '../lib/sshAttachments'
/** Which physical modifier the registry's abstract `Cmd` resolves to for the find-bar chord. */
@@ -4698,6 +4702,24 @@ export function TerminalNode({
))}
</div>
)}
+ {data.icon ? (
+ <button
+ className="term-node__icon nodrag"
+ title="Change icon"
+ onClick={(e) => {
+ e.stopPropagation()
+ void nodeIconDialog({
+ nodeId: id,
+ title: (data.title as string) ?? '',
+ icon: data.icon as NodeIcon
+ }).then((choice) =>
+ applyIconChoice(choice, (icon) => updateNodeData(id, { icon }))
+ )
+ }}
+ >
+ <NodeIconView icon={data.icon as NodeIcon} size={15} />
+ </button>
+ ) : null}
{editingTitle ? (
<input
className="term-node__title nodrag"
diff --git a/src/renderer/nodes/browser-partition-parity.test.tsx b/src/renderer/nodes/browser-partition-parity.test.tsx
index f1d0022bb..12513eaef 100644
--- a/src/renderer/nodes/browser-partition-parity.test.tsx
+++ b/src/renderer/nodes/browser-partition-parity.test.tsx
@@ -79,6 +79,7 @@ function partitionFromModal(sessionPartition: string | undefined): string | null
onOpenCanvas={vi.fn()}
onRename={vi.fn()}
onEditSticky={vi.fn()}
+ onSetIcon={vi.fn()}
onBrowserNav={vi.fn()}
/>
)
diff --git a/src/renderer/state/workspace.test.ts b/src/renderer/state/workspace.test.ts
index 65e4c6d0f..496893e6f 100644
--- a/src/renderer/state/workspace.test.ts
+++ b/src/renderer/state/workspace.test.ts
@@ -541,6 +541,66 @@ describe('group worktree serialization', () => {
})
})
+describe('node icon serialization', () => {
+ const withIcon = (icon: unknown): CanvasNode =>
+ ({
+ id: 't1',
+ type: 'terminal',
+ position: { x: 0, y: 0 },
+ width: 320,
+ height: 240,
+ data: { title: 'T', color: '#888', group: null, icon }
+ }) as unknown as CanvasNode
+
+ const stateWithIcon = (icon: unknown) => ({
+ id: 't1',
+ kind: 'terminal' as const,
+ position: { x: 0, y: 0 },
+ size: { width: 320, height: 240 },
+ title: 'T',
+ color: '#888',
+ group: null,
+ icon
+ })
+
+ it('round-trips an emoji icon', () => {
+ const icon = { type: 'emoji', value: '\u{1F680}' }
+ const states = flowToNodeStates([withIcon(icon)])
+ expect(states[0].icon).toEqual(icon)
+ expect(nodeStatesToFlow(states)[0].data.icon).toEqual(icon)
+ })
+
+ it('round-trips an image icon', () => {
+ const icon = { type: 'image', path: './.nodeterm/images/logo.png' }
+ const states = flowToNodeStates([withIcon(icon)])
+ expect(states[0].icon).toEqual(icon)
+ expect(nodeStatesToFlow(states)[0].data.icon).toEqual(icon)
+ })
+
+ it('leaves a node without one undefined, so an untouched canvas serializes as it always did', () => {
+ expect(flowToNodeStates([withIcon(undefined)])[0].icon).toBeUndefined()
+ })
+
+ // project.json is git-shared and hand-editable, so hydration is a trust boundary. A path that is
+ // not an image would otherwise reach `fs.readBinary` on load.
+ it('drops a hostile icon on the way IN', () => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const hydrate = (icon: unknown) => nodeStatesToFlow([stateWithIcon(icon) as any])[0].data.icon
+ expect(hydrate({ type: 'image', path: '/home/u/.ssh/id_rsa' })).toBeUndefined()
+ expect(hydrate({ type: 'image', path: './../../.ssh/id_rsa.png' })).toBeUndefined()
+ expect(hydrate({ type: 'nonsense' })).toBeUndefined()
+ expect(hydrate('\u{1F680}')).toBeUndefined()
+ expect(hydrate({ type: 'emoji', value: 'abcdef' })).toEqual({ type: 'emoji', value: 'a' })
+ })
+
+ // And on the way OUT too: live node data can be reached by a peer canvas mutation, and whatever
+ // is written here becomes the next reader's "trusted" file.
+ it('drops a hostile icon on the way OUT', () => {
+ expect(flowToNodeStates([withIcon({ type: 'image', path: '/etc/passwd' })])[0].icon).toBeUndefined()
+ expect(flowToNodeStates([withIcon({ type: 'emoji', value: '' })])[0].icon).toBeUndefined()
+ })
+})
+
describe('resolveNewNodeAccount', () => {
const accounts = [{ id: 'a1', label: 'work', createdAt: 0 }]
it('prefers the explicit pick', () =>
diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.ts
index edceb2085..caa60ac5d 100644
--- a/src/renderer/state/workspace.ts
+++ b/src/renderer/state/workspace.ts
@@ -19,6 +19,7 @@ import { projectLaunchInfoNow } from './projectLaunchInfo'
import { isAgentEnabled, launchableDefaultAgent } from './agentAvailability'
import { codexSharedIdentity } from './codexIdentity'
import { sshHostKey } from '@shared/ssh'
+import { normalizeNodeIcon } from '@shared/node-icon'
import { useSettings } from './settings'
// Re-exported so Canvas (and anything else in the renderer) keeps importing it from here, while the
@@ -1795,6 +1796,10 @@ export function nodeStatesToFlow(states: CanvasNodeState[]): CanvasNode[] {
tags: n.tags,
collapsed,
hideFanout: n.hideFanout,
+ // Validated HERE, at the seam where a git-shared, hand-editable project file becomes live
+ // node data — so every surface that renders an icon gets a value this module vouched for
+ // rather than each one re-deciding. An unrecognized icon becomes no icon.
+ icon: normalizeNodeIcon(n.icon),
expandedHeight: n.size.height,
premaxRect: n.premaxRect,
shell: n.shell,
@@ -1869,6 +1874,11 @@ export function flowToNodeStates(nodes: CanvasNode[]): CanvasNodeState[] {
tags: n.data.tags,
collapsed: n.data.collapsed,
hideFanout: n.data.hideFanout,
+ // React Flow's node `data` is `Record<string, unknown>`, so the icon comes back out
+ // untyped. Re-validating on the way OUT (not just on the way in) also means a value a
+ // peer canvas mutation or a future caller put on live node data cannot be written to the
+ // shared file unchecked — the file is only ever as trustworthy as its last writer.
+ icon: normalizeNodeIcon(n.data.icon),
parentId: n.parentId,
shell: n.data.shell,
cwd: n.data.cwd,
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 5bf018ffb..f41949b1e 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -11750,3 +11750,126 @@ body.focus-mode .dock:hover {
color: var(--muted);
font-size: 13px;
}
+
+/* ── Node icons (emoji or picture) ─────────────────────────────────────────────────────────
+ One shared box for every surface that draws a node's icon — canvas header, kanban card, card
+ modal, sessions sidebar — so the same session reads the same in all four. Sized by the caller
+ (inline width/height) because a 13px sidebar row and a 16px modal header want different boxes;
+ everything else about how it draws is here.
+
+ `line-height: 1` matters more than it looks: an emoji inherits the surrounding line box, and a
+ header row that is exactly its own text height grows by a couple of px when one is inserted —
+ which nudges every chip beside it. */
+.node-icon {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ flex-shrink: 0;
+ line-height: 1;
+ overflow: hidden;
+ /* Emoji fonts differ in how much of the em they fill; centering the glyph in a fixed box keeps
+ a 🚀 and a 🟢 optically the same size rather than the same font-size. */
+ text-align: center;
+}
+
+.node-icon img {
+ width: 100%;
+ height: 100%;
+ /* `contain`, not `cover`: an icon the user picked is usually a logo, and cropping a logo to a
+ square is the one thing that makes it unrecognizable at 14px. */
+ object-fit: contain;
+ border-radius: 3px;
+ display: block;
+}
+
+/* The canvas node header's icon is a button (click re-opens the picker) but must not look like
+ one — it sits between the color swatch and the title, which are both flat. */
+.term-node__icon {
+ background: none;
+ border: none;
+ padding: 0;
+ margin: 0;
+ display: inline-flex;
+ align-items: center;
+ cursor: pointer;
+ flex-shrink: 0;
+ opacity: 0.95;
+}
+.term-node__icon:hover {
+ opacity: 1;
+}
+
+.kanban-card__row > .node-icon.kanban-card__icon {
+ margin-top: 4px; /* optically centers on the first title line, like the color dot beside it */
+}
+
+/* The card modal always offers the action, so its slot is present even with no icon set — muted
+ until it has one, so an unset icon reads as an affordance rather than as a missing image. */
+.kanban-modal__icon {
+ background: none;
+ border: none;
+ padding: 2px;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ cursor: pointer;
+ color: var(--muted);
+ border-radius: 5px;
+ flex-shrink: 0;
+}
+.kanban-modal__icon:hover {
+ background: rgba(var(--tint-rgb), 0.1);
+ color: var(--text);
+}
+.kanban-modal__icon--empty {
+ opacity: 0.5;
+}
+.kanban-modal__icon--empty:hover {
+ opacity: 1;
+}
+
+/* ── The icon picker dialog ───────────────────────────────────────────────────────────────── */
+.node-icon-dialog {
+ min-width: 340px;
+}
+
+.node-icon-dialog__grid {
+ display: grid;
+ grid-template-columns: repeat(9, 1fr);
+ gap: 2px;
+ margin: 10px 0 4px;
+}
+
+.node-icon-dialog__swatch {
+ background: none;
+ border: none;
+ border-radius: 6px;
+ padding: 4px 0;
+ font-size: 18px;
+ line-height: 1.2;
+ cursor: pointer;
+}
+.node-icon-dialog__swatch:hover {
+ background: rgba(var(--tint-rgb), 0.12);
+}
+.node-icon-dialog__swatch.is-current {
+ background: color-mix(in srgb, var(--accent) 35%, transparent);
+}
+
+.node-icon-dialog__row {
+ display: flex;
+ gap: 8px;
+ align-items: center;
+ margin-top: 6px;
+}
+
+.node-icon-dialog__input {
+ flex: 1;
+ min-width: 0;
+}
+
+.node-icon-dialog__error {
+ margin: 8px 0 0;
+ font-size: 12px;
+ color: var(--danger);
+}
diff --git a/src/shared/node-icon.test.ts b/src/shared/node-icon.test.ts
new file mode 100644
index 000000000..638eeb74c
--- /dev/null
+++ b/src/shared/node-icon.test.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest'
+import {
+ nodeIconMime,
+ normalizeNodeIcon,
+ portableIconPath,
+ resolveIconPath
+} from './node-icon'
+
+// The value under test arrives from `.nodeterm/project.json` — git-shared, hand-editable, and on
+// an SSH project a file on someone else's host. Every case below is a thing that file can say.
+describe('normalizeNodeIcon', () => {
+ it('keeps a single emoji', () => {
+ expect(normalizeNodeIcon({ type: 'emoji', value: 'rocket'.length ? '\u{1F680}' : '' })).toEqual({
+ type: 'emoji',
+ value: '\u{1F680}'
+ })
+ })
+
+ it('keeps a ZWJ sequence whole', () => {
+ // 11 UTF-16 units. A naive length cap would reject it; a naive slice would cut it into a
+ // fragment that renders as two lone people. Neither is acceptable.
+ const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}'
+ expect(normalizeNodeIcon({ type: 'emoji', value: family })).toEqual({
+ type: 'emoji',
+ value: family
+ })
+ })
+
+ it('truncates a multi-character value to its first grapheme', () => {
+ expect(normalizeNodeIcon({ type: 'emoji', value: 'abc' })).toEqual({ type: 'emoji', value: 'a' })
+ })
+
+ it('caps a blob from a shared file instead of rendering it into every surface', () => {
+ const blob = '\u{1F680}'.repeat(5000)
+ const out = normalizeNodeIcon({ type: 'emoji', value: blob })
+ expect(out).toEqual({ type: 'emoji', value: '\u{1F680}' })
+ })
+
+ it('strips control characters rather than letting a paste carry them into a header', () => {
+ const withNewline = `${String.fromCharCode(10)}${String.fromCharCode(7)}\u{1F41B}`
+ expect(normalizeNodeIcon({ type: 'emoji', value: withNewline })).toEqual({
+ type: 'emoji',
+ value: '\u{1F41B}'
+ })
+ })
+
+ it('refuses an emoji that is only whitespace or control characters', () => {
+ expect(normalizeNodeIcon({ type: 'emoji', value: ' ' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'emoji', value: String.fromCharCode(9) })).toBeUndefined()
+ })
+
+ it('refuses shapes that are not an icon at all', () => {
+ expect(normalizeNodeIcon(undefined)).toBeUndefined()
+ expect(normalizeNodeIcon(null)).toBeUndefined()
+ expect(normalizeNodeIcon('\u{1F680}')).toBeUndefined()
+ expect(normalizeNodeIcon(42)).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'svg', markup: '<script/>' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'emoji', value: 7 })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: 7 })).toBeUndefined()
+ })
+
+ it('keeps an absolute image path with a known extension', () => {
+ expect(normalizeNodeIcon({ type: 'image', path: '/tmp/a/logo.PNG' })).toEqual({
+ type: 'image',
+ path: '/tmp/a/logo.PNG'
+ })
+ })
+
+ it('keeps a project-relative image path', () => {
+ expect(normalizeNodeIcon({ type: 'image', path: './.nodeterm/images/logo.png' })).toEqual({
+ type: 'image',
+ path: './.nodeterm/images/logo.png'
+ })
+ })
+
+ // The gate that stops a cloned project.json from aiming fs.readBinary at a private key.
+ it('refuses a path that is not an image', () => {
+ expect(normalizeNodeIcon({ type: 'image', path: '/home/u/.ssh/id_rsa' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: '/etc/passwd' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: '/home/u/README' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: '/home/u/notes.png.txt' })).toBeUndefined()
+ })
+
+ it('refuses a relative path that traverses out of the project', () => {
+ expect(normalizeNodeIcon({ type: 'image', path: './../../.ssh/id_rsa.png' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: './a/../../b.png' })).toBeUndefined()
+ })
+
+ it('refuses a rootless path, which has nothing to resolve against', () => {
+ expect(normalizeNodeIcon({ type: 'image', path: 'logo.png' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: '../logo.png' })).toBeUndefined()
+ expect(normalizeNodeIcon({ type: 'image', path: '' })).toBeUndefined()
+ })
+
+ it('refuses a path carrying control characters', () => {
+ const sneaky = `/tmp/a${String.fromCharCode(0)}.png`
+ expect(normalizeNodeIcon({ type: 'image', path: sneaky })).toBeUndefined()
+ })
+})
+
+describe('nodeIconMime', () => {
+ it('maps known extensions case-insensitively', () => {
+ expect(nodeIconMime('/a/b.PNG')).toBe('image/png')
+ expect(nodeIconMime('/a/b.jpeg')).toBe('image/jpeg')
+ expect(nodeIconMime('./x.svg')).toBe('image/svg+xml')
+ })
+
+ it('answers undefined for a name with no extension', () => {
+ expect(nodeIconMime('/a/README')).toBeUndefined()
+ expect(nodeIconMime('/a/.gitignore')).toBeUndefined()
+ expect(nodeIconMime('/a/b.key')).toBeUndefined()
+ })
+})
+
+describe('portableIconPath', () => {
+ it('rewrites a path inside the project to ./ form so it travels with the repo', () => {
+ expect(portableIconPath('/repo/.nodeterm/images/a.png', '/repo')).toBe(
+ './.nodeterm/images/a.png'
+ )
+ // A trailing slash on the cwd must not produce a doubled separator or a missed match.
+ expect(portableIconPath('/repo/.nodeterm/images/a.png', '/repo/')).toBe(
+ './.nodeterm/images/a.png'
+ )
+ })
+
+ it('leaves a path outside the project absolute', () => {
+ expect(portableIconPath('/elsewhere/a.png', '/repo')).toBe('/elsewhere/a.png')
+ // A sibling directory that merely shares a prefix is NOT inside the project.
+ expect(portableIconPath('/repo-two/a.png', '/repo')).toBe('/repo-two/a.png')
+ })
+
+ it('leaves everything absolute when the project has no local cwd', () => {
+ expect(portableIconPath('/appdata/canvas-images/a.png', undefined)).toBe(
+ '/appdata/canvas-images/a.png'
+ )
+ })
+})
+
+describe('resolveIconPath', () => {
+ it('resolves a ./ path against the project cwd', () => {
+ expect(resolveIconPath('./.nodeterm/images/a.png', '/repo')).toBe('/repo/.nodeterm/images/a.png')
+ expect(resolveIconPath('./.nodeterm/images/a.png', '/repo/')).toBe(
+ '/repo/.nodeterm/images/a.png'
+ )
+ })
+
+ it('passes an absolute path through', () => {
+ expect(resolveIconPath('/appdata/a.png', '/repo')).toBe('/appdata/a.png')
+ expect(resolveIconPath('/appdata/a.png', undefined)).toBe('/appdata/a.png')
+ })
+
+ // The icon simply does not draw. It must never fall back to reading something else.
+ it('answers undefined for a ./ path on a project with no local cwd', () => {
+ expect(resolveIconPath('./.nodeterm/images/a.png', undefined)).toBeUndefined()
+ })
+
+ it('answers undefined for a traversing or rootless path', () => {
+ expect(resolveIconPath('./../secrets/a.png', '/repo')).toBeUndefined()
+ expect(resolveIconPath('a.png', '/repo')).toBeUndefined()
+ })
+})
+
+// Round-tripping is the property the portability story actually rests on: what we store must be
+// what we can read back, for both a project-local and an app-local icon.
+describe('portable round trip', () => {
+ it('survives store -> normalize -> resolve', () => {
+ for (const [abs, cwd] of [
+ ['/repo/.nodeterm/images/a.png', '/repo'],
+ ['/appdata/canvas-images/b.png', undefined]
+ ] as const) {
+ const stored = portableIconPath(abs, cwd)
+ const icon = normalizeNodeIcon({ type: 'image', path: stored })
+ expect(icon).toBeDefined()
+ expect(resolveIconPath((icon as { path: string }).path, cwd)).toBe(abs)
+ }
+ })
+})
diff --git a/src/shared/node-icon.ts b/src/shared/node-icon.ts
new file mode 100644
index 000000000..392583013
--- /dev/null
+++ b/src/shared/node-icon.ts
@@ -0,0 +1,170 @@
+/**
+ * A canvas node's user-chosen icon: one emoji/character, or a small image file.
+ *
+ * The value is persisted in `.nodeterm/project.json`, which is git-shared, hand-editable and —
+ * for an SSH project — a file on the remote host. So nothing here trusts its input: every value
+ * that reaches a render or a filesystem read goes through `normalizeNodeIcon` FIRST, at the point
+ * of use, exactly as `permissionModeFlag` re-validates a permission mode and `safeSessionProgram`
+ * re-validates a session program. The TypeScript type is a compile-time claim about our own
+ * writers; it says nothing about a file someone cloned.
+ *
+ * Three rules, and each one is the answer to a specific way this could go wrong:
+ *
+ * 1. **An emoji is ONE grapheme.** Without a cap, `"icon": {"type":"emoji","value":"<40kB>"}`
+ * in a shared project file is a blob rendered into every node header, every kanban card and
+ * every sidebar row. Truncating is safe (the user sees a shorter icon than they typed);
+ * refusing outright would drop a perfectly good four-person ZWJ family emoji, which is 11
+ * UTF-16 units and would fail any naive length check.
+ *
+ * 2. **An image path must LOOK like an image.** The extension gate is what stops a hostile
+ * project.json from aiming `fs.readBinary` at `~/.ssh/id_rsa`. It is not a complete jail —
+ * the file can still name any *.png on the machine, exactly as an editor node's `filePath`
+ * always could — but the bytes only ever become an `<img>` in a renderer with a `'self'` CSP
+ * and no network, so the reachable outcome is "an icon fails to draw", not exfiltration.
+ *
+ * 3. **A relative path may not traverse.** `./` paths are resolved against the project cwd (see
+ * below), so a `./..`-prefixed one would walk straight out of the project. Same rule, and the
+ * same reasoning, as `isSafeQuickOpenRelPath` on the remote quick-open index.
+ *
+ * **Portability.** An icon image lives beside the canvas that names it, in the project's own
+ * git-shared `.nodeterm/images/` (see core/canvas-images.ts). A path stored absolutely would
+ * therefore travel to a teammate as a path only the author's machine has — the file arrives, the
+ * icon does not. So a path under the project cwd is stored `./`-relative and resolved on read,
+ * which is the convention `toPortableNodes` already established for node cwds. Everything else
+ * (a cwd-less canvas, an SSH project, the app-local fallback `saveCanvasImage` takes when the
+ * project folder will not accept the write) stays absolute and simply does not travel — the same
+ * degrade canvas image nodes take, and not an error.
+ */
+
+/** Extensions an icon image may have, mapped to the MIME type its data URL is built with. */
+export const NODE_ICON_MIME: Record<string, string> = {
+ png: 'image/png',
+ jpg: 'image/jpeg',
+ jpeg: 'image/jpeg',
+ gif: 'image/gif',
+ webp: 'image/webp',
+ bmp: 'image/bmp',
+ ico: 'image/x-icon',
+ svg: 'image/svg+xml',
+ avif: 'image/avif'
+}
+
+/** A node's icon: one emoji/character, or an image file beside the project. */
+export type NodeIcon =
+ | { type: 'emoji'; value: string }
+ | { type: 'image'; path: string }
+
+/**
+ * Hard ceiling on an emoji's UTF-16 length, applied when `Intl.Segmenter` is unavailable so the
+ * grapheme walk below cannot be the only thing standing between a shared file and a blob. Sized
+ * to fit the longest emoji anyone actually types: a four-person ZWJ family is 11 units, a flag
+ * sequence with modifiers a little more.
+ */
+const EMOJI_MAX_UNITS = 24
+
+/**
+ * Control characters (C0 + DEL) are matched by code point rather than by a regex character class,
+ * so this file stays pure ASCII and no tool between here and the repo can mangle the range.
+ */
+const isControlCodePoint = (cp: number): boolean => cp < 0x20 || cp === 0x7f
+
+const stripControl = (s: string): string =>
+ Array.from(s)
+ .filter((ch) => !isControlCodePoint(ch.codePointAt(0) ?? 0))
+ .join('')
+
+const hasControl = (s: string): boolean =>
+ Array.from(s).some((ch) => isControlCodePoint(ch.codePointAt(0) ?? 0))
+
+interface GraphemeSegmenter {
+ segment(input: string): Iterable<{ segment: string }>
+}
+
+/** The MIME type for an icon image path, or undefined when the extension is not an image one. */
+export function nodeIconMime(path: string): string | undefined {
+ const name = path.split('/').pop() ?? ''
+ // A name with no dot has no extension: `.split('.').pop()` would return the whole name, so
+ // `README` would resolve as an extension and only miss by luck.
+ if (!name.includes('.')) return undefined
+ return NODE_ICON_MIME[name.split('.').pop()!.toLowerCase()]
+}
+
+/**
+ * The first grapheme cluster of `raw`, with control characters (including the newlines a paste
+ * can carry) removed first. `Intl.Segmenter` is the correct tool and is present in both shells'
+ * runtimes; the length cap is the fallback for a runtime without it, never the primary rule —
+ * slicing UTF-16 units would cut a ZWJ sequence in half and render a fragment.
+ */
+function firstGrapheme(raw: string): string {
+ const clean = stripControl(raw).trim()
+ if (!clean) return ''
+ const ctor = (
+ Intl as unknown as {
+ Segmenter?: new (locale?: string, options?: { granularity: string }) => GraphemeSegmenter
+ }
+ ).Segmenter
+ if (ctor) {
+ for (const s of new ctor(undefined, { granularity: 'grapheme' }).segment(clean)) return s.segment
+ return ''
+ }
+ return clean.slice(0, EMOJI_MAX_UNITS)
+}
+
+/** True when a `./`-relative icon path stays inside the project root. */
+function isSafeRelIconPath(rel: string): boolean {
+ return rel.split('/').every((seg) => seg !== '' && seg !== '..' && seg !== '.')
+}
+
+/**
+ * Validate an icon value read from a persisted (hostile) source. Returns the value to use, or
+ * **undefined** — which renders as no icon at all, i.e. the pre-feature node. Never throws, and
+ * never substitutes a nearest match: an unrecognized icon is no icon.
+ */
+export function normalizeNodeIcon(raw: unknown): NodeIcon | undefined {
+ if (!raw || typeof raw !== 'object') return undefined
+ const v = raw as { type?: unknown; value?: unknown; path?: unknown }
+ if (v.type === 'emoji') {
+ if (typeof v.value !== 'string') return undefined
+ const value = firstGrapheme(v.value)
+ return value ? { type: 'emoji', value } : undefined
+ }
+ if (v.type === 'image') {
+ if (typeof v.path !== 'string') return undefined
+ const path = v.path.trim()
+ if (!path || hasControl(path) || !nodeIconMime(path)) return undefined
+ if (path.startsWith('./')) {
+ return isSafeRelIconPath(path.slice(2)) ? { type: 'image', path } : undefined
+ }
+ // Anything else must be an absolute POSIX path: a bare `foo.png` has no root to resolve
+ // against, and resolving it against the cwd of whatever process happens to be running is
+ // precisely the kind of guess this module refuses to make.
+ return path.startsWith('/') ? { type: 'image', path } : undefined
+ }
+ return undefined
+}
+
+/**
+ * How an absolute image path is STORED on a node: `./`-relative when it sits inside the project's
+ * own folder (so it travels with the repo), absolute otherwise. `projectCwd` is undefined for a
+ * cwd-less canvas and for an SSH project, where the image is written app-locally.
+ */
+export function portableIconPath(absPath: string, projectCwd?: string): string {
+ if (!projectCwd) return absPath
+ const root = projectCwd.replace(/\/+$/, '')
+ if (!root || !absPath.startsWith(`${root}/`)) return absPath
+ const rel = absPath.slice(root.length + 1)
+ return rel && isSafeRelIconPath(rel) ? `./${rel}` : absPath
+}
+
+/**
+ * The absolute path to read an icon image from, or undefined when it cannot be resolved — a
+ * `./` path on a project that has no local cwd (it was written by a machine that did). Undefined
+ * means the icon does not draw; it must never mean "read something else".
+ */
+export function resolveIconPath(storedPath: string, projectCwd?: string): string | undefined {
+ if (!storedPath.startsWith('./')) return storedPath.startsWith('/') ? storedPath : undefined
+ const rel = storedPath.slice(2)
+ if (!isSafeRelIconPath(rel)) return undefined
+ const root = projectCwd?.replace(/\/+$/, '')
+ return root ? `${root}/${rel}` : undefined
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 1be5668d6..738326a7b 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -327,6 +327,13 @@ export interface CanvasNodeState {
collapsed?: boolean
/** Agent nodes only: when true, this node's subagent/loop fan-out cards are hidden. */
hideFanout?: boolean
+ /**
+ * A user-chosen icon shown wherever this node is listed (canvas header, kanban card, sessions
+ * sidebar): one emoji/character, or an image file. Absent = the node draws exactly as it did
+ * before the feature. Validate with `normalizeNodeIcon` at the point of use — this value comes
+ * from a git-shared, hand-editable project file. See @shared/node-icon.
+ */
+ icon?: import('./node-icon').NodeIcon
/** Parent group node id, if this node belongs to a group frame. */
parentId?: string
// terminal-only