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 { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { useReactFlow, useStore } from '@xyflow/react'
import {
attachConnected,
canHotSwitch,
deviceClaims,
resolveEntry,
runDirLabel,
runNodeTitle,
type LaunchEntry,
type RunDevice,
type RunEntriesResult,
type RunNodeConfig,
type RunSnapshot,
type RunStatus
} from '@shared/run-config'
import { isShellCommand } from '@shared/agents/pane'
import { SIMULATOR_UDID, embedsFlutterWeb } from '@shared/run-config'
import { INLINE_SIM_HEIGHT, type InlineSimulatorConfig, type SimulatorNodeConfig } from '@shared/simulator'
import { SimulatorView } from './SimulatorNode'
import { BrowserSurface } from './BrowserSurface'
import {
isWebDeviceId,
isPreviewUrl,
localUrlFromOutput,
previewKindFor,
type PreviewKind,
type RunBrowserConfig
} from '@shared/run-preview'
import { simulatorAvailable } from '../lib/addMenuSpec'
import { useSession } from '../session/session'
import { useProjects } from '../state/projects'
import { createBrowserNode, createSimulatorNode, terminalNodeSize, type CanvasNode } from '../state/workspace'
import { IconPlay, IconReload } from '../components/icons'
import { sleep } from '@shared/sleep'
/**
* The run node's toolbar: VS Code's "Run Without Debugging" for any `.vscode/launch.json`
* configuration, over the node's own terminal.
*
* [folder ▾] [configuration ▾] [device ▾ — Flutter only] [⟳]
* ▶ Run / ■ Stop ⚡ Reload ↻ Restart [reload on save] status ⋯
*
* The host writes a launcher script for the chosen configuration (see `buildLauncher`) and this bar
* types the one line that runs it, so the run's output, keys and lifetime are the terminal's.
* Stop is SIGINT to the run's process group (Ctrl+C), then SIGTERM if it will not go. Flutter's
* `flutter run` additionally gets hot reload / hot restart by signal and reload on save; every
* other type's Restart is stop + run.
*
* The terminal is hidden by default (⋯ shows it, with the extra-arguments field): hidden, the node
* is just these rows, fitted to their height.
*/
const STATUS_POLL_MS = 2_000
const STOP_GRACE_MS = 5_000
const NOTE_MS = 6_000
type Busy = 'booting' | 'starting' | 'stopping' | 'reloading' | 'restarting' | 'switching' | null
const CHOOSE_FOLDER = '\u0000choose'
const NO_ENTRY = '\u0000none'
interface Props {
nodeId: string
config: RunNodeConfig
/** A compound's sibling: start the run once on mount. */
autoStart: boolean
/** The simulator shown inside this node, when it is (`data.runSimulator`). */
simulator?: InlineSimulatorConfig
/** The browser shown inside this node, when it is (`data.runBrowser`). */
browser?: RunBrowserConfig
}
/** Node id → title → device, for every run node on the live canvas, as one primitive. */
function liveSig(s: { nodes: unknown[] }): string {
let out = ''
for (const n of s.nodes as CanvasNode[]) {
const r = n.data?.runConfig
if (r?.deviceId) out += `${n.id}\u0001${n.data.title}\u0001${r.deviceId}\u0002`
}
return out
}
function storedSig(s: ReturnType<typeof useProjects.getState>): string {
let out = ''
for (const p of s.projects) {
if (p.closed) continue
for (const n of p.nodes) {
if (n.runConfig?.deviceId) out += `${n.id}\u0001${n.title}\u0001${n.runConfig.deviceId}\u0002`
}
}
return out
}
function parseSig(sig: string): Array<{ id: string; title: string; runConfig: { deviceId: string } }> {
return sig
.split('\u0002')
.filter(Boolean)
.map((row) => {
const [id, title, deviceId] = row.split('\u0001')
return { id, title, runConfig: { deviceId } }
})
}
export function RunBar({ nodeId, config, autoStart, simulator, browser: browserPanel }: Props) {
const session = useSession()
const { api } = session
const { updateNodeData, setNodes, getNodes } = useReactFlow()
const [listing, setListing] = useState<RunEntriesResult | null>(null)
const [devices, setDevices] = useState<RunDevice[] | null>(null)
const [devicesError, setDevicesError] = useState<string | null>(null)
const [projects, setProjects] = useState<string[]>([])
const [status, setStatus] = useState<RunStatus | null>(null)
const [busy, setBusy] = useState<Busy>(null)
const [note, setNote] = useState<{ kind: 'error' | 'info'; text: string } | null>(null)
const [needsRerun, setNeedsRerun] = useState(false)
const [argsDraft, setArgsDraft] = useState(config.extraArgs ?? '')
const mounted = useRef(true)
useEffect(() => () => void (mounted.current = false), [])
const cfgRef = useRef(config)
cfgRef.current = config
// The preview panel, for the run-start path above it (see the 📱 / 🌐 section below).
const browserOpenRef = useRef(false)
const popOutRef = useRef<{ kind: PreviewKind; id: string } | null>(null)
const setPreviewRef = useRef<(next: { kind: 'browser'; cfg: RunBrowserConfig }) => void>(() => undefined)
/** The entry the node resolves to now (kept current below), for callbacks and the status poll. */
const entryRef = useRef<LaunchEntry | undefined>(undefined)
const running = !!status?.running
const say = useCallback((kind: 'error' | 'info', text: string) => setNote({ kind, text }), [])
useEffect(() => {
if (!note) return
const t = setTimeout(() => setNote(null), NOTE_MS)
return () => clearTimeout(t)
}, [note])
/** Patch the node's run config; the title follows folder + configuration while it is ours. */
const patch = useCallback(
(next: Partial<RunNodeConfig>, opts?: { changesRun?: boolean; entryName?: string }) => {
updateNodeData(nodeId, (n) => {
const prev = (n.data.runConfig as RunNodeConfig | undefined) ?? cfgRef.current
const runConfig: RunNodeConfig = { ...prev, ...next }
const data: Record<string, unknown> = { runConfig }
if (next.projectDir && next.projectDir !== prev.projectDir) data.cwd = next.projectDir
if (n.data.titleAuto !== false && (next.projectDir || next.launchConfig || opts?.entryName)) {
data.title = runNodeTitle(runConfig.projectDir, opts?.entryName ?? runConfig.launchConfig)
}
return data
})
if (opts?.changesRun && cfgRef.current && running) setNeedsRerun(true)
},
[nodeId, updateNodeData, running]
)
// ── Loads ────────────────────────────────────────────────────────────────────────────────
const loadEntries = useCallback(() => {
void api.runConfig.entries(cfgRef.current.projectDir).then((r) => {
if (mounted.current) setListing(r)
})
}, [api])
useEffect(() => {
let live = true
setListing(null)
void api.runConfig.entries(config.projectDir).then((r) => {
if (live) setListing(r)
})
void api.runConfig.discoverProjects(config.projectDir).then((dirs) => {
if (live) setProjects(dirs)
})
return () => {
live = false
}
}, [api, config.projectDir])
const entries = listing?.entries ?? []
const entry: LaunchEntry | undefined = useMemo(
() => resolveEntry(entries, config.launchConfig),
[entries, config.launchConfig]
)
const wantsDevices = entries.some((e) => e.usesDevice)
entryRef.current = entry
const loadDevices = useCallback(
(refresh: boolean) => {
void api.runConfig.devices(refresh).then((r) => {
if (!mounted.current) return
setDevices(r.devices)
setDevicesError(r.error ?? null)
})
},
[api]
)
useEffect(() => {
if (wantsDevices && devices === null) loadDevices(false)
}, [wantsDevices, devices, loadDevices])
// Set while WE are stopping the run, so its end is not reported as unexpected.
const stoppingRef = useRef(false)
const lastRunningRef = useRef<boolean | null>(null)
/** What the live run was started from — what a folder switch must match to keep the app.
* Set at Run; recovered from the node's config when the run was already going at mount (the
* config cannot have changed before this view existed to change it). Cleared when it ends. */
const runningRef = useRef<RunSnapshot | null>(null)
const pollStatus = useCallback(async () => {
const s = await api.runConfig.status(nodeId)
if (!mounted.current) return s.running
if (!s.running && !stoppingRef.current) runningRef.current = null
if (s.running && !runningRef.current && entryRef.current) {
const c = cfgRef.current
runningRef.current = { projectDir: c.projectDir, deviceId: c.deviceId, flavor: entryRef.current.flavor, hotReload: entryRef.current.hotReload }
}
if (lastRunningRef.current === true && !s.running && !stoppingRef.current && !cfgRef.current.showTerminal) {
const how = s.exitCode === null || s.exitCode === 0 ? 'The run ended' : `The run exited with code ${s.exitCode}`
setNote({ kind: s.exitCode ? 'error' : 'info', text: `${how} — open ⋯ to see the terminal output.` })
}
lastRunningRef.current = s.running
setStatus(s)
return s.running
}, [api, nodeId])
useEffect(() => {
void pollStatus()
const t = setInterval(() => {
if (document.visibilityState === 'visible') void pollStatus()
}, STATUS_POLL_MS)
return () => clearInterval(t)
}, [pollStatus])
// Reload on save lives in core and outlives this view (the run keeps going in tmux).
const hotReload = !!entry?.hotReload
useEffect(() => {
void api.runConfig.watch(nodeId, hotReload && config.reloadOnSave ? config.projectDir : null)
}, [api, nodeId, hotReload, config.reloadOnSave, config.projectDir])
// ── Derived ──────────────────────────────────────────────────────────────────────────────
const showDevice = !!entry?.usesDevice && !entry.pinnedDevice
const live = useStore(liveSig)
const stored = useProjects(storedSig)
const claimsFor = useCallback(
(deviceId: string | undefined) => {
const l = parseSig(live)
const ids = new Set(l.map((n) => n.id))
return deviceClaims([...l, ...parseSig(stored).filter((n) => !ids.has(n.id))], nodeId, deviceId)
},
[live, stored, nodeId]
)
// First open: adopt the configuration VS Code would show first, and (Flutter) a running
// simulator nobody else is using — so a fresh node is usually one click from running.
useEffect(() => {
if (listing && !config.launchConfig && entry) patch({ launchConfig: entry.name }, { entryName: entry.name })
}, [listing, config.launchConfig, entry, patch])
useEffect(() => {
if (!devices || config.deviceId || !showDevice) return
const free = devices.find((d) => d.kind === 'simulator' && d.state === 'booted' && claimsFor(d.id).length === 0)
if (free) patch({ deviceId: free.id, deviceName: free.name })
}, [devices, config.deviceId, showDevice, claimsFor, patch])
const device = devices?.find((d) => d.id === config.deviceId)
const claims = showDevice ? claimsFor(config.deviceId) : []
// ── Actions ──────────────────────────────────────────────────────────────────────────────
const start = useCallback(
async (override?: Partial<RunNodeConfig>) => {
const cfg = { ...cfgRef.current, ...override }
const target = resolveEntry(entries, cfg.launchConfig)
if (target?.usesDevice && !target.pinnedDevice && !cfg.deviceId) {
say('error', 'Pick a device first.')
return
}
const pane = await api.pty.paneCommand(nodeId)
if (pane !== null && !isShellCommand(pane)) {
say('error', `“${pane}” is running in this terminal — stop it first.`)
return
}
const dev = devices?.find((d) => d.id === cfg.deviceId)
if (target?.usesDevice && !target.pinnedDevice && dev?.kind === 'simulator' && dev.state !== 'booted') {
setBusy('booting')
if (!(await api.runConfig.bootDevice(dev.id))) {
setBusy(null)
say('error', `Could not boot ${dev.name}.`)
return
}
loadDevices(true)
}
setBusy('starting')
const r = await api.runConfig.start(nodeId, cfg)
if (!r.ok) {
setBusy(null)
say('error', r.error)
return
}
if (r.kind === 'browser') {
setBusy(null)
if (!isPreviewUrl(r.url)) {
say('error', `Only http(s) URLs open in the browser panel (${r.url}).`)
return
}
// The page opens in this node's browser panel (or the panel popped out of it).
const out = popOutRef.current
if (out?.kind === 'browser') updateNodeData(out.id, { url: r.url })
else setPreviewRef.current({ kind: 'browser', cfg: { url: r.url } })
return
}
if (r.kind === 'compound') {
// This node runs the first member; the rest open beside it and start at once.
const [first, ...rest] = r.members
setBusy(null)
if (rest.length) {
const base = cfgRef.current
window.dispatchEvent(
new CustomEvent('nodeterm:open-run-config', {
detail: {
sourceNodeId: nodeId,
configs: rest.map((name) => ({ projectDir: base.projectDir, launchConfig: name, reloadOnSave: base.reloadOnSave }))
}
})
)
}
patch({ launchConfig: first }, { entryName: first })
await start({ launchConfig: first })
return
}
runningRef.current = { projectDir: cfg.projectDir, deviceId: cfg.deviceId, flavor: target?.flavor, hotReload: r.hotReload }
const sent = await api.pty.sendText(nodeId, r.command)
setNeedsRerun(false)
// A Flutter web run that opted in to showing here (the host runs it on Flutter's web server —
// see `webServerDevice`): open the browser panel for it, unless it is open or popped out already.
const runDevice = target?.pinnedDevice ?? cfg.deviceId
if (target?.usesDevice && isWebDeviceId(runDevice) && embedsFlutterWeb(cfg) && !browserOpenRef.current) {
setPreviewRef.current({ kind: 'browser', cfg: {} })
}
if (sent === 'pasted-not-submitted') say('info', 'The command is in the terminal — press Enter to start.')
else if (sent !== true) say('error', 'Could not type into this terminal.')
const deadline = Date.now() + 15_000
while (mounted.current && Date.now() < deadline) {
if (await pollStatus()) break
await sleep(400)
}
if (mounted.current) setBusy(null)
},
[api, nodeId, entries, devices, loadDevices, pollStatus, patch, say]
)
const waitStopped = useCallback(
async (ms: number) => {
const deadline = Date.now() + ms
while (mounted.current && Date.now() < deadline) {
if (!(await pollStatus())) return true
await sleep(300)
}
return false
},
[pollStatus]
)
const stop = useCallback(async () => {
setBusy('stopping')
stoppingRef.current = true
let stopped = false
if (await api.runConfig.stop(nodeId)) {
stopped = await waitStopped(STOP_GRACE_MS)
// Ctrl+C was not enough (a program that traps it): ask harder, once.
if (!stopped && (await api.runConfig.stop(nodeId, true))) stopped = await waitStopped(STOP_GRACE_MS)
} else {
stopped = !(await pollStatus())
}
stoppingRef.current = false
if (mounted.current) {
setBusy(null)
if (!stopped) say('error', 'The run did not stop — open ⋯ to check the terminal.')
}
return stopped
}, [api, nodeId, waitStopped, pollStatus, say])
const restart = useCallback(async () => {
if (running && !(await stop())) return
await start()
}, [running, stop, start])
/**
* Switch the running Flutter app to the node's (new) folder WITHOUT rebuilding it:
* 1. `d` — flutter run/attach's own "detach": the tool exits, the app keeps running;
* 2. `flutter attach` from the new folder, to the same device;
* 3. once it has connected, a hot RESTART (SIGUSR2). Not a reload: a freshly attached tool only
* pushes files that change after it connected, so the new checkout's code would mostly not
* reach the app. A restart pushes the whole program — the app's state resets, nothing native
* is rebuilt.
* Every failure leaves the app running and says so; Rebuild stays one click away.
*/
const switchKeepApp = useCallback(async () => {
const cfg = cfgRef.current
setBusy('switching')
stoppingRef.current = true
await api.pty.sendText(nodeId, 'd', { enter: false })
const detached = await waitStopped(10_000)
stoppingRef.current = false
if (!detached) {
setBusy(null)
say('error', 'The running tool did not detach — open ⋯ to check the terminal.')
return
}
const r = await api.runConfig.start(nodeId, cfg, { attach: true })
if (!r.ok || r.kind !== 'process') {
setBusy(null)
say('error', `${r.ok ? 'Could not attach.' : r.error} The app is still running on the device; Rebuild restarts it from this folder.`)
return
}
const sent = await api.pty.sendText(nodeId, r.command)
if (sent !== true) {
setBusy(null)
say('error', sent === 'pasted-not-submitted' ? 'The attach command is in the terminal — press Enter.' : 'Could not type into this terminal.')
return
}
// Wait for the attach to connect (it prints its key help once it has). Discovering the app
// can take a while on a busy simulator; an attach that exits early has failed.
let connected = false
let sawRunning = false
const deadline = Date.now() + 120_000
while (mounted.current && Date.now() < deadline) {
if (attachConnected(await api.pty.capture(nodeId))) {
connected = true
break
}
const alive = await pollStatus()
if (alive) sawRunning = true
else if (sawRunning) break
await sleep(700)
}
if (!mounted.current) return
if (!connected) {
setBusy(null)
say('error', 'flutter attach did not connect — open ⋯ to see why. Rebuild starts the app from this folder.')
return
}
const restarted = await api.runConfig.signal(nodeId, 'restart')
runningRef.current = { projectDir: cfg.projectDir, deviceId: cfg.deviceId, flavor: entryRef.current?.flavor, hotReload: true }
setNeedsRerun(false)
setBusy(null)
say(
restarted ? 'info' : 'error',
restarted
? `Switched to ${runDirLabel(cfg.projectDir)} without rebuilding — hot restarted (the app's state was reset).`
: 'Attached, but the hot restart failed — press R in the terminal.'
)
}, [api, nodeId, waitStopped, pollStatus, say])
const signal = useCallback(
async (kind: 'reload' | 'restart') => {
setBusy(kind === 'reload' ? 'reloading' : 'restarting')
const ok = await api.runConfig.signal(nodeId, kind)
if (!mounted.current) return
setTimeout(() => mounted.current && setBusy(null), 600)
if (!ok) say('error', 'The app is not running.')
},
[api, nodeId, say]
)
// A compound's sibling starts by itself, once.
const autoStarted = useRef(false)
useEffect(() => {
if (!autoStart || autoStarted.current || !listing || (wantsDevices && devices === null)) return
autoStarted.current = true
updateNodeData(nodeId, { runAutoStart: undefined })
void start()
}, [autoStart, listing, wantsDevices, devices, start, nodeId, updateNodeData])
const onFolder = useCallback(
async (value: string) => {
let dir: string | null = value
if (value === CHOOSE_FOLDER) dir = await api.dialog.selectFolder()
if (!dir || dir === cfgRef.current.projectDir) return
patch({ projectDir: dir, launchConfig: undefined }, { changesRun: true })
},
[api, patch]
)
const onDevice = useCallback(
(id: string) => {
const d = devices?.find((x) => x.id === id)
patch({ deviceId: id, deviceName: d?.name }, { changesRun: true })
},
[devices, patch]
)
// ── Terminal toggle + compact sizing ─────────────────────────────────────────────────────
//
// Hidden (the default), the node is just its control rows: the terminal body is hidden by CSS
// (`.term-node:has(.run-bar--compact)`, the same `display: none` path collapse uses — xterm and
// the tmux client stay alive) and the node's height is fitted to what is left. The height the
// terminal had is remembered on the node (not persisted) and handed back on show.
const showTerminal = !!config.showTerminal
const barRef = useRef<HTMLDivElement>(null)
const fitCompact = useCallback(() => {
const bar = barRef.current
const root = bar?.closest('.term-node') as HTMLElement | null
if (!bar || !root) return
let h = 0
for (const child of Array.from(root.children) as HTMLElement[]) {
if (child.classList.contains('term-node__body')) continue
const pos = getComputedStyle(child).position
if (pos === 'absolute' || pos === 'fixed') continue
h += child.offsetHeight
}
const cs = getComputedStyle(root)
h = Math.ceil(h + (parseFloat(cs.borderTopWidth) || 0) + (parseFloat(cs.borderBottomWidth) || 0))
if (h <= 0) return
setNodes((ns) =>
ns.map((n) => {
if (n.id !== nodeId || n.data.collapsed || n.height === h) return n
return { ...n, height: h, style: { ...n.style, height: h } }
})
)
}, [nodeId, setNodes])
useLayoutEffect(() => {
// With a simulator open the NODE's size is the user's: the panel fills it and scales with it.
if (showTerminal || simulator || browserPanel) return
const bar = barRef.current
if (!bar) return
fitCompact()
const ro = new ResizeObserver(() => fitCompact())
ro.observe(bar)
return () => ro.disconnect()
}, [showTerminal, simulator, browserPanel, fitCompact])
// ── 📱 / 🌐 The preview panel, inside this node ────────────────────────────────────────────
//
// One panel under the control rows, of the kind the run calls for (`previewKindFor`): a simulator
// for a run on a phone (its device preselected when it is one — an iOS UDID, or an Android
// emulator's adb serial, which is what Flutter names it — else empty to pick any), a browser for a
// run that targets one or serves a page (its URL from the launch configuration, or picked out of
// the run's output once it prints one). The button opens and closes it; ⇱ pops it out into its
// own node, whose ⇲ (or this button) docks it back. While it is open the panel fills the node, so
// resizing the node scales it; the compact fit above stands down. Opening grows the node by a
// panel's worth; closing hands it back (the compact fit, or the same amount with the terminal shown).
const panelRef = useRef<HTMLDivElement>(null)
const previewKind = previewKindFor({
picksDevice: showDevice,
deviceId: config.deviceId,
deviceKind: device?.kind,
browserConfig: !!entry?.browser,
pinnedDeviceId: entry?.usesDevice ? entry.pinnedDevice : undefined
})
const panelOpen = !!simulator || !!browserPanel
/** A panel popped out of this node into its own: its id and kind. Read as one primitive. */
const poppedOutSig = useStore((st) => {
for (const n of st.nodeLookup.values()) {
if (n.type === 'simulator' && (n.data.simulator as SimulatorNodeConfig | undefined)?.dockTo === nodeId) return `simulator:${n.id}`
if (n.type === 'browser' && n.data.dockTo === nodeId) return `browser:${n.id}`
}
return ''
})
const poppedOut = poppedOutSig ? { kind: poppedOutSig.slice(0, poppedOutSig.indexOf(':')) as PreviewKind, id: poppedOutSig.slice(poppedOutSig.indexOf(':') + 1) } : null
browserOpenRef.current = !!browserPanel || poppedOut?.kind === 'browser'
popOutRef.current = poppedOut
/** The kind the button shows: an open or popped-out panel's own, else what the run calls for. */
const shownKind: PreviewKind = simulator ? 'simulator' : browserPanel ? 'browser' : poppedOut ? poppedOut.kind : previewKind
type Preview = { kind: 'simulator'; cfg: InlineSimulatorConfig } | { kind: 'browser'; cfg: RunBrowserConfig } | undefined
/** Show `next` inside this node (or nothing), resizing the node around the change. `extra` adds or
* removes other nodes in the same update (pop out / dock back). */
const setPreview = useCallback(
(next: Preview, extra?: (ns: CanvasNode[]) => CanvasNode[]) => {
const panelNow = panelRef.current?.offsetHeight || INLINE_SIM_HEIGHT
setNodes((all) => {
const ns = (extra ? extra(all as CanvasNode[]) : all) as CanvasNode[]
return ns.map((n) => {
if (n.id !== nodeId) return n
const was = !!n.data.runSimulator || !!n.data.runBrowser
const data = {
...n.data,
runSimulator: next?.kind === 'simulator' ? next.cfg : undefined,
runBrowser: next?.kind === 'browser' ? next.cfg : undefined
}
if (was === !!next) return { ...n, data }
const showing = !!(n.data.runConfig as RunNodeConfig | undefined)?.showTerminal
// Hidden terminal + closing: the compact fit takes the height back by itself.
if (!next && !showing) return { ...n, data }
const now = (n.height as number | undefined) ?? n.measured?.height ?? 0
const height = Math.max(120, now + (next ? INLINE_SIM_HEIGHT : -panelNow))
return { ...n, height, style: { ...n.style, height }, data }
})
})
},
[nodeId, setNodes]
)
setPreviewRef.current = setPreview
/** ⇲ / the button on a popped-out panel: its node goes, and it comes back inside this one. */
const dockBack = useCallback(
(otherId: string) => {
const other = getNodes().find((n) => n.id === otherId)
if (!other) return
const remove = (ns: CanvasNode[]) => ns.filter((n) => n.id !== otherId)
if (other.type === 'browser') {
const url = other.data.url as string | undefined
setPreview({ kind: 'browser', cfg: isPreviewUrl(url) ? { url } : {} }, remove)
return
}
const { dockTo: _d, ...device } = (other.data.simulator as SimulatorNodeConfig | undefined) ?? {}
void _d
setPreview({ kind: 'simulator', cfg: device }, remove)
},
[getNodes, setPreview]
)
// A popped-out node's ⇲ asks for this.
useEffect(() => {
const onDock = (e: Event) => {
const d = (e as CustomEvent<{ nodeId?: string; runNodeId?: string }>).detail
if (d?.runNodeId === nodeId && d.nodeId) dockBack(d.nodeId)
}
window.addEventListener('nodeterm:dock-preview', onDock)
return () => window.removeEventListener('nodeterm:dock-preview', onDock)
}, [nodeId, dockBack])
/** The page this run shows: a browser configuration's own URL, else the newest local URL in the
* run's output. Null when there is none yet. */
const browserUrlNow = useCallback(async (): Promise<RunBrowserConfig> => {
if (entry?.browser) {
const r = await api.runConfig.start(nodeId, cfgRef.current).catch(() => null)
return r?.ok && r.kind === 'browser' && isPreviewUrl(r.url) ? { url: r.url } : {}
}
const text = await api.pty.capture(nodeId, true).catch(() => '')
const url = localUrlFromOutput(text)
return url ? { url, auto: true } : {}
}, [api, nodeId, entry?.browser])
// The run's own device (the configuration's, else the pick) — a Flutter web run when it is a
// browser device, which shows here only when `embedBrowser` is on.
const runDevice = entry?.usesDevice ? (entry.pinnedDevice ?? config.deviceId) : undefined
const flutterWebRun = isWebDeviceId(runDevice)
/** The button: hides an open panel, docks a popped-out one back, and otherwise shows the one this
* run calls for — a node runs one thing, so it is never a choice. */
const onPreviewButton = () => {
if (panelOpen) return setPreview(undefined)
if (poppedOut) return dockBack(poppedOut.id)
void openPreview(previewKind)
}
const openPreview = async (kind: PreviewKind) => {
if (kind === 'browser') {
if (flutterWebRun && running && !embedsFlutterWeb(config)) {
say('info', 'This Flutter web run is in its own Chrome window — turn on ⋯ → “Show web inside this node” and run again to show it here.')
}
setPreview({ kind: 'browser', cfg: await browserUrlNow() })
return
}
const id = showDevice ? config.deviceId : undefined
let next: InlineSimulatorConfig = {}
if (id && SIMULATOR_UDID.test(id)) next = { udid: id.toUpperCase(), name: device?.name ?? config.deviceName }
else if (id && /^emulator-\d+$/.test(id)) {
const avd = (await api.simulator.devices().catch(() => ({ devices: [] }))).devices.find((d) => d.serial === id)
if (avd) next = { udid: avd.id, name: avd.name }
}
setPreview({ kind: 'simulator', cfg: next })
}
// An open panel follows the run: pick a browser device and the simulator becomes the browser, and
// the other way round. The popped-out kind is left alone (the person moved it out on purpose).
const openPreviewRef = useRef(openPreview)
openPreviewRef.current = openPreview
const openKind: PreviewKind | null = simulator ? 'simulator' : browserPanel ? 'browser' : null
useEffect(() => {
if (openKind && openKind !== previewKind) void openPreviewRef.current(previewKind)
}, [openKind, previewKind])
/** ⇱: the panel becomes its own node beside this one, which can dock back. */
const popOut = () => {
if (!simulator && !browserPanel) return
setPreview(undefined, (ns) => {
const src = ns.find((n) => n.id === nodeId)
if (!src) return ns
let node: CanvasNode
if (simulator) node = createSimulatorNode(ns.length, { ...simulator, dockTo: nodeId })
else {
node = createBrowserNode(ns.length, browserPanel?.url ?? '')
node.data = { ...node.data, dockTo: nodeId }
}
const w = src.measured?.width ?? (src.width as number | undefined) ?? 640
node.position = { x: src.position.x + w + 40, y: src.position.y }
return [...ns, src.parentId ? { ...node, parentId: src.parentId, extent: 'parent' as const } : node]
})
}
const onSimConfig = useCallback(
(next: SimulatorNodeConfig) => {
updateNodeData(nodeId, (n) => (n.data.runSimulator ? { runSimulator: { ...next, dockTo: undefined } } : {}))
},
[nodeId, updateNodeData]
)
const onBrowserUrl = useCallback(
(url: string) => {
if (!isPreviewUrl(url)) return
updateNodeData(nodeId, (n) => {
const was = n.data.runBrowser as RunBrowserConfig | undefined
if (!was || was.url === url) return {}
return { runBrowser: { url, ...(was.auto ? { auto: true } : {}) } }
})
},
[nodeId, updateNodeData]
)
// Waiting for a page: while the browser panel has none and the run is up, read its output until
// it prints a local URL. A new run starts the wait over when the last URL was picked out of the
// output (a dev server may come back on another port); a URL the person typed is kept.
const lastRunning = useRef(running)
useEffect(() => {
const was = lastRunning.current
lastRunning.current = running
if (!was && running && browserPanel?.auto) updateNodeData(nodeId, { runBrowser: {} })
}, [running, browserPanel?.auto, nodeId, updateNodeData])
const waitingForUrl = !!browserPanel && !browserPanel.url && running && !entry?.browser
useEffect(() => {
if (!waitingForUrl) return
let live = true
const look = async () => {
const text = await api.pty.capture(nodeId, true).catch(() => '')
const url = live ? localUrlFromOutput(text) : null
if (url) updateNodeData(nodeId, (n) => (n.data.runBrowser && !(n.data.runBrowser as RunBrowserConfig).url ? { runBrowser: { url, auto: true } } : {}))
}
void look()
const t = setInterval(() => void look(), 1500)
return () => {
live = false
clearInterval(t)
}
}, [waitingForUrl, api, nodeId, updateNodeData])
const toggleTerminal = useCallback(() => {
const next = !showTerminal
setNodes((ns) =>
ns.map((n) => {
if (n.id !== nodeId) return n
const runConfig = { ...((n.data.runConfig as RunNodeConfig | undefined) ?? cfgRef.current), showTerminal: next }
const current = (n.measured?.height ?? (n.height as number | undefined)) || 0
if (next) {
const remembered = n.data.runTerminalHeight as number | undefined
const height = Math.max(remembered ?? 0, terminalNodeSize().height)
return { ...n, height, style: { ...n.style, height }, data: { ...n.data, runConfig } }
}
return { ...n, data: { ...n.data, runConfig, runTerminalHeight: current } }
})
)
}, [showTerminal, nodeId, setNodes])
// ── Render ───────────────────────────────────────────────────────────────────────────────
const folderOptions = useMemo(() => {
const set = new Set(projects)
set.add(config.projectDir)
return [...set].sort((a, b) => a.localeCompare(b))
}, [projects, config.projectDir])
const deviceLabel = (d: RunDevice) => {
const used = claimsFor(d.id)
const plat = d.platform ? (d.kind === 'simulator' ? ` · ${d.platform}` : ` (${d.platform})`) : ''
const twin = devices?.some((o) => o.id !== d.id && o.name === d.name && o.platform === d.platform)
return `${d.name}${plat}${twin ? ` · ${d.id.slice(0, 4)}` : ''}${used.length ? ` — in use by ${used[0]}` : ''}`
}
const booted = devices?.filter((d) => d.kind === 'simulator' && d.state === 'booted') ?? []
const shutdown = devices?.filter((d) => d.kind === 'simulator' && d.state !== 'booted') ?? []
const others = devices?.filter((d) => d.kind !== 'simulator') ?? []
const configs = entries.filter((e) => e.kind === 'config')
const compounds = entries.filter((e) => e.kind === 'compound')
const entryOption = (e: LaunchEntry) => (
<option key={e.name} value={e.name}>
{e.name}
{e.kind === 'config' ? ` · ${e.typeLabel}` : ''}
{e.supported ? '' : ' (can’t run here)'}
</option>
)
const browser = !!entry?.browser
// Folder/configuration changed under a running Flutter app that the new choice would build the
// same way: offer to switch without rebuilding (canHotSwitch states the rule).
const hotSwitch = canHotSwitch(runningRef.current, { config, entry })
const canRun = !!entry?.supported && !busy
const statusText =
busy === 'booting'
? 'Booting simulator…'
: busy === 'starting'
? 'Starting…'
: busy === 'stopping'
? 'Stopping…'
: busy === 'reloading'
? 'Hot reload'
: busy === 'restarting'
? 'Hot restart'
: busy === 'switching'
? 'Switching…'
: running
? 'Running'
: status?.exitCode
? `Exited (${status.exitCode})`
: status
? 'Stopped'
: ''
const statusKind = busy ? 'busy' : running ? 'running' : status?.exitCode ? 'failed' : 'stopped'
const blocker =
listing?.error ??
(listing && entries.length === 0 ? 'No .vscode/launch.json in this folder — choose another folder.' : null) ??
(entry && !entry.supported ? entry.reason : null)
return (
<div ref={barRef} className={`run-bar nodrag nowheel${showTerminal ? '' : ' run-bar--compact'}${panelOpen ? ' run-bar--sim' : ''}`}>
<div className="run-bar__row">
<select
className="run-bar__select run-bar__select--folder"
value={config.projectDir}
title={config.projectDir}
onChange={(e) => void onFolder(e.target.value)}
>
{folderOptions.map((d) => (
<option key={d} value={d}>
{runDirLabel(d)}
</option>
))}
<option value={CHOOSE_FOLDER}>Choose folder…</option>
</select>
<select
className="run-bar__select run-bar__select--config"
value={entry?.name ?? NO_ENTRY}
disabled={entries.length === 0}
title={entry ? `${entry.name}${entry.preLaunchTask ? ` — runs “${entry.preLaunchTask}” first` : ''}` : ''}
onChange={(e) => patch({ launchConfig: e.target.value }, { changesRun: true, entryName: e.target.value })}
>
{entries.length === 0 && <option value={NO_ENTRY}>{listing ? 'No configurations' : 'Loading…'}</option>}
{configs.map(entryOption)}
{compounds.length > 0 && <optgroup label="Compounds">{compounds.map(entryOption)}</optgroup>}
</select>
{entry?.usesDevice && entry.pinnedDevice && (
<span className="run-bar__pinned" title="This configuration chooses its own device">
{entry.pinnedDevice}
</span>
)}
{showDevice && (
<select
className={`run-bar__select${claims.length ? ' run-bar__select--warn' : ''}`}
value={config.deviceId ?? ''}
title={
claims.length
? `Also selected by ${claims.join(', ')} — two runs on one device replace each other`
: (devicesError ?? device?.name ?? 'Device')
}
onChange={(e) => onDevice(e.target.value)}
>
{!config.deviceId && <option value="">{devices ? 'Pick a device…' : 'Loading devices…'}</option>}
{config.deviceId && !device && <option value={config.deviceId}>{config.deviceName ?? config.deviceId}</option>}
{booted.length > 0 && (
<optgroup label="Running simulators">
{booted.map((d) => (
<option key={d.id} value={d.id}>
{deviceLabel(d)}
</option>
))}
</optgroup>
)}
{shutdown.length > 0 && (
<optgroup label="Simulators (boots on run)">
{shutdown.map((d) => (
<option key={d.id} value={d.id}>
{deviceLabel(d)}
</option>
))}
</optgroup>
)}
{others.length > 0 && (
<optgroup label="Other devices">
{others.map((d) => (
<option key={d.id} value={d.id}>
{deviceLabel(d)}
</option>
))}
</optgroup>
)}
</select>
)}
<button
type="button"
className="run-bar__icon"
title={showDevice ? 'Reload launch.json and devices' : 'Reload launch.json'}
aria-label="Refresh"
onClick={() => {
loadEntries()
if (wantsDevices) loadDevices(true)
}}
>
⟳
</button>
</div>
<div className="run-bar__row">
{running ? (
<button type="button" className="run-bar__btn run-bar__btn--stop" title="Stop (Ctrl+C)" disabled={!!busy} onClick={() => void stop()}>
<span className="run-bar__stop-glyph" aria-hidden /> Stop
</button>
) : (
<button
type="button"
className="run-bar__btn run-bar__btn--run"
title={browser ? 'Open in a browser node' : entry?.kind === 'compound' ? 'Run every configuration in this compound' : 'Run'}
disabled={!canRun}
onClick={() => void start()}
>
<IconPlay /> {browser ? 'Open' : 'Run'}
</button>
)}
{hotReload ? (
<>
<button type="button" className="run-bar__btn" title="Hot reload (r)" disabled={!running || !!busy} onClick={() => void signal('reload')}>
⚡ Reload
</button>
<button type="button" className="run-bar__btn" title="Hot restart (R)" disabled={!running || !!busy} onClick={() => void signal('restart')}>
<IconReload /> Restart
</button>
<label className="run-bar__toggle" title="Hot reload when a .dart file under lib/ changes">
<input type="checkbox" checked={config.reloadOnSave} onChange={(e) => patch({ reloadOnSave: e.target.checked })} />
Reload on save
</label>
</>
) : (
!browser && (
<button type="button" className="run-bar__btn" title="Stop and run again" disabled={!running || !!busy} onClick={() => void restart()}>
<IconReload /> Restart
</button>
)
)}
{needsRerun && running && hotSwitch && (
<>
<button
type="button"
className="run-bar__btn run-bar__btn--accent"
title="Keep the app on the device: detach, attach from the new folder, hot restart. Its state resets; nothing native is rebuilt."
disabled={!!busy}
onClick={() => void switchKeepApp()}
>
⇄ Switch (keep app)
</button>
<button
type="button"
className="run-bar__btn"
title="Stop and run again from scratch — needed when the folders differ in native code (plugins, ios/, Info.plist)"
disabled={!!busy}
onClick={() => void restart()}
>
Rebuild
</button>
</>
)}
{needsRerun && running && !hotSwitch && (
<button
type="button"
className="run-bar__btn run-bar__btn--accent"
title="Stop and run again with the new folder, configuration or device"
disabled={!!busy}
onClick={() => void restart()}
>
Apply & re-run
</button>
)}
<span className="run-bar__spacer" />
<span className={`run-bar__status run-bar__status--${statusKind}`}>{statusText}</span>
{simulatorAvailable(session.source === 'relay') && (
<>
{browserPanel && (
<button type="button" className="run-bar__icon" title="Pop the browser out into its own node" aria-label="Pop out" onClick={popOut}>
⇱
</button>
)}
<button
type="button"
className={`run-bar__icon${panelOpen || poppedOut ? ' run-bar__icon--on' : ''}`}
title={previewButtonTitle(shownKind, panelOpen, !!poppedOut)}
aria-label={panelOpen ? `Hide the ${shownKind}` : `Show the ${shownKind}`}
aria-pressed={panelOpen}
onClick={onPreviewButton}
>
{shownKind === 'browser' ? '🌐' : '📱'}
</button>
</>
)}
<button
type="button"
className={`run-bar__icon${showTerminal ? ' run-bar__icon--on' : ''}`}
title={showTerminal ? 'Hide the terminal' : 'Show the terminal and extra arguments'}
aria-label={showTerminal ? 'Hide the terminal' : 'Show the terminal'}
aria-pressed={showTerminal}
onClick={toggleTerminal}
>
⋯
</button>
</div>
{showTerminal && (
<div className="run-bar__row">
<input
className="run-bar__args"
placeholder="Extra arguments, e.g. --dart-define=API_BASE_URL=http://localhost:8081/api/"
value={argsDraft}
spellCheck={false}
onChange={(e) => setArgsDraft(e.target.value)}
onBlur={() => patch({ extraArgs: argsDraft.trim() || undefined }, { changesRun: true })}
onKeyDown={(e) => {
if (e.key === 'Enter') (e.target as HTMLInputElement).blur()
e.stopPropagation()
}}
/>
{flutterWebRun && (
<label
className="run-bar__check"
title="On: Flutter’s web server serves the app to the browser inside this node. Off: Flutter opens its own Chrome window."
>
<input
type="checkbox"
checked={embedsFlutterWeb(config)}
onChange={(e) => patch({ embedBrowser: e.target.checked ? true : undefined }, { changesRun: true })}
/>
Show web inside this node
</label>
)}
</div>
)}
{(note || blocker) && (
<div className={`run-bar__note run-bar__note--${note?.kind ?? 'error'}`}>{note?.text ?? blocker}</div>
)}
{browserPanel && (
<div ref={panelRef} className="run-sim-host">
<div className="run-web">
<BrowserSurface
nodeId={`${nodeId}.web`}
url={browserPanel.url ?? ''}
onUrlChange={onBrowserUrl}
onTitleChange={ignoreTitle}
blank={
<div className="run-web__waiting">
{running ? 'Waiting for the run to print its local address… or type one above.' : 'Run it to show its page here — or type an address above.'}
</div>
}
/>
</div>
</div>
)}
{simulator && (
<div ref={panelRef} className="run-sim-host">
<SimulatorView
streamId={`${nodeId}.sim`}
config={simulator}
onConfig={onSimConfig}
label={simulator.name ?? 'Simulator'}
className="run-sim"
barExtras={
<button className="run-bar__icon" title="Pop out into its own node" aria-label="Pop out" onClick={popOut}>
⇱
</button>
}
/>
</div>
)}
</div>
)
}
/** The browser panel keeps no title (the run node has its own); stable, so the page's listeners
* are not re-attached on every render. */
function ignoreTitle(): void {}
function previewButtonTitle(kind: PreviewKind, open: boolean, poppedOut: boolean): string {
const what = kind === 'browser' ? 'browser' : 'simulator'
if (open) return `Hide the ${what}`
if (poppedOut) return `Dock the ${what} back into this node`
return 'Show a simulator or a browser here'
}