Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(canvas): give a session an emoji or picture icon
Lorenzo Albanese (alblor)a2ce6d689af7
diff --git a/CLAUDE.md b/CLAUDE.mdindex 7e3596bd7..cf6051550 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -171,7 +171,8 @@ Fire-time `TriggerArmStore.isArmed` re-ask everywhere; every rule test-pinned. Tmachine-local, content-bound `core/trigger-arm-store.ts` (a spec that arrives or CHANGES via gitreads 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 amissing `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 maagain; 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.tsxindex 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.tsxindex 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.tsindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 ? (<inputclassName="kanban-modal__rename"diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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: stringcolor: stringagentId?: AgentId+ icon?: NodeIconisAgent: booleanstatusKind: StatusKindstateLabel: 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.tsindex 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.tsindex 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.tsxindex 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 ? (<inputclassName="term-node__title nodrag"diff --git a/src/renderer/nodes/browser-partition-parity.test.tsx b/src/renderer/nodes/browser-partition-parity.test.tsxindex 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 | nullonOpenCanvas={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.tsindex 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.tsindex 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.cssindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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