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 — click selects, double-click opens, type-ahead

reviewbccc02ec05ec
diff --git a/src/renderer/lib/filesNode.test.ts b/src/renderer/lib/filesNode.test.ts
index afbe8dcc7..4092790ba 100644
--- a/src/renderer/lib/filesNode.test.ts
+++ b/src/renderer/lib/filesNode.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from 'vitest'
import {
breadcrumbs,
+ childOnPath,
childPath,
classifyEmptyListing,
displacedFilesPatch,
@@ -8,7 +9,12 @@ import {
fileOpenTarget,
filterEntries,
folderTitle,
- parentDir
+ listKeyAction,
+ parentDir,
+ scrollTopToReveal,
+ TYPEAHEAD_RESET_MS,
+ typeAhead,
+ typeAheadIndex
} from './filesNode'
describe('breadcrumbs', () => {
@@ -231,3 +237,119 @@ describe('downloadMenuEntries', () => {
expect(labels('http', '/srv/app/src', { dir: true, here: true })).toEqual(['Download this folder (.tar.gz)'])
})
})
+
+describe('typeAheadIndex', () => {
+ const names = ['alpha', 'Apple', 'beta', 'banana', 'build', 'çiçek']
+
+ it('jumps to the first entry starting with a letter, case-insensitively', () => {
+ expect(typeAheadIndex(names, -1, 'b')).toBe(2)
+ expect(typeAheadIndex(names, -1, 'A')).toBe(0)
+ })
+
+ it('cycles through the entries sharing a letter when the letter is pressed again (Windows)', () => {
+ expect(typeAheadIndex(names, 2, 'b')).toBe(3)
+ expect(typeAheadIndex(names, 3, 'b')).toBe(4)
+ expect(typeAheadIndex(names, 4, 'b')).toBe(2) // wraps
+ // A fast "bb" is still cycling, not a search for a name starting with "bb".
+ expect(typeAheadIndex(names, 2, 'bb')).toBe(3)
+ })
+
+ it('treats a typed word as a prefix and keeps the current entry while it still matches', () => {
+ expect(typeAheadIndex(names, -1, 'ba')).toBe(3)
+ expect(typeAheadIndex(names, 3, 'ban')).toBe(3)
+ expect(typeAheadIndex(names, 2, 'bu')).toBe(4)
+ })
+
+ it('matches non-ASCII names', () => {
+ expect(typeAheadIndex(names, -1, 'ç')).toBe(5)
+ })
+
+ it('reports no match rather than moving somewhere arbitrary', () => {
+ expect(typeAheadIndex(names, 1, 'z')).toBe(-1)
+ expect(typeAheadIndex([], -1, 'a')).toBe(-1)
+ expect(typeAheadIndex(names, 0, '')).toBe(-1)
+ })
+})
+
+describe('typeAhead', () => {
+ const names = ['alpha', 'beta', 'bravo']
+
+ it('builds a word from keys typed in quick succession', () => {
+ const a = typeAhead({ buffer: '', at: 0 }, 'b', 1000, names, -1)
+ expect(a.index).toBe(1)
+ const b = typeAhead(a.state, 'r', 1200, names, a.index)
+ expect(b.state.buffer).toBe('br')
+ expect(b.index).toBe(2)
+ })
+
+ it('starts a fresh word after a pause', () => {
+ const a = typeAhead({ buffer: 'br', at: 1000 }, 'a', 1000 + TYPEAHEAD_RESET_MS + 1, names, 2)
+ expect(a.state.buffer).toBe('a')
+ expect(a.index).toBe(0)
+ })
+})
+
+describe('listKeyAction', () => {
+ const k = (key: string, mods: { alt?: boolean; meta?: boolean; ctrl?: boolean } = {}) => ({ key, ...mods })
+
+ it('moves the selection with the arrows, clamped at both ends', () => {
+ expect(listKeyAction(k('ArrowDown'), 1, 5)).toEqual({ kind: 'select', index: 2 })
+ expect(listKeyAction(k('ArrowDown'), 4, 5)).toEqual({ kind: 'select', index: 4 })
+ expect(listKeyAction(k('ArrowUp'), 1, 5)).toEqual({ kind: 'select', index: 0 })
+ expect(listKeyAction(k('ArrowUp'), 0, 5)).toEqual({ kind: 'select', index: 0 })
+ })
+
+ it('enters the list from nothing selected at the natural end', () => {
+ expect(listKeyAction(k('ArrowDown'), -1, 5)).toEqual({ kind: 'select', index: 0 })
+ expect(listKeyAction(k('ArrowUp'), -1, 5)).toEqual({ kind: 'select', index: 4 })
+ expect(listKeyAction(k('Home'), 3, 5)).toEqual({ kind: 'select', index: 0 })
+ expect(listKeyAction(k('End'), 0, 5)).toEqual({ kind: 'select', index: 4 })
+ })
+
+ it('opens the selection with Enter (and ⌘↓, the Finder chord) — never with nothing selected', () => {
+ expect(listKeyAction(k('Enter'), 2, 5)).toEqual({ kind: 'open', index: 2 })
+ expect(listKeyAction(k('ArrowDown', { meta: true }), 2, 5)).toEqual({ kind: 'open', index: 2 })
+ expect(listKeyAction(k('Enter'), -1, 5)).toBeNull()
+ })
+
+ it('goes up a folder with Backspace, Alt+↑ (Windows) and ⌘↑ (Finder), even in an empty folder', () => {
+ expect(listKeyAction(k('Backspace'), -1, 0)).toEqual({ kind: 'up' })
+ expect(listKeyAction(k('ArrowUp', { alt: true }), 2, 5)).toEqual({ kind: 'up' })
+ expect(listKeyAction(k('ArrowUp', { meta: true }), 2, 5)).toEqual({ kind: 'up' })
+ })
+
+ it('has nothing to select in an empty listing, and leaves other chords alone', () => {
+ expect(listKeyAction(k('ArrowDown'), -1, 0)).toBeNull()
+ expect(listKeyAction(k('a', { ctrl: true }), 0, 5)).toBeNull()
+ expect(listKeyAction(k('Escape'), 0, 5)).toBeNull()
+ })
+})
+
+describe('childOnPath', () => {
+ it('names the entry of an ancestor that leads back to where we were', () => {
+ expect(childOnPath('/a', '/a/b/c')).toBe('b')
+ expect(childOnPath('/', '/a/b')).toBe('a')
+ expect(childOnPath('/a/', '/a/b/')).toBe('b')
+ expect(childOnPath('~', '~/proj')).toBe('proj')
+ })
+
+ it('is null when the destination is not a strict ancestor', () => {
+ expect(childOnPath('/a/b', '/a')).toBeNull()
+ expect(childOnPath('/a', '/a')).toBeNull()
+ expect(childOnPath('/ab', '/a/b')).toBeNull()
+ expect(childOnPath('/x', '/a/b')).toBeNull()
+ expect(childOnPath('a', '/a/b')).toBeNull()
+ })
+})
+
+describe('scrollTopToReveal', () => {
+ it('leaves a fully visible row where it is', () => {
+ expect(scrollTopToReveal(100, 20, 50, 200)).toBe(50)
+ })
+ it('scrolls up just enough for a row above the view', () => {
+ expect(scrollTopToReveal(30, 20, 50, 200)).toBe(30)
+ })
+ it('scrolls down just enough for a row below the view', () => {
+ expect(scrollTopToReveal(260, 20, 50, 200)).toBe(80)
+ })
+})
diff --git a/src/renderer/lib/filesNode.ts b/src/renderer/lib/filesNode.ts
index 462f9948e..b91184c6e 100644
--- a/src/renderer/lib/filesNode.ts
+++ b/src/renderer/lib/filesNode.ts
@@ -225,3 +225,113 @@ export function downloadMenuEntries(
if (route === 'scp') entries.push({ label: 'Download to…', pickFolder: true })
return entries
}
+
+/**
+ * How long a pause ends a type-ahead word. Typing "bu" within this window searches for "bu…";
+ * after it, the next key starts over.
+ */
+export const TYPEAHEAD_RESET_MS = 1000
+
+/**
+ * Windows-Explorer type-ahead: the index of the entry `buffer` selects, or -1 for no match.
+ *
+ * - One letter — or the same letter repeated ("b", "bb") — CYCLES: the next entry after
+ * `current` starting with it, wrapping. That is how pressing B three times walks the B's.
+ * - A word ("bui") is a prefix search from `current` INCLUSIVE, so extending a word that still
+ * matches the selected entry keeps it rather than jumping past it.
+ *
+ * Case-insensitive; `current` is -1 when nothing is selected.
+ */
+export function typeAheadIndex(names: readonly string[], current: number, buffer: string): number {
+ if (!buffer || names.length === 0) return -1
+ const q = buffer.toLowerCase()
+ const cycling = [...q].every((c) => c === q[0])
+ const needle = cycling ? q[0] : q
+ const start = cycling ? current + 1 : Math.max(current, 0)
+ for (let i = 0; i < names.length; i++) {
+ const idx = (start + i) % names.length
+ if (names[idx].toLowerCase().startsWith(needle)) return idx
+ }
+ return -1
+}
+
+export interface TypeAheadState {
+ buffer: string
+ /** When the last key was typed (ms). */
+ at: number
+}
+
+/** Fold one typed key into the type-ahead word and resolve what it selects. */
+export function typeAhead(
+ state: TypeAheadState,
+ key: string,
+ now: number,
+ names: readonly string[],
+ current: number
+): { state: TypeAheadState; index: number } {
+ const buffer = (now - state.at > TYPEAHEAD_RESET_MS ? '' : state.buffer) + key
+ return { state: { buffer, at: now }, index: typeAheadIndex(names, current, buffer) }
+}
+
+export type ListKeyAction = { kind: 'select'; index: number } | { kind: 'open'; index: number } | { kind: 'up' } | null
+
+/**
+ * What a navigation key does in a files node's listing. `current` is the selected index (-1 for
+ * none) and `count` the number of entries shown. Windows and Finder chords both work, because a
+ * user reaches for whichever their hands know: Enter / ⌘↓ open, Backspace / Alt+↑ / ⌘↑ go up.
+ * `null` = not a listing key; the caller lets it through.
+ */
+export function listKeyAction(
+ e: { key: string; alt?: boolean; meta?: boolean; ctrl?: boolean },
+ current: number,
+ count: number
+): ListKeyAction {
+ if (e.ctrl) return null
+ if (e.key === 'ArrowUp' && (e.alt || e.meta)) return { kind: 'up' }
+ if (e.key === 'ArrowDown' && e.meta) return current >= 0 ? { kind: 'open', index: current } : null
+ if (e.alt || e.meta) return null
+ if (e.key === 'Backspace') return { kind: 'up' }
+ if (e.key === 'Enter') return current >= 0 ? { kind: 'open', index: current } : null
+ if (count === 0) return null
+ const last = count - 1
+ switch (e.key) {
+ case 'ArrowDown':
+ return { kind: 'select', index: current < 0 ? 0 : Math.min(current + 1, last) }
+ case 'ArrowUp':
+ return { kind: 'select', index: current < 0 ? last : Math.max(current - 1, 0) }
+ case 'Home':
+ return { kind: 'select', index: 0 }
+ case 'End':
+ return { kind: 'select', index: last }
+ default:
+ return null
+ }
+}
+
+/**
+ * The entry of `to` that leads back toward `from`, when `to` is a strict ancestor of it — so going
+ * up (the ↑ button, Backspace, a breadcrumb) lands with the folder you came out of selected, the
+ * way Windows Explorer and Finder do. `null` when `to` is not an ancestor (entering a subfolder,
+ * or a jump elsewhere), which means "select nothing".
+ */
+export function childOnPath(to: string, from: string): string | null {
+ if (to.startsWith('/') !== from.startsWith('/')) return null
+ const a = to.split('/').filter(Boolean)
+ const b = from.split('/').filter(Boolean)
+ if (b.length <= a.length) return null
+ for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return null
+ return b[a.length]
+}
+
+/**
+ * The list's `scrollTop` that brings a row fully into view, moving as little as possible (the
+ * `block: 'nearest'` rule). Computed by hand rather than with `scrollIntoView`, which also scrolls
+ * every scrollable ANCESTOR — inside the canvas that includes React Flow's own overflow:hidden
+ * containers, and it would shove the whole pane sideways under a transformed viewport.
+ * All values are layout pixels (offsetTop/offsetHeight/clientHeight), so canvas zoom is irrelevant.
+ */
+export function scrollTopToReveal(rowTop: number, rowHeight: number, scrollTop: number, viewHeight: number): number {
+ if (rowTop < scrollTop) return rowTop
+ if (rowTop + rowHeight > scrollTop + viewHeight) return rowTop + rowHeight - viewHeight
+ return scrollTop
+}
diff --git a/src/renderer/nodes/FilesNode.tsx b/src/renderer/nodes/FilesNode.tsx
index 31d1bf422..0ccb64a40 100644
--- a/src/renderer/nodes/FilesNode.tsx
+++ b/src/renderer/nodes/FilesNode.tsx
@@ -25,7 +25,7 @@
* 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 { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { NodeResizer, useReactFlow, type NodeProps } from '@xyflow/react'
import type { DirEntry } from '@shared/types'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
@@ -33,13 +33,18 @@ import { COLLAPSED_HEIGHT, type CanvasNode } from '../state/workspace'
import { NodeColorSwatches } from '../components/NodeColorSwatches'
import {
breadcrumbs,
+ childOnPath,
childPath,
classifyEmptyListing,
downloadMenuEntries,
fileOpenTarget,
filterEntries,
folderTitle,
- parentDir
+ listKeyAction,
+ parentDir,
+ scrollTopToReveal,
+ typeAhead,
+ type TypeAheadState
} from '../lib/filesNode'
import { ancestorDirs, createTargetDir, newEntryPath } from '../lib/explorerCreate'
import { sshFs } from '../terminal/ssh-fs'
@@ -107,6 +112,15 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
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)
+ /**
+ * The selected entry, stamped with the directory it was selected IN, so every way the cwd
+ * changes (navigation, a removed worktree re-pointing the node) drops a selection that no longer
+ * names anything here without a clearing effect. Transient — a reload opens with none.
+ */
+ const [sel, setSel] = useState<{ cwd: string; name: string } | null>(null)
+ const typeRef = useRef<TypeAheadState>({ buffer: '', at: 0 })
+ const listRef = useRef<HTMLDivElement>(null)
+ const rowRefs = useRef(new Map<string, HTMLDivElement>())
const collapsed = !!data.collapsed
/**
@@ -227,8 +241,12 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
const patch: Record<string, unknown> = { cwd: to }
if (data.titleAuto !== false) patch.title = folderTitle(to)
updateNodeData(id, patch)
+ // Going UP (↑, Backspace, a breadcrumb) lands on the folder you came out of, as in Windows
+ // Explorer and Finder; going down or sideways selects nothing.
+ const cameFrom = childOnPath(to, cwd)
+ setSel(cameFrom ? { cwd: to, name: cameFrom } : null)
},
- [id, updateNodeData, data.titleAuto]
+ [id, updateNodeData, data.titleAuto, cwd]
)
const open = useCallback(
@@ -374,6 +392,64 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
)
const shown = useMemo(() => filterEntries(entries ?? [], query), [entries, query])
+ const selectedName = sel && sel.cwd === cwd ? sel.name : null
+ /** -1 when nothing is selected, or the selection is filtered out of view. */
+ const selIndex = useMemo(
+ () => (selectedName === null ? -1 : shown.findIndex((e) => e.name === selectedName)),
+ [shown, selectedName]
+ )
+ const select = useCallback((name: string) => setSel({ cwd, name }), [cwd])
+
+ // Keep the selection in view as the keyboard moves it — and after going up, once the parent's
+ // listing has arrived, so the folder you came out of is on screen.
+ useEffect(() => {
+ const list = listRef.current
+ const row = selectedName === null ? undefined : rowRefs.current.get(selectedName)
+ if (!list || !row) return
+ list.scrollTop = scrollTopToReveal(row.offsetTop, row.offsetHeight, list.scrollTop, list.clientHeight)
+ }, [selectedName, shown])
+
+ /**
+ * The listing's keyboard, live while the list has focus (a click on a row gives it focus).
+ * Everything handled here is also STOPPED here: bubbling on, an arrow reaches React Flow's node
+ * wrapper — which moves the selected node — and a letter or Backspace reaches the canvas
+ * dispatcher, where Backspace means "delete the selected nodes".
+ */
+ const onListKeyDown = useCallback(
+ (e: React.KeyboardEvent) => {
+ if (e.defaultPrevented || e.nativeEvent.isComposing) return
+ const claim = (): void => {
+ e.preventDefault()
+ e.stopPropagation()
+ }
+ const action = listKeyAction(
+ { key: e.key, alt: e.altKey, meta: e.metaKey, ctrl: e.ctrlKey },
+ selIndex,
+ shown.length
+ )
+ if (action) {
+ claim()
+ if (action.kind === 'select') select(shown[action.index].name)
+ else if (action.kind === 'open') open(shown[action.index])
+ else if (cwd && cwd !== '/') navigate(parentDir(cwd))
+ return
+ }
+ if (e.altKey || e.metaKey || e.ctrlKey) return
+ // An arrow with nowhere to go (empty folder, first/last row) still belongs to the list.
+ if (e.key.startsWith('Arrow') || e.key === 'Home' || e.key === 'End') {
+ claim()
+ return
+ }
+ // Type-ahead: any printable character. Space is left alone — it is not how names are found,
+ // and the canvas takes it (capture phase) as hold-to-pan before it gets here anyway.
+ if (e.key.length !== 1 || e.key === ' ') return
+ claim()
+ const res = typeAhead(typeRef.current, e.key, Date.now(), shown.map((x) => x.name), selIndex)
+ typeRef.current = res.state
+ if (res.index >= 0) select(shown[res.index].name)
+ },
+ [selIndex, shown, select, open, cwd, navigate]
+ )
const crumbs = useMemo(() => breadcrumbs(cwd), [cwd])
return (
@@ -495,7 +571,10 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
/>
<div
+ ref={listRef}
className="files-node__list nodrag nowheel"
+ tabIndex={0}
+ onKeyDown={onListKeyDown}
onContextMenu={(e) => openMenu(e, null)}
>
{/* Four distinct states, kept distinct. "Still loading", "could not read", "the
@@ -514,10 +593,23 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
shown.map((entry) => (
<div
key={entry.name}
- className={`files-node__row${entry.ignored ? ' is-ignored' : ''}`}
+ ref={(el) => {
+ if (el) rowRefs.current.set(entry.name, el)
+ else rowRefs.current.delete(entry.name)
+ }}
+ className={`files-node__row${entry.ignored ? ' is-ignored' : ''}${
+ entry.name === selectedName ? ' is-selected' : ''
+ }`}
title={childPath(cwd, entry.name)}
- onClick={() => open(entry)}
- onContextMenu={(e) => openMenu(e, entry)}
+ // Click selects, double-click opens (a folder navigates into itself) — the
+ // desktop file-manager contract, and what makes the keyboard usable: a single
+ // click that opened could never leave a selection for the arrows to move.
+ onClick={() => select(entry.name)}
+ onDoubleClick={() => open(entry)}
+ onContextMenu={(e) => {
+ select(entry.name)
+ openMenu(e, entry)
+ }}
>
<EntryGlyph dir={entry.dir} />
<span className="files-node__name">{entry.name}</span>
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 4b28b9a63..3190e6507 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -14186,11 +14186,18 @@ body.focus-mode .dock:hover {
}
.files-node__list {
+ /* The offsetParent of its rows — keyboard scrolling reads row.offsetTop against it. */
+ position: relative;
flex: 1;
overflow-y: auto;
padding: 0 4px 6px;
min-height: 0;
}
+/* Focusable so it can take the keyboard (arrows, Enter, type-ahead). The selected row is the
+ focus indicator, as in a desktop file manager, so the box itself draws no ring. */
+.files-node__list:focus {
+ outline: none;
+}
.files-node__row {
display: flex;
@@ -14205,6 +14212,14 @@ body.focus-mode .dock:hover {
.files-node__row:hover {
background: rgba(var(--tint-rgb), 0.08);
}
+/* Selection reads like the Explorer drawer's, and like an OS list: full strength while the list
+ has the keyboard, muted once focus is elsewhere — so it is clear where a typed letter will go. */
+.files-node__row.is-selected {
+ background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+.files-node__list:focus .files-node__row.is-selected {
+ background: color-mix(in srgb, var(--accent) 26%, transparent);
+}
/* 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 {