Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(canvas): file-manager node — a directory listing on the canvas

Lorenzo Albanese (alblor)cb2fcbef50cf
diff --git a/CLAUDE.md b/CLAUDE.md
index ed36bc93f..0ea14aeaa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -161,12 +161,12 @@ separate store mirroring node state — earlier dual-source designs caused sync
`src/renderer/state/workspace.ts` holds only pure helpers: the color palette, the node
factories (`createTerminalNode`, `createSshTerminalNode`, `createAgentNode(agentId, …)`,
`createAccountLoginNode`, `createStickyNode`, `createGroupNode`, `createEditorNode`,
-`createDiffNode`, `createVideoNode`, `createWebNode`, `createBrowserNode`, `createDinoNode`,
-`createTriggerNode`), the
+`createDiffNode`, `createVideoNode`, `createWebNode`, `createBrowserNode`, `createFilesNode`,
+`createDinoNode`, `createTriggerNode`), the
group transforms (`groupSelectedNodes`, `ungroupNodes`, `duplicateNode`), and the
`nodeStatesToFlow` / `flowToNodeStates` serializers. Node kinds (`NodeKind` in
`src/shared/types.ts`): `terminal | sticky | group | editor | diff | video | web | browser |
-subagent | loop | dino | trigger` — `subagent` and `loop` are render-only (ephemeral hook-driven
+files | subagent | loop | dino | trigger` — `subagent` and `loop` are render-only (ephemeral hook-driven
viz) and never persisted. `trigger` (issue #493, all four
phases landed) is a first-class PERSISTED kind. The whole host-side
machine is composed ONCE in `core/trigger-service.ts` (`startTriggerService`) and booted
@@ -850,6 +850,44 @@ session.
- **browser** (`BrowserNode.tsx`) — a navigable Chromium browser wrapping the shared
`BrowserSurface` (webview + toolbar); the last top-level URL persists to `data.url`, and the same
surface backs the kanban card modal's browser popup.
+- **files** (`FilesNode.tsx`) — a file-manager node: ONE directory listing (`data.cwd`, persisted),
+ pinned to the canvas beside the terminals working in it. Deliberately not a second Explorer: the
+ drawer is a single tree rooted at the project cwd that covers the canvas, so it gives you one
+ cursor and a lot of scrolling; several of these give you `src/renderer/nodes` next to the agent
+ editing it and another on `docs/`. Navigate in place (breadcrumbs collapse deep paths but every
+ crumb stays clickable), filter, create a file/folder, copy a path, reveal, and open a terminal in
+ the folder shown (a `nodeterm:open-terminal` event, the sibling of `nodeterm:open-file`).
+ - **It adds NO new IPC.** Everything runs on the existing `FsApi` (`list`/`mkdir`/`exists`/
+ `write`) — which is why it works on Desktop, the Server Edition, an SSH project and a relay tab
+ on day one. **Rename/move/delete are the deliberate v1 gap**: each needs a new leaf in
+ `core/fs-ops`, an IPC channel, preload, the ws-bridge, `main/ssh-fs` (remote quoting) and the
+ relay host-service, plus confirm dialogs and dangerous-path guards. That is a separate change
+ with separate risk, not a corner to cut inside this one.
+ - **Which filesystem** is `EditorNode`'s decision, read the same way: `data.sshFs` → the SSH
+ project's host over the ControlMaster; otherwise the node's own SESSION api, which is the local
+ core for a local project and the PEER's for a relay tab. Reading it off `useSession()` rather
+ than `window.nodeTerminal` is the entire reason a relay tab browses the right machine.
+ - **Opening is delegated, never reimplemented**: a file dispatches `nodeterm:open-file`, so
+ editor-vs-video-vs-image routing stays in Canvas's one `openFile` and this node never grows a
+ second opinion about what a `.png` is. `fileOpenTarget` decides only canvas-vs-OS, and a
+ REMOTE listing never reaches the OS branch — `shell.openPath` opens a path on THIS machine, so
+ handing it a host path either does nothing or, if that path exists here too, opens an unrelated
+ local file.
+ - **Four empty states stay four** (loading / could not read / the folder is empty / the filter
+ matches nothing). Collapsing any pair into one blank pane is the failure this file warns about
+ elsewhere, and an empty filter matches everything so select-all+delete cannot blank the list.
+ - The title tracks the folder only while `titleAuto` is unset — the same contract an agent node's
+ session name uses, so navigating never overwrites a name the user typed.
+ - A files node inside a REMOVED worktree is displaced like an editor, not like a terminal
+ (`displacedByWorktree`): it has no session to disturb, so it is caught by path wherever it sits,
+ and it gets its `cwd` re-pointed rather than an editor's `fileMissing` — a directory can be
+ re-pointed, a dead file cannot. Left out, it would show "Could not read this folder" forever
+ AND keep the dead path in `project.json`.
+ - Creation is gated on the project having a directory (`hasCwd`) on every surface — pane menu,
+ Dock, sidebar "+", ⌘K, and the group-frame menu, where it inherits a bound **worktree's** cwd
+ via `cwdForNewNodeIn`, so a frame per branch also means a file tree per branch.
+ - **Mobile**: N/A — *nodeterm mobile* attaches to tmux sessions over the transport protocol and
+ has no canvas or file-browsing concept; adding one means extending that protocol.
- **dino** (`DinoNode.tsx`) — a small self-contained T-Rex-style runner on a canvas (no PTY);
high score persists via `data.highScore`.
- **trigger** (`TriggerNode.tsx`) — a canvas-owned schedule (cron / interval / once) that
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index e438ba49a..3e8560c36 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -81,6 +81,7 @@ import { LazyEditorNode, LazyDiffNode } from '../nodes/lazyMonacoNodes'
import { DinoNode } from '../nodes/DinoNode'
import { TriggerNode } from '../nodes/TriggerNode'
import BrowserNode from '../nodes/BrowserNode'
+import { FilesNode } from '../nodes/FilesNode'
import { normalizeAddress } from '../nodes/browserUrl'
import VideoNode from '../nodes/VideoNode'
import WebNode from '../nodes/WebNode'
@@ -490,6 +491,7 @@ import {
createBrowserNode,
createDinoNode,
createTriggerNode,
+ createFilesNode,
createDiffNode,
createEditorNode,
createGroupNode,
@@ -1530,7 +1532,8 @@ export function Canvas() {
trigger: withNodeBoundary(TriggerNode),
video: withNodeBoundary(VideoNode),
web: withNodeBoundary(WebNode),
- browser: withNodeBoundary(BrowserNode)
+ browser: withNodeBoundary(BrowserNode),
+ files: withNodeBoundary(FilesNode)
}),
[]
)
@@ -3944,13 +3947,21 @@ export function Canvas() {
const d = (e as CustomEvent<{ path: string }>).detail
if (d?.path) revealProjectFile(d.path)
}
+ // A file-manager node asking for a terminal in the folder it is showing. Same
+ // no-direct-line-to-the-canvas pattern as the two above.
+ const onTerminal = (e: Event): void => {
+ const d = (e as CustomEvent<{ cwd?: string }>).detail
+ if (d?.cwd) addTerminal(undefined, undefined, undefined, d.cwd)
+ }
window.addEventListener('nodeterm:open-file', onOpen)
window.addEventListener('nodeterm:reveal-file', onReveal)
+ window.addEventListener('nodeterm:open-terminal', onTerminal)
return () => {
window.removeEventListener('nodeterm:open-file', onOpen)
window.removeEventListener('nodeterm:reveal-file', onReveal)
+ window.removeEventListener('nodeterm:open-terminal', onTerminal)
}
- }, [openFile, revealProjectFile])
+ }, [openFile, revealProjectFile, addTerminal])
// Mic button on a terminal node's header (TerminalNode dispatches this — same
// no-direct-line-to-canvas pattern as nodeterm:open-file above). Unlike toggleDictation's
@@ -4123,6 +4134,33 @@ export function Canvas() {
[commitActiveToStore, writeDisk]
)
+ /**
+ * Open a file-manager node. It starts at the group's worktree cwd if it is being created inside
+ * a bound frame, else the project's own root — for an SSH project that is the REMOTE root, and
+ * the node is stamped `sshFs` so it lists the host rather than this machine (the same pairing
+ * `openFile` makes for an Explorer-opened remote file).
+ *
+ * Refused, rather than opened empty, when the project has no directory at all: a cwd-less canvas
+ * has nothing to browse, and a file manager rooted at `/` by default would be a worse answer
+ * than a sentence saying so.
+ */
+ const addFiles = useCallback(
+ (center?: { x: number; y: number }, groupId?: string, cwdOverride?: string) => {
+ const project = useProjects.getState().getProject(activeProjectId)
+ const cwd = cwdOverride ?? cwdForNewNodeIn(groupId) ?? project?.ssh?.remoteCwd ?? project?.cwd
+ if (!cwd) {
+ setCopyError('This canvas has no folder yet — open one from the project tab first.')
+ return
+ }
+ setNodes((ns) => {
+ const node = createFilesNode(ns.length, cwd, center ?? emptyNodePos(), !!project?.ssh)
+ return [...ns, groupId ? parentInto(node, groupId) : node]
+ })
+ markDirty()
+ },
+ [setNodes, markDirty, activeProjectId, emptyNodePos, cwdForNewNodeIn, parentInto]
+ )
+
const addSticky = useCallback(
(center?: { x: number; y: number }, groupId?: string) => {
setNodes((ns) => {
@@ -7866,6 +7904,9 @@ export function Canvas() {
},
...agentCreationItems(at, groupId),
{ label: 'New sticky note', icon: <IconNote />, onClick: () => addSticky(at, groupId) },
+ // Inside a worktree-bound frame this roots the manager at the WORKTREE, not the project —
+ // `cwdForNewNodeIn` is what makes a frame per branch also mean a file tree per branch.
+ { label: 'New file manager', icon: <IconExplorer />, onClick: () => addFiles(at, groupId) },
{ type: 'separator' },
...(isHidden('colors', useSettings.getState().settings.hiddenNodeMenuItems)
? []
@@ -7964,6 +8005,7 @@ export function Canvas() {
browser: (at) => addBrowser(at),
web: (at) => void addWebView(at),
sticky: (at) => addSticky(at),
+ files: (at) => addFiles(at),
dino: (at) => addDino(at),
trigger: (at) => addTrigger(at),
openFile: (at) => void openFileDialog(at),
@@ -7975,6 +8017,7 @@ export function Canvas() {
addTerminal,
openRemotePicker,
addBrowser,
+ addFiles,
addWebView,
addSticky,
addDino,
@@ -11924,6 +11967,17 @@ export function Canvas() {
})
),
{ id: 'new-sticky', label: 'New sticky note', icon: <IconNote />, run: () => addSticky() },
+ // Needs a folder to root itself in, exactly like "New file…" below.
+ ...(newFileHasCwd
+ ? [
+ {
+ id: 'new-files',
+ label: 'New file manager',
+ icon: <IconExplorer />,
+ run: () => addFiles()
+ }
+ ]
+ : []),
{ id: 'new-dino', label: 'New dino game', icon: <IconDino />, run: () => addDino() },
{ id: 'open-file', label: 'Open file…', icon: <IconEditor />, run: () => void openFileDialog() },
// "New file…" needs a project folder to create into — hidden when the project has no cwd.
@@ -13080,6 +13134,7 @@ export function Canvas() {
onSpawnTeam={() => setSpawnTeamDialog({})}
onAddDino={addDino}
onAddTrigger={addTrigger}
+ onAddFiles={() => addFiles()}
onAddAgent={(aid, accountId) => addAgentNode(aid, undefined, undefined, accountId)}
onOpenFile={() => void openFileDialog()}
onAddRemote={() => openRemotePicker({ x: window.innerWidth / 2, y: window.innerHeight / 2 })}
diff --git a/src/renderer/components/Dock.tsx b/src/renderer/components/Dock.tsx
index 08e2e1c07..918773727 100644
--- a/src/renderer/components/Dock.tsx
+++ b/src/renderer/components/Dock.tsx
@@ -26,6 +26,7 @@ interface DockProps {
onSpawnTeam: () => void
onAddDino: () => void
onAddTrigger: () => void
+ onAddFiles: () => void
onAddAgent: (agentId: AgentId, accountId?: string) => void
onOpenFile: () => void
onAddRemote: () => void
@@ -66,6 +67,7 @@ export function Dock({
onSpawnTeam,
onAddDino,
onAddTrigger,
+ onAddFiles,
onAddAgent,
onOpenFile,
onAddRemote,
@@ -158,6 +160,7 @@ export function Dock({
spawnTeam: onSpawnTeam,
dino: onAddDino,
trigger: onAddTrigger,
+ files: onAddFiles,
openFile: onOpenFile,
newFile: onNewFile,
worktree: onAddWorktree
diff --git a/src/renderer/lib/addMenuSpec.test.tsx b/src/renderer/lib/addMenuSpec.test.tsx
index 45df08c1d..528c0ffd5 100644
--- a/src/renderer/lib/addMenuSpec.test.tsx
+++ b/src/renderer/lib/addMenuSpec.test.tsx
@@ -17,6 +17,7 @@ const handlers = (overrides: Partial<AddHandlers> = {}): AddHandlers => ({
browser: noop,
web: noop,
sticky: noop,
+ files: noop,
dino: noop,
trigger: noop,
openFile: noop,
@@ -32,6 +33,7 @@ const allKinds: AddItem['kind'][] = [
'browser',
'web',
'sticky',
+ 'files',
'dino',
'trigger',
'open-file',
@@ -60,6 +62,7 @@ describe('contentAddItemsToMenuItems', () => {
'New browser',
'New web view…',
'New sticky note',
+ 'New file manager',
'New dino game',
'New trigger…',
'Open file…',
@@ -69,6 +72,14 @@ describe('contentAddItemsToMenuItems', () => {
])
})
+ it('hides "New file manager" when the project has no cwd', () => {
+ const items = contentAddItemsToMenuItems(CONTENT_ADD_ITEMS, handlers(), {
+ hasCwd: false,
+ isSshProject: false
+ })
+ expect(items.some((i) => 'label' in i && i.label === 'New file manager')).toBe(false)
+ })
+
// A cwd-less project is a supported, persisted canvas — the folder-shaped rows must degrade
// EXPLICITLY (the SSH worktree row's rule), not vanish. Hiding them left the user with no row and
// no reason, and the fix ("Set folder…") one menu away with nothing pointing at it.
@@ -147,6 +158,7 @@ describe('contentAddItemsToDockRows', () => {
'browser',
'web',
'sticky',
+ 'files',
'dino',
'trigger',
'open-file',
@@ -158,6 +170,14 @@ describe('contentAddItemsToDockRows', () => {
expect(rows.some((r) => r.kind === 'remote')).toBe(false)
})
+ it('hides "files" when there is no cwd', () => {
+ const rows = contentAddItemsToDockRows(CONTENT_ADD_ITEMS, handlers(), {
+ hasCwd: false,
+ isSshProject: false
+ })
+ expect(rows.some((r) => r.kind === 'files')).toBe(false)
+ })
+
it('DISABLES "new-file" with its reason when there is no cwd — the Dock keeps the row too', () => {
const rows = contentAddItemsToDockRows(CONTENT_ADD_ITEMS, handlers(), {
hasCwd: false,
diff --git a/src/renderer/lib/addMenuSpec.tsx b/src/renderer/lib/addMenuSpec.tsx
index 0e5cf832f..ccc6fca07 100644
--- a/src/renderer/lib/addMenuSpec.tsx
+++ b/src/renderer/lib/addMenuSpec.tsx
@@ -24,6 +24,7 @@ import {
IconBranch,
IconDino,
IconEditor,
+ IconExplorer,
IconGroup,
IconNote,
IconRemote,
@@ -46,6 +47,7 @@ export type AddItem =
| { kind: 'browser' }
| { kind: 'web' }
| { kind: 'sticky' }
+ | { kind: 'files' } // requiresCwd
| { kind: 'dino' }
| { kind: 'trigger' }
| { kind: 'open-file' }
@@ -66,6 +68,7 @@ export const CONTENT_ADD_ITEMS: readonly AddItem[] = [
{ kind: 'browser' },
{ kind: 'web' },
{ kind: 'sticky' },
+ { kind: 'files' },
{ kind: 'dino' },
{ kind: 'trigger' },
{ kind: 'open-file' },
@@ -96,6 +99,7 @@ export interface AddHandlers {
browser: (at?: AddPos) => void
web: (at?: AddPos) => void
sticky: (at?: AddPos) => void
+ files: (at?: AddPos) => void
dino: (at?: AddPos) => void
/** Adds a trigger node (issue #493) — a canvas-owned schedule that fires into another node. */
trigger: (at?: AddPos) => void
@@ -159,6 +163,13 @@ export function contentAddItemsToMenuItems(
case 'sticky':
out.push({ label: 'New sticky note', icon: <IconNote />, onClick: () => handlers.sticky(at) })
break
+ case 'files':
+ // Needs a directory to root itself in — hidden on a cwd-less canvas for the same reason
+ // "New file…" is: an affordance that can only report "there is no folder" is not one.
+ if (ctx.hasCwd) {
+ out.push({ label: 'New file manager', icon: <IconExplorer />, onClick: () => handlers.files(at) })
+ }
+ break
case 'dino':
out.push({ label: 'New dino game', icon: <IconDino />, onClick: () => handlers.dino(at) })
break
@@ -246,6 +257,11 @@ export function contentAddItemsToDockRows(
case 'sticky':
out.push({ kind: 'sticky', label: 'Sticky Note', icon: <IconNote />, onClick: () => handlers.sticky() })
break
+ case 'files':
+ if (ctx.hasCwd) {
+ out.push({ kind: 'files', label: 'File Manager', icon: <IconExplorer />, onClick: () => handlers.files() })
+ }
+ break
case 'dino':
out.push({ kind: 'dino', label: 'Dino Game', icon: <IconDino />, onClick: () => handlers.dino() })
break
diff --git a/src/renderer/lib/filesNode.test.ts b/src/renderer/lib/filesNode.test.ts
new file mode 100644
index 000000000..1826bcce7
--- /dev/null
+++ b/src/renderer/lib/filesNode.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+import { breadcrumbs, childPath, fileOpenTarget, filterEntries, folderTitle, parentDir } from './filesNode'
+
+describe('breadcrumbs', () => {
+ it('walks a shallow path in full', () => {
+ expect(breadcrumbs('/a/b')).toEqual([
+ { name: '/', path: '/' },
+ { name: 'a', path: '/a' },
+ { name: 'b', path: '/a/b' }
+ ])
+ })
+
+ it('is just root at the root', () => {
+ expect(breadcrumbs('/')).toEqual([{ name: '/', path: '/' }])
+ })
+
+ it('collapses a deep path but keeps every crumb navigable', () => {
+ const crumbs = breadcrumbs('/one/two/three/four/five/six', 3)
+ expect(crumbs.map((c) => c.name)).toEqual(['/', '…', 'four', 'five', 'six'])
+ // The ellipsis is not decoration: it goes to the deepest directory it hid, so a user can
+ // climb back out one level at a time instead of being teleported to root.
+ expect(crumbs[1].path).toBe('/one/two/three')
+ expect(crumbs[crumbs.length - 1].path).toBe('/one/two/three/four/five/six')
+ })
+
+ it('does not collapse a path that exactly fits', () => {
+ expect(breadcrumbs('/a/b/c', 3).map((c) => c.name)).toEqual(['/', 'a', 'b', 'c'])
+ })
+})
+
+describe('folderTitle', () => {
+ it('names the directory', () => expect(folderTitle('/home/me/repo')).toBe('repo'))
+ it('names the root', () => expect(folderTitle('/')).toBe('/'))
+ it('ignores a trailing slash', () => expect(folderTitle('/home/me/repo/')).toBe('repo'))
+})
+
+describe('childPath', () => {
+ it('joins normally', () => expect(childPath('/a/b', 'c.ts')).toBe('/a/b/c.ts'))
+ it('does not double the separator at the root', () => expect(childPath('/', 'etc')).toBe('/etc'))
+ it('absorbs a trailing slash', () => expect(childPath('/a/', 'b')).toBe('/a/b'))
+})
+
+describe('parentDir', () => {
+ it('climbs one level', () => expect(parentDir('/a/b/c')).toBe('/a/b'))
+ it('stops at the root', () => expect(parentDir('/a')).toBe('/'))
+ it('stays at the root', () => expect(parentDir('/')).toBe('/'))
+})
+
+describe('filterEntries', () => {
+ const entries = [{ name: 'README.md' }, { name: 'src' }, { name: 'package.json' }]
+
+ it('matches case-insensitively anywhere in the name', () => {
+ expect(filterEntries(entries, 'age').map((e) => e.name)).toEqual(['package.json'])
+ expect(filterEntries(entries, 'readme').map((e) => e.name)).toEqual(['README.md'])
+ })
+
+ // The bug this pins: select-all + delete leaves '' (or a stray space), and a filter that treats
+ // that as "match nothing" blanks the whole listing with no way to tell why.
+ it('matches everything for an empty or whitespace query', () => {
+ expect(filterEntries(entries, '')).toEqual(entries)
+ expect(filterEntries(entries, ' ')).toEqual(entries)
+ })
+
+ it('can legitimately match nothing', () => {
+ expect(filterEntries(entries, 'zzz')).toEqual([])
+ })
+})
+
+describe('fileOpenTarget', () => {
+ it('opens text and images on the canvas', () => {
+ expect(fileOpenTarget('/a/notes.md')).toBe('canvas')
+ expect(fileOpenTarget('/a/logo.png')).toBe('canvas')
+ expect(fileOpenTarget('/a/Makefile')).toBe('canvas')
+ })
+
+ it('opens video on the canvas (the video node, not Monaco)', () => {
+ expect(fileOpenTarget('/a/clip.mp4')).toBe('canvas')
+ expect(fileOpenTarget('/a/clip.mov')).toBe('canvas')
+ })
+
+ it('hands binaries and archives to the OS', () => {
+ expect(fileOpenTarget('/a/installer.dmg')).toBe('os')
+ expect(fileOpenTarget('/a/bundle.zip')).toBe('os')
+ expect(fileOpenTarget('/a/data.sqlite')).toBe('os')
+ })
+
+ // shell.openPath opens a path on THIS machine. For a remote listing that is either a silent
+ // no-op or, if the path happens to exist locally too, an unrelated local file.
+ it('never hands a remote path to the OS', () => {
+ expect(fileOpenTarget('/a/installer.dmg', { remote: true })).toBe('canvas')
+ expect(fileOpenTarget('/a/bundle.zip', { remote: true })).toBe('canvas')
+ expect(fileOpenTarget('/a/notes.md', { remote: true })).toBe('canvas')
+ })
+})
diff --git a/src/renderer/lib/filesNode.ts b/src/renderer/lib/filesNode.ts
new file mode 100644
index 000000000..5eeb9a907
--- /dev/null
+++ b/src/renderer/lib/filesNode.ts
@@ -0,0 +1,82 @@
+/**
+ * The decisions a file-manager node makes, kept pure so they can be pressed in a test rather than
+ * clicked in the app: which directory "up" is, what the breadcrumb shows, what a filter matches,
+ * and what happens when you open a thing.
+ *
+ * Paths are `/`-separated absolutes throughout, remote ones included — the node talks to an
+ * `FsApi`, which is the same shape for the local filesystem, an SSH project's host over the
+ * ControlMaster, and a relay peer's core.
+ */
+import { isVideoFile } from '../state/workspace'
+import { opensInEditor } from './openTarget'
+
+export { parentDir } from './explorerCreate'
+
+/** One breadcrumb: what to show, and where clicking it goes. */
+export interface Crumb {
+ name: string
+ path: string
+}
+
+/**
+ * A node header is a few hundred pixels wide and a real project path is not. `max` is the number
+ * of TRAILING segments kept; anything deeper is collapsed into a single leading crumb that still
+ * navigates (to the last dropped directory), because a breadcrumb you cannot click is just text.
+ * Root is always reachable as the first crumb for the same reason.
+ */
+export function breadcrumbs(path: string, max = 3): Crumb[] {
+ const segs = path.split('/').filter(Boolean)
+ const all: Crumb[] = [{ name: '/', path: '/' }]
+ let acc = ''
+ for (const s of segs) {
+ acc += `/${s}`
+ all.push({ name: s, path: acc })
+ }
+ if (all.length <= max + 1) return all
+ // Keep root, then an ellipsis crumb that navigates to the deepest hidden directory, then the
+ // tail. `max + 1` accounts for root, which is never dropped.
+ const hidden = all.slice(1, all.length - max)
+ const ellipsis: Crumb = { name: '…', path: hidden[hidden.length - 1].path }
+ return [all[0], ellipsis, ...all.slice(all.length - max)]
+}
+
+/** The node's title: the directory's own name, or '/' at the root. */
+export function folderTitle(path: string): string {
+ return path.split('/').filter(Boolean).pop() ?? '/'
+}
+
+/** Join a directory and an entry name. Trailing slashes on the dir are absorbed, so the root
+ * ('/') does not produce a doubled separator. */
+export function childPath(dir: string, name: string): string {
+ return `${dir.replace(/\/+$/, '')}/${name}`
+}
+
+/**
+ * Filter listed entries by a substring, case-insensitively. An empty or whitespace-only query
+ * matches everything — a filter box that silently hides the whole listing when the user selects
+ * and deletes their text is the bug this guards.
+ */
+export function filterEntries<T extends { name: string }>(entries: T[], query: string): T[] {
+ const q = query.trim().toLowerCase()
+ if (!q) return entries
+ return entries.filter((e) => e.name.toLowerCase().includes(q))
+}
+
+/**
+ * What opening a FILE should do.
+ *
+ * `canvas` — open it as a node on the canvas (an editor for text and images, a video player for
+ * media). This is what the canvas `nodeterm:open-file` listener already does.
+ * `os` — hand it to the operating system's default application, for the things Monaco can
+ * only render as garbage: archives, installers, databases, binaries.
+ *
+ * `remote` (an SSH project, or a relay tab) forces `canvas`, and that is not a limitation dressed
+ * up as a choice: `shell.openPath` opens a path on THIS machine, so handing it a path that exists
+ * on another one either fails silently or — worse, if the path happens to exist here too — opens
+ * a completely unrelated local file. The same rule Canvas's own `openProjectFile` follows.
+ */
+export function fileOpenTarget(path: string, opts: { remote?: boolean } = {}): 'canvas' | 'os' {
+ if (opts.remote) return 'canvas'
+ if (isVideoFile(path)) return 'canvas'
+ return opensInEditor(path) ? 'canvas' : 'os'
+}
diff --git a/src/renderer/lib/nodeSizing.ts b/src/renderer/lib/nodeSizing.ts
index 274bbac69..cd7db2662 100644
--- a/src/renderer/lib/nodeSizing.ts
+++ b/src/renderer/lib/nodeSizing.ts
@@ -19,6 +19,7 @@ export const NODE_MIN_SIZES: Record<NodeKind, { width: number; height: number }>
video: { width: 320, height: 200 },
web: { width: 320, height: 200 },
browser: { width: 360, height: 240 },
+ files: { width: 220, height: 160 },
subagent: { width: 180, height: 84 },
loop: { width: 180, height: 84 },
dino: { width: 400, height: 160 },
diff --git a/src/renderer/nodes/FilesNode.tsx b/src/renderer/nodes/FilesNode.tsx
new file mode 100644
index 000000000..bcff07352
--- /dev/null
+++ b/src/renderer/nodes/FilesNode.tsx
@@ -0,0 +1,386 @@
+/**
+ * A file-manager node: one directory listing, on the canvas, beside the terminals that work in it.
+ *
+ * This is NOT a second Explorer. The Explorer drawer is a single tree rooted at the active
+ * project's cwd, and it is modal in practice — it covers the canvas and you close it to get back
+ * to work. A file manager node is a persisted canvas object pinned to ONE directory, so you can
+ * keep `src/renderer/nodes` open next to the agent working in it and a second one on `docs/`,
+ * where a tree gives you one cursor and a lot of scrolling.
+ *
+ * **Which filesystem** is the same decision `EditorNode` makes, read the same way: an SSH project's
+ * node (`data.sshFs`) lists the project's HOST over the ControlMaster; everything else lists
+ * through the node's own session api — which is the local core for a local project and the PEER's
+ * core for a relay tab, so a relay tab browses the machine its terminals are actually on. Getting
+ * this from `useSession()` rather than `window.nodeTerminal` is the whole reason a relay tab works
+ * here for free.
+ *
+ * **Opening is delegated, not reimplemented.** A file dispatches `nodeterm:open-file` — the event
+ * `TerminalNode`'s Cmd+click links already use — so editor / image / video routing stays in
+ * Canvas's one `openFile`, and this node never grows a second opinion about what a `.png` is.
+ * Directories navigate in place (persisted, so a reload comes back where you were).
+ */
+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 { breadcrumbs, childPath, fileOpenTarget, filterEntries, folderTitle, parentDir } from '../lib/filesNode'
+import { ancestorDirs, createTargetDir, newEntryPath } from '../lib/explorerCreate'
+import { sshFs } from '../terminal/ssh-fs'
+import { useSession } from '../session/session'
+import { useProjects } from '../state/projects'
+import { promptDialog } from '../components/promptDialog'
+import { ContextMenu, type MenuItem } from '../components/ContextMenu'
+import { isBrowserRuntime } from '../bridge/runtime'
+
+/** Surface a transient error the way every other node does (Canvas listens for this). */
+const toast = (message: string): void => {
+ window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
+}
+
+function EntryGlyph({ dir }: { dir: boolean }) {
+ return dir ? (
+ <svg className="files-node__glyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6">
+ <path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+ </svg>
+ ) : (
+ <svg className="files-node__glyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6">
+ <path d="M6 3h8l4 4v14H6z" />
+ <path d="M14 3v4h4" />
+ </svg>
+ )
+}
+
+export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
+ const { updateNodeData, deleteElements, setNodes } = useReactFlow()
+ const [showColors, setShowColors] = useState(false)
+ const [editingTitle, setEditingTitle] = useState(false)
+ const [titleBefore, setTitleBefore] = useState('')
+ const [entries, setEntries] = useState<DirEntry[] | null>(null)
+ const [error, setError] = useState('')
+ const [query, setQuery] = useState('')
+ const [menu, setMenu] = useState<{ x: number; y: number; items: MenuItem[] } | null>(null)
+ /** Bumped to force a re-list after a create; `cwd` alone cannot express "same dir, new content". */
+ const [version, setVersion] = useState(0)
+
+ const collapsed = !!data.collapsed
+ const cwd = (data.cwd as string) || '/'
+ const isSshFs = !!data.sshFs
+ const { api, source } = useSession()
+ const activeProjectId = useProjects((s) => s.activeProjectId)
+ const fs = isSshFs && activeProjectId ? sshFs(activeProjectId) : api.fs
+ /** A listing this machine's OS cannot act on: an SSH host's files, or a relay peer's. */
+ const remote = isSshFs || source === 'relay'
+ /** `shell.*` is Electron-only — in the browser the reveal row would be a button that does
+ * nothing, which teaches less than not offering it. */
+ const canReveal = !remote && !isBrowserRuntime()
+
+ useEffect(() => {
+ let live = true
+ setError('')
+ void fs
+ .list(cwd)
+ .then((list) => {
+ if (live) setEntries(list)
+ })
+ .catch(() => {
+ if (!live) return
+ setEntries([])
+ setError('Could not read this folder.')
+ })
+ return () => {
+ live = false
+ }
+ // `fs` is rebuilt each render (sshFs returns a fresh object), so it is deliberately not a
+ // dependency — the identity that matters is the project + the sshFs flag, both of which
+ // change `cwd`'s meaning and are covered by the deps that are here.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [cwd, isSshFs, activeProjectId, version])
+
+ const navigate = useCallback(
+ (to: string) => {
+ // The title tracks the folder ONLY while the user has not renamed the node by hand — the
+ // same `titleAuto` contract agent nodes use for their session name. Renaming a file manager
+ // "assets" and then having it silently become "images" on the next click would be the node
+ // overwriting the user.
+ const patch: Record<string, unknown> = { cwd: to }
+ if (data.titleAuto !== false) patch.title = folderTitle(to)
+ updateNodeData(id, patch)
+ setQuery('')
+ },
+ [id, updateNodeData, data.titleAuto]
+ )
+
+ const open = useCallback(
+ (entry: DirEntry) => {
+ const path = childPath(cwd, entry.name)
+ if (entry.dir) {
+ navigate(path)
+ return
+ }
+ if (fileOpenTarget(path, { remote }) === 'os') {
+ api.shell.openPath(path)
+ return
+ }
+ // Canvas owns editor-vs-video routing; `ssh` tells its `openFile` to read over the
+ // project's remote fs rather than this machine's.
+ window.dispatchEvent(
+ new CustomEvent('nodeterm:open-file', { detail: { path, ssh: isSshFs } })
+ )
+ },
+ [cwd, navigate, remote, api, isSshFs]
+ )
+
+ /** Create a file or a folder under `dir`, then re-list. Shared by both menu rows because the
+ * only difference is the last call — and the validation, the intermediate dirs and the
+ * already-exists check are exactly the things that must not be written twice. */
+ const create = useCallback(
+ async (dir: string, kind: 'file' | 'folder') => {
+ const name = await promptDialog({
+ message: kind === 'file' ? 'New file name:' : 'New folder name:',
+ confirmLabel: 'Create'
+ })
+ if (name === null) return
+ const target = newEntryPath(dir, name)
+ if (!target) {
+ toast('That name cannot be used.')
+ return
+ }
+ if (await fs.exists(target)) {
+ toast(`${name.trim()} already exists.`)
+ return
+ }
+ // A nested name ("a/b/c.ts") needs its intermediate directories first — mkdir is recursive,
+ // so one call on the deepest one is enough.
+ const parents = ancestorDirs(dir, name)
+ if (parents.length && !(await fs.mkdir(parents[parents.length - 1]))) {
+ toast('Could not create that folder.')
+ return
+ }
+ const ok = kind === 'folder' ? await fs.mkdir(target) : await fs.write(target, '')
+ if (!ok) {
+ toast(kind === 'folder' ? 'Could not create that folder.' : 'Could not create that file.')
+ return
+ }
+ setVersion((v) => v + 1)
+ if (kind === 'file') {
+ window.dispatchEvent(
+ new CustomEvent('nodeterm:open-file', { detail: { path: target, ssh: isSshFs } })
+ )
+ }
+ },
+ [fs, isSshFs]
+ )
+
+ const openMenu = useCallback(
+ (e: React.MouseEvent, entry: DirEntry | null) => {
+ e.preventDefault()
+ e.stopPropagation()
+ const path = entry ? childPath(cwd, entry.name) : cwd
+ const dir = entry ? createTargetDir(path, entry.dir) : cwd
+ const items: MenuItem[] = []
+ if (entry) {
+ items.push({ label: entry.dir ? 'Open folder' : 'Open', onClick: () => open(entry) })
+ }
+ if (!entry || entry.dir) {
+ items.push({
+ label: 'New terminal here',
+ onClick: () =>
+ window.dispatchEvent(
+ new CustomEvent('nodeterm:open-terminal', { detail: { cwd: entry ? path : cwd } })
+ )
+ })
+ }
+ items.push({ type: 'separator' })
+ items.push({ label: 'New file…', onClick: () => void create(dir, 'file') })
+ items.push({ label: 'New folder…', onClick: () => void create(dir, 'folder') })
+ items.push({ type: 'separator' })
+ items.push({
+ label: 'Copy path',
+ onClick: () => api.clipboard.writeText(path)
+ })
+ if (canReveal) {
+ items.push({ label: 'Reveal in file manager', onClick: () => api.shell.reveal(path) })
+ }
+ setMenu({ x: e.clientX, y: e.clientY, items })
+ },
+ [cwd, open, create, api, canReveal]
+ )
+
+ const toggleCollapse = () =>
+ setNodes((ns) =>
+ ns.map((n) => {
+ if (n.id !== id) return n
+ const next = !n.data.collapsed
+ const expandedHeight =
+ (n.data.expandedHeight as number) ?? n.measured?.height ?? (n.height as number) ?? 460
+ const height = next ? COLLAPSED_HEIGHT : expandedHeight
+ return {
+ ...n,
+ height,
+ style: { ...n.style, height },
+ data: { ...n.data, collapsed: next, expandedHeight }
+ }
+ })
+ )
+
+ const shown = useMemo(() => filterEntries(entries ?? [], query), [entries, query])
+ const crumbs = useMemo(() => breadcrumbs(cwd), [cwd])
+
+ return (
+ <div className={`files-node${selected ? ' selected' : ''}${collapsed ? ' collapsed' : ''}`}>
+ <NodeResizer
+ minWidth={NODE_MIN_SIZES.files.width}
+ minHeight={NODE_MIN_SIZES.files.height}
+ isVisible={selected && !collapsed}
+ color={data.color as string}
+ />
+
+ <div className="files-node__header" style={{ background: `${data.color}22` }}>
+ <button className="term-node__collapse" title={collapsed ? 'Expand' : 'Collapse'} onClick={toggleCollapse}>
+ {collapsed ? '▸' : '▾'}
+ </button>
+ <button
+ className="term-node__color"
+ style={{ background: data.color as string }}
+ title="Color"
+ 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>
+ )}
+ {editingTitle ? (
+ <input
+ className="term-node__title nodrag"
+ value={(data.title as string) ?? ''}
+ spellCheck={false}
+ autoFocus
+ // A hand rename stops the title tracking the folder — same contract as an agent
+ // node's session name (`titleAuto`), so navigating never overwrites a chosen name.
+ onChange={(e) => updateNodeData(id, { title: e.target.value, titleAuto: false })}
+ onBlur={() => setEditingTitle(false)}
+ onKeyDown={(e) => {
+ if (e.key === 'Enter') {
+ e.preventDefault()
+ setEditingTitle(false)
+ } else if (e.key === 'Escape') {
+ e.preventDefault()
+ updateNodeData(id, { title: titleBefore })
+ setEditingTitle(false)
+ }
+ }}
+ />
+ ) : (
+ <span
+ className="term-node__title-text nodrag"
+ title="Click to rename"
+ onClick={() => {
+ setTitleBefore((data.title as string) ?? '')
+ setEditingTitle(true)
+ }}
+ >
+ {(data.title as string) || folderTitle(cwd)}
+ </span>
+ )}
+ {isSshFs && <span className="files-node__chip">SSH</span>}
+ {!editingTitle && <span className="term-node__spacer" />}
+ <button
+ className="files-node__btn nodrag"
+ title="Up one folder"
+ disabled={cwd === '/'}
+ onClick={() => navigate(parentDir(cwd))}
+ >
+ ↑
+ </button>
+ <button
+ className="files-node__btn nodrag"
+ title="Refresh"
+ onClick={() => setVersion((v) => v + 1)}
+ >
+ ⟳
+ </button>
+ <button className="term-node__close" title="Close" onClick={() => deleteElements({ nodes: [{ id }] })}>
+ ×
+ </button>
+ </div>
+
+ {!collapsed && (
+ <>
+ <div className="files-node__crumbs nodrag">
+ {crumbs.map((c, i) => (
+ <span key={`${c.path}-${i}`} className="files-node__crumb-wrap">
+ {/* No separator after the ROOT crumb — its own label is already "/", and a
+ separator there renders the doubled "/ / …" this replaced. */}
+ {i > 0 && crumbs[i - 1].name !== '/' && <span className="files-node__sep">/</span>}
+ <button className="files-node__crumb" title={c.path} onClick={() => navigate(c.path)}>
+ {c.name}
+ </button>
+ </span>
+ ))}
+ </div>
+
+ <input
+ className="files-node__filter nodrag"
+ value={query}
+ placeholder="Filter…"
+ spellCheck={false}
+ onChange={(e) => setQuery(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === 'Escape') {
+ e.preventDefault()
+ setQuery('')
+ }
+ }}
+ />
+
+ <div
+ className="files-node__list nodrag nowheel"
+ onContextMenu={(e) => openMenu(e, null)}
+ >
+ {/* Four distinct states, kept distinct. "Still loading", "could not read", "the
+ folder is empty" and "your filter matches nothing" are different facts, and
+ collapsing any of them into a blank pane is exactly the failure this repo's
+ house rules call out. */}
+ {entries === null ? (
+ <div className="files-node__empty">Loading…</div>
+ ) : error ? (
+ <div className="files-node__empty files-node__empty--error">{error}</div>
+ ) : entries.length === 0 ? (
+ <div className="files-node__empty">This folder is empty.</div>
+ ) : shown.length === 0 ? (
+ <div className="files-node__empty">Nothing matches “{query.trim()}”.</div>
+ ) : (
+ shown.map((entry) => (
+ <div
+ key={entry.name}
+ className={`files-node__row${entry.ignored ? ' is-ignored' : ''}`}
+ title={childPath(cwd, entry.name)}
+ onClick={() => open(entry)}
+ onContextMenu={(e) => openMenu(e, entry)}
+ >
+ <EntryGlyph dir={entry.dir} />
+ <span className="files-node__name">{entry.name}</span>
+ </div>
+ ))
+ )}
+ </div>
+ </>
+ )}
+
+ {menu && (
+ <ContextMenu x={menu.x} y={menu.y} items={menu.items} onClose={() => setMenu(null)} />
+ )}
+ </div>
+ )
+}
diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.ts
index c9730519c..b9309457d 100644
--- a/src/renderer/state/workspace.ts
+++ b/src/renderer/state/workspace.ts
@@ -59,6 +59,9 @@ const TRIGGER_SIZE = { width: 300, height: 170 }
const VIDEO_SIZE = { width: 640, height: 420 }
const WEB_SIZE = { width: 720, height: 520 }
const BROWSER_SIZE = { width: 800, height: 560 }
+// Tall and narrow: a file manager is a LIST, and the thing that runs out first is vertical room
+// for entries, not horizontal room for names (which ellipsize).
+const FILES_SIZE = { width: 340, height: 460 }
/** Height of a node when collapsed (header only). */
export const COLLAPSED_HEIGHT = 40
@@ -1017,6 +1020,37 @@ export function createBrowserNode(
}
}
+/**
+ * Creates a file-manager node browsing `cwd`.
+ *
+ * `sshFs` is stamped for an SSH project so the node lists the PROJECT'S HOST over the
+ * ControlMaster instead of this machine — the same flag, read the same way, that `createEditorNode`
+ * and `createVideoNode` already use. Without it an SSH project's file manager would quietly browse
+ * the local filesystem at a path that means something else there.
+ */
+export function createFilesNode(
+ index: number,
+ cwd: string,
+ center?: { x: number; y: number },
+ sshFs?: boolean
+): CanvasNode {
+ return {
+ id: nextId('files'),
+ type: 'files',
+ position: placeAt(center, index, FILES_SIZE.width, FILES_SIZE.height),
+ width: FILES_SIZE.width,
+ height: FILES_SIZE.height,
+ style: { width: FILES_SIZE.width, height: FILES_SIZE.height },
+ data: {
+ title: cwd.split('/').filter(Boolean).pop() || '/',
+ color: '#ffd60a',
+ group: null,
+ cwd,
+ ...(sshFs ? { sshFs: true } : {})
+ }
+ }
+}
+
/** Creates a diff editor node for a changed file (relative path + repo cwd). */
export function createDiffNode(
index: number,
@@ -1938,7 +1972,9 @@ export function flowToNodeStates(nodes: CanvasNode[]): CanvasNodeState[] {
? DINO_SIZE
: kind === 'trigger'
? TRIGGER_SIZE
- : TERMINAL_SIZE
+ : kind === 'files'
+ ? FILES_SIZE
+ : TERMINAL_SIZE
return nodes
.map((n) => {
const kind: NodeKind = (n.type as NodeKind) ?? 'terminal'
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 03ee692ba..d692dc680 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -11969,3 +11969,171 @@ body.focus-mode .dock:hover {
font-size: 12px;
color: var(--danger);
}
+
+/* ── File manager node ─────────────────────────────────────────────────────────────────────
+ A directory listing pinned to the canvas. Shaped like the sticky note (card + grab header)
+ rather than the terminal, because it is content you arrange, not a session you attach to. */
+.files-node {
+ width: 100%;
+ height: 100%;
+ display: flex;
+ flex-direction: column;
+ background: rgba(var(--card-rgb), 0.96);
+ border: 1px solid var(--border);
+ border-radius: 10px;
+ overflow: hidden;
+ box-shadow: 0 8px 28px rgba(0, 0, 0, calc(0.35 * var(--shadow-k)));
+}
+
+.files-node.selected {
+ box-shadow: 0 0 0 1px var(--accent), 0 8px 28px rgba(0, 0, 0, calc(0.4 * var(--shadow-k)));
+}
+
+.files-node__header {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 5px 8px;
+ cursor: grab;
+ flex-shrink: 0;
+}
+
+.files-node__chip {
+ font-size: 10px;
+ letter-spacing: 0.4px;
+ padding: 1px 5px;
+ border-radius: 4px;
+ background: rgba(var(--tint-rgb), 0.12);
+ color: var(--muted);
+ flex-shrink: 0;
+}
+
+.files-node__btn {
+ background: none;
+ border: none;
+ color: var(--muted);
+ cursor: pointer;
+ font-size: 13px;
+ line-height: 1;
+ padding: 2px 4px;
+ border-radius: 4px;
+ flex-shrink: 0;
+}
+.files-node__btn:hover:not(:disabled) {
+ background: rgba(var(--tint-rgb), 0.1);
+ color: var(--text);
+}
+.files-node__btn:disabled {
+ opacity: 0.3;
+ cursor: default;
+}
+
+/* The breadcrumb is one line and never wraps: a two-line path would push the listing down on
+ every navigation, and the listing is the thing the node exists to show. Deep paths are
+ collapsed upstream (see `breadcrumbs`), so this only has to refuse to grow. */
+.files-node__crumbs {
+ display: flex;
+ align-items: center;
+ flex-wrap: nowrap;
+ overflow: hidden;
+ padding: 0 8px 4px;
+ font-size: 11px;
+ color: var(--muted);
+ flex-shrink: 0;
+}
+
+.files-node__crumb-wrap {
+ display: inline-flex;
+ align-items: center;
+ min-width: 0;
+}
+
+.files-node__sep {
+ opacity: 0.4;
+ margin: 0 2px;
+}
+
+.files-node__crumb {
+ background: none;
+ border: none;
+ padding: 1px 2px;
+ color: inherit;
+ font-size: 11px;
+ cursor: pointer;
+ border-radius: 3px;
+ max-width: 120px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.files-node__crumb:hover {
+ color: var(--text);
+ background: rgba(var(--tint-rgb), 0.1);
+}
+
+.files-node__filter {
+ margin: 0 8px 6px;
+ padding: 3px 7px;
+ background: rgba(var(--tint-rgb), 0.06);
+ border: 1px solid var(--border);
+ border-radius: 6px;
+ color: var(--text);
+ font-size: 12px;
+ outline: none;
+ flex-shrink: 0;
+}
+.files-node__filter:focus {
+ border-color: var(--accent);
+}
+
+.files-node__list {
+ flex: 1;
+ overflow-y: auto;
+ padding: 0 4px 6px;
+ min-height: 0;
+}
+
+.files-node__row {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ padding: 3px 6px;
+ border-radius: 5px;
+ cursor: pointer;
+ font-size: 12px;
+ color: var(--text);
+}
+.files-node__row:hover {
+ background: rgba(var(--tint-rgb), 0.08);
+}
+/* Dimmed exactly like the Explorer drawer dims them — same fact (`DirEntry.ignored`), so it must
+ read the same way in both places. */
+.files-node__row.is-ignored {
+ opacity: 0.45;
+}
+
+.files-node__glyph {
+ width: 14px;
+ height: 14px;
+ flex-shrink: 0;
+ color: var(--muted);
+}
+
+.files-node__name {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.files-node__empty {
+ padding: 10px 8px;
+ font-size: 12px;
+ color: var(--muted);
+}
+.files-node__empty--error {
+ color: var(--danger);
+}
+
+.files-node.collapsed .files-node__header {
+ border-bottom: none;
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 5e956163c..ece2dfa3f 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -272,7 +272,7 @@ export interface RecycledInfo {
// 'subagent' and 'loop' are render-only (ephemeral hook-driven viz) and never persisted.
// 'trigger' is a first-class PERSISTED kind (issue #493) — the canvas-owned schedule node; its
// spec rides `CanvasNodeState.trigger` and is sanitized on every load path (@shared/trigger).
-export type NodeKind = 'terminal' | 'sticky' | 'group' | 'editor' | 'diff' | 'video' | 'web' | 'browser' | 'subagent' | 'loop' | 'dino' | 'trigger'
+export type NodeKind = 'terminal' | 'sticky' | 'group' | 'editor' | 'diff' | 'video' | 'web' | 'browser' | 'files' | 'subagent' | 'loop' | 'dino' | 'trigger'
/** Persisted state of a single canvas node (terminal, sticky note, group frame, or editor). */
/**
diff --git a/src/shared/worktree.test.ts b/src/shared/worktree.test.ts
index 04ed2e74e..05fec8db7 100644
--- a/src/shared/worktree.test.ts
+++ b/src/shared/worktree.test.ts
@@ -342,12 +342,18 @@ describe('displacedByWorktree', () => {
// Shares the prefix but is a sibling directory, not really inside the worktree.
{ id: 'editor-prefix', type: 'editor', data: { filePath: '/wt/feature/index.ts' } },
{ id: 'diff-in', type: 'diff', data: { cwd: wt, filePath: 'src/index.ts' } },
- { id: 'diff-out', type: 'diff', data: { cwd: '/repo', filePath: 'src/index.ts' } }
+ { id: 'diff-out', type: 'diff', data: { cwd: '/repo', filePath: 'src/index.ts' } },
+ // File-manager nodes: displaced by PATH wherever they sit (they have no session to disturb),
+ // so one outside the group counts where a terminal outside it does not.
+ { id: 'files-in', type: 'files', parentId: 'g', data: { cwd: `${wt}/src` } },
+ { id: 'files-outside-group', type: 'files', data: { cwd: wt } },
+ { id: 'files-out', type: 'files', data: { cwd: '/repo' } },
+ { id: 'files-prefix', type: 'files', data: { cwd: '/wt/feature' } }
]
it('collects every descendant terminal living in the worktree, nested ones included', () => {
expect([...displacedByWorktree(nodes, 'g', wt)].sort()).toEqual(
- ['diff-in', 'editor-in', 'nested', 'term'].sort()
+ ['diff-in', 'editor-in', 'files-in', 'files-outside-group', 'nested', 'term'].sort()
)
})
@@ -363,12 +369,25 @@ describe('displacedByWorktree', () => {
'inner',
'editor-out',
'editor-prefix',
- 'diff-out'
+ 'diff-out',
+ 'files-out',
+ 'files-prefix'
]) {
expect(got.has(id)).toBe(false)
}
})
+ // A file manager left pointing into a removed worktree shows "Could not read this folder"
+ // forever AND keeps the dead path in project.json — the same persisted-dead-path failure the
+ // terminal branch exists to prevent. It has no session, so unlike a terminal it is displaced
+ // wherever it sits, and it gets its cwd re-pointed rather than an editor's `fileMissing`.
+ it('collects a file-manager node by path, in the group or not', () => {
+ const got = displacedByWorktree(nodes, 'g', wt)
+ expect(got.has('files-in')).toBe(true)
+ expect(got.has('files-outside-group')).toBe(true)
+ expect(nodes.find((n) => n.id === 'files-outside-group')?.parentId).toBeUndefined()
+ })
+
it('collects an editor/diff node by path even though it has no parentId at all', () => {
// Same as 'editor-in'/'diff-in' above, spelled out: neither carries a parentId, and neither
// is a descendant of 'g' by any group-membership test — only the path says they're displaced.
diff --git a/src/shared/worktree.ts b/src/shared/worktree.ts
index b1e3b0799..55d8d2b2d 100644
--- a/src/shared/worktree.ts
+++ b/src/shared/worktree.ts
@@ -448,7 +448,9 @@ interface WorktreeNodeLike {
/**
* The nodes a worktree teardown DISPLACES: every descendant of the bound group that carries a
* working directory (a terminal or a chat) inside the worktree path, PLUS any editor/diff node
- * anywhere on the canvas whose file lives inside it.
+ * anywhere on the canvas whose file lives inside it, PLUS any file-manager node anywhere whose
+ * directory is inside it (see the `files` branch for why its rule is the editor one, not the
+ * terminal one).
*
* BOTH teardown paths derive from this — Remove (which also ends their sessions and respawns them)
* and a stale group's Unbind (which touches no process at all). Unbind is the documented recovery
@@ -484,6 +486,20 @@ export function displacedByWorktree(
if (!under.has(n.id)) continue
const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined
if (isInsideDir(cwd, worktreePath)) out.add(n.id)
+ } else if (n.type === 'files') {
+ // Checked ANYWHERE on the canvas, like editor/diff and unlike terminal — the `under`
+ // restriction on terminals is there because displacing one RESPAWNS it, and a session the
+ // user rooted here by hand should not be restarted from under them. A file manager has no
+ // session: the directory it is showing is simply gone, wherever the node happens to sit, and
+ // resetting its cwd costs the user nothing. Left alone it would show "Could not read this
+ // folder" forever AND keep the dead path in project.json, which is the same persisted-dead-
+ // path failure the terminal branch above exists to prevent.
+ //
+ // It gets `cwd` reset rather than `fileMissing`: a directory CAN be re-pointed at the
+ // fallback, which is exactly why editor/diff get the flag instead — there is nothing
+ // sensible to re-point a dead FILE at.
+ const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined
+ if (isInsideDir(cwd, worktreePath)) out.add(n.id)
} else if (n.type === 'editor' || n.type === 'diff') {
const filePath = typeof n.data?.filePath === 'string' ? n.data.filePath : undefined
const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined