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
import type { LUCIDE_ICON_IDS } from './project-icon'
/**
* A canvas node's user-chosen icon: one emoji/character, a curated glyph, 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. **Both `/` and
* `\\` count as separators when that rule is applied, on every platform** — see
* `isSafeRelIconPath`.
*
* **Two dialects in, one dialect out.** The value is written by one machine and read by another,
* so validation ACCEPTS a Windows path (`C:\\...`) and a POSIX one (`/...`) regardless of where
* the check runs, while everything this module STORES is POSIX-separated. Both halves are
* load-bearing:
*
* • Accepting both everywhere is what stops a mac's `flowToNodeStates` from silently deleting a
* Windows teammate's icons: refuse `C:\\...` on mac and a mac user merely opening the shared
* canvas and saving it strips them from `project.json`. A Windows absolute path on a mac does
* not RESOLVE, of course — it just does not draw, exactly as a POSIX absolute path from someone
* else's machine already does not. That is a degrade, and a degrade is not a reason to destroy
* the value on the way past.
* • Storing one dialect is what makes the `./` form portable at all. A stored `.\\a\\b.png` would
* mean "a file called `a\\b.png`" on POSIX and "`b.png` inside `a`" on Windows. So
* `normalizeNodeIcon` canonicalizes a relative path to `./` with forward slashes, the same way
* it canonicalizes an emoji to its first grapheme.
*
* **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, a curated glyph, or an image file beside the project. */
export type NodeIcon =
| { type: 'emoji'; value: string }
| { type: 'lucide'; name: string }
| { type: 'image'; path: string }
/**
* The curated glyphs a node icon may be (issue #291): what a terminal IS — a shell, a git repo, a
* database session — rather than an emoji mood. Stored as `{ type: 'lucide', name }`, the shape a
* project icon's glyph already has, so one vocabulary covers both.
*
* A closed allowlist and a SUBSET of the project icon's `LUCIDE_ICON_IDS` — the type below makes
* the compiler refuse an id outside it — so the renderer draws a node glyph from the same map a
* project glyph uses and no second lucide table exists. Order is the picker's grid order. The
* label is the button's accessible name and tooltip; it is never stored.
*/
export const NODE_GLYPHS: readonly { readonly id: (typeof LUCIDE_ICON_IDS)[number]; readonly label: string }[] = [
{ id: 'terminal', label: 'Shell' },
{ id: 'folder-git', label: 'Git repo' },
{ id: 'database', label: 'Database' },
{ id: 'server', label: 'Server' },
{ id: 'cloud', label: 'Cloud' },
{ id: 'globe', label: 'Web' },
{ id: 'code', label: 'Code' },
{ id: 'braces', label: 'Config' },
{ id: 'file-text', label: 'Docs' },
{ id: 'book', label: 'Notes' },
{ id: 'package', label: 'Build' },
{ id: 'rocket', label: 'Deploy' },
{ id: 'beaker', label: 'Tests' },
{ id: 'bug', label: 'Debug' },
{ id: 'wrench', label: 'Tools' },
{ id: 'cpu', label: 'System' },
{ id: 'shield', label: 'Security' },
{ id: 'key', label: 'Secrets' }
]
const NODE_GLYPH_IDS: ReadonlySet<string> = new Set(NODE_GLYPHS.map((g) => g.id))
/**
* 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 }>
}
/**
* A path separator. BOTH are separators everywhere, never "`\` only on Windows": the value is
* written by one machine and validated on another, so a check that reads `\` as an ordinary
* filename character on the validating machine is simply wrong about the machine that will read
* it. Applying the strict rule on every platform costs a POSIX user only the ability to name an
* icon file with a literal backslash in it.
*/
const SEP_RE = /[\\/]/
/** `./` or `.\` — the marker for a path stored relative to the project root. */
const REL_PREFIX_RE = /^\.[\\/]/
/**
* A drive-qualified absolute path: `C:\...` or `C:/...`. The separator is REQUIRED, because
* `C:x.png` is drive-RELATIVE — it resolves against whatever directory that drive happens to be
* sitting on in the reading process, which is precisely the guess this module refuses to make.
*/
const DRIVE_ABS_RE = /^[A-Za-z]:[\\/]/
/**
* A UNC path: `\\host\share\...` or `//host/share/...`. Refused, matching the decision already
* made for terminal file links (`renderer/terminal/file-links.ts`, which consumes UNC
* specifically so it can refuse it). Reading one reaches ANOTHER MACHINE over SMB, which is a
* long way outside "an icon beside the canvas" and is exactly the reach the extension gate exists
* to keep narrow. Note this also refuses a POSIX `//foo/bar`, where a leading `//` is
* implementation-defined anyway — no real icon path is lost.
*/
const UNC_RE = /^(?:\\\\|\/\/)/
/** Absolute in EITHER dialect, and not a network path. The one predicate all three exported
* functions ask, so they cannot disagree about what "absolute" means. */
function isAbsoluteIconPath(path: string): boolean {
if (UNC_RE.test(path)) return false
return path.startsWith('/') || DRIVE_ABS_RE.test(path)
}
/** The final segment of a path in either dialect — `C:\a\b.png` and `/a/b.png` both give
* `b.png`. Exported because the picker needs the same answer when it names the copied file. */
export function iconFileName(path: string): string {
const segments = path.split(SEP_RE)
return segments[segments.length - 1] ?? ''
}
/** 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 = iconFileName(path)
// 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.
*
* Splitting on BOTH separators is the whole point, and it is not a Windows nicety. Splitting on
* `/` alone, `./a\..\..\secret.png` is ONE segment — not `''`, not `.`, not `..` — so it passed
* this guard on every platform and then walked two directories out of the project the moment a
* Windows reader resolved it. One machine writes this value and another reads it, so the rule has
* to hold where it is CHECKED, not only where it happens to be dangerous.
*
* A segment may also not contain `:`. On Windows that is either a drive qualifier (`./C:/Windows`)
* or an NTFS alternate data stream (`./icon.png:payload`), and a project-relative icon path has no
* business expressing either.
*/
function isSafeRelIconPath(rel: string): boolean {
const segments = rel.split(SEP_RE)
return segments.every(
(seg) => seg !== '' && seg !== '.' && seg !== '..' && !seg.includes(':')
)
}
/**
* 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 === 'lucide') {
// Exact match only — no trimming or case-folding. The value is written by the picker, so a
// near miss is a hand edit or a newer build's glyph, and an unrecognized icon is no icon.
const name = (raw as { name?: unknown }).name
return typeof name === 'string' && NODE_GLYPH_IDS.has(name) ? { type: 'lucide', name } : 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 (REL_PREFIX_RE.test(path)) {
const rel = path.slice(2)
if (!isSafeRelIconPath(rel)) return undefined
// Canonicalize to the one stored dialect. A hand-edited `.\a\b.png` means two different
// files on the two platforms; rewriting it here (the same way an emoji is rewritten to its
// first grapheme) is what keeps the shared file unambiguous for its next reader.
return { type: 'image', path: `./${rel.replace(/\\/g, '/')}` }
}
// Anything else must be absolute, in either dialect: 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. An absolute path is kept BYTE FOR
// BYTE — it belongs to one machine's filesystem and is not ours to rewrite.
return isAbsoluteIconPath(path) ? { 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) return absPath
// The prefix test is separator-INSENSITIVE: `saveCanvasImage` builds its answer with the host's
// own `path.join`, so on Windows it comes back `C:\proj\.nodeterm\images\x.png` while
// `project.cwd` may carry either separator. Comparing raw strings there simply never matched,
// and the icon silently stayed absolute — travelling nowhere, with nothing said about it.
//
// The comparison stays CASE-sensitive even though Windows filesystems usually are not: both
// sides come from the same `project.cwd` in practice, so they match exactly, and a
// case-insensitive test would wrongly relativize on a case-sensitive filesystem. Not matching
// costs only portability; matching wrongly costs correctness.
const toPosix = (p: string): string => p.replace(/\\/g, '/')
const posixRoot = toPosix(root)
const posixAbs = toPosix(absPath)
if (!posixAbs.startsWith(`${posixRoot}/`)) return absPath
const rel = posixAbs.slice(posixRoot.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 {
// Re-asked rather than assumed: this is exported, and the next caller may not have come through
// `normalizeNodeIcon` (the same reasoning `loadNodeIconSrc` gives for re-checking the MIME).
if (!REL_PREFIX_RE.test(storedPath)) {
return isAbsoluteIconPath(storedPath) ? storedPath : undefined
}
const rel = storedPath.slice(2)
if (!isSafeRelIconPath(rel)) return undefined
const root = projectCwd?.replace(/[\\/]+$/, '')
if (!root) return undefined
// Joined with `/` even when `root` is a Windows path: Node's fs accepts forward slashes on
// Windows, and one deterministic spelling keeps `nodeIconImage`'s per-path cache from holding
// two entries for one file.
return `${root}/${rel.replace(/\\/g, '/')}`
}
/**
* The cwd a `./` icon path may be resolved against, given a project — or undefined when there
* isn't one it can honestly use.
*
* This exists because the rule was written TWICE and the two copies drifted, which is the failure
* this repo warns about elsewhere. The picker's write side already said
* `project.ssh ? undefined : project.cwd`; the read side said only `project.cwd`. For an SSH
* project those are different facts: `cwd` is a path on the REMOTE host, while the icon is read
* through the LOCAL `api.fs` (an SSH project runs on the local session — only a RELAY tab's api
* belongs to another machine). So a `./` icon written by someone who has that repo checked out
* locally resolved, on the SSH client, to the same relative path under a remote root — and asked
* this machine to read it. That is a local file that has nothing to do with the icon, and it is
* shown if it happens to exist.
*
* Answering undefined means the icon does not draw, which is the honest outcome: that file is on
* a machine whose filesystem this reader cannot see. Absolute paths are unaffected, and absolute
* is exactly what the write side stores for an SSH project.
*/
export function localIconCwd(project: { cwd?: string; ssh?: unknown } | undefined): string | undefined {
if (!project || project.ssh) return undefined
return project.cwd
}