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(colors): put the agent brand colors in the node palette, and let --color take a name

enes1945f6178f6d
diff --git a/CLAUDE.md b/CLAUDE.md
index 6d36d5876..198ef993b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2845,6 +2845,58 @@ 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 colors (one palette, two sections)
+
+`src/shared/node-colors.ts` is the palette AND the control boundary — the picker's list and the
+allowlist `color --color C` validates against are the same array, deliberately, so the two can
+never disagree about what a legal colour is.
+
+It has two sections. The seven macOS **system** colours are the list it always was. The **agent**
+section is the brand colour of every builtin in `AGENT_CONFIG` plus `FALLBACK_AGENT_COLOR`, and it
+exists because those colours were *already on the canvas*: `createAgentNode` paints a new node from
+`AGENT_CONFIG` (the phone's `appendProjectNode` does the same), so a Claude node is born `#d97757`
+— which the picker could not offer back once the user changed it, and which
+`nodeterm color --color '#d97757'` refused with `node-color-invalid`, the app rejecting its own
+colour. MEASURED against the live hook server before the change; both faces are one gap.
+
+- **The agent section is DERIVED from `AGENT_CONFIG`, never re-typed.** Adding a builtin agent
+ extends the palette by construction. `node-colors.test.ts` pins it three ways — every builtin's
+ colour is in `NODE_COLORS`, every agent swatch's label is that agent's label, and `node-colors.ts`
+ contains no agent hex as a literal on a non-comment line. A second copy of a colour table is the
+ drift this file warns about everywhere else, and it has already happened once (see mobile below).
+- **`SYSTEM_NODE_COLORS` is the subset for surfaces where the value is drawn as TEXT or as an
+ opaque fill** — the app accent (`--accent` sits under hardcoded `#fff`), a project colour (the
+ active tab's label is `color: p.color`) and a kanban column colour (`ColumnPill` draws the title
+ in the raw hex at 10 px). It is also the **auto-assign rotation** for new frames, spawned teams
+ and fresh columns: rotating a frame onto Claude's orange says "this frame is Claude's" and means
+ nothing of the kind. The reason those surfaces differ is a measurement, not taste — on the dark
+ theme white on gemini `#4285f4` is ~3.6:1 and on grok `#64748b` ~4.0:1, both under the 4.5:1 floor
+ for the 10.5 px badge, and grok grey as tab text is ~2.6:1. Everywhere the colour is a dot, a
+ border or a 6–20 % wash (node headers, sticky, files, group frames, the account default colour)
+ offers the FULL palette.
+- **`resolveNodeColor` runs BEFORE the allowlist, and only its output is ever persisted.** It takes
+ a palette name (`blue`, `teal`, `claude`, `github copilot`) or the hex in any case, and yields a
+ canonical value or `undefined`. Names are accepted because the refusal they earned was measured
+ and expensive: seven opaque hexes taught nobody which one was teal, so a caller's next guess was
+ another name and another refusal. The boundary is unchanged by this — a name can only ever
+ resolve to a value the allowlist already held, and a name is never stored. The refusal now prints
+ `name #hex` per swatch (`nodeColorChoices`), and the agent-facing skill text is generated from the
+ same function per the canvas-control sync rule.
+ `open-project --color` takes the same treatment against the **system** resolver; it used to reach
+ `registerProject` with no validation at all.
+- **One component draws every picker** (`components/NodeColorSwatches.tsx`), because the palette now
+ has structure — headings and per-swatch names — and six copies of `NODE_COLORS.map(...)` are six
+ places to forget the heading. `NodeColorSwatches.guard.test.ts` fails on a `.color-popover` this
+ component does not own and on any renderer file that maps the palette into its own swatch row.
+ The name is the feature: an agent brand colour is unidentifiable as a bare circle.
+- **Mobile keeps its OWN list and is not updated here.** *nodeterm mobile* (`nodeterm-ios`,
+ separate private repo) hand-copies the agent colours in `NewSession.swift`, stamped
+ *"last verified 2026-07-17"*, to colour a session it creates; it has no node-colour picker at all,
+ so the palette change reaches it as nothing to do. That mirror is the concrete precedent for why
+ the desktop half is derived rather than typed — and it means a future brand-colour change owes an
+ iOS follow-up (@eneskirca), not a desktop one.
+
+
## Node icons (emoji or picture)
A node may carry `data.icon` (`NodeIcon` in `@shared/node-icon`): `{type:'emoji', value}` or
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 734e290d9..34344ec00 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -97,6 +97,16 @@ lane unaffected.
PR; copy that really is macOS-specific (the ptmx-limit banner, the notch step) is exempt by name
with its reason. Comments are not scanned.
+- **The node colour palette is ONE list, and it is also the control boundary.**
+ `src/shared/node-colors.ts` is what every picker draws and what `nodeterm color --color C`
+ validates against — so a colour the UI offers and a colour the CLI accepts cannot drift apart.
+ Its agent section is DERIVED from `AGENT_CONFIG`, never re-typed: add a builtin agent and the
+ palette grows by itself. If you are adding a surface that lets someone choose a node colour,
+ render `<NodeColorSwatches>` rather than mapping the array yourself (a guard test fails on a
+ hand-rolled swatch row) — and if the value will be drawn as TEXT or as an opaque fill under
+ white, take `SYSTEM_NODE_COLOR_SWATCHES` instead, with the contrast reason in a comment. Deep
+ version, including the measured numbers: CLAUDE.md § Node colors.
+
- **Every loosening of a security gate must be a SETTING the user can see and revoke.** A "don't
ask again" that lives only in a dialog is a permission granted once and never findable again. The
canvas-control destructive confirm is the pattern to copy (`@shared/control-confirm`): the dialog
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index d76660f1f..dc07a7a86 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -11,7 +11,7 @@ import { RETRYABLE } from './agents/agent-message-decide'
import { FANOUT_PER_TURN, PAIR_MIN_INTERVAL_MS } from './agents/agent-message-flow'
import { BROWSER_RETRYABLE, BROWSER_OUTCOME_LABEL } from './browser-outcomes'
import { BROWSER_KEYS, BROWSER_TIMEOUT_DEFAULT_MS, BROWSER_TIMEOUT_MAX_MS } from './browser-verb'
-import { NODE_COLORS } from '@shared/node-colors'
+import { nodeColorChoices } from '@shared/node-colors'
import { codexThreadIdentityResolverSh } from './codex-thread-identity-sh'
/**
@@ -424,7 +424,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {
'- `rename --node <id> --title "New Name"` — rename any node (terminals, groups, stickies…).',
' Renaming to the title the node ALREADY has is a no-op: nothing is typed into its agent',
' session, and the reply says `already named`. Re-assert your own name as often as you like.',
- `- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is one of: ${NODE_COLORS.join(', ')}.`,
+ `- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is a palette NAME`,
+ ` or its hex: ${nodeColorChoices()}. The agent names paint a node its CLI's own brand color.`,
'- `write --node <id> --text "..."` / `close --node <id,id>` — type into / close nodes.',
' `close` takes a COMMA LIST and asks about the whole list in ONE dialog, so close a finished',
' wave in a single call rather than one call per node. Every id must exist on the canvas: an',
@@ -924,7 +925,10 @@ Verbs:
- \`rename --node <id> --title "New Name"\` — rename any node (terminals, groups, stickies…).
Renaming to the title the node ALREADY has is a no-op: nothing is typed into its agent
session, and the reply says \`already named\`. Re-assert your own name as often as you like.
-- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is one of: ${NODE_COLORS.join(', ')}.
+- \`color --node <id,id> --color C\` — recolor nodes, frames, or stickies. C is a palette NAME or
+ its hex (either is accepted, and the hex is case-insensitive): ${nodeColorChoices()}.
+ The agent names are that CLI's own brand color — \`--color claude\` paints a node the color a
+ Claude node is born with. \`group\` takes the same \`--color\`.
- \`write --node <id> --text "..."\` — type text into a terminal node. (Asks the user to confirm.)
- \`close --node <id,id>\` — close one node or several. \`--node\` takes a COMMA LIST, and the whole
list is confirmed in ONE dialog — so when a wave of stations is finished, close them in a single
@@ -1005,7 +1009,7 @@ Typical requests this skill covers:
- "Move this node into that group" → \`move --nodes <id> --group <targetGroupId>\` (not \`group\`, which only
wraps loose nodes). "Break up this group" → \`ungroup --group <id>\`.
- "Rename this node/group" → \`rename\`.
-- "Color these nodes/groups by subject" → \`color --node <id,id> --color <palette value>\`.
+- "Color these nodes/groups by subject" → \`color --node <id,id> --color <name or hex>\` (e.g. \`--color teal\`).
## Nodeterm orchestration ("Build with Nodeterm orchestration")
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index b08516547..229dd8ae4 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -469,7 +469,12 @@ import {
import { uuid } from '../lib/uuid'
import { planReopen, type ReopenPlan } from '../lib/reopenPlan'
import { oneLine } from '@shared/one-line'
-import { invalidNodeColorMessage, isNodeColor } from '@shared/node-colors'
+import {
+ invalidNodeColorMessage,
+ invalidSystemNodeColorMessage,
+ resolveNodeColor,
+ resolveSystemNodeColor
+} from '@shared/node-colors'
import { parseLenses, verifyLensPrompt, verifySynthesisPrompt } from '../lib/verifyPanel'
import { useSettings } from '../state/settings'
import { activePermissionMode, grokCliCapsNow, projectPermissionMode } from '../state/permissionMode'
@@ -9228,6 +9233,18 @@ export function Canvas() {
}
const opTitle =
oneLine((opLive?.data.title as string) ?? opStored?.title ?? '') || sourceNodeId
+ // A project color is the ACTIVE TAB's TEXT color, so it takes the narrower system subset
+ // (see isSystemNodeColor) — and it takes a subset at ALL because this flag reached
+ // `registerProject` unvalidated: an agent-supplied string persisted into project.json and
+ // interpolated into a style, which is exactly the boundary node-colors.ts exists to be.
+ let opColor: string | undefined
+ if (args.color !== undefined) {
+ opColor = resolveSystemNodeColor(args.color)
+ if (opColor === undefined) {
+ reply({ ok: false, error: invalidSystemNodeColorMessage() })
+ return
+ }
+ }
// Apply one consent decision: register (create/adopt/idempotent hit) without activating,
// persist, remember the (caller, project) pair for dialog dedupe — authorization stays
// main-side — and reply with the id the caller can feed `--project`.
@@ -9235,7 +9252,7 @@ export function Canvas() {
const r = useProjects.getState().registerProject({
resolvedCwd,
name: args.name,
- color: args.color,
+ color: opColor,
...(adoptProbed ? { probed: adoptProbed } : {})
})
recordAttachConsent(sourceNodeId, r.project.id)
@@ -10510,9 +10527,16 @@ export function Canvas() {
return
}
case 'group': {
- if (args.color !== undefined && !isNodeColor(args.color)) {
- reply({ ok: false, error: invalidNodeColorMessage() })
- return
+ // Resolve BEFORE the allowlist: `--color claude` and `--color #D97757` are what a
+ // caller actually types, and both land on the same canonical palette value. Only the
+ // resolved value is ever persisted (see resolveNodeColor).
+ let groupColor: string | undefined
+ if (args.color !== undefined) {
+ groupColor = resolveNodeColor(args.color)
+ if (groupColor === undefined) {
+ reply({ ok: false, error: invalidNodeColorMessage() })
+ return
+ }
}
const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
const live = nodesRef.current as CanvasNode[]
@@ -10531,7 +10555,7 @@ export function Canvas() {
reply({ ok: false, error: 'group: nodes must be siblings in one container and may not include an ancestor with its descendant' })
return
}
- if (args.label || args.color) {
+ if (args.label || groupColor) {
grouped = grouped.map((nd) =>
nd.id === groupNode.id
? {
@@ -10539,7 +10563,7 @@ export function Canvas() {
data: {
...nd.data,
...(args.label ? { title: args.label } : {}),
- ...(args.color ? { color: args.color } : {})
+ ...(groupColor ? { color: groupColor } : {})
}
}
: nd
@@ -11214,7 +11238,8 @@ export function Canvas() {
return
}
case 'color': {
- if (!isNodeColor(args.color)) {
+ const color = resolveNodeColor(args.color)
+ if (color === undefined) {
reply({ ok: false, error: invalidNodeColorMessage() })
return
}
@@ -11231,7 +11256,7 @@ export function Canvas() {
setNodes((nodes) =>
nodes.map((node) =>
selected.has(node.id)
- ? { ...node, data: { ...node.data, color: args.color } }
+ ? { ...node, data: { ...node.data, color } }
: node
)
)
@@ -11240,8 +11265,8 @@ export function Canvas() {
const note = skipped ? ` (${skipped} unknown id(s) skipped)` : ''
reply({
ok: true,
- message: `colored ${colored.length} node(s) ${args.color}${note}`,
- result: { colored, skipped, color: args.color }
+ message: `colored ${colored.length} node(s) ${color}${note}`,
+ result: { colored, skipped, color }
})
return
}
diff --git a/src/renderer/canvas/control-color.source.test.ts b/src/renderer/canvas/control-color.source.test.ts
new file mode 100644
index 000000000..e8e574859
--- /dev/null
+++ b/src/renderer/canvas/control-color.source.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+import { NODE_COLORS, SYSTEM_NODE_COLORS } from '@shared/node-colors'
+
+/**
+ * STRUCTURAL pins for the `color` / `group` / `open-project` colour boundary inside Canvas's
+ * control dispatch — same class of test as `control-open-project.source.test.ts`, and for the same
+ * reason: the blocks live inside a 7000-line component with no unit seam, while the decision
+ * itself (`resolveNodeColor`) is fully unit-tested in `shared/node-colors.test.ts`.
+ *
+ * What these pin is the WIRING, which is exactly what was wrong: the palette and the boundary are
+ * the same list, so a picker that offers Claude's own colour and a CLI that refuses it were one
+ * bug wearing two faces — and `open-project --color` reached the projects store with no boundary
+ * at all.
+ */
+const src = readFileSync(new URL('./Canvas.tsx', import.meta.url), 'utf8').replace(/\r\n/g, '\n')
+
+function block(marker: string): string {
+ const start = src.indexOf(marker)
+ expect(start, marker).toBeGreaterThan(-1)
+ const rest = src.slice(start + marker.length)
+ const end = rest.indexOf('\n case ')
+ return end === -1 ? rest.slice(0, 4000) : rest.slice(0, end)
+}
+
+describe('the colour boundary in control dispatch (source pins)', () => {
+ it('the color verb resolves the flag instead of allowlisting it raw', () => {
+ const body = block("case 'color': {")
+ expect(body).toContain('resolveNodeColor(args.color)')
+ // The raw flag must never reach node data: a NAME is resolved to its canonical hex and only
+ // the resolved value is persisted.
+ expect(body).not.toContain('color: args.color')
+ expect(body).toContain('invalidNodeColorMessage()')
+ })
+
+ it('the group verb resolves its optional --color the same way', () => {
+ const body = block("case 'group': {")
+ expect(body).toContain('resolveNodeColor(args.color)')
+ expect(body).not.toContain('{ color: args.color }')
+ })
+
+ it('open-project validates its --color against the NARROWER system boundary', () => {
+ // A project colour becomes the active tab's TEXT colour, and this flag used to reach
+ // registerProject unvalidated.
+ const start = src.indexOf(`if (verb === 'open-project')`)
+ expect(start).toBeGreaterThan(-1)
+ const rest = src.slice(start)
+ const end = rest.indexOf('// ──', 10)
+ const body = end === -1 ? rest : rest.slice(0, end)
+ expect(body).toContain('resolveSystemNodeColor(args.color)')
+ expect(body).toContain('invalidSystemNodeColorMessage()')
+ expect(body).not.toContain('color: args.color')
+ })
+
+ it('spells no palette hex of its own outside the two documented status fallbacks', () => {
+ // Canvas keeps a small set of hardcoded status colours (the minimap's working/needs-you/unread
+ // strokes and the subagent edge accent). Those are deliberate and are NOT palette entries the
+ // user can pick — what must not appear is a re-typed palette list.
+ const listLike = /\[\s*'#[0-9a-f]{6}'\s*,\s*'#[0-9a-f]{6}'/i
+ expect(listLike.test(src), 'Canvas must not carry its own colour palette array').toBe(false)
+ })
+})
+
+describe('the palette the CLI accepts is the palette the pickers draw', () => {
+ it('is one list, and the system section is a prefix of it', () => {
+ expect(NODE_COLORS.length).toBeGreaterThan(SYSTEM_NODE_COLORS.length)
+ expect(NODE_COLORS.slice(0, SYSTEM_NODE_COLORS.length)).toEqual([...SYSTEM_NODE_COLORS])
+ })
+})
diff --git a/src/renderer/canvas/toKanbanSession.ts b/src/renderer/canvas/toKanbanSession.ts
index 57db91a68..a680a782d 100644
--- a/src/renderer/canvas/toKanbanSession.ts
+++ b/src/renderer/canvas/toKanbanSession.ts
@@ -1,6 +1,6 @@
import type { SshConnection } from '@shared/ssh'
import type { NodeIcon } from '@shared/node-icon'
-import { NODE_COLORS, type CanvasNode } from '../state/workspace'
+import { SYSTEM_NODE_COLORS, type CanvasNode } from '../state/workspace'
import type { KanbanSession } from '../components/kanban/KanbanView'
/** One canvas node as a board card, or null when this kind is not a card at all (a group frame, an
@@ -12,7 +12,7 @@ export function toKanbanSession(n: CanvasNode): KanbanSession | null {
return {
id: n.id,
title: (n.data.title as string) || 'Browser',
- color: (n.data.color as string) ?? NODE_COLORS[0],
+ color: (n.data.color as string) ?? SYSTEM_NODE_COLORS[0],
kind: 'browser',
url: n.data.url as string | undefined,
partition: n.data.partition as string | undefined,
@@ -29,7 +29,7 @@ export function toKanbanSession(n: CanvasNode): KanbanSession | null {
// A note has no title of its own — its trimmed first line is the card label. Bodies are
// markdown, so a leading heading marker is presentation, not part of the label.
title: text.trim().split('\n')[0].replace(/^#{1,6}\s+/, '').trim().slice(0, 80) || 'Note',
- color: (n.data.color as string) ?? NODE_COLORS[2],
+ color: (n.data.color as string) ?? SYSTEM_NODE_COLORS[2],
kind: 'sticky',
text,
textUpdatedAt: n.data.textUpdatedAt as number | undefined,
@@ -42,7 +42,7 @@ export function toKanbanSession(n: CanvasNode): KanbanSession | null {
return {
id: n.id,
title: (n.data.title as string) ?? '',
- color: (n.data.color as string) ?? NODE_COLORS[0],
+ color: (n.data.color as string) ?? SYSTEM_NODE_COLORS[0],
kind: 'terminal',
agentId: n.data.agentId as string | undefined,
icon: n.data.icon as NodeIcon | undefined,
diff --git a/src/renderer/canvas/toKanbanSessionState.ts b/src/renderer/canvas/toKanbanSessionState.ts
index e5185cf70..564321233 100644
--- a/src/renderer/canvas/toKanbanSessionState.ts
+++ b/src/renderer/canvas/toKanbanSessionState.ts
@@ -1,5 +1,5 @@
import type { CanvasNodeState } from '@shared/types'
-import { NODE_COLORS } from '../state/workspace'
+import { SYSTEM_NODE_COLORS } from '../state/workspace'
import type { KanbanSession } from '../components/kanban/KanbanView'
import type { ModalSpawn } from '../components/kanban/ModalTerminal'
@@ -20,7 +20,7 @@ export function toKanbanSessionState(n: CanvasNodeState): KanbanSession | null {
return {
id: n.id,
title: n.title || 'Browser',
- color: n.color ?? NODE_COLORS[0],
+ color: n.color ?? SYSTEM_NODE_COLORS[0],
kind: 'browser',
url: n.url,
partition: n.partition,
@@ -32,7 +32,7 @@ export function toKanbanSessionState(n: CanvasNodeState): KanbanSession | null {
return {
id: n.id,
title: stickyTitle(txt),
- color: n.color ?? NODE_COLORS[2],
+ color: n.color ?? SYSTEM_NODE_COLORS[2],
kind: 'sticky',
text: txt,
textUpdatedAt: n.textUpdatedAt,
@@ -57,7 +57,7 @@ export function toKanbanSessionState(n: CanvasNodeState): KanbanSession | null {
return {
id: n.id,
title: n.title ?? '',
- color: n.color ?? NODE_COLORS[0],
+ color: n.color ?? SYSTEM_NODE_COLORS[0],
kind: 'terminal',
agentId: n.agentId,
spawn
diff --git a/src/renderer/components/ContextMenu.tsx b/src/renderer/components/ContextMenu.tsx
index 5c8424142..ce05a8e85 100644
--- a/src/renderer/components/ContextMenu.tsx
+++ b/src/renderer/components/ContextMenu.tsx
@@ -1,6 +1,6 @@
import { useState, type ReactNode } from 'react'
import { createPortal } from 'react-dom'
-import { NODE_COLORS } from '../state/workspace'
+import { NodeColorSwatches } from './NodeColorSwatches'
import { useMenuFlip } from '../ui/useMenuFlip'
export type MenuItem =
@@ -78,18 +78,14 @@ export function ContextMenu({ x, y, items, onClose, zIndex, scroll }: ContextMen
if (item.type === 'label') return <div key={i} className="ctx-label">{item.label}</div>
if (item.type === 'colors') {
return (
- <div key={i} className="ctx-colors">
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- style={{ background: c }}
- onClick={() => {
- item.onPick(c)
- onClose()
- }}
- />
- ))}
- </div>
+ <NodeColorSwatches
+ key={i}
+ className="ctx-colors"
+ onPick={(c) => {
+ item.onPick(c)
+ onClose()
+ }}
+ />
)
}
if (item.type === 'submenu') {
diff --git a/src/renderer/components/NodeColorSwatches.guard.test.ts b/src/renderer/components/NodeColorSwatches.guard.test.ts
new file mode 100644
index 000000000..d76b90f00
--- /dev/null
+++ b/src/renderer/components/NodeColorSwatches.guard.test.ts
@@ -0,0 +1,62 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const RENDERER = join(__dirname, '..')
+
+function sources(dir: string, out: string[] = []): string[] {
+ for (const entry of readdirSync(dir)) {
+ const full = join(dir, entry)
+ if (statSync(full).isDirectory()) {
+ sources(full, out)
+ continue
+ }
+ if (!/\.tsx?$/.test(entry) || /\.test\.tsx?$/.test(entry)) continue
+ out.push(full)
+ }
+ return out
+}
+
+/**
+ * The palette now has STRUCTURE — two sections and a name per swatch — and the reason it is one
+ * component rather than six copies of `NODE_COLORS.map(...)` is that six copies each have to grow
+ * the heading, the tooltip and the accessible name separately, and the one that doesn't is the one
+ * where the user cannot tell which circle is Claude's.
+ *
+ * The failure this catches is concrete and cheap to make: a new node kind copy-pastes the popover
+ * block out of `TerminalNode`, and its picker silently offers half a palette. Same shape as the
+ * `fs.rename` and tmux-socket guards — nobody reading one file can see it.
+ */
+describe('every color picker renders the shared, sectioned palette', () => {
+ const files = sources(RENDERER)
+
+ it('only NodeColorSwatches may own a .color-popover container', () => {
+ const offenders: string[] = []
+ for (const file of files) {
+ const src = readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
+ // The class is only ever legitimate as the container NodeColorSwatches is asked to draw.
+ for (const match of src.matchAll(/className="color-popover"/g)) {
+ const before = src.slice(Math.max(0, match.index - 200), match.index)
+ if (!/<NodeColorSwatches[^>]*$/.test(before)) {
+ offenders.push(relative(RENDERER, file))
+ }
+ }
+ }
+ expect(offenders, 'render the palette through <NodeColorSwatches className="color-popover">').toEqual([])
+ })
+
+ it('no renderer file maps over the palette to build its own swatch row', () => {
+ // NODE_COLORS itself stays importable (fallback colors, rotations); what must not come back is
+ // a hand-rolled picker built by mapping it.
+ const offenders: string[] = []
+ for (const file of files) {
+ if (file.endsWith(join('components', 'NodeColorSwatches.tsx'))) continue
+ const src = readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
+ if (/\bNODE_COLORS\.map\(/.test(src)) offenders.push(relative(RENDERER, file))
+ }
+ expect(
+ offenders,
+ 'use <NodeColorSwatches>, or SYSTEM_NODE_COLOR_SWATCHES where the value is drawn as text'
+ ).toEqual([])
+ })
+})
diff --git a/src/renderer/components/NodeColorSwatches.tsx b/src/renderer/components/NodeColorSwatches.tsx
new file mode 100644
index 000000000..ee515270f
--- /dev/null
+++ b/src/renderer/components/NodeColorSwatches.tsx
@@ -0,0 +1,56 @@
+import { Fragment } from 'react'
+import { NODE_COLOR_SECTIONS, type NodeColorSwatch } from '@shared/node-colors'
+
+/**
+ * The node-color picker's contents: every palette section, each under its own heading, with a
+ * named swatch per color.
+ *
+ * ONE component for every surface that draws the palette (node headers, the pane/selection
+ * context menu, the sticky and files headers, the group frame, the kanban card modal's node)
+ * because the palette now has STRUCTURE — sections and names — and six copies of a
+ * `NODE_COLORS.map(...)` would each have to grow the heading, the tooltip and the selected ring
+ * separately. The container keeps its own class so each surface stays laid out as it was.
+ *
+ * The names are the point of the change, not decoration: an agent color is unidentifiable as a
+ * bare circle ("which of these two oranges is Claude's?"), and the swatch's accessible name is
+ * the only thing a screen reader has to go on either way.
+ */
+export function NodeColorSwatches({
+ className,
+ buttonClassName,
+ selected,
+ onPick
+}: {
+ className: string
+ buttonClassName?: string
+ /** The currently applied color, if the surface knows it — drawn with a ring. */
+ selected?: string
+ onPick: (color: string) => void
+}): React.ReactElement {
+ return (
+ <div className={className}>
+ {NODE_COLOR_SECTIONS.map((section) => (
+ <Fragment key={section.label}>
+ <div className="swatch-section__label">{section.label}</div>
+ <div className="swatch-section__grid">
+ {section.swatches.map((swatch: NodeColorSwatch) => (
+ <button
+ key={swatch.value}
+ type="button"
+ className={buttonClassName}
+ style={{ background: swatch.value }}
+ title={swatch.label}
+ aria-label={swatch.label}
+ // Only where the surface KNOWS the current color: a menu strip that draws no
+ // selection must not tell a screen reader every swatch is un-pressed.
+ aria-pressed={selected === undefined ? undefined : selected === swatch.value}
+ data-selected={selected === swatch.value ? 'true' : undefined}
+ onClick={() => onPick(swatch.value)}
+ />
+ ))}
+ </div>
+ </Fragment>
+ ))}
+ </div>
+ )
+}
diff --git a/src/renderer/components/kanban/KanbanColumn.tsx b/src/renderer/components/kanban/KanbanColumn.tsx
index a2c9930cb..cf874cfe7 100644
--- a/src/renderer/components/kanban/KanbanColumn.tsx
+++ b/src/renderer/components/kanban/KanbanColumn.tsx
@@ -2,7 +2,7 @@ import { Fragment, memo, useLayoutEffect, useRef, useState } from 'react'
import { createPortal } from 'react-dom'
import { IconClose } from '../icons'
import type { KanbanColumn as KanbanColumnT } from '@shared/types'
-import { NODE_COLORS } from '../../state/workspace'
+import { SYSTEM_NODE_COLOR_SWATCHES } from '@shared/node-colors'
import type { KanbanCreateChoice, KanbanCreateOption } from './KanbanView'
import { byLane, type KanbanSourceId } from '../../lib/kanbanSources'
@@ -174,10 +174,15 @@ export const KanbanColumn = memo(function KanbanColumn({
</div>
{column && swatchesOpen && (
<div className="kanban-col__swatches">
- {NODE_COLORS.map((c) => (
+ {/* System subset, not the agent colors: ColumnPill draws a column's color as 10px
+ TEXT on an 18% wash of itself, where grok grey and copilot purple fall under the
+ contrast floor. Node pickers offer the full palette. */}
+ {SYSTEM_NODE_COLOR_SWATCHES.map(({ value: c, label }) => (
<button
key={c}
className="kanban-col__swatch"
+ title={label}
+ aria-label={label}
style={{ background: c }}
onClick={() => {
if (column) onRecolor?.(column.id, c)
diff --git a/src/renderer/components/settings/sections/AccountsSection.color.test.tsx b/src/renderer/components/settings/sections/AccountsSection.color.test.tsx
index ac3dd206c..37ddc0713 100644
--- a/src/renderer/components/settings/sections/AccountsSection.color.test.tsx
+++ b/src/renderer/components/settings/sections/AccountsSection.color.test.tsx
@@ -1,5 +1,6 @@
// @vitest-environment jsdom
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { AGENT_CONFIG } from '@shared/agents/config'
import { createRoot, type Root } from 'react-dom/client'
import { act } from 'react'
import { AccountsSection } from './AccountsSection'
@@ -67,12 +68,25 @@ describe('AccountsSection — default node color', () => {
it('stores the picked color on the account', () => {
const { host, root } = renderSection([account])
act(() => {
- swatch(host, 'work', 'Node color #0a84ff').click()
+ swatch(host, 'work', 'Node color Blue').click()
})
expect(colorOf('a1')).toBe('#0a84ff')
root.unmount()
})
+ it('offers the agent brand colors under their own heading', () => {
+ // The account picker is a NODE color picker, so it carries the whole palette — a second
+ // Claude login painted Claude's own clay is the case this feature exists for.
+ const { host, root } = renderSection([account])
+ act(() => {
+ swatch(host, 'work', `Node color ${AGENT_CONFIG.claude.label}`).click()
+ })
+ expect(colorOf('a1')).toBe(AGENT_CONFIG.claude.color)
+ const group = host.querySelector('[aria-label="Default node color for work"]')
+ expect(group?.textContent).toContain('Agents')
+ root.unmount()
+ })
+
it('clears the color back to the agent default', () => {
const { host, root } = renderSection([{ ...account, color: '#0a84ff' }])
act(() => {
@@ -84,8 +98,8 @@ describe('AccountsSection — default node color', () => {
it('marks the picked swatch as selected', () => {
const { host, root } = renderSection([{ ...account, color: '#0a84ff' }])
- expect(swatch(host, 'work', 'Node color #0a84ff').getAttribute('aria-pressed')).toBe('true')
- expect(swatch(host, 'work', 'Node color #32d74b').getAttribute('aria-pressed')).toBe('false')
+ expect(swatch(host, 'work', 'Node color Blue').getAttribute('aria-pressed')).toBe('true')
+ expect(swatch(host, 'work', 'Node color Green').getAttribute('aria-pressed')).toBe('false')
expect(swatch(host, 'work', 'Default').getAttribute('aria-pressed')).toBe('false')
root.unmount()
})
@@ -100,7 +114,7 @@ describe('AccountsSection — default node color', () => {
const other: ClaudeAccount = { id: 'a2', label: 'personal', createdAt: 0, color: '#ff453a' }
const { host, root } = renderSection([account, other])
act(() => {
- swatch(host, 'work', 'Node color #0a84ff').click()
+ swatch(host, 'work', 'Node color Blue').click()
})
expect(colorOf('a1')).toBe('#0a84ff')
expect(colorOf('a2')).toBe('#ff453a')
@@ -113,7 +127,7 @@ describe('AccountsSection — default node color', () => {
it('stores the picked color on a Codex account', () => {
const { host, root } = renderSection([], [{ id: 'c1', label: 'codex work' }])
act(() => {
- swatch(host, 'codex work', 'Node color #32d74b').click()
+ swatch(host, 'codex work', 'Node color Green').click()
})
expect(codexColorOf('c1')).toBe('#32d74b')
root.unmount()
@@ -133,7 +147,7 @@ describe('AccountsSection — default node color', () => {
it('colors a Codex account without touching a Claude account of the same id', () => {
const { host, root } = renderSection([{ ...account, id: 'x1' }], [{ id: 'x1', label: 'codex' }])
act(() => {
- swatch(host, 'codex', 'Node color #32d74b').click()
+ swatch(host, 'codex', 'Node color Green').click()
})
expect(codexColorOf('x1')).toBe('#32d74b')
expect(colorOf('x1')).toBeUndefined()
diff --git a/src/renderer/components/settings/sections/AccountsSection.tsx b/src/renderer/components/settings/sections/AccountsSection.tsx
index 52f71a594..077005dad 100644
--- a/src/renderer/components/settings/sections/AccountsSection.tsx
+++ b/src/renderer/components/settings/sections/AccountsSection.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { Fragment, useEffect, useState } from 'react'
import { IconClose } from '../../icons'
import type { ClaudeAccount, ClaudeSkillShareResult } from '@shared/types'
import type { CodexAccount } from '@shared/codex-account'
@@ -8,7 +8,8 @@ import { useAgentStatus } from '../../../state/agentStatus'
import { useSettings } from '../../../state/settings'
import { useSystemAccount } from '../../../state/systemAccount'
import { useSystemCodexAccount } from '../../../state/systemCodexAccount'
-import { isAccountLoginNode, NODE_COLORS } from '../../../state/workspace'
+import { isAccountLoginNode } from '../../../state/workspace'
+import { NODE_COLOR_SECTIONS } from '@shared/node-colors'
import { useProjects } from '../../../state/projects'
import { useSshConn } from '../../../state/sshConn'
import { useSshServers } from '../../../state/sshServers'
@@ -170,21 +171,33 @@ function AccountColorSwatches({
>
✕
</button>
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- type="button"
- // "<what> <hex>", the convention the Appearance accent picker set — a bare hex is not a
- // name a screen reader can do anything with.
- aria-label={`Node color ${c}`}
- aria-pressed={color === c}
- onClick={() => onPick(c)}
- style={{ background: c }}
- className={cn(
- 'size-5 rounded-full border-2',
- color === c ? 'border-text' : 'border-transparent'
- )}
- />
+ {NODE_COLOR_SECTIONS.map((section, i) => (
+ <Fragment key={section.label}>
+ {/* The agent section is headed so a user can tell WHICH circle is Claude's — the whole
+ point of putting the brand colors in the palette. The first section keeps its
+ historical bare row. */}
+ {i > 0 ? (
+ <span className="text-[11px] text-muted">{section.label}</span>
+ ) : null}
+ {section.swatches.map((swatch) => (
+ <button
+ key={swatch.value}
+ type="button"
+ // "<what> <name>", the convention the Appearance accent picker set — a bare hex is
+ // not a name a screen reader can do anything with, which is also why the palette
+ // now carries labels rather than only values.
+ aria-label={`Node color ${swatch.label}`}
+ title={swatch.label}
+ aria-pressed={color === swatch.value}
+ onClick={() => onPick(swatch.value)}
+ style={{ background: swatch.value }}
+ className={cn(
+ 'size-5 rounded-full border-2',
+ color === swatch.value ? 'border-text' : 'border-transparent'
+ )}
+ />
+ ))}
+ </Fragment>
))}
</div>
)
diff --git a/src/renderer/components/settings/sections/AppearanceSection.tsx b/src/renderer/components/settings/sections/AppearanceSection.tsx
index 108b6669f..e43840d35 100644
--- a/src/renderer/components/settings/sections/AppearanceSection.tsx
+++ b/src/renderer/components/settings/sections/AppearanceSection.tsx
@@ -1,5 +1,5 @@
import { useSettings } from '../../../state/settings'
-import { NODE_COLORS } from '../../../state/workspace'
+import { SYSTEM_NODE_COLOR_SWATCHES } from '@shared/node-colors'
import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { FieldRow } from '../FieldRow'
@@ -190,11 +190,16 @@ export function AppearanceSection({ isActive }: { isActive: boolean }): React.JS
<div className="flex items-center justify-between gap-4 py-2.5">
<span className="text-[13px] text-text">Accent</span>
<div className="flex flex-wrap gap-2">
- {NODE_COLORS.map((c) => (
+ {/* The SYSTEM subset only, never the whole palette: `--accent` is painted as an
+ opaque background under hardcoded #fff (.dock-add, the dictation button, the
+ badge), where white on gemini blue is ~3.6:1 and on grok grey ~4.0:1 - under the
+ 4.5:1 floor for the 10.5px badge. See isSystemNodeColor. */}
+ {SYSTEM_NODE_COLOR_SWATCHES.map(({ value: c, label }) => (
<button
key={c}
type="button"
- aria-label={`Accent ${c}`}
+ aria-label={`Accent ${label}`}
+ title={label}
onClick={() => update({ accent: c })}
style={{ background: c }}
className={cn(
diff --git a/src/renderer/components/settings/sections/ProjectSettingsSection.tsx b/src/renderer/components/settings/sections/ProjectSettingsSection.tsx
index 1a8d08c9e..ec6818875 100644
--- a/src/renderer/components/settings/sections/ProjectSettingsSection.tsx
+++ b/src/renderer/components/settings/sections/ProjectSettingsSection.tsx
@@ -14,7 +14,7 @@ import { useSettings } from '../../../state/settings'
import { useSystemAccount } from '../../../state/systemAccount'
import { markWorkspaceDirty } from '../../../state/workspaceDirty'
import {
- NODE_COLORS,
+ SYSTEM_NODE_COLORS,
accountsForProject,
sshAccountsHint,
systemAccountDisplay
@@ -268,7 +268,7 @@ function EditableProjectSection({
name={project.name}
icon={project.icon}
color={project.color}
- colors={NODE_COLORS}
+ colors={SYSTEM_NODE_COLORS}
dark={appTheme === 'dark'}
// Only the section the user is actually viewing probes the (uncached, live) GitHub
// avatar. During a settings SEARCH many sections are VISIBLE-but-not-active — gating
diff --git a/src/renderer/lib/kanban.ts b/src/renderer/lib/kanban.ts
index 010ddce5e..c14c03d6c 100644
--- a/src/renderer/lib/kanban.ts
+++ b/src/renderer/lib/kanban.ts
@@ -1,5 +1,5 @@
import type { BoardLogAuthor, CanvasNodeState, KanbanAssignment, KanbanCardMeta, KanbanColumn, KanbanLabel, KanbanLabelColor, KanbanPriority, Project, ProjectKanban } from '@shared/types'
-import { NODE_COLORS } from '../state/workspace'
+import { SYSTEM_NODE_COLORS } from '../state/workspace'
import { DEFAULT_BOARD_COLUMNS, makeColumnId } from '@shared/kanban-default-board'
// Pure kanban board transforms — the ONLY place board structure changes. The UI computes
@@ -23,7 +23,7 @@ export function defaultKanban(): ProjectKanban {
/** Color for the next added column — cycles the node palette. */
export function nextColumnColor(k: ProjectKanban): string {
- return NODE_COLORS[k.columns.length % NODE_COLORS.length]
+ return SYSTEM_NODE_COLORS[k.columns.length % SYSTEM_NODE_COLORS.length]
}
export function addColumn(k: ProjectKanban, title: string, color: string): ProjectKanban {
diff --git a/src/renderer/nodes/FilesNode.tsx b/src/renderer/nodes/FilesNode.tsx
index 6cc1cbd26..cb420de01 100644
--- a/src/renderer/nodes/FilesNode.tsx
+++ b/src/renderer/nodes/FilesNode.tsx
@@ -29,7 +29,8 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
import { NodeResizer, useReactFlow, type NodeProps } from '@xyflow/react'
import type { DirEntry } from '@shared/types'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
-import { COLLAPSED_HEIGHT, NODE_COLORS, type CanvasNode } from '../state/workspace'
+import { COLLAPSED_HEIGHT, type CanvasNode } from '../state/workspace'
+import { NodeColorSwatches } from '../components/NodeColorSwatches'
import {
breadcrumbs,
childPath,
@@ -356,18 +357,14 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
onClick={() => setShowColors((v) => !v)}
/>
{showColors && (
- <div className="color-popover">
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- style={{ background: c }}
- onClick={() => {
- updateNodeData(id, { color: c })
- setShowColors(false)
- }}
- />
- ))}
- </div>
+ <NodeColorSwatches
+ className="color-popover"
+ selected={data.color as string | undefined}
+ onPick={(c) => {
+ updateNodeData(id, { color: c })
+ setShowColors(false)
+ }}
+ />
)}
{editingTitle ? (
<input
diff --git a/src/renderer/nodes/GroupNode.tsx b/src/renderer/nodes/GroupNode.tsx
index 631d54af8..324033f13 100644
--- a/src/renderer/nodes/GroupNode.tsx
+++ b/src/renderer/nodes/GroupNode.tsx
@@ -3,7 +3,8 @@ import { Tooltip } from '../components/Tooltip'
import { IconClose, IconUngroup } from '../components/icons'
import { NodeResizer, useReactFlow, type NodeProps } from '@xyflow/react'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
-import { NODE_COLORS, ungroupNodes, type CanvasNode } from '../state/workspace'
+import { ungroupNodes, type CanvasNode } from '../state/workspace'
+import { NodeColorSwatches } from '../components/NodeColorSwatches'
import { useProjects } from '../state/projects'
import { useWorktrees, WORKTREE_STATUS_POLL_MS } from '../state/worktrees'
import { useProjectSetup } from '../state/projectSetup'
@@ -175,18 +176,14 @@ export function GroupNode({ id, data, selected }: NodeProps<CanvasNode>) {
/>
</Tooltip>
{showColors && (
- <div className="color-popover">
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- style={{ background: c }}
- onClick={() => {
- updateNodeData(id, { color: c })
- setShowColors(false)
- }}
- />
- ))}
- </div>
+ <NodeColorSwatches
+ className="color-popover"
+ selected={data.color as string | undefined}
+ onPick={(c) => {
+ updateNodeData(id, { color: c })
+ setShowColors(false)
+ }}
+ />
)}
<input
className="group-node__name nodrag"
diff --git a/src/renderer/nodes/StickyNode.tsx b/src/renderer/nodes/StickyNode.tsx
index b29cd0efa..090ae9221 100644
--- a/src/renderer/nodes/StickyNode.tsx
+++ b/src/renderer/nodes/StickyNode.tsx
@@ -3,7 +3,8 @@ import { Tooltip } from '../components/Tooltip'
import { IconChevronDown, IconChevronRight, IconClose } from '../components/icons'
import { Handle, NodeResizer, Position, useReactFlow, type NodeProps } from '@xyflow/react'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
-import { COLLAPSED_HEIGHT, NODE_COLORS, type CanvasNode } from '../state/workspace'
+import { COLLAPSED_HEIGHT, type CanvasNode } from '../state/workspace'
+import { NodeColorSwatches } from '../components/NodeColorSwatches'
import { ColumnPill } from '../components/kanban/ColumnPill'
import { NoteMarkdown } from '../components/NoteMarkdown'
import { relativeTime } from '../lib/relativeTime'
@@ -108,18 +109,14 @@ export function StickyNode({ id, data, selected }: NodeProps<CanvasNode>) {
/>
</Tooltip>
{showColors && (
- <div className="color-popover">
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- style={{ background: c }}
- onClick={() => {
- updateNodeData(id, { color: c })
- setShowColors(false)
- }}
- />
- ))}
- </div>
+ <NodeColorSwatches
+ className="color-popover"
+ selected={data.color as string | undefined}
+ onPick={(c) => {
+ updateNodeData(id, { color: c })
+ setShowColors(false)
+ }}
+ />
)}
{editingTitle ? (
<input
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index cac352846..7211e4ca2 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -171,7 +171,8 @@ import { useWorktrees } from '../state/worktrees'
import { isRemoteSessionNode } from '@shared/worktree'
import { useSession, useActiveSessionPresence } from '../session/session'
import { isBrowserRuntime } from '../bridge/runtime'
-import { agentLaunchOverride, COLLAPSED_HEIGHT, NODE_COLORS, type CanvasNode } from '../state/workspace'
+import { agentLaunchOverride, COLLAPSED_HEIGHT, type CanvasNode } from '../state/workspace'
+import { NodeColorSwatches } from '../components/NodeColorSwatches'
import { AccountChip, useAccountChip } from '../components/AccountChip'
import { effectiveAccountId } from '../lib/accountChip'
import {
@@ -5031,18 +5032,14 @@ export function TerminalNode({
/>
</Tooltip>
{showColors && (
- <div className="color-popover">
- {NODE_COLORS.map((c) => (
- <button
- key={c}
- style={{ background: c }}
- onClick={() => {
- updateNodeData(id, { color: c })
- setShowColors(false)
- }}
- />
- ))}
- </div>
+ <NodeColorSwatches
+ className="color-popover"
+ selected={data.color as string | undefined}
+ onPick={(c) => {
+ updateNodeData(id, { color: c })
+ setShowColors(false)
+ }}
+ />
)}
{data.icon ? (
<button
diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.ts
index 4c940c4e3..94b5c31d8 100644
--- a/src/renderer/state/workspace.ts
+++ b/src/renderer/state/workspace.ts
@@ -10,7 +10,12 @@ import type {
} from '@shared/types'
import { DEFAULT_SETTINGS } from '@shared/types'
import type { AgentId, AgentPermissionMode, BuiltinAgentId } from '@shared/agents/config'
-import { agentConfig, capabilityAgentId, supportsSessionIdFlag } from '@shared/agents/config'
+import {
+ agentConfig,
+ capabilityAgentId,
+ FALLBACK_AGENT_COLOR,
+ supportsSessionIdFlag
+} from '@shared/agents/config'
import { assembleLaunchCommand } from '@shared/agents/launch'
import { agentAccountColor } from '@shared/agents/account-color'
import { boundAccountId } from '@shared/agents/account-binding'
@@ -34,11 +39,11 @@ import { useSettings } from './settings'
export { applyCanvasMutation } from '@shared/canvas-mutations'
export { accountNodeColor, agentAccountColor } from '@shared/agents/account-color'
import { sanitizeInboundNode } from '@shared/node-exec'
-import { NODE_COLORS } from '@shared/node-colors'
+import { SYSTEM_NODE_COLORS } from '@shared/node-colors'
// Preserve the renderer's long-standing import surface; validation and the palette now live in
// shared so Server Edition and canvas-control accept exactly what these pickers display.
-export { NODE_COLORS } from '@shared/node-colors'
+export { NODE_COLORS, SYSTEM_NODE_COLORS } from '@shared/node-colors'
const TERMINAL_SIZE = { width: 640, height: 440 }
const STICKY_SIZE = { width: 240, height: 200 }
@@ -310,7 +315,7 @@ export function createTerminalNode(
...placeNode('terminal', center, index, size.width, size.height),
data: {
title: `Terminal ${index + 1}`,
- color: NODE_COLORS[index % NODE_COLORS.length],
+ color: SYSTEM_NODE_COLORS[index % SYSTEM_NODE_COLORS.length],
group: null,
tags: [],
cwd: ssh ? ssh.remoteCwd : cwd,
@@ -336,7 +341,7 @@ export function createSshTerminalNode(
...placeNode('terminal', center, index, size.width, size.height),
data: {
title: server.label,
- color: NODE_COLORS[index % NODE_COLORS.length],
+ color: SYSTEM_NODE_COLORS[index % SYSTEM_NODE_COLORS.length],
group: null,
tags: [],
ssh: {
@@ -522,9 +527,6 @@ export function resolveNewNodeAgent(
return explicit ?? projectDefaultAgent(projectId, settings) ?? launchableDefaultAgent(settings)
}
-/** Fallback color for custom / unknown agents that have no config-provided color. */
-const FALLBACK_AGENT_COLOR = '#888888'
-
/**
* Resolves an agent's label/color/launch command. Builtins come from the static config;
* custom agents are looked up by id in the settings store. Falls back to the id itself for
@@ -1147,7 +1149,7 @@ export function createGroupNode(
style: { width: size.width, height: size.height },
data: {
title: `Group ${index + 1}`,
- color: NODE_COLORS[index % NODE_COLORS.length],
+ color: SYSTEM_NODE_COLORS[index % SYSTEM_NODE_COLORS.length],
group: null
}
}
@@ -1163,7 +1165,7 @@ export function createProject(
return {
id: nextId('project'),
name: name ?? `Project ${index + 1}`,
- color: NODE_COLORS[index % NODE_COLORS.length],
+ color: SYSTEM_NODE_COLORS[index % SYSTEM_NODE_COLORS.length],
cwd,
...(ssh ? { ssh } : {}),
viewport: { x: 0, y: 0, zoom: 1 },
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 540e3f1b7..6183eb31c 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -2775,9 +2775,11 @@ body,
top: 26px;
left: 6px;
z-index: 5;
- display: grid;
- grid-template-columns: repeat(4, 1fr);
+ /* Sections stack; the swatches inside each one keep the old 4-up grid via --swatch-cols. */
+ display: flex;
+ flex-direction: column;
gap: 6px;
+ --swatch-cols: 4;
background: var(--panel-header);
border: 1px solid var(--border);
border-radius: 8px;
@@ -3191,12 +3193,35 @@ body,
}
.ctx-colors {
- display: grid;
- grid-template-columns: repeat(7, 1fr);
+ display: flex;
+ flex-direction: column;
gap: 5px;
+ --swatch-cols: 7;
padding: 6px 8px;
}
+/* Shared by every palette surface (NodeColorSwatches). The heading is what tells the user which
+ circle is Claude's — an agent brand color is unidentifiable as a bare dot. */
+.swatch-section__label {
+ font-size: 9.5px;
+ font-weight: 600;
+ letter-spacing: 0.04em;
+ text-transform: uppercase;
+ color: var(--muted);
+}
+
+.swatch-section__grid {
+ display: grid;
+ grid-template-columns: repeat(var(--swatch-cols, 7), 1fr);
+ gap: 5px;
+}
+
+.color-popover button[data-selected='true'],
+.ctx-colors button[data-selected='true'] {
+ outline: 1.5px solid var(--text);
+ outline-offset: 1.5px;
+}
+
.ctx-colors button {
width: 18px;
height: 18px;
diff --git a/src/server/headless-node-factory.test.ts b/src/server/headless-node-factory.test.ts
index 08311f36b..09e33e622 100644
--- a/src/server/headless-node-factory.test.ts
+++ b/src/server/headless-node-factory.test.ts
@@ -730,6 +730,21 @@ describe('HeadlessNodeFactory', () => {
expect(projectFile.nodes.find((node) => node.id === 'sticky-color')?.color).toBe('#32d74b')
})
+ it('accepts a palette NAME and a mixed-case hex, persisting the canonical value', async () => {
+ // Complaint (1): `--color '#d97757'` — the colour a Claude node is BORN with — used to be
+ // refused by the boundary. It is in the palette now, and so is its name.
+ await expect(factory.color('term-source', {
+ node: 'term-upstream',
+ color: 'claude'
+ })).resolves.toMatchObject({ ok: true, result: { color: '#d97757' } })
+ await expect(factory.color('term-source', {
+ node: 'term-upstream',
+ color: '#0A84FF'
+ })).resolves.toMatchObject({ ok: true, result: { color: '#0a84ff' } })
+ const project = (await store.load({ sideline: false })).projects[0]
+ expect(project.nodes.find((node) => node.id === 'term-upstream')?.color).toBe('#0a84ff')
+ })
+
it('refuses invalid group and recolor values by name without persistence or fanout', async () => {
await expect(factory.group('term-source', {
nodes: 'term-upstream,term-owned',
diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.ts
index 810ea733b..4b936922b 100644
--- a/src/server/headless-node-factory.ts
+++ b/src/server/headless-node-factory.ts
@@ -6,8 +6,8 @@ import { gateProjectTarget, GRANT_CAP } from '../core/project-grants'
import { planBridges, type LinkEndpoint } from '../shared/canvas-link'
import {
invalidNodeColorMessage,
- isNodeColor,
- NODE_COLORS,
+ resolveNodeColor,
+ SYSTEM_NODE_COLORS,
type NodeColor
} from '../shared/node-colors'
import { applyStickyWrite, parseStickyArgs, resolveStickyRef } from '../shared/sticky-write'
@@ -395,7 +395,7 @@ function groupPersistedNodes(
height: maxY - minY + GROUP_PAD * 2 + GROUP_HEADER
},
title: label || `Group ${groupIndex + 1}`,
- color: color ?? NODE_COLORS[groupIndex % NODE_COLORS.length],
+ color: color ?? SYSTEM_NODE_COLORS[groupIndex % SYSTEM_NODE_COLORS.length],
group: null,
...(parentId ? { parentId } : {})
}
@@ -922,8 +922,10 @@ export class HeadlessNodeFactory {
if (flagError) return { ok: false, error: `group: ${flagError}` }
let color: NodeColor | undefined
if (args.color !== undefined) {
- if (!isNodeColor(args.color)) return { ok: false, error: invalidNodeColorMessage() }
- color = args.color
+ // Names and mixed-case hex resolve to the one canonical palette value; anything else is
+ // the same refusal as before. Only the resolved value is persisted.
+ color = resolveNodeColor(args.color)
+ if (color === undefined) return { ok: false, error: invalidNodeColorMessage() }
}
const workspace = await this.deps.workspaceStore.load({ sideline: false })
const source = sourceProject(workspace, sourceNodeId)
@@ -1012,7 +1014,8 @@ export class HeadlessNodeFactory {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['node', 'color']))
if (flagError) return { ok: false, error: `color: ${flagError}` }
- if (!isNodeColor(args.color)) return { ok: false, error: invalidNodeColorMessage() }
+ const color = resolveNodeColor(args.color)
+ if (color === undefined) return { ok: false, error: invalidNodeColorMessage() }
const workspace = await this.deps.workspaceStore.load({ sideline: false })
const source = sourceProject(workspace, sourceNodeId)
@@ -1027,7 +1030,7 @@ export class HeadlessNodeFactory {
const changed = ids
.map((id) => source.project.nodes.find((node) => node.id === id))
.filter((node): node is CanvasNodeState => !!node)
- .map((node) => ({ ...node, color: args.color }))
+ .map((node) => ({ ...node, color }))
if (!changed.length) {
return { ok: false, error: 'color: none of the given node ids exist in the caller project' }
}
@@ -1039,8 +1042,8 @@ export class HeadlessNodeFactory {
const note = skipped ? ` (${skipped} unknown id(s) skipped)` : ''
return {
ok: true,
- message: `colored ${changed.length} node(s) ${args.color}${note}`,
- result: { colored: changed.map((node) => node.id), skipped, color: args.color }
+ message: `colored ${changed.length} node(s) ${color}${note}`,
+ result: { colored: changed.map((node) => node.id), skipped, color }
}
})
}
@@ -1122,7 +1125,7 @@ export class HeadlessNodeFactory {
for (let i = 0; i < count; i++) {
let command = args.cmd
let title = `Terminal ${startIndex + i + 1}`
- let color: string = NODE_COLORS[(startIndex + i) % NODE_COLORS.length]
+ let color: string = SYSTEM_NODE_COLORS[(startIndex + i) % SYSTEM_NODE_COLORS.length]
let mintedSessionId: string | undefined
let permissionMode
if (verb === 'open-agent') {
diff --git a/src/shared/kanban-default-board.test.ts b/src/shared/kanban-default-board.test.ts
index a76a93762..f95f9d453 100644
--- a/src/shared/kanban-default-board.test.ts
+++ b/src/shared/kanban-default-board.test.ts
@@ -5,7 +5,7 @@
// in the same PR.
import { describe, expect, it } from 'vitest'
import { DEFAULT_BOARD_COLUMNS, makeColumnId } from './kanban-default-board'
-import { NODE_COLORS } from './node-colors'
+import { SYSTEM_NODE_COLORS } from './node-colors'
describe('DEFAULT_BOARD_COLUMNS', () => {
it('is To Do / In Progress / Done, in that order', () => {
@@ -14,9 +14,9 @@ describe('DEFAULT_BOARD_COLUMNS', () => {
it('paints them from the node palette: blue, yellow, green', () => {
expect(DEFAULT_BOARD_COLUMNS.map((c) => c.color)).toEqual([
- NODE_COLORS[0],
- NODE_COLORS[2],
- NODE_COLORS[1]
+ SYSTEM_NODE_COLORS[0],
+ SYSTEM_NODE_COLORS[2],
+ SYSTEM_NODE_COLORS[1]
])
expect(DEFAULT_BOARD_COLUMNS.map((c) => c.color)).toEqual(['#0a84ff', '#ffd60a', '#32d74b'])
})
diff --git a/src/shared/kanban-default-board.ts b/src/shared/kanban-default-board.ts
index 69622a2f0..01810920e 100644
--- a/src/shared/kanban-default-board.ts
+++ b/src/shared/kanban-default-board.ts
@@ -13,7 +13,7 @@
* every later reader addresses columns by the ids that board carries — so two surfaces agreeing on
* an id would buy nothing and a fixed id would collide across projects.
*/
-import { NODE_COLORS } from './node-colors'
+import { SYSTEM_NODE_COLORS } from './node-colors'
export interface DefaultBoardColumn {
title: string
@@ -22,9 +22,9 @@ export interface DefaultBoardColumn {
/** The three starting columns, in board order. */
export const DEFAULT_BOARD_COLUMNS: readonly DefaultBoardColumn[] = [
- { title: 'To Do', color: NODE_COLORS[0] },
- { title: 'In Progress', color: NODE_COLORS[2] },
- { title: 'Done', color: NODE_COLORS[1] }
+ { title: 'To Do', color: SYSTEM_NODE_COLORS[0] },
+ { title: 'In Progress', color: SYSTEM_NODE_COLORS[2] },
+ { title: 'Done', color: SYSTEM_NODE_COLORS[1] }
] as const
/**
diff --git a/src/shared/node-colors.test.ts b/src/shared/node-colors.test.ts
index 3f1e95af4..f7ec0e19a 100644
--- a/src/shared/node-colors.test.ts
+++ b/src/shared/node-colors.test.ts
@@ -1,10 +1,23 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
+import { AGENT_CONFIG, BUILTIN_AGENT_IDS, FALLBACK_AGENT_COLOR } from './agents/config'
import {
+ AGENT_NODE_COLOR_SWATCHES,
invalidNodeColorMessage,
+ invalidSystemNodeColorMessage,
isNodeColor,
+ isSystemNodeColor,
NODE_COLORS,
- NODE_COLOR_INVALID_ERROR
+ NODE_COLOR_INVALID_ERROR,
+ NODE_COLOR_SECTIONS,
+ NODE_COLOR_SWATCHES,
+ nodeColorChoices,
+ resolveNodeColor,
+ resolveSystemNodeColor,
+ SYSTEM_NODE_COLOR_SWATCHES,
+ SYSTEM_NODE_COLORS
} from './node-colors'
describe('node color palette', () => {
@@ -15,10 +28,165 @@ describe('node color palette', () => {
}
})
- it('returns a stable named refusal without echoing hostile input', () => {
+ it('returns a stable named refusal that prints a name beside every hex', () => {
const message = invalidNodeColorMessage()
expect(message).toContain(NODE_COLOR_INVALID_ERROR)
- expect(message).toContain(NODE_COLORS.join(', '))
expect(message).not.toContain('\n')
+ // The whole point of the rewrite: `#6ac4dc` taught nobody it was teal, so the caller's next
+ // guess was another name and another refusal.
+ for (const swatch of NODE_COLOR_SWATCHES) {
+ expect(message, swatch.label).toContain(`${swatch.aliases[0]} ${swatch.value}`)
+ }
+ })
+
+ it('names only the system subset in the system refusal', () => {
+ const message = invalidSystemNodeColorMessage()
+ expect(message).toContain('blue #0a84ff')
+ expect(message).not.toContain('#d97757')
+ })
+})
+
+describe('the agent section is DERIVED from AGENT_CONFIG, never re-typed', () => {
+ // The guard: this repo has already shipped one hand-copied mirror of these hexes (the iOS
+ // companion's, stamped "last verified 2026-07-17"). A second copy inside node-colors.ts would
+ // pass every behavior test in this file and silently stop matching the day a brand color moves.
+ it('offers every builtin agent color, by identity', () => {
+ for (const id of BUILTIN_AGENT_IDS) {
+ expect(NODE_COLORS, id).toContain(AGENT_CONFIG[id].color)
+ }
+ expect(NODE_COLORS).toContain(FALLBACK_AGENT_COLOR)
+ })
+
+ it('labels each agent swatch with that agent label and accepts its id as an alias', () => {
+ for (const id of BUILTIN_AGENT_IDS) {
+ const swatch = AGENT_NODE_COLOR_SWATCHES.find((s) => s.value === AGENT_CONFIG[id].color)
+ expect(swatch, id).toBeTruthy()
+ expect(swatch?.label).toBe(AGENT_CONFIG[id].label)
+ expect(swatch?.aliases).toContain(id)
+ expect(resolveNodeColor(id)).toBe(AGENT_CONFIG[id].color)
+ }
+ })
+
+ it('holds no agent hex as a literal in its own source', () => {
+ const src = readFileSync(join(__dirname, 'node-colors.ts'), 'utf8').replace(/\r\n/g, '\n')
+ const code = src
+ .split('\n')
+ .filter((line) => !/^\s*(\*|\/\/|\/\*)/.test(line))
+ .join('\n')
+ for (const id of BUILTIN_AGENT_IDS) {
+ expect(code.toLowerCase(), `${id} color is re-typed instead of derived`).not.toContain(
+ AGENT_CONFIG[id].color.toLowerCase()
+ )
+ }
+ expect(code).toContain("from './agents/config'")
+ })
+
+ it('deduplicates by value, so two agents sharing a hex draw one swatch', () => {
+ const values = NODE_COLORS.map((v) => v.toLowerCase())
+ expect(new Set(values).size).toBe(values.length)
+ })
+})
+
+describe('sections', () => {
+ it('keeps the system colors first and their indices stable', () => {
+ // kanban-default-board.ts names indices 0/1/2 of the system list; and NODE_COLORS is the
+ // system list followed by the agents, so an APPEND is safe and an insert is not.
+ expect(SYSTEM_NODE_COLORS.slice(0, 7)).toEqual([
+ '#0a84ff',
+ '#32d74b',
+ '#ffd60a',
+ '#ff453a',
+ '#bf5af2',
+ '#6ac4dc',
+ '#ff9f0a'
+ ])
+ expect(NODE_COLORS.slice(0, SYSTEM_NODE_COLORS.length)).toEqual([...SYSTEM_NODE_COLORS])
+ })
+
+ it('is the flattened section list, with a heading per section', () => {
+ expect(NODE_COLOR_SECTIONS.map((s) => s.label)).toEqual(['Colors', 'Agents'])
+ for (const section of NODE_COLOR_SECTIONS) expect(section.label).not.toBe('')
+ expect(NODE_COLOR_SWATCHES.map((s) => s.value)).toEqual([...NODE_COLORS])
+ expect(NODE_COLOR_SECTIONS[0].swatches).toEqual(SYSTEM_NODE_COLOR_SWATCHES)
+ expect(NODE_COLOR_SECTIONS[1].swatches).toEqual(AGENT_NODE_COLOR_SWATCHES)
+ })
+
+ it('every swatch has a label and at least one alias', () => {
+ for (const swatch of NODE_COLOR_SWATCHES) {
+ expect(swatch.label.trim(), swatch.value).not.toBe('')
+ expect(swatch.aliases.length, swatch.value).toBeGreaterThan(0)
+ for (const alias of swatch.aliases) expect(alias, swatch.value).toBe(alias.toLowerCase())
+ }
+ })
+})
+
+describe('resolveNodeColor', () => {
+ it('resolves every hex to itself', () => {
+ for (const color of NODE_COLORS) expect(resolveNodeColor(color)).toBe(color)
+ })
+
+ it('resolves names and mixed-case hex to the canonical value', () => {
+ expect(resolveNodeColor('blue')).toBe('#0a84ff')
+ expect(resolveNodeColor(' Teal ')).toBe('#6ac4dc')
+ expect(resolveNodeColor('cyan')).toBe('#6ac4dc')
+ expect(resolveNodeColor('claude')).toBe(AGENT_CONFIG.claude.color)
+ expect(resolveNodeColor('Claude Code')).toBe(AGENT_CONFIG.claude.color)
+ expect(resolveNodeColor('claudecode')).toBe(AGENT_CONFIG.claude.color)
+ expect(resolveNodeColor('#D97757')).toBe(AGENT_CONFIG.claude.color)
+ })
+
+ it('refuses everything else, and never invents a value', () => {
+ for (const bad of [
+ '#ffffff',
+ 'var(--accent)',
+ 'rgb(1,2,3)',
+ 'magenta',
+ '',
+ ' ',
+ undefined,
+ null,
+ 42,
+ { value: '#0a84ff' },
+ 'constructor',
+ '__proto__',
+ 'toString'
+ ]) {
+ expect(resolveNodeColor(bad), String(bad)).toBeUndefined()
+ }
+ })
+
+ it('only ever yields a value the allowlist already accepted', () => {
+ for (const swatch of NODE_COLOR_SWATCHES) {
+ for (const alias of swatch.aliases) {
+ const resolved = resolveNodeColor(alias)
+ expect(resolved, alias).toBeDefined()
+ expect(isNodeColor(resolved), alias).toBe(true)
+ }
+ }
+ })
+})
+
+describe('the narrower system boundary', () => {
+ // Accent, project color and kanban column color draw the value as TEXT or as an opaque fill
+ // under hardcoded #fff, where the agent brand hues fall under the contrast floor.
+ it('accepts the system colors and refuses the agent ones', () => {
+ for (const color of SYSTEM_NODE_COLORS) expect(isSystemNodeColor(color), color).toBe(true)
+ for (const swatch of AGENT_NODE_COLOR_SWATCHES) {
+ expect(isSystemNodeColor(swatch.value), swatch.label).toBe(false)
+ expect(resolveSystemNodeColor(swatch.aliases[0]), swatch.label).toBeUndefined()
+ }
+ })
+
+ it('still resolves system names', () => {
+ expect(resolveSystemNodeColor('orange')).toBe('#ff9f0a')
+ expect(resolveSystemNodeColor('#FF9F0A')).toBe('#ff9f0a')
+ })
+
+ it('prints only the system choices', () => {
+ const choices = nodeColorChoices(SYSTEM_NODE_COLOR_SWATCHES)
+ expect(choices).toContain('purple #bf5af2')
+ for (const swatch of AGENT_NODE_COLOR_SWATCHES) {
+ expect(choices, swatch.label).not.toContain(swatch.value)
+ }
})
})
diff --git a/src/shared/node-colors.ts b/src/shared/node-colors.ts
index da25fc61c..ba2fdc877 100644
--- a/src/shared/node-colors.ts
+++ b/src/shared/node-colors.ts
@@ -1,28 +1,200 @@
+import { AGENT_CONFIG, BUILTIN_AGENT_IDS, FALLBACK_AGENT_COLOR } from './agents/config'
+
/**
* The node/frame/sticky palette shown by every renderer color picker.
*
* This is also the control boundary: agent-supplied colors must be one of these exact values,
* never an arbitrary CSS token that would be persisted and interpolated into node styles.
+ *
+ * It has TWO sections and they are one list, deliberately:
+ *
+ * - the seven system colors, which is what the palette was;
+ * - the AGENT brand colors, which every agent node has WORN SINCE IT WAS CREATED
+ * (`createAgentNode` colors a node from `AGENT_CONFIG`, and the phone does the same) but which
+ * the palette never contained. So a Claude node was born `#d97757`, the right-click picker
+ * could not offer that color back once the user changed it, and `color --color '#d97757'` was
+ * refused by the boundary below with `node-color-invalid` — the app's own color, rejected by
+ * the app. Both halves of that are this file.
+ *
+ * The agent section is DERIVED from `AGENT_CONFIG`, never re-typed. A second copy of a color
+ * table is the drift CLAUDE.md warns about, and it has already happened once: the iOS companion
+ * keeps a hand-copied mirror stamped "last verified 2026-07-17".
+ */
+
+export interface NodeColorSwatch {
+ /** The persisted value. Canonical, lowercase hex — this is what lands in `data.color`. */
+ readonly value: string
+ /** Human name, shown as the swatch's tooltip / accessible name. */
+ readonly label: string
+ /**
+ * Lowercase words `resolveNodeColor` accepts for this swatch besides its hex. The FIRST is the
+ * primary one and is what the CLI's help text and refusal message print beside the hex.
+ */
+ readonly aliases: readonly string[]
+}
+
+/**
+ * The seven macOS system colors. This subset — not the whole palette — is what the auto-assign
+ * ROTATIONS use (new frames, spawned teams, fresh kanban columns) and what the app-accent picker
+ * offers: rotating a frame onto Claude's orange would say "this frame is Claude's" when it means
+ * nothing of the kind, and an agent brand color is not an app accent. Their INDICES are load
+ * bearing (`kanban-default-board.ts` names 0/1/2), so append here, never insert.
+ */
+export const SYSTEM_NODE_COLOR_SWATCHES: readonly NodeColorSwatch[] = [
+ { value: '#0a84ff', label: 'Blue', aliases: ['blue'] },
+ { value: '#32d74b', label: 'Green', aliases: ['green'] },
+ { value: '#ffd60a', label: 'Yellow', aliases: ['yellow'] },
+ { value: '#ff453a', label: 'Red', aliases: ['red'] },
+ { value: '#bf5af2', label: 'Purple', aliases: ['purple'] },
+ { value: '#6ac4dc', label: 'Teal', aliases: ['teal', 'cyan'] },
+ { value: '#ff9f0a', label: 'Orange', aliases: ['orange'] }
+]
+
+/**
+ * The agent brand colors, read out of `AGENT_CONFIG` in builtin order, plus the grey that
+ * `createAgentNode` gives a CUSTOM agent (`FALLBACK_AGENT_COLOR`) — a color real nodes wear and
+ * the picker could not express either.
+ *
+ * Deduped by value: nothing stops two agents sharing a hex, and a duplicate would collide as a
+ * React key and draw the same swatch twice. First occurrence wins, so a future agent that adopts
+ * an existing color simply adds its name as an alias of the swatch that is already there.
+ */
+export const AGENT_NODE_COLOR_SWATCHES: readonly NodeColorSwatch[] = dedupe([
+ ...BUILTIN_AGENT_IDS.map((id) => ({
+ value: AGENT_CONFIG[id].color,
+ label: AGENT_CONFIG[id].label,
+ // The agent id is the alias an orchestrator already knows (`open-agent --agent claude`), and
+ // the label lets a human type what the swatch says.
+ aliases: aliasesFor(id, AGENT_CONFIG[id].label)
+ })),
+ { value: FALLBACK_AGENT_COLOR, label: 'Custom agent', aliases: ['custom', 'grey', 'gray'] }
+])
+
+function aliasesFor(id: string, label: string): readonly string[] {
+ const lower = label.toLowerCase()
+ const squashed = lower.replace(/\s+/g, '')
+ return [...new Set([id.toLowerCase(), lower, squashed])]
+}
+
+function dedupe(swatches: readonly NodeColorSwatch[]): NodeColorSwatch[] {
+ const seen = new Map<string, NodeColorSwatch>()
+ for (const swatch of swatches) {
+ const value = swatch.value.toLowerCase()
+ const existing = seen.get(value)
+ if (existing) {
+ seen.set(value, {
+ ...existing,
+ aliases: [...new Set([...existing.aliases, ...swatch.aliases])]
+ })
+ continue
+ }
+ seen.set(value, { ...swatch, value })
+ }
+ return [...seen.values()]
+}
+
+/** The palette as the pickers draw it: sections, in order, each with its own heading. */
+export const NODE_COLOR_SECTIONS: readonly { readonly label: string; readonly swatches: readonly NodeColorSwatch[] }[] = [
+ { label: 'Colors', swatches: SYSTEM_NODE_COLOR_SWATCHES },
+ { label: 'Agents', swatches: AGENT_NODE_COLOR_SWATCHES }
+]
+
+/** Every swatch, in section order. */
+export const NODE_COLOR_SWATCHES: readonly NodeColorSwatch[] = NODE_COLOR_SECTIONS.flatMap(
+ (section) => section.swatches
+)
+
+/** The full allowlist — what a picker may set and what the control verbs may persist. */
+export const NODE_COLORS: readonly string[] = NODE_COLOR_SWATCHES.map((swatch) => swatch.value)
+
+/** @see SYSTEM_NODE_COLOR_SWATCHES — the rotation/accent subset, NOT the whole palette. */
+export const SYSTEM_NODE_COLORS: readonly string[] = SYSTEM_NODE_COLOR_SWATCHES.map((s) => s.value)
+
+/**
+ * A palette value. Deliberately `string` and not a literal union any more: half the palette is
+ * now DERIVED from `AGENT_CONFIG` at runtime, and a union can only be written by re-typing those
+ * hexes here — the second copy this file exists to avoid. Nothing is lost that was load bearing:
+ * every value this guards arrives from the wire (a control POST) or from hand-edited JSON, where
+ * a compile-time union proves nothing, and `isNodeColor` is and always was the real boundary.
*/
-export const NODE_COLORS = [
- '#0a84ff', // systemBlue
- '#32d74b', // systemGreen
- '#ffd60a', // systemYellow
- '#ff453a', // systemRed
- '#bf5af2', // systemPurple
- '#6ac4dc', // systemTeal
- '#ff9f0a' // systemOrange
-] as const
-
-export type NodeColor = (typeof NODE_COLORS)[number]
+export type NodeColor = string
export const NODE_COLOR_INVALID_ERROR = 'node-color-invalid'
export function isNodeColor(value: unknown): value is NodeColor {
- return typeof value === 'string' && (NODE_COLORS as readonly string[]).includes(value)
+ return typeof value === 'string' && NODE_COLORS.includes(value)
+}
+
+/**
+ * The narrower boundary for the three surfaces where a palette value stops being a dot, a border
+ * or a 6–20% wash and becomes TEXT or an opaque fill: the app ACCENT (`--accent`, drawn under
+ * hardcoded `#fff` in `.dock-add` and the dictation button), a PROJECT color (the active tab
+ * label is `color: p.color`) and a kanban COLUMN color (`ColumnPill` draws the title in the raw
+ * hex at 10 px on an 18% wash of itself).
+ *
+ * The seven system colors were chosen to be legible that way; the agent brand colors were chosen
+ * by six other companies for a logo. Measured on the dark theme: white on gemini `#4285f4` is
+ * ~3.6:1 and on grok `#64748b` ~4.0:1, both under the 4.5:1 floor for the 10.5 px badge, and grok
+ * grey as tab text lands at ~2.6:1. So those surfaces keep the subset — the reason they differ is
+ * a contrast measurement, not taste, and `styles.theme.test.ts` is where the floors live.
+ */
+export function isSystemNodeColor(value: unknown): value is NodeColor {
+ return typeof value === 'string' && SYSTEM_NODE_COLORS.includes(value)
+}
+
+/** @see isSystemNodeColor — `resolveNodeColor` restricted to the system section. */
+export function resolveSystemNodeColor(input: unknown): NodeColor | undefined {
+ const resolved = resolveNodeColor(input)
+ return resolved !== undefined && isSystemNodeColor(resolved) ? resolved : undefined
+}
+
+const BY_ALIAS: ReadonlyMap<string, string> = (() => {
+ const map = new Map<string, string>()
+ for (const swatch of NODE_COLOR_SWATCHES) {
+ map.set(swatch.value, swatch.value)
+ for (const alias of swatch.aliases) if (!map.has(alias)) map.set(alias, swatch.value)
+ }
+ return map
+})()
+
+/**
+ * What the user or an agent TYPED, resolved to a canonical palette value — or undefined, which is
+ * still a refusal. Accepts the hex in any case, and the swatch's name (`blue`, `claude`,
+ * `github copilot`).
+ *
+ * Names are accepted because the refusal they used to earn was measured and it was expensive: a
+ * palette of seven opaque hexes taught nobody which one was teal, and `--color blue` — the
+ * obvious thing a person and a model both type — came back `node-color-invalid` with a list of
+ * hexes. Names cost nothing at the boundary: resolution happens BEFORE the allowlist check and
+ * can only ever produce a value that was already in it, so what gets persisted is the same
+ * canonical hex it always was. A name is never stored.
+ */
+export function resolveNodeColor(input: unknown): NodeColor | undefined {
+ if (typeof input !== 'string') return undefined
+ return BY_ALIAS.get(input.trim().toLowerCase())
+}
+
+/**
+ * `name #hex` for every swatch — the CLI's own vocabulary, printed for agents and humans.
+ *
+ * The refusal used to print seven bare hexes. That is a complete answer and an unusable one:
+ * nothing in `#6ac4dc, #ff9f0a` says which is teal, so the caller's next guess is another name and
+ * another refusal. Printing the name it can actually type ends the loop in one round trip.
+ */
+export function nodeColorChoices(
+ swatches: readonly NodeColorSwatch[] = NODE_COLOR_SWATCHES
+): string {
+ return swatches.map((swatch) => `${swatch.aliases[0]} ${swatch.value}`).join(', ')
}
/** Stable named refusal shared by desktop and Server Edition control dispatch. */
export function invalidNodeColorMessage(): string {
- return `${NODE_COLOR_INVALID_ERROR}: --color must be one of ${NODE_COLORS.join(', ')}`
+ return `${NODE_COLOR_INVALID_ERROR}: --color takes a palette name or its hex — ${nodeColorChoices()}`
+}
+
+/** @see isSystemNodeColor — the same refusal for the narrower surfaces. */
+export function invalidSystemNodeColorMessage(): string {
+ return `${NODE_COLOR_INVALID_ERROR}: --color takes a palette name or its hex — ${nodeColorChoices(
+ SYSTEM_NODE_COLOR_SWATCHES
+ )}`
}