The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import 'dart:math' as math;
// A browser leaves the Finder out of main.dart.js until a Finder tile is drawn.
import '../finder/widgets/finder_pane_panel.dart'
if (dart.library.js_interop) '../web/parts/finder_pane_panel.dart';
import '../super_tabs/pane.dart';
import '../super_tabs/saved_session.dart';
import '../sharing/shared_harness_panel.dart';
import 'dart:async';
import 'dart:typed_data';
import 'package:harness/shared/theme/app_icons.dart';
import 'package:desktop_drop/desktop_drop.dart';
import 'package:flutter/material.dart';
import 'package:xterm/xterm.dart';
import 'window_chrome.dart';
import '../clipboard/image_bytes.dart';
import '../core/runtime_platform.dart';
import '../core/dsh_catalog.dart' show DshEntry;
import '../core/models.dart' show Agent, ConnectionStatus, kUntitledPane;
import '../clipboard/native_clipboard.dart';
import '../shared/theme/app_theme.dart' as grid;
import '../shared/theme/appearance_prefs_store.dart';
// `hide TerminalKey`: this file's own shortcut-label class, unused here, collides with xterm's
// `TerminalKey` (needed for the local image-drop Ctrl+V nudge — see `_dropImage`).
import '../shortcuts/app_shortcuts.dart' hide TerminalKey;
import '../state/account_devices.dart' show registerRefusalSentence;
import '../state/app_state.dart';
import '../state/harness_sessions.dart' show heldLaunchDetail;
import '../state/pane_preset.dart';
import '../state/pane_arrangement.dart';
import 'pane_fixed_width.dart';
import '../state/terminal_pane.dart';
import '../state/workspace_chrome.dart';
import '../terminal/terminal_binary.dart';
import '../terminal/terminal_text.dart';
import '../terminal/terminal_session.dart';
import '../theme/app_theme.dart';
import 'agent_drag.dart';
import 'cloud_chat_pane.dart';
import 'harness_join_guide_screen.dart';
import 'link_machine_screen.dart';
import 'new_agent_dialog.dart';
import 'new_device_notice.dart' show DeviceListReviewLine, showDeviceListReview;
import 'delete_agent_dialog.dart';
import 'restart_agent_action.dart';
import 'terminal_panel.dart';
import 'harness_activity_mark.dart';
import 'web_pane_panel.dart';
import 'transient_menus.dart';
import 'pane_resize_handle.dart';
import 'pane_split_edges.dart';
import '../agent_messages/pane_shared_chips.dart';
import 'box_chrome.dart' show kPaneInset, terminalPaneBorder, PaneOpacity;
import 'desktop_chrome.dart';
/// The view drawn alone when only one fits (a phone): the real zoom, else the
/// focused view, else the first before anything has focus.
int? soloPaneId(AppNotifier app) =>
app.zoomedPaneId ?? app.focusedPaneId ?? app.panes.firstOrNull?.id;
/// Terminal views arranged by the chosen preset. Swarms keep each view under
/// one stable parent as its rectangle, visibility and keyboard focus change.
class PaneGrid extends StatelessWidget {
const PaneGrid({
super.key,
required this.notifier,
this.swarmMode = false,
this.empty,
this.onOpenModels,
this.onSplitPane,
this.soloFocused = false,
this.companionViewer,
this.companionConversation,
this.devicesViewer,
this.devicesConversation,
});
final AppNotifier notifier;
final bool swarmMode;
final Widget? empty;
final void Function(int paneId, String machineId, String agentId)?
onOpenModels;
final void Function(int paneId, PaneResizeAxis axis)? onSplitPane;
/// Draw only the focused view, full size, as if zoomed — without zooming:
/// the tab's saved layout and zoom stay as they are (a phone shows one
/// harness at a time; the same desk on a computer keeps its grid).
final bool soloFocused;
/// The built-in companion DSH viewer; its agent uses the ordinary terminal.
final WidgetBuilder? companionViewer;
final WidgetBuilder? companionConversation;
final WidgetBuilder? devicesViewer;
final WidgetBuilder? devicesConversation;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return ValueListenableBuilder<AgentDragRef?>(
valueListenable: agentDrag,
builder: (context, dragging, _) {
if (swarmMode) {
return _SwarmCanvas(
notifier: notifier,
dragging: dragging,
empty: empty,
onOpenModels: onOpenModels,
onSplitPane: onSplitPane,
soloFocused: soloFocused,
companionViewer: companionViewer,
companionConversation: companionConversation,
devicesViewer: devicesViewer,
devicesConversation: devicesConversation,
);
}
final panes = notifier.panes;
final zoomed = notifier.zoomedPaneId;
final visible = zoomed == null
? panes
: panes.where((p) => p.id == zoomed).toList();
Widget cell(TerminalPane pane, {bool visible = true}) => _PaneCell(
key: pane.cellKey,
notifier: notifier,
pane: pane,
dragging: dragging,
visible: visible,
swarmMode: swarmMode,
onOpenModels: onOpenModels,
onSplitPane: onSplitPane,
companionViewer: companionViewer,
companionConversation: companionConversation,
devicesViewer: devicesViewer,
devicesConversation: devicesConversation,
);
final cells = <Widget>[
for (final pane in visible) cell(pane),
if (!swarmMode && dragging != null && notifier.canAddPane)
_DropZone(
notifier: notifier,
paneId: null,
dragging: dragging,
child: const _AddSlot(),
),
];
return panes.isEmpty
? empty ?? _EmptyGrid(notifier: notifier)
: _arrange(cells);
},
);
}
/// Keyed on the number of CELLS, not of panes: mid-drag an extra drop slot
/// joins them, and the grid on screen is the one the shape has to describe.
Widget _arrange(List<Widget> cells) {
final preset = notifier.presetFor(cells.length);
if (preset != null &&
(preset.usesTileGeometry ||
(preset == PanePreset.rows && cells.length > 2))) {
return _PresetCells(cells: cells, preset: preset);
}
// Lattices use a stated or measured column count. Spanning presets keep
// their own geometry, including the default five-pane middle column.
if (cells.length == 5 && preset == PanePreset.middleMain) {
// The one five-tile shape that is not a lattice: a full-height column down
// the middle, two stacked either side. Read in TILE order — 1 and 4 to the
// left, 2 in the middle, 3 and 5 to the right — which is how a person
// numbers them, and it is the same order `PanePreset.tilesFor` describes,
// so the picker's drawing and this cannot disagree.
return _Axis(
axis: Axis.horizontal,
children: [
_Axis(axis: Axis.vertical, children: [cells[0], cells[3]]),
cells[1],
_Axis(axis: Axis.vertical, children: [cells[2], cells[4]]),
],
);
}
if (cells.length > 4) {
return _Lattice(
cells: cells,
columns: preset?.statedColumns,
onColumns: (c) => notifier.gridColumns = c,
);
}
switch (cells.length) {
case 1:
return cells[0];
case 2:
return LayoutBuilder(
builder: (context, constraints) {
// `splitLong` halves whichever side is longer, so two tiles on a
// wide window are columns and two on a tall one are rows: a
// terminal's usable size is its column count first, and halving the
// short axis is what protects it. The other two say it outright.
final side = switch (preset) {
PanePreset.columns => Axis.horizontal,
PanePreset.rows => Axis.vertical,
_ =>
constraints.maxWidth >= constraints.maxHeight
? Axis.horizontal
: Axis.vertical,
};
return _Axis(axis: side, children: cells);
},
);
case 3:
// Three across has no spanning tile, so it is the lattice with its
// column count stated rather than measured — the same widget the
// five-and-up grid uses, which is what makes its walls, its 40-column
// floor and its scroll fallback behave identically everywhere.
if (preset == PanePreset.cols3) {
return _Lattice(cells: cells, columns: 3);
}
// The rest each have ONE spanning tile — the whole reason three is not
// a grid. Which tile spans, and on which side, is the choice.
return switch (preset) {
PanePreset.oneOverTwo => _Axis(
axis: Axis.vertical,
children: [
cells[0],
_Axis(axis: Axis.horizontal, children: [cells[1], cells[2]]),
],
),
PanePreset.mainLeft => _Axis(
axis: Axis.horizontal,
children: [
cells[0],
_Axis(axis: Axis.vertical, children: [cells[1], cells[2]]),
],
),
_ => _Axis(
axis: Axis.vertical,
children: [
_Axis(axis: Axis.horizontal, children: [cells[0], cells[1]]),
cells[2],
],
),
};
default:
if (preset == PanePreset.cols4) {
return _Lattice(cells: cells, columns: 4);
}
if (preset == PanePreset.mainAndStack) {
return _Axis(
axis: Axis.horizontal,
children: [
cells[0],
_Axis(
axis: Axis.vertical,
children: [cells[1], cells[2], cells[3]],
),
],
);
}
// The square. Both rows are cut at the same place, so the column wall
// is one line down the whole grid rather than a staircase.
return _Axis(
axis: Axis.vertical,
children: [
_Axis(axis: Axis.horizontal, children: [cells[0], cells[1]]),
_Axis(axis: Axis.horizontal, children: [cells[2], cells[3]]),
],
);
}
}
}
/// Switching layouts must not reparent terminal subtrees. GlobalKey grafting
/// preserves State but invalidates inherited dependencies throughout each view.
/// This canvas changes rectangles under a single Stack instead, including when
/// a large Swarm needs to scroll. Unvisited views remain unmounted.
class _SwarmCanvas extends StatefulWidget {
const _SwarmCanvas({
required this.notifier,
required this.dragging,
this.empty,
this.onOpenModels,
this.onSplitPane,
this.soloFocused = false,
this.companionViewer,
this.companionConversation,
this.devicesViewer,
this.devicesConversation,
});
final AppNotifier notifier;
final AgentDragRef? dragging;
final Widget? empty;
final void Function(int paneId, String machineId, String agentId)?
onOpenModels;
final void Function(int paneId, PaneResizeAxis axis)? onSplitPane;
final bool soloFocused;
final WidgetBuilder? companionViewer;
final WidgetBuilder? companionConversation;
final WidgetBuilder? devicesViewer;
final WidgetBuilder? devicesConversation;
@override
State<_SwarmCanvas> createState() => _SwarmCanvasState();
}
class _SwarmCanvasState extends State<_SwarmCanvas> {
final _scroll = ScrollController(keepScrollOffset: false);
final _horizontalScroll = ScrollController(keepScrollOffset: false);
final _offsets = <String, Offset>{};
final _inputLayers = <int, GlobalKey<_PaneLayerState>>{};
final _idleFocus = FocusNode(
debugLabel: 'Tab navigation',
skipTraversal: true,
);
late Object _lastInputDestination;
final _resizeFocus = FocusNode(debugLabel: 'Resize focused harness');
final _resizeHelp = OverlayPortalController();
VoidCallback? _unregisterResizeHelp;
void _hideResizeHelp() {
if (_resizeHelp.isShowing) _resizeHelp.hide();
_unregisterResizeHelp?.call();
_unregisterResizeHelp = null;
}
late int _resizeRequest;
late String _activeId;
late int _focusRequest;
Size? _viewportSize;
bool _focusRevealPending = false;
/// The most columns the host draws at this window's width, read at build.
int? _maxColumns;
/// The view drawn alone: the real zoom, or [soloPaneId] when solo.
int? get _shownZoom => widget.soloFocused
? soloPaneId(widget.notifier)
: widget.notifier.zoomedPaneId;
Object get _inputDestination => (
widget.notifier.activeSwarmId,
widget.notifier.focusedPaneId,
widget.notifier.paneFocusRequest,
_shownZoom,
widget.notifier.tabStripFocused,
);
@override
void initState() {
super.initState();
_lastInputDestination = _inputDestination;
_resizeRequest = widget.notifier.paneResizeRequest;
_activeId = widget.notifier.activeSwarmId;
_focusRequest = widget.notifier.paneFocusRequest;
widget.notifier.addListener(_onAppChanged);
terminalFontStore.addListener(_onFontChanged);
appearancePrefsStore.addListener(_onFontChanged);
}
@override
void didUpdateWidget(_SwarmCanvas oldWidget) {
super.didUpdateWidget(oldWidget);
if (!identical(oldWidget.notifier, widget.notifier)) {
oldWidget.notifier.removeListener(_onAppChanged);
widget.notifier.addListener(_onAppChanged);
_offsets.clear();
_activeId = widget.notifier.activeSwarmId;
_focusRequest = widget.notifier.paneFocusRequest;
_resizeRequest = widget.notifier.paneResizeRequest;
_lastInputDestination = _inputDestination;
if (_scroll.hasClients) _scroll.jumpTo(0);
if (_horizontalScroll.hasClients) _horizontalScroll.jumpTo(0);
}
}
void _onAppChanged() {
final app = widget.notifier;
if (_lastInputDestination != _inputDestination) {
_lastInputDestination = _inputDestination;
_syncInputFocus();
}
if (_resizeRequest != app.paneResizeRequest) {
_resizeRequest = app.paneResizeRequest;
_resizeFocus.requestFocus();
_resizeHelp.show();
_unregisterResizeHelp ??= registerTransientMenu(_hideResizeHelp);
}
if (_activeId != app.activeSwarmId) {
_hideResizeHelp();
_offsets[_activeId] = Offset(
_horizontalScroll.hasClients ? _horizontalScroll.offset : 0,
_scroll.hasClients ? _scroll.offset : 0,
);
_activeId = app.activeSwarmId;
// The notification precedes the frame. Restore before layout/paint so
// switching never briefly displays the previous Swarm's scroll offset.
final offset = _offsets[_activeId] ?? Offset.zero;
if (_scroll.hasClients) _scroll.jumpTo(offset.dy);
if (_horizontalScroll.hasClients) _horizontalScroll.jumpTo(offset.dx);
final open = app.swarms.map((s) => s.id).toSet();
_offsets.removeWhere((id, _) => !open.contains(id));
}
if (_focusRequest != app.paneFocusRequest) {
_focusRequest = app.paneFocusRequest;
_focusRevealPending = true;
_revealFocusedPane();
}
setState(() {});
}
void _syncInputFocus() {
final app = widget.notifier;
final visible = {
for (final pane in app.panes)
if (_shownZoom == null || pane.id == _shownZoom) pane.id,
};
// Exclude the outgoing views and enable the destination's existing focus
// tree now. Painting/layout still happens in the normal scheduled frame.
for (final entry in _inputLayers.entries) {
entry.value.currentState?.prepareInput(visible.contains(entry.key));
}
if (!_idleFocus.canRequestFocus ||
ModalRoute.of(context)?.isCurrent == false) {
return;
}
// A closed tab left the keyboard on the tab strip: the tab shown now does
// not take it until the person goes into it. The screen focuses the strip.
if (app.tabStripFocused) return;
if (app.focusedPane?.session?.focusInput() != true &&
app.focusedPane?.focusViewerInput?.call() != true) {
// Blank pages and not-yet-mounted destinations must release the old
// terminal's text client immediately, without focusing welcome search.
_idleFocus.requestFocus();
}
}
void _revealFocusedPane({bool correctingLayout = false}) {
final viewport = _viewportSize;
if (viewport == null || !_scroll.hasClients) return;
final app = widget.notifier;
final panes = app.panes
.where((p) => _shownZoom == null || p.id == _shownZoom)
.toList();
final index = panes.indexWhere((p) => p.id == app.focusedPaneId);
if (index < 0) return;
final geometry = _SwarmGeometry(
count: panes.length,
viewport: viewport,
preset: app.presetFor(panes.length),
minimum: _MinTile.of(),
sizes: app.activeSwarm.paneSizes,
).within(_maxColumns, viewport: viewport, minimum: _MinTile.of());
final rect = geometry.rectangles[index];
void reveal(
ScrollController scroll,
double start,
double end,
double viewportExtent,
double canvasExtent,
) {
if (!scroll.hasClients) return;
final current = scroll.offset;
final offset = start < current || end - start > viewportExtent
? start
: end > current + viewportExtent
? end - viewportExtent
: current;
final target = offset.clamp(
0.0,
(canvasExtent - viewportExtent).clamp(0.0, double.infinity),
);
if (target != current) {
if (correctingLayout) {
// Correct before the scroll view lays out, without notifying during
// layout. Both axes retain their controllers and terminal children.
scroll.position.correctPixels(target);
} else {
scroll.jumpTo(target);
}
}
}
reveal(_scroll, rect.top, rect.bottom, viewport.height, geometry.height);
reveal(
_horizontalScroll,
rect.left,
rect.right,
viewport.width,
geometry.width,
);
}
void _onFontChanged() => setState(() {});
@override
void dispose() {
widget.notifier.removeListener(_onAppChanged);
_unregisterResizeHelp?.call();
terminalFontStore.removeListener(_onFontChanged);
appearancePrefsStore.removeListener(_onFontChanged);
_resizeFocus.dispose();
_idleFocus.dispose();
_scroll.dispose();
_horizontalScroll.dispose();
super.dispose();
}
/// Cache retained terminal presentation, including read-only output.
/// Never-attached connection/setup views still read their complete state.
/// Theme/font dependencies continue updating retained descendants directly.
Object? _presentation(TerminalPane pane, bool visible) {
if (!visible) return null;
final app = widget.notifier;
final machine = app.stateOf(pane.machineId);
final agent = machine?.agents
.where((a) => a.id == pane.agentId)
.firstOrNull;
final session = pane.session;
if (session == null) return Object();
return (
notifier: app,
location: (app.activeSwarmId, app.panes.indexOf(pane)),
layoutRequest: (app.paneLayoutRequest, app.panes.length, _shownZoom),
machine: machine?.machine,
local: machine?.isLocalMachine,
online: machine?.nodeOnline,
// The web words a computer on its way back; the pane follows it.
connection: machine?.connectionStatus,
needsLink: machine?.needsLink,
localTransport: machine?.usesLocalTransport,
agent: agent,
project: agent == null ? null : machine?.projectOf(agent),
session: session,
terminal: session.terminal,
name: session.agentName,
status: session.status,
error: session.errorMessage ?? session.errorCode,
link: session.linkMode,
upload: session.uploadProgress,
focused: app.isPaneFocused(pane.id),
emphasized: app.isPaneEmphasized(pane),
focusRequest: app.isPaneFocused(pane.id) ? app.paneFocusRequest : 0,
focusByUser: app.paneFocusByUser,
single: app.panes.length == 1,
pinned: app.isPanePinned(pane),
zoomed: app.zoomedPaneId == pane.id,
canSplitRight:
app.preparePaneSplit(PaneResizeAxis.x, paneId: pane.id) != null,
canSplitDown:
app.preparePaneSplit(PaneResizeAxis.y, paneId: pane.id) != null,
composer: pane.composerVisible,
blocked:
app.questionFor(pane.machineId, pane.agentId ?? session.agentId) !=
null,
dragging: widget.dragging,
);
}
/// How [count] panes of the active tab are laid out in [viewport].
_SwarmGeometry _geometry(int count, Size viewport) => _SwarmGeometry(
count: count,
viewport: viewport,
preset: widget.notifier.presetFor(count),
minimum: _MinTile.of(),
sizes: widget.notifier.activeSwarm.paneSizes,
);
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return LayoutBuilder(
builder: (context, constraints) {
final app = widget.notifier;
final viewportChanged = _viewportSize != constraints.biggest;
_viewportSize = constraints.biggest;
if (_focusRevealPending && viewportChanged) {
_revealFocusedPane(correctingLayout: true);
}
_focusRevealPending = false;
final visible = [
for (final pane in app.panes)
if (_shownZoom == null || pane.id == _shownZoom) pane,
];
final layout = _geometry(visible.length, constraints.biggest);
// Solo draws one pane of a desk that is still there: the desk is what
// gets recorded, so a split made on a phone has something to divide.
final desk = _shownZoom == null
? layout
: widget.soloFocused && app.zoomedPaneId == null
? _geometry(app.panes.length, constraints.biggest)
: null;
if (desk != null) {
app.activeSwarm.arranged = desk.arrangement;
app.activeSwarm.arrangedKey = desk.key;
final minimum = _MinTile.of();
app.activeSwarm.arrangedMinimum = Size(
(minimum.width + kPaneGap) / (desk.width + kPaneGap),
(minimum.height + kPaneGap) / (desk.height + kPaneGap),
);
}
if (layout.columns != null) app.gridColumns = layout.columns;
_maxColumns = WorkspaceChrome.of(context)
.maxPaneColumnsAt(MediaQuery.sizeOf(context).width);
final drawn = layout.within(
_maxColumns,
viewport: constraints.biggest,
minimum: _MinTile.of(),
);
// A tile that asks for its own width (a Finder showing only its
// files) takes it; its divider is not dragged while it does.
final pinned = pinFixedColumn(
drawn.rectangles,
[for (final pane in visible) pane.fixedWidth],
Size(drawn.width, drawn.height),
gap: kPaneGap,
minOther: _MinTile.of().width,
);
final tiles = pinned ?? drawn.rectangles;
final rectangles = {
for (var i = 0; i < visible.length; i++) visible[i].id: tiles[i],
};
final retainedIds = app.allPanes.map((pane) => pane.id).toSet();
_inputLayers.removeWhere((id, _) => !retainedIds.contains(id));
final scrollBehavior = ScrollConfiguration.of(context);
// Both scroll views stay mounted when content fits. Stable ancestry
// retains terminal views as a split grows or shrinks the canvas.
return Focus(
focusNode: _idleFocus,
includeSemantics: false,
child: Scrollbar(
key: const ValueKey('swarm-horizontal-scrollbar'),
controller: _horizontalScroll,
thumbVisibility: drawn.width > constraints.maxWidth,
scrollbarOrientation: ScrollbarOrientation.bottom,
notificationPredicate: (notification) =>
notification.depth == 1 &&
notification.metrics.axis == Axis.horizontal,
// Keep the horizontal thumb at the viewport's bottom even when the
// workspace also scrolls vertically. Terminals retain their bars.
child: SingleChildScrollView(
controller: _scroll,
child: ScrollConfiguration(
behavior: scrollBehavior.copyWith(scrollbars: false),
child: SingleChildScrollView(
controller: _horizontalScroll,
scrollDirection: Axis.horizontal,
child: ScrollConfiguration(
behavior: scrollBehavior,
child: SizedBox(
width: drawn.width,
height: drawn.height,
child: Stack(
children: [
if (visible.isEmpty)
Positioned.fill(
child: widget.empty ?? _EmptyGrid(notifier: app),
),
for (final pane in app.allPanes)
if (rectangles.containsKey(pane.id) ||
pane.lastViewSize != null)
Positioned.fromRect(
key: ValueKey(pane.id),
rect:
rectangles[pane.id] ??
Offset.zero & pane.lastViewSize!,
child: _PaneLayer(
key: _inputLayers.putIfAbsent(
pane.id,
() => GlobalKey<_PaneLayerState>(),
),
session: pane.session,
visible: rectangles.containsKey(pane.id),
presentation: _presentation(
pane,
rectangles.containsKey(pane.id),
),
child: _PaneCell(
key: pane.cellKey,
notifier: app,
pane: pane,
dragging: widget.dragging,
visible: rectangles.containsKey(pane.id),
swarmMode: true,
onOpenModels: widget.onOpenModels,
onSplitPane: widget.onSplitPane,
solo: widget.soloFocused,
companionViewer: widget.companionViewer,
companionConversation:
widget.companionConversation,
devicesViewer: widget.devicesViewer,
devicesConversation:
widget.devicesConversation,
),
),
),
// Dividers resize the recorded layout, so none
// while a narrower drawing stands in for it.
if (_shownZoom == null &&
pinned == null &&
identical(drawn, layout) &&
layout.arrangement?.dividers.isNotEmpty == true)
Positioned.fill(child: _resizeLayer(layout)),
],
),
),
),
),
),
),
),
);
},
);
}
Widget _resizeLayer(_SwarmGeometry layout) {
final app = widget.notifier;
final swarmId = app.activeSwarmId;
final arrangement = layout.arrangement!;
final focused = app.panes.indexWhere(
(pane) => pane.id == app.focusedPaneId,
);
final preferred = arrangement.dividers
.where((divider) => divider.touches(focused))
.firstOrNull;
final extent = Size(layout.width + kPaneGap, layout.height + kPaneGap);
final reach = math.max(kPaneGap, _kDividerReach);
final floor = _MinTile.of();
final minimum = Size(
(floor.width + kPaneGap) / extent.width,
(floor.height + kPaneGap) / extent.height,
);
return OverlayPortal(
controller: _resizeHelp,
overlayChildBuilder: (context) => Positioned(
bottom: 24,
left: 24,
right: 24,
child: IgnorePointer(
child: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 760),
child: DesktopDialogSurface(
key: const ValueKey('pane-resize-hint'),
radius: DesktopChrome.menuRadius,
child: Padding(
padding: const EdgeInsets.symmetric(
horizontal: 16,
vertical: 12,
),
child: Wrap(
spacing: 16,
runSpacing: 8,
crossAxisAlignment: WrapCrossAlignment.center,
children: [
Text(
'Resize panes',
style: DesktopChrome.control(medium: true),
),
for (final (key, action) in const [
('Arrow keys', 'Adjust'),
('Shift', 'Larger steps'),
('Tab', 'Next divider'),
('Esc', 'Done'),
])
Text.rich(
TextSpan(
children: [
TextSpan(
text: '$key ',
style: DesktopChrome.control(medium: true),
),
TextSpan(text: action),
],
),
style: DesktopChrome.metadata(),
),
],
),
),
),
),
),
),
),
child: FocusScope(
onFocusChange: (focused) {
if (!focused) _hideResizeHelp();
},
child: Stack(
children: [
for (final divider in arrangement.dividers)
Positioned.fromRect(
key: ValueKey('resize:$swarmId:${layout.key}:${divider.id}'),
rect: divider.axis == PaneResizeAxis.x
? Rect.fromLTWH(
divider.position * extent.width -
(kPaneGap + reach) / 2,
divider.start * extent.height,
reach,
(divider.end - divider.start) * extent.height -
kPaneGap,
)
: Rect.fromLTWH(
divider.start * extent.width,
divider.position * extent.height -
(kPaneGap + reach) / 2,
(divider.end - divider.start) * extent.width - kPaneGap,
reach,
),
child: PaneResizeHandle(
arrangement: arrangement,
divider: divider,
extent: extent,
minimum: minimum,
focusNode: identical(divider, preferred)
? _resizeFocus
: null,
onChanged: (next, persist) => app.resizePanes(
swarmId,
layout.key!,
next,
persist: persist,
),
onLeave: () {
final id = app.focusedPaneId;
if (id != null) app.focusPane(id, reveal: true);
},
),
),
],
),
),
);
}
}
/// Convert the same unit rectangles used by the layout picker and keyboard
/// navigation to pixels. A boundary at fraction f maps to f * (extent + gap);
/// subtracting one gap from each tile preserves spanning and nested cuts.
class _SwarmGeometry {
_SwarmGeometry({
required int count,
required Size viewport,
required PanePreset? preset,
required Size minimum,
Map<String, PaneArrangement> sizes = const {},
}) : width = viewport.width,
height = viewport.height {
if (count == 0) return;
if (count == 1) {
rectangles = [Offset.zero & viewport];
arrangement = PaneArrangement(const [Rect.fromLTRB(0, 0, 1, 1)]);
key = '1:single';
return;
}
var shape = preset ?? PanePreset.defaultFor(count)!;
if (shape == PanePreset.splitLong && viewport.height > viewport.width) {
shape = PanePreset.rows;
}
final manual = sizes['$count:manual'];
if (manual == null &&
(shape == PanePreset.auto || shape.statedColumns != null)) {
columns =
(shape.statedColumns ?? (viewport.width / minimum.width).floor())
.clamp(1, count);
final rows = (count / columns!).ceil();
height = (rows * minimum.height + kPaneGap * (rows - 1)).clamp(
viewport.height,
double.infinity,
);
}
key = manual != null
? '$count:manual'
: '$count:${(preset ?? PanePreset.defaultFor(count))!.id}:${columns ?? 0}:${shape.id}';
arrangement =
sizes[key] ?? PaneArrangement(shape.tilesFor(count, columns: columns));
for (final tile in arrangement!.tiles) {
if (manual != null) {
width = ((minimum.width + kPaneGap) / tile.width - kPaneGap).clamp(
width,
double.infinity,
);
}
height = ((minimum.height + kPaneGap) / tile.height - kPaneGap).clamp(
height,
double.infinity,
);
}
rectangles = _pixels(arrangement!.tiles, width, height);
}
/// [tiles] across [viewport]'s width, each row at least [minimum] tall:
/// taller than the viewport, and scrolled, when the rows need it.
_SwarmGeometry._balanced(
List<Rect> tiles, {
required Size viewport,
required Size minimum,
}) : width = viewport.width,
height = viewport.height {
final rows = {for (final tile in tiles) tile.top}.length;
height = (rows * minimum.height + kPaneGap * (rows - 1)).clamp(
viewport.height,
double.infinity,
);
arrangement = PaneArrangement(tiles);
rectangles = _pixels(tiles, width, height);
}
/// This layout drawn at most [maxColumns] wide, the tiles in balanced rows:
/// a tablet browser's grid ([WorkspaceChrome.maxPaneColumnsAt]). Only the
/// drawing — what the tab records stays this layout, so the same desk keeps
/// its grid on a computer. Itself when it is no wider than that.
_SwarmGeometry within(
int? maxColumns, {
required Size viewport,
required Size minimum,
}) {
final tiles = arrangement?.tiles;
if (maxColumns == null || tiles == null) return this;
final columns = {for (final tile in tiles) tile.left}.length;
if (columns <= maxColumns) return this;
final shape = switch (maxColumns) {
<= 2 => PanePreset.balanced2,
3 => PanePreset.balanced3,
4 => PanePreset.balanced4,
_ => PanePreset.balanced5,
};
return _SwarmGeometry._balanced(
shape.tilesFor(tiles.length),
viewport: viewport,
minimum: minimum,
);
}
/// Unit [tiles] in pixels on a [width] by [height] canvas. A boundary at
/// fraction f lands at f * (extent + gap), less one gap per tile.
static List<Rect> _pixels(List<Rect> tiles, double width, double height) => [
for (final tile in tiles)
Rect.fromLTWH(
tile.left * (width + kPaneGap),
tile.top * (height + kPaneGap),
(tile.width * (width + kPaneGap) - kPaneGap).clamp(0, double.infinity),
(tile.height * (height + kPaneGap) - kPaneGap).clamp(
0,
double.infinity,
),
),
];
String? key;
PaneArrangement? arrangement;
double width, height;
int? columns;
List<Rect> rectangles = const [];
}
/// Non-retained grids use the same geometry for the new spanning presets.
/// The active Swarm canvas continues to keep all terminal subtrees in place.
class _PresetCells extends StatelessWidget {
const _PresetCells({required this.cells, required this.preset});
final List<Widget> cells;
final PanePreset preset;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return LayoutBuilder(
builder: (context, constraints) {
final minimum = _MinTile.of();
final geometry = _SwarmGeometry(
count: cells.length,
viewport: constraints.biggest,
preset: preset,
minimum: Size(minimum.width, minimum.height),
);
final canvas = SizedBox(
width: constraints.maxWidth,
height: geometry.height,
child: Stack(
children: [
for (var i = 0; i < cells.length; i++)
Positioned.fromRect(
rect: geometry.rectangles[i],
child: ClipRect(child: cells[i]),
),
],
),
);
return geometry.height > constraints.maxHeight
? SingleChildScrollView(child: canvas)
: canvas;
},
);
}
}
/// A hidden view retains its last configuration and geometry. Status changes
/// update a replaced session; showing it applies fresh machine/agent metadata.
class _PaneLayer extends StatefulWidget {
const _PaneLayer({
super.key,
required this.session,
required this.visible,
required this.presentation,
required this.child,
});
final TerminalSession? session;
final bool visible;
final Object? presentation;
final Widget child;
@override
State<_PaneLayer> createState() => _PaneLayerState();
}
class _PaneLayerState extends State<_PaneLayer> {
final _focus = FocusNode(canRequestFocus: false, skipTraversal: true);
late Widget _layer = _buildLayer();
@override
void initState() {
super.initState();
prepareInput(widget.visible);
}
void prepareInput(bool visible) {
_focus.descendantsAreFocusable = visible;
_focus.descendantsAreTraversable = visible;
}
@override
void didUpdateWidget(_PaneLayer oldWidget) {
super.didUpdateWidget(oldWidget);
prepareInput(widget.visible);
if (oldWidget.visible != widget.visible ||
oldWidget.presentation != widget.presentation ||
!identical(oldWidget.session, widget.session)) {
_layer = _buildLayer();
}
}
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return _layer;
}
@override
void dispose() {
_focus.dispose();
super.dispose();
}
Widget _buildLayer() => Offstage(
offstage: !widget.visible,
child: TickerMode(
enabled: widget.visible,
child: Focus.withExternalFocusNode(
focusNode: _focus,
includeSemantics: false,
child: widget.child,
),
),
);
}
/// Five or more tiles: a grid, sized by what a terminal actually needs.
///
/// The column count is NOT ceil(sqrt(n)). A terminal is unusable below 40
/// columns — both this app and the daemon clamp there, and the daemon does it
/// silently, so a tile narrower than that shows a grid wider than its own box
/// and simply loses the right-hand text. So width decides how many columns
/// there can be, and the rows fall out of that.
///
/// Every line is draggable, and each axis remembers its own fractions.
class _Lattice extends StatelessWidget {
const _Lattice({required this.cells, this.columns, this.onColumns});
final List<Widget> cells;
/// Told what was actually laid out.
///
/// `auto` is the one shape whose column count is not in its own description —
/// it is measured from the window here — and ⌘↑ / ⌘↓ have to know the real
/// shape to move by a row. A plain field write, never a notify: this runs
/// inside build, and telling the tree to rebuild from inside its own build is
/// how a frame loop starts.
final ValueChanged<int>? onColumns;
/// A column count the shape asked for, instead of the one the width implies.
/// Still bounded by the floor below — a shape cannot conjure room that is
/// not there, and four columns on a narrow window is four unusable tiles.
final int? columns;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
final minTile = _MinTile.of();
return LayoutBuilder(
builder: (context, constraints) {
final n = cells.length;
// As many columns as the width can carry at the floor, never more than
// the tiles to put in them, and never fewer than one.
final byWidth = (constraints.maxWidth / minTile.width).floor();
final wanted = this.columns ?? byWidth;
final columns = wanted.clamp(1, n);
final rows = (n / columns).ceil();
onColumns?.call(columns);
// Does the window have the height for this many rows at the floor?
//
// When it does not, the grid SCROLLS rather than squeezing. Squeezing
// is the tempting answer and it is wrong twice over: the daemon clamps
// the terminal at twelve rows regardless, so the shrunk tile shows a
// grid taller than its own box, and the pane's own chrome overflows —
// measured at six tiles in 736px, which is 115px each against a 46px
// header. Nine usable tiles behind a scrollbar beat nine unusable ones
// in view.
final needed = rows * minTile.height + kPaneGap * (rows - 1);
final scrolls = needed > constraints.maxHeight;
final grid = _Axis(
axis: Axis.vertical,
children: [
for (var r = 0; r < rows; r++)
_Axis(
axis: Axis.horizontal,
children: [
for (var c = 0; c < columns; c++)
// The last row can be short. An empty box rather than a
// stretched neighbour: a tile that silently grows to twice
// its siblings reads as a layout bug, not as a spare slot.
// Clipped, because a tile can be squeezed below the floor:
// the grid still has to draw every pane it was given, and
// a window too small for this many is the user's call to
// make. What it must NOT do is let a pane paint outside
// its own box — that is a render overflow, which is a bug
// whatever the window size.
if (r * columns + c < n)
ClipRect(child: cells[r * columns + c])
else
const SizedBox.shrink(),
],
),
],
);
if (!scrolls) return grid;
return SingleChildScrollView(
child: SizedBox(height: needed, child: grid),
);
},
);
}
}
/// N children along one axis, sharing the space evenly, with a gap between each
/// pair.
///
/// The proportions come from the SHAPE — which nesting it puts the tiles in —
/// and nothing moves them. Dragging a
/// boundary used to be how you got a layout the app did not offer; now the
/// shapes themselves are the list, and a boundary that cannot be dragged does
/// not need a grab strip, a cursor, a floor to clamp against, or a remembered
/// position — all of which have gone with it.
class _Axis extends StatelessWidget {
const _Axis({required this.axis, required this.children});
final Axis axis;
final List<Widget> children;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
if (children.length < 2) {
return children.isEmpty ? const SizedBox.shrink() : children.first;
}
final laid = <Widget>[];
for (var i = 0; i < children.length; i++) {
// Equal shares, and no arithmetic here to disagree with the box being
// divided — every shape in this grid turns out to be an even cut at some
// level of nesting, including the main-and-stack one: half the width, and
// three equal rows in that half.
laid.add(Expanded(child: children[i]));
if (i < children.length - 1) laid.add(_Gap(axis: axis));
}
return Flex(
direction: axis,
// Stretch, so a gap spans the cross axis without being told a height it
// cannot know.
crossAxisAlignment: CrossAxisAlignment.stretch,
children: laid,
);
}
}
/// The smallest a tile may be dragged to, in pixels.
///
/// MEASURED, not guessed, and it is the whole reason a divider clamps at all:
/// both ends already floor a terminal at 40 columns and 12 rows, and the daemon
/// applies that floor SILENTLY (`boundedSize` in tmuxStream.ts). Drag a tile
/// narrower than 40 columns and nothing reports it — the pane simply shows a
/// grid wider than the space it has, clipped, with nothing on screen saying
/// why. So the divider stops where the terminal does.
///
/// The font is one process-wide setting, so one measurement serves every tile.
class _MinTile {
static TerminalStyle? _forStyle;
static Size _cached = Size.zero;
static Size of() {
final style = terminalFontStore.value;
if (identical(style, _forStyle)) return _cached;
// The renderer measures its cell by laying out ten 'm' and dividing; do the
// same here rather than inventing a second idea of how wide a column is.
final painter = TextPainter(
text: TextSpan(
text: 'mmmmmmmmmm',
style: terminalTextStyle(height: style.height),
),
textDirection: TextDirection.ltr,
)..layout();
final cellW = painter.width / 10;
final cellH = painter.height;
painter.dispose();
_forStyle = style;
// 46 is the pane header, which is chrome the terminal never gets.
_cached = Size(40 * cellW + 16, 46 + 12 * cellH + 8);
return _cached;
}
}
/// Pane gaps share the outer workspace inset in both directions.
double get kPaneGap => kPaneInset;
/// A divider's reach when panes touch: the Compact style has no gap to grab.
const double _kDividerReach = 8;
/// What shows through the gaps.
///
/// Space only separates when the two sides differ, and every tile is the
/// window's own colour — so on the window's own background the gaps would be
/// invisible and the grid would read as one enormous terminal with seams in it.
/// The first attempt used [AppPalette.cardBg], one step off the window — six
/// values apart in dark (#181818 against #1E1E1E). That is enough to see across
/// a whole panel and not nearly enough at the scale that matters here: a corner
/// curve is a few antialiased pixels wide, and against a background almost the
/// same colour it does not read as a curve at all, it reads as a dirty notch.
/// So the field is a deliberate step, not a nudge.
class GridField extends StatelessWidget {
const GridField({super.key, required this.child});
/// `linear-gradient(160deg, …)`. A CSS angle runs clockwise from north, so 160° points down and to
/// the right — which is (sin160, cos160) as an alignment pair, give or take the sign convention.
static const _plum = LinearGradient(
begin: Alignment(-0.342, -0.940),
end: Alignment(0.342, 0.940),
colors: [Color(0xFF3A1F2E), Color(0xFF4A2438), Color(0xFF1E1224)],
stops: [0, 0.5, 1],
);
/// `radial-gradient(55% 60% at 80% 18%, rgba(255,200,140,.6) 0, transparent 62%)`. A CSS percentage
/// position maps to an Alignment as `2p - 1`: 80% → 0.6, 18% → -0.64.
static const _amber = RadialGradient(
center: Alignment(0.6, -0.64),
radius: 0.55,
colors: [Color(0x99FFC88C), Color(0x00FFC88C)],
stops: [0, 0.62],
);
/// `radial-gradient(50% 55% at 12% 88%, rgba(230,90,110,.5) 0, transparent 62%)`.
static const _rose = RadialGradient(
center: Alignment(-0.76, 0.76),
radius: 0.5,
colors: [Color(0x80E65A6E), Color(0x00E65A6E)],
stops: [0, 0.62],
);
final Widget child;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return DecoratedBox(
decoration: const BoxDecoration(gradient: _plum),
child: DecoratedBox(
decoration: const BoxDecoration(gradient: _rose),
child: DecoratedBox(
decoration: const BoxDecoration(gradient: _amber),
child: child,
),
),
);
}
}
/// The space between two tiles.
///
/// It was a one-pixel line, and before that nine pixels of draggable grab strip
/// around one. A drawn boundary is the wrong tool here: every tile is already a
/// self-contained thing with its own header, its own engine and its own machine,
/// and a shared line asks the eye to work out which side each edge belongs to.
/// Set the tiles apart instead and the grouping needs no drawing at all — the
/// page shows through, and each pane reads as a card the way it reads on the
/// dial and in the rail.
///
/// Empty on purpose: what fills it is whatever is behind the grid, so a theme
/// change moves the background and this follows with no colour of its own.
class _Gap extends StatelessWidget {
const _Gap({required this.axis});
/// The axis the tiles are laid along — so the space between two columns is
/// vertical, and this is [Axis.horizontal].
final Axis axis;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return SizedBox(
width: axis == Axis.horizontal ? kPaneGap : null,
height: axis == Axis.horizontal ? null : kPaneGap,
);
}
}
/// How round a card's corners are — a pane, and the rail beside it. Public for the same reason
/// [kPaneGap] is: the rail is a card now, and two places typing 10 is how they drift apart.
const double kPaneRadius = grid.AppDesktop.paneRadius;
/// Whether panes are drawn square and touching.
bool get _compactPanes =>
appearancePrefsStore.value.panes.style == PaneStyle.compact;
/// How round a pane's corners are — the shared card radius, so a terminal does not read as a different
/// KIND of surface from the rail beside it. Square in the Compact style.
double get _paneRadius => _compactPanes ? 0 : kPaneRadius;
/// How much of a faded pane's content still shows.
const double _fadedContent = .55;
class _PaneCell extends StatelessWidget {
const _PaneCell({
super.key,
required this.notifier,
required this.pane,
required this.dragging,
this.visible = true,
this.swarmMode = false,
this.onOpenModels,
this.onSplitPane,
this.solo = false,
this.companionViewer,
this.companionConversation,
this.devicesViewer,
this.devicesConversation,
});
final AppNotifier notifier;
final TerminalPane pane;
final AgentDragRef? dragging;
final bool visible;
final bool swarmMode;
final void Function(int paneId, String machineId, String agentId)?
onOpenModels;
final void Function(int paneId, PaneResizeAxis axis)? onSplitPane;
final WidgetBuilder? companionViewer;
final WidgetBuilder? companionConversation;
final WidgetBuilder? devicesViewer;
final WidgetBuilder? devicesConversation;
/// Drawn alone under [PaneGrid.soloFocused]: it reads as the only view — no
/// dimming or zoom, since it already fills the screen. The focused rim still
/// identifies whether its machine is local or remote.
final bool solo;
bool get _single => solo || notifier.panes.length == 1;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return RepaintBoundary(
child: ValueListenableBuilder<AppearancePrefs>(
valueListenable: appearancePrefsStore,
builder: (context, prefs, _) => LayoutBuilder(
builder: (context, constraints) {
if (visible) pane.lastViewSize = constraints.biggest;
return _build(context, prefs);
},
),
),
);
}
/// Focus Follows Mouse, only while the keyboard is already in the grid: with
/// a menu, a dialog or a field elsewhere holding it, the pointer crossing a
/// pane must not take the keys away.
void _followMouse(BuildContext context) {
if (!visible || dragging != null || paneDragging.value != null) return;
if (notifier.isPaneFocused(pane.id)) return;
final holder = FocusManager.instance.primaryFocus;
final inGrid =
holder == null ||
holder == FocusManager.instance.rootScope ||
holder.context?.findAncestorWidgetOfExactType<PaneGrid>() != null;
if (inGrid) notifier.focusPane(pane.id, reveal: true);
}
Widget _build(BuildContext context, AppearancePrefs prefs) {
grid.AppTheme.watch(context);
final focused = visible && notifier.isPaneFocused(pane.id);
final remote = notifier.stateOf(pane.machineId)?.isLocalMachine == false;
// Keep the selected harness's terminal and viewers clear, including while
// a menu owns input. This changes paint, never the keyboard's destination.
final panes = prefs.panes;
final faded = !_single && !notifier.isPaneEmphasized(pane);
final agentId = pane.agentId;
final blocked =
agentId != null &&
notifier.questionFor(pane.machineId, agentId) != null;
return MouseRegion(
opaque: false,
onEnter: (_) {
if (panes.focusFollowsMouse) _followMouse(context);
},
child: Listener(
// The same press selects the pane and reaches its terminal or viewer.
behavior: HitTestBehavior.translucent,
onPointerDown: (_) => notifier.focusPane(pane.id),
child: ValueListenableBuilder<PaneDragRef?>(
valueListenable: paneDragging,
builder: (context, inFlight, child) => PaneSplitEdges(
enabled:
swarmMode &&
visible &&
!solo &&
agentId != null &&
pane.sharedHarness == null &&
onSplitPane != null &&
!notifier.activeSwarm.isUtility &&
!notifier.activeSwarm.isOrchestrator &&
notifier.zoomedPaneId == null &&
notifier.canAddPane &&
dragging == null &&
inFlight == null,
canSplitRight:
notifier.preparePaneSplit(PaneResizeAxis.x, paneId: pane.id) !=
null,
canSplitDown:
notifier.preparePaneSplit(PaneResizeAxis.y, paneId: pane.id) !=
null,
onSplit: (axis) => onSplitPane?.call(pane.id, axis),
child: child!,
),
// Passthrough: the frame keeps the exact constraints the grid gives it. The landing is ALWAYS
// here, painting nothing between landings, so a landing never reparents the terminal.
child: Stack(
fit: StackFit.passthrough,
children: [
_frame(
prefs,
focused: focused,
remote: remote,
fadeSurface: faded && panes.fade.fadesSurface,
fadeContent: faded && panes.fade.fadesContent,
highlight: focused && !_single && panes.highlightActive,
blocked: blocked,
),
Positioned.fill(
child: IgnorePointer(
child: _PaneLanding(notifier: notifier, pane: pane),
),
),
],
),
),
),
);
}
Widget _clipContent({required Widget child}) {
// GTK overlays cannot render under a rounded Flutter clip.
if (RuntimePlatform.isLinux && pane.isWeb) {
return ClipRect(child: child);
}
// Keep terminal backgrounds inside the pane rim.
return ClipRRect(
borderRadius: BorderRadius.circular(math.max(0, _paneRadius - 1)),
child: child,
);
}
Widget _frame(
AppearancePrefs prefs, {
required bool focused,
required bool remote,
required bool fadeSurface,
required bool fadeContent,
required bool highlight,
required bool blocked,
}) {
final compact = prefs.panes.style == PaneStyle.compact;
final rim = terminalPaneBorder(focused: focused, remote: remote);
// Touching panes share one line: each draws only its right and bottom, so
// two neighbours make one line rather than two. A border that isn't the
// same on every side can't carry a radius, and has none to carry here.
final radius = compact ? null : BorderRadius.circular(_paneRadius);
return Builder(
builder: (context) => Container(
key: ValueKey('pane-frame:${pane.id}'),
decoration: BoxDecoration(
// UNCHANGED, and deliberately: the terminal renders its own background
// inside this box, so a tile that stops matching the window colour
// shows a seam between the header strip and the terminal under it.
// What changes to make the gaps visible is the field BEHIND the grid
// (see _GridField), which is the part the gaps actually show.
//
// Over a Background: a terminal paints its own translucent fills, so
// the frame adds none (two would stack); a status pane has only this.
color: PaneOpacity.of(context) < 1 && pane.session != null
? null
: PaneOpacity.fill(
context,
pane.isDevices
? grid.AppPalette.swarmWelcome
: grid.AppPalette.windowBg,
),
borderRadius: radius,
// The rim is always drawn — it is what gives an unfocused card its
// edge, now that no shared line does. Devices is a page, not a card
// among cards: a ring around all of it says nothing.
border: pane.isDevices
? const Border.fromBorderSide(BorderSide.none)
: compact
? Border(right: rim, bottom: rim)
: Border.fromBorderSide(rim),
),
// A neutral gray veil lifts inactive backgrounds and softens their text
// without changing terminal colors. Paint attention above the veil so
// a waiting question keeps its full-strength amber rim. Keep this
// decoration present even when clear: inserting/removing it would
// reparent the terminal and lose its input, scroll and selection state.
// The active pane's highlight is here too, not on the rim: painted over
// the pane, it can't resize anything as focus moves.
foregroundDecoration: BoxDecoration(
color: fadeSurface
? const Color(0xFF9D9D9D).withValues(alpha: .30)
: null,
border: blocked
? Border.all(color: grid.AppPalette.warn, width: 2)
: highlight
? Border.all(color: AppColors.accent)
: null,
borderRadius: radius,
),
// Keeps a terminal's constant repainting inside its own layer instead
// of dirtying the whole grid. No key: nothing reads this boundary, it
// only has to exist.
child: _clipContent(
child: RepaintBoundary(
child: _FileDropZone(
notifier: notifier,
pane: pane,
visible: visible,
child: _SwapZone(
notifier: notifier,
paneId: pane.id,
child: _DropZone(
notifier: notifier,
paneId: pane.id,
dragging: dragging,
child: ValueListenableBuilder<PaneDragRef?>(
valueListenable: paneDragging,
// The tile being carried fades where it sits, so the grid shows
// where it came FROM while the ghost shows where it is going.
builder: (context, inFlight, child) => Opacity(
opacity: inFlight?.paneId == pane.id
? 0.35
: fadeContent
? _fadedContent
: 1,
child: child,
),
child: pane.isDevices
? devicesViewer?.call(context) ??
const SizedBox.shrink()
: pane.isCompanion
? companionViewer?.call(context) ??
const SizedBox.shrink()
: pane.agentId == null &&
devicesConversation != null &&
notifier.swarms.any(
(tab) =>
tab.isDevices && tab.panes.contains(pane),
)
? devicesConversation!(context)
: pane.agentId == null &&
companionConversation != null &&
notifier.swarms.any(
(tab) =>
tab.isCompanions &&
tab.panes.contains(pane),
)
? companionConversation!(context)
: _PaneContent(
notifier: notifier,
pane: pane,
single: _single,
visible: visible,
swarmMode: swarmMode,
onOpenModels: onOpenModels,
onSplitPane: onSplitPane,
),
),
),
),
),
),
),
),
);
}
}
/// ⌘B's receipt (`AppNotifier.markLanding`): the selection blue washes over the pane a task just landed
/// in, once, and fades, so the eye finds where the words went. A wash, not a rim: pane rims carry focus
/// and location and never glow (`desktop/design/desktop-design-system.md`). Optional motion, so Reduce
/// Motion skips it and the pane taking focus is the receipt.
const _landingFor = Duration(milliseconds: 900);
class _PaneLanding extends StatelessWidget {
const _PaneLanding({required this.notifier, required this.pane});
final AppNotifier notifier;
final TerminalPane pane;
@override
Widget build(BuildContext context) {
return ValueListenableBuilder(
valueListenable: notifier.paneLanding,
builder: (context, landing, _) {
if (landing == null ||
landing.machineId != pane.machineId ||
landing.agentId != pane.agentId ||
MediaQuery.disableAnimationsOf(context) ||
// Mounted after the moment has passed: nothing is landing now.
DateTime.now().difference(landing.at) > _landingFor) {
return const SizedBox.shrink();
}
return TweenAnimationBuilder<double>(
key: ValueKey('pane-landing:${pane.id}:${landing.seq}'),
tween: Tween(begin: 1, end: 0),
duration: _landingFor,
curve: Curves.easeOut,
onEnd: () => notifier.endLanding(landing.seq),
builder: (context, wash, _) => wash == 0
? const SizedBox.shrink()
: DecoratedBox(
key: ValueKey('pane-landing:${pane.id}'),
decoration: BoxDecoration(
color: DesktopChrome.selection.withValues(
alpha: DesktopChrome.selection.a * wash,
),
borderRadius: BorderRadius.circular(_paneRadius),
),
),
);
},
);
}
}
class _PaneContent extends StatelessWidget {
const _PaneContent({
required this.notifier,
required this.pane,
required this.single,
required this.visible,
required this.swarmMode,
this.onOpenModels,
this.onSplitPane,
});
final AppNotifier notifier;
final TerminalPane pane;
final bool single;
final bool visible;
final bool swarmMode;
final void Function(int paneId, String machineId, String agentId)?
onOpenModels;
final void Function(int paneId, PaneResizeAxis axis)? onSplitPane;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
final machine = notifier.stateOf(pane.machineId);
final swarmId = notifier.activeSwarmId;
void closeView() {
// A tab switch can precede the frame that replaces this callback. Shared
// panes keep their identity, so the pane id alone cannot identify its tab.
if (notifier.activeSwarmId != swarmId) return;
unawaited(notifier.requestClosePane(pane.id));
}
final superPane = SuperPane.maybeOf(context);
final VoidCallback? close = superPane == null ? closeView : null;
final failure = superPane?.failures[(pane.machineId, pane.agentId)];
if (failure != null) {
return _PaneStatus(
title:
superPane?.titleFor(pane.machineId, pane.agentId ?? '') ?? 'Agent',
icon: AppIcons.terminal,
message: failure,
actionLabel: 'Retry',
onAction: superPane?.onRetry,
);
}
VoidCallback? split(PaneResizeAxis axis) =>
swarmMode &&
onSplitPane != null &&
!notifier.activeSwarm.isUtility &&
!notifier.activeSwarm.isOrchestrator &&
notifier.preparePaneSplit(axis, paneId: pane.id) != null
? () => onSplitPane!(pane.id, axis)
: null;
if (pane.sharedHarness case final grant?) {
return SharedHarnessPanel(
key: ValueKey('shared-pane-${pane.id}'),
notifier: notifier,
pane: pane,
grant: grant,
visible: visible,
onClose: close,
hasAccess:
machine?.machine.sharedHarnesses.any((s) => s.id == grant.id) ==
true,
);
}
// A folder browsed in place: no agent and no terminal behind it.
if (pane.finderRoot case final root? when pane.isFinder) {
return FinderPanePanel(
key: ValueKey('finder-pane-${pane.id}'),
root: root,
onGuardClose: (guard) => pane.beforeClose = guard,
onFixedWidth: (width) => notifier.setPaneFixedWidth(pane.id, width),
compactHeader: swarmMode,
);
}
// A harness's viewer: the one tile that is not a terminal and not about a
// machine. Decided first, before anything below reads `agentId` — which a
// viewer keeps null on purpose (see TerminalPane.ownerAgentId).
if (pane.isWeb) {
final owner = machine?.agents
.where((agent) => agent.id == pane.ownerAgentId)
.firstOrNull;
return WebPanePanel(
key: ValueKey('web-pane-${pane.id}'),
notifier: notifier,
pane: pane,
title: viewerPaneName(owner, machine?.dsh.entries ?? const []),
visible: visible,
ownerName: owner?.name ?? pane.ownerAgentId ?? 'Viewer',
ownerEngine: owner?.identityEngine,
ownerDisplayName: owner?.identityDisplayName,
verdict: owner?.verdict,
working:
owner != null &&
notifier.agentIsProcessing(pane.machineId, owner.id),
onClose: close,
compactHeader: swarmMode,
zoomed: notifier.zoomedPaneId == pane.id,
onToggleZoom:
superPane == null &&
swarmMode &&
(!single || notifier.zoomedPaneId == pane.id)
? () {
notifier.focusPane(pane.id);
notifier.toggleZoomPane();
}
: null,
);
}
final session = pane.session;
final wantedAgentId = pane.agentId;
final activityMark = wantedAgentId == null
? null
: HarnessActivityMark(
app: notifier,
machineId: pane.machineId,
agentId: wantedAgentId,
visible: visible,
);
final agent = machine?.agents
.where((agent) => agent.id == wantedAgentId)
.firstOrNull;
final agentName = agent?.displayName;
// A cloud harness has no terminal to attach: its pane is a conversation
// (widgets/cloud_chat_pane.dart), and every other pane stays a terminal.
if (agent != null && agent.isCloud) {
return CloudChatPane(
key: ValueKey('cloud-pane-${pane.id}'),
notifier: notifier,
machineId: pane.machineId,
agent: agent,
visible: visible,
compactHeader: swarmMode,
onClose: close,
);
}
final needsLink =
machine != null &&
machine.isRemote &&
!machine.isLocalMachine &&
machine.needsLink;
final offline =
machine != null &&
(machine.nodeOnline == false ||
(machine.isLocalMachine && !machine.usesLocalTransport));
// On its way back rather than gone: worded where the host labels pane
// states (the web), and not typed into until it is back.
final dialing =
WorkspaceChrome.of(context).labelsPaneStatus &&
machine != null &&
!machine.machine.isShared &&
(machine.connectionStatus == ConnectionStatus.connecting ||
machine.connectionStatus == ConnectionStatus.reconnecting);
// Availability changes the header and input permission, never the renderer's
// ancestry. Retained output, selection, scroll and Find stay in this view.
if (session != null) {
// A software renderer (notably WSLg's llvmpipe) cannot keep up when
// every visible terminal schedules a full text layout for every output
// chunk. Keep the active tile realtime and coalesce background output
// only once the grid has three terminal panes. The buffer remains live,
// so the next paint contains every intervening chunk.
final terminalPaneCount = notifier.panes
.where((candidate) => candidate.session != null)
.length;
final throttleBackgroundOutput =
swarmMode &&
visible &&
!notifier.isPaneFocused(pane.id) &&
notifier.zoomedPaneId == null &&
terminalPaneCount >= 3;
final TerminalNotice? notice;
final sharedWaiting = machine == null && wantedAgentId != null
? notifier.sharedWaitingName(pane.machineId, wantedAgentId)
: null;
final sharingEnded = machine == null
? notifier.sharingEnded(pane.machineId)
: null;
if (sharedWaiting != null) {
// Another account's harness, restored before this window knows its
// machine: who it waits for, never "isn't available" (seam 3).
notice = terminalNotice(
label: 'Waiting',
icon: AppIcons.hourglass,
detail: '$sharedWaiting · waiting',
);
} else if (sharingEnded != null) {
// Its owner stopped sharing the machine: say who, and the one thing left to do here.
final tab = notifier.swarms
.where((swarm) => swarm.panes.contains(pane))
.firstOrNull;
notice = terminalNotice(
label: 'No longer shared',
icon: AppIcons.unlink,
detail:
'${sharingEnded.owner} stopped sharing ${sharingEnded.name} with you. The harness stays on their machine; what is shown here is read only.',
actionLabel: 'Close',
onAction: () =>
notifier.closePane(pane.id, swarmId: tab?.id).ignore(),
banner: true,
);
} else if (machine == null) {
notice = terminalNotice(
label: 'Unavailable',
icon: AppIcons.cloudOff,
detail: notifier.machineInventoryLoaded
? 'This machine isn’t available. Retained output is read only.'
: 'Waiting for this machine. Retained output is read only.',
);
} else if (needsLink) {
// A frozen device list — or an account with no room for this device —
// may be why it asks: the band says so, beside the password.
final review =
notifier.deviceListNeedsReview || notifier.deviceListTooMany;
notice = terminalNotice(
label: 'Link required',
icon: AppIcons.unlink,
detail: review
? [
'${machine.machine.displayName} needs linking.',
if (notifier.deviceListNeedsReview)
'Your device list needs a review.',
if (notifier.deviceListTooMany)
registerRefusalSentence('TOO_MANY'),
].join(' ')
: '${machine.machine.displayName} needs linking. Retained output is read only.',
// A tile still showing its last screen gets the same way out as an
// empty one — the band's button asks for the remote password.
actionLabel: 'Link…',
onAction: () => showLinkMachineScreenDialog(
context,
notifier,
pane.machineId,
).ignore(),
secondaryLabel: review ? 'Machines' : null,
onSecondary: review
? () => showDeviceListReview(context, notifier)
: null,
banner: review,
);
} else if (offline) {
notice = terminalNotice(
label: 'Offline',
icon: AppIcons.cloudOff,
detail:
'${machine.machine.displayName} is offline. Retained output is read only.',
);
} else if (dialing) {
final again = machine.connectionStatus == ConnectionStatus.reconnecting;
notice = terminalNotice(
label: again ? 'Reconnecting…' : 'Connecting…',
icon: AppIcons.refreshCw,
detail:
'${again ? 'Reconnecting' : 'Connecting'} to ${machine.machine.displayName}. Keys typed now are not sent.',
dimsScreen: true,
);
} else if (agent?.isStopped == true) {
final opening = notifier.pendingAgentRestart(
pane.machineId,
wantedAgentId!,
);
final resume = superPane?.onResume;
final canResume = resume != null && !machine.belongsToOtherAccount;
notice = terminalNotice(
label: opening?.busy == true ? 'Opening' : 'Stopped',
icon: AppIcons.terminal,
detail:
opening?.result?.error ??
(superPane != null
? 'This agent is stopped. Retained output is read only.'
: 'Open to continue your saved conversation. Retained output is read only.'),
actionLabel: opening?.busy == true
? null
: superPane == null
? 'Open'
: canResume
? 'Resume'
: null,
onAction: superPane == null
? () => notifier.openSavedPane(pane.id).ignore()
: canResume
? () => resume(pane.machineId, wantedAgentId)
: null,
banner: true,
);
} else if (agent != null && agent.launchState == 'held') {
// Held back by the daemon until it can start it safely: say why,
// rather than "Unavailable" over an empty pane.
notice = terminalNotice(
label: 'Waiting',
icon: AppIcons.hourglass,
detail: heldLaunchDetail(agent),
banner: true,
);
} else if (agent == null || !agent.terminalAvailable) {
notice = terminalNotice(
label: 'Unavailable',
icon: AppIcons.terminal,
detail:
agent?.terminalUnavailableReason ??
'This harness is unavailable on ${machine.machine.displayName}. Retained output is read only.',
);
} else if (agent.launchState == 'starting') {
notice = terminalNotice(
label: 'Starting',
icon: AppIcons.terminal,
detail: 'You can answer setup prompts in this terminal while the agent starts.',
banner: true,
);
} else if (agent.launchState == 'failed') {
// Unconfirmed can mean the shell has not reached the engine at all.
// Keep input available for setup prompts, and re-check the existing
// resume rather than starting another conversation.
final unconfirmed = agent.launchError == 'RESUME_UNCONFIRMED';
notice = terminalNotice(
label: unconfirmed ? 'Not confirmed' : 'Start failed',
icon: unconfirmed ? AppIcons.circleHelp : AppIcons.circleAlert,
detail: unconfirmed
? 'Answer setup prompts below, then check again.'
: agent.launchDetail ??
'The engine failed to start. Terminal output is preserved.',
banner: true,
actionLabel: unconfirmed ? 'Check again' : 'Restart',
onAction: unconfirmed
? () => unawaited(notifier.selectAgent(pane.machineId, agent.id))
: () =>
restartHarness(context, notifier, pane.machineId, agent.id),
);
} else {
notice = null;
}
// Joining a shared tab: dimmed until the tab's owner's computer answers.
final joining =
wantedAgentId != null &&
sharedPaneChipState(
notifier,
pane.machineId,
wantedAgentId,
).joining !=
null;
final panel = LayoutBuilder(
builder: (context, constraints) => TerminalPanel(
notifier: notifier,
session: session,
viewportSize: constraints.biggest,
paneLocation: (notifier.activeSwarmId, notifier.panes.indexOf(pane)),
layoutRequest: (
notifier.paneLayoutRequest,
notifier.panes.length,
notifier.zoomedPaneId,
),
focused: visible && notifier.isPaneFocused(pane.id),
outputRepaintInterval: throttleBackgroundOutput
? const Duration(milliseconds: 80)
: null,
focusRequest: notifier.isPaneFocused(pane.id)
? notifier.paneFocusRequest
: 0,
focusByUser: notifier.paneFocusByUser,
visible: visible,
compactHeader: swarmMode,
composerVisible: pane.composerVisible,
firstTask: pane.firstTask,
onFirstTaskSubmitted: pane.firstTask == null
? null
: () => pane.firstTask = '',
// Launch progress/failure describes the engine, not permission to
// type into its terminal. Connection and control ownership still
// gate input independently in TerminalPanel/TerminalSession.
// A held harness stays writable: the app hears of the daemon starting
// it a moment late, and the pane may already be the agent's.
readOnly:
machine == null ||
needsLink ||
offline ||
dialing ||
agent == null ||
!agent.terminalAvailable,
notice: notice,
onToggleComposer: () => notifier.toggleComposer(pane.id),
onClose: single && !swarmMode ? null : close,
onOpenModels: onOpenModels == null
? null
: () =>
onOpenModels!(pane.id, session.machineId, session.agentId),
onSplitDown: split(PaneResizeAxis.y),
onSplitRight: split(PaneResizeAxis.x),
// The same confirmation the rail's row menu opens. Only for an
// agent the machine still lists — a pane whose agent is already
// gone has nothing to end.
onDelete: agent == null
? null
: () => confirmDeleteAgent(
context,
notifier,
pane.machineId,
agent.id,
agent.displayName,
engine: agent.engine,
),
zoomed: notifier.zoomedPaneId == pane.id,
onToggleZoom:
superPane == null &&
swarmMode &&
(!single || notifier.zoomedPaneId == pane.id)
? () {
notifier.focusPane(pane.id);
notifier.toggleZoomPane();
}
: null,
onRendererFocus: () => notifier.focusPaneFromRenderer(pane.id),
paneDrag: single
? null
: PaneDragHandle(
ref: PaneDragRef(paneId: pane.id),
size: constraints.biggest,
),
),
);
return joining ? Opacity(opacity: .55, child: panel) : panel;
}
// Another account's harness, restored before the inventory (or the grant)
// reaches this window: it waits for its owner, never "isn't available" or
// a takeover offer (seam 3).
if (machine == null && wantedAgentId != null) {
if (notifier.sharedWaitingName(pane.machineId, wantedAgentId)
case final owner?) {
return _PaneStatus(
activity: activityMark,
title: kUntitledPane,
icon: AppIcons.hourglass,
message: '$owner · waiting',
onClose: single && !swarmMode ? null : close,
busy: true,
// Another account's name: one line, cut short, never markup.
singleLine: true,
);
}
}
// A never-attached view has no output to preserve: keep its setup guidance.
if (machine == null) {
// Waiting ends once the inventory has answered, even when it has no row
// for this saved pane. Keep Retry mounted during refresh so keyboard focus
// survives. Repeated activation joins the same retry in AppNotifier.
final listFailed = notifier.machineListError != null;
final retrying = notifier.machinesRefreshing;
final waiting = !listFailed && !notifier.machineInventoryLoaded;
final stale = notifier.machinesAreStale;
return _PaneStatus(
activity: activityMark,
title: wantedAgentId == null ? 'Machine' : kUntitledPane,
icon: listFailed || stale ? AppIcons.cloudOff : AppIcons.unlink,
message: listFailed
? 'Could not load machines. Retry to reconnect.'
: waiting
? 'Waiting for this machine to answer…'
: stale
? 'Could not confirm this machine’s status. Retry to reconnect.'
: 'This machine isn’t available. Check that it’s still linked to your account.',
onClose: single && !swarmMode ? null : close,
busy: waiting || retrying,
actionLabel: waiting ? null : 'Retry',
onAction: waiting ? null : notifier.retryMachines,
);
}
if (needsLink) {
return _PaneStatus(
activity: activityMark,
title: agentName ?? machine.machine.displayName,
icon: AppIcons.unlink,
message:
'${machine.machine.displayName} is not linked to this computer yet. '
'Link it with the remote password set on that machine.',
onClose: single && !swarmMode ? null : close,
// The way out, where the dead end was: the same card the Machines
// panel's Connect row opens, asking for that machine's remote
// password. It closes itself the moment the link lands, and this tile
// goes back to attaching.
actionLabel: 'Link…',
onAction: () => showLinkMachineScreenDialog(
context,
notifier,
pane.machineId,
).ignore(),
footer: DeviceListReviewLine(notifier: notifier, center: true),
);
}
if (offline) {
return _Guide(
activity: activityMark,
single: single && !swarmMode,
onClose: close,
title: agentName ?? machine.machine.displayName,
compactMessage: machine.isLocalMachine
? 'Harness is not running on this computer.'
: 'Harness is not running on ${machine.machine.displayName}.',
compactIcon: AppIcons.cloudOff,
full: HarnessJoinGuideScreen(
notifier: notifier,
machineState: machine,
agentName: agentName ?? 'selected harness',
),
);
}
if (wantedAgentId == null) {
return _PaneStatus(
activity: activityMark,
title: machine.machine.displayName,
icon: AppIcons.circleCheck,
message: 'This machine is ready. Drag a harness here to open it.',
onClose: close,
);
}
// The daemon is still on its first scan, so an agent missing from the list may simply not have
// been reached yet — say "loading", not "gone" (owner, 2026-10-01). It attaches on its own.
if (agentName == null && (machine.localEndpoint?.scanning ?? false)) {
return _PaneStatus(
activity: activityMark,
title: kUntitledPane,
icon: AppIcons.hourglass,
message: 'Loading harnesses on ${machine.machine.displayName}…',
busy: true,
onClose: close,
);
}
if (agentName == null) {
return _PaneStatus(
activity: activityMark,
title: wantedAgentId,
icon: AppIcons.circleHelp,
message: 'This harness is no longer on ${machine.machine.displayName}.',
onClose: close,
);
}
if (agent?.isStopped == true) {
if (superPane != null) {
final resume = superPane.onResume;
return Column(
children: [
_PaneHeader(
title:
superPane.titleFor(pane.machineId, wantedAgentId) ??
agentName,
activity: activityMark,
),
Divider(height: 1, color: AppColors.border),
Expanded(
child: SuperTabSavedSession(
key: ValueKey((pane.machineId, wantedAgentId)),
app: notifier,
machineId: pane.machineId,
harnessId: wantedAgentId,
onResume: resume != null && !machine.belongsToOtherAccount
? () => resume(pane.machineId, wantedAgentId)
: null,
),
),
],
);
}
final opening = notifier.pendingAgentRestart(
pane.machineId,
wantedAgentId,
);
return _PaneStatus(
activity: activityMark,
title: agentName,
icon: AppIcons.terminal,
message: opening?.busy == true
? 'Opening saved conversation…'
: opening?.result?.error ?? 'This harness is stopped. Open it to continue your saved conversation.',
onClose: close,
busy: opening?.busy == true,
actionLabel: opening?.busy == true ? null : 'Open',
onAction: () => notifier.openSavedPane(pane.id).ignore(),
);
}
// Held back by the daemon until it can start it safely (a conversation
// another process may have open): it says so and why, and starts by
// itself. It read "terminal unavailable (no verified terminal pane)".
if (agent != null && agent.launchState == 'held') {
return _PaneStatus(
activity: activityMark,
title: agentName,
icon: AppIcons.hourglass,
message: heldLaunchDetail(agent),
onClose: close,
busy: true,
);
}
if (agent != null && !agent.terminalAvailable) {
return _PaneStatus(
activity: activityMark,
title: agentName,
icon: AppIcons.terminal,
message:
agent.terminalUnavailableReason ??
'This harness has no available terminal.',
onClose: close,
);
}
// Nothing is attaching, and nothing will: this machine's CLI cannot open a
// terminal without taking it from whoever has it, so an open here waits for
// a person rather than happening behind one (`AttachIntent`). A spinner
// would promise something that is never coming.
if (!machine.terminalNoTakeoverAvailable) {
return _PaneStatus(
activity: activityMark,
title: agentName,
icon: AppIcons.terminal,
message:
'Open this harness here. Another screen may be using its terminal; '
'opening takes it, because ${machine.machine.displayName} runs an '
'older Harness CLI.',
onClose: single && !swarmMode ? null : close,
actionLabel: 'Open here',
onAction: () {
notifier.selectAgent(pane.machineId, wantedAgentId).ignore();
},
);
}
return _PaneStatus(
activity: activityMark,
title: agentName,
icon: AppIcons.hourglass,
message: 'Attaching…',
onClose: single && !swarmMode ? null : close,
busy: true,
);
}
}
/// Where an OS file (from Finder/Nautilus, not an in-app drag) may be dropped onto this pane.
///
/// Outermost of the three drop layers on a tile ([_SwapZone]/[_DropZone] handle in-app Flutter
/// drags; this one is a native OS drag session, a different event channel entirely — `desktop_drop`
/// does not consume ordinary pointer/click/scroll events, so nesting order among the three doesn't
/// matter functionally). Unlike the other two, there is no app-wide "what's being dragged" notifier
/// to key hover state off — `desktop_drop` only tells THIS widget about drags over it — so this one
/// is a StatefulWidget with its own local hover flag instead of a shared `ValueListenableBuilder`.
///
/// An image is sent through the exact same pipeline as a clipboard image paste
/// ([TerminalSession.pasteImage]); a non-image file's path is pasted as text — directly, with no
/// network round-trip, when this pane's machine is local, or via [TerminalSession.pasteFile] (which
/// writes it to disk on that machine first) when the pane's machine is remote. See the plan this
/// shipped from for why that asymmetry is intentional.
class _FileDropZone extends StatefulWidget {
const _FileDropZone({
required this.notifier,
required this.pane,
required this.visible,
required this.child,
});
final AppNotifier notifier;
final TerminalPane pane;
final bool visible;
final Widget child;
@override
State<_FileDropZone> createState() => _FileDropZoneState();
}
class _FileDropZoneState extends State<_FileDropZone> {
bool _hovering = false;
bool get _active =>
mounted && widget.visible && widget.notifier.panes.contains(widget.pane);
bool _canDeliver(TerminalSession session, String streamId) =>
_active &&
identical(widget.pane.session, session) &&
session.streamId == streamId &&
session.acceptsInput;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
return DropTarget(
key: ValueKey('pane-file-drop-${widget.pane.id}'),
enable: widget.visible && (widget.pane.session?.acceptsInput ?? false),
onDragEntered: (_) => setState(() => _hovering = true),
onDragExited: (_) => setState(() => _hovering = false),
onDragDone: (details) async {
setState(() => _hovering = false);
await _handleDrop(details.files);
},
child: Stack(
fit: StackFit.expand,
children: [
widget.child,
if (_hovering)
Positioned.fill(
child: IgnorePointer(
child: Container(
color: AppColors.accent.withValues(alpha: 0.16),
child: Center(
child: Container(
padding: const EdgeInsets.symmetric(
horizontal: 12,
vertical: 8,
),
decoration: BoxDecoration(
color: grid.AppPalette.panelBg,
border: Border.all(color: AppColors.accent),
borderRadius: BorderRadius.circular(6),
),
child: Text(
'Drop to attach',
style: grid.AppType.mono(
fontWeight: FontWeight.w500,
color: AppColors.text,
),
),
),
),
),
),
),
],
),
);
}
void _toast(String message) {
if (!mounted) return;
ScaffoldMessenger.of(context)
.showSnackBar(SnackBar(content: Text(message)));
}
static String _mb(int bytes) =>
'${(bytes / (1024 * 1024)).toStringAsFixed(0)} MB';
/// Reads just enough of the file to sniff its format (see [looksLikeImage]) without loading a
/// large drop fully into memory before deciding which ceiling even applies to it.
Future<Uint8List> _peekHead(DropItem item, int maxBytes) async {
final chunks = <int>[];
await for (final chunk in item.openRead(0, maxBytes)) {
chunks.addAll(chunk);
if (chunks.length >= maxBytes) break;
}
return Uint8List.fromList(chunks);
}
Future<void> _handleDrop(List<DropItem> files) async {
if (files.isEmpty || !_active) return;
final session = widget.pane.session;
if (session == null || !session.acceptsInput) return;
final streamId = session.streamId!;
widget.notifier.focusPane(widget.pane.id);
final machine = widget.notifier.stateOf(widget.pane.machineId);
final images = <DropItem>[];
final others = <DropItem>[];
for (final item in files) {
if (item is DropItemDirectory) {
others.add(item);
continue;
}
Uint8List head;
try {
head = await _peekHead(item, 16);
} catch (_) {
continue;
}
if (looksLikeImage(head)) {
images.add(item);
} else {
others.add(item);
}
}
// Only the first image: several back-to-back would race the same OS clipboard + single Ctrl+V
// nudge on the daemon side — see pasteImage's own doc.
if (images.isNotEmpty) {
await _dropImage(images.first, machine, session, streamId);
if (images.length > 1) {
final ignored = images.length - 1;
_toast(
'$ignored more image${ignored > 1 ? 's' : ''} ignored — drop one image at a time',
);
}
}
// Every non-image file, independently — no shared resource to race over.
for (final item in others) {
await _dropFile(item, machine, session, streamId);
}
}
Future<void> _dropImage(
DropItem item,
MachineState? machine,
TerminalSession session,
String streamId,
) async {
if (!_canDeliver(session, streamId)) return;
// Not "cannot receive a native image paste" — that's a real capability gap, this is just a
// race between the drop landing and machine state loading. Conflating the two would send the
// user to fix a machine that is perfectly fine.
if (machine == null) {
_toast('Machine info not ready yet — try again in a moment');
return;
}
Uint8List raw;
try {
raw = await item.readAsBytes();
} catch (_) {
_toast('Could not read ${item.name}');
return;
}
final png = await ensurePngBytes(raw);
if (!_canDeliver(session, streamId)) return;
if (png == null) {
_toast('${item.name} is not a readable image');
return;
}
// Local pane: the app itself IS the target OS, so it writes ITS OWN clipboard directly
// instead of sending the bytes over the wire, then nudges the engine exactly like an
// ordinary local clipboard paste already does (see terminal_panel.dart's `_paste()`) — never
// the chunked-upload path, which is for a genuinely remote machine's DIFFERENT clipboard.
if (machine.isLocalMachine) {
final wrote = await NativeClipboard.writeImagePng(png);
if (!_canDeliver(session, streamId)) return;
if (!wrote) {
_toast('Could not set the clipboard on this machine');
return;
}
session.terminal.keyInput(TerminalKey.keyV, ctrl: true);
return;
}
if (!machine.terminalImagePasteAvailable) {
_toast('This machine cannot receive a native image paste yet');
return;
}
if (png.length > terminalLocalImagePasteMaxPayloadBytes) {
_toast(
'${item.name} is larger than ${_mb(terminalLocalImagePasteMaxPayloadBytes)}',
);
return;
}
await session.pasteImage(png);
}
Future<void> _dropFile(
DropItem item,
MachineState? machine,
TerminalSession session,
String streamId,
) async {
if (!_canDeliver(session, streamId)) return;
// Same reasoning as _dropImage: null here is a transient race, not "this machine can't do
// this" — say so distinctly rather than falling through to the remote/upload branch below,
// which would silently take the wire for what might actually be a local pane.
if (machine == null) {
_toast('Machine info not ready yet — try again in a moment');
return;
}
// Local pane: the file already has a valid path on this same machine — nothing to transfer.
if (machine.isLocalMachine) {
await session.pasteText(item.path);
return;
}
// A folder has no single-file byte content to transfer to a remote machine — out of scope.
if (item is DropItemDirectory) {
_toast("Folders can't be sent to a remote machine yet");
return;
}
if (!machine.terminalPasteFileAvailable) {
_toast('This machine cannot receive a dropped file yet');
return;
}
Uint8List bytes;
try {
bytes = await item.readAsBytes();
} catch (_) {
_toast('Could not read ${item.name}');
return;
}
if (!_canDeliver(session, streamId)) return;
if (bytes.length > terminalLocalPasteFileMaxPayloadBytes) {
_toast(
'${item.name} is larger than ${_mb(terminalLocalPasteFileMaxPayloadBytes)}',
);
return;
}
await session.pasteFile(item.name, bytes);
}
}
/// Where a dragged pane may be dropped: on an edge it lands beside this one, as
/// in the TUI, and in the middle the two trade places.
///
/// A sibling of [_DropZone] rather than a branch inside it: they are live at
/// different times and mean different things at the same pixel — a rail row
/// landing here REPLACES what this tile shows, a pane landing here MOVES.
/// `DragTarget<T>` keeps them apart by generic, so neither has to ask what kind
/// of drag is in flight.
class _SwapZone extends StatelessWidget {
const _SwapZone({
required this.notifier,
required this.paneId,
required this.child,
});
final AppNotifier notifier;
final int paneId;
final Widget child;
/// The edge the hand is over, read from the zone's own box.
PaneSide? _edge(BuildContext context) {
final pointer = paneDragPointer.value;
final box = context.findRenderObject();
if (pointer == null || box is! RenderBox || !box.hasSize) return null;
return paneSideAt(box.globalToLocal(pointer), box.size);
}
void _drop(BuildContext context, int moving) {
final edge = _edge(context);
if (edge == null) {
notifier.reorderPane(moving, paneId);
} else if (notifier.canMovePaneBeside(moving, paneId, edge)) {
notifier.movePaneBeside(moving, paneId, edge);
} else if (!notifier.isPaneBeside(moving, paneId, edge)) {
// This layout can't take a pane out cleanly: trade places instead, which
// is what the preview said.
notifier.reorderPane(moving, paneId);
}
}
/// What the drop would do, drawn where it would happen.
Widget _preview(BuildContext zone, int moving) {
return ValueListenableBuilder<Offset?>(
valueListenable: paneDragPointer,
// The zone's box, which exists: this builder's own has no render object
// on the frame the hand arrives, and would read as the middle.
builder: (_, _, _) {
final edge = _edge(zone);
if (edge != null && notifier.isPaneBeside(moving, paneId, edge)) {
return const SizedBox.expand();
}
if (edge != null && notifier.canMovePaneBeside(moving, paneId, edge)) {
return Align(
alignment: switch (edge) {
PaneSide.left => Alignment.centerLeft,
PaneSide.right => Alignment.centerRight,
PaneSide.top => Alignment.topCenter,
PaneSide.bottom => Alignment.bottomCenter,
},
child: FractionallySizedBox(
widthFactor: edge.axis == PaneResizeAxis.x ? .5 : 1,
heightFactor: edge.axis == PaneResizeAxis.y ? .5 : 1,
child: Container(
key: ValueKey('pane-drop-${edge.name}'),
decoration: BoxDecoration(
color: AppColors.accent.withValues(alpha: 0.16),
border: Border.all(color: AppColors.accent),
),
),
),
);
}
return Container(
color: AppColors.accent.withValues(alpha: 0.16),
child: Center(
child: Container(
padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
decoration: BoxDecoration(
color: grid.AppPalette.panelBg,
border: Border.all(color: AppColors.accent),
borderRadius: BorderRadius.circular(6),
),
child: Text(
'Swap with this pane',
style: grid.AppType.mono(
fontWeight: FontWeight.w500,
color: AppColors.text,
),
),
),
),
);
},
);
}
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
return ValueListenableBuilder<PaneDragRef?>(
valueListenable: paneDragging,
builder: (context, dragging, _) {
return Stack(
fit: StackFit.expand,
children: [
child,
Positioned.fill(
child: IgnorePointer(
// Off entirely unless a pane is in flight, so the terminal
// underneath keeps every click the rest of the time.
ignoring:
notifier.activeSwarm.isCompanions ||
notifier.activeSwarm.isDevices ||
dragging == null ||
dragging.paneId == paneId,
child: Builder(
builder: (zone) => DragTarget<PaneDragRef>(
onAcceptWithDetails: (details) =>
_drop(zone, details.data.paneId),
builder: (context, candidate, _) => candidate.isEmpty
? const SizedBox.expand()
: _preview(zone, candidate.first!.paneId),
),
),
),
),
],
);
},
);
}
}
/// A full-screen guide, but only where one fits.
///
/// The link and join screens are fixed-width cards written for the whole
/// window. In a quarter tile they would overflow rather than shrink, so a tile
/// too small to hold one says the same thing in a sentence. Measured, not
/// counted: a small window has the same problem with a single tile.
class _Guide extends StatelessWidget {
const _Guide({
required this.single,
required this.onClose,
required this.title,
this.activity,
required this.compactMessage,
required this.compactIcon,
required this.full,
});
final bool single;
final VoidCallback? onClose;
final String title;
final Widget? activity;
final String compactMessage;
final IconData compactIcon;
final Widget full;
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return LayoutBuilder(
builder: (context, constraints) {
final roomForCard =
constraints.maxWidth >= 520 &&
constraints.maxHeight >= (single ? 500 : 546);
if (roomForCard) {
if (single) return full;
return Column(
children: [
_PaneHeader(title: title, onClose: onClose, activity: activity),
Expanded(child: full),
],
);
}
return _PaneStatus(
activity: activity,
title: title,
icon: compactIcon,
message: compactMessage,
onClose: single ? null : onClose,
);
},
);
}
}
/// The same 46pt strip TerminalPanel draws, for the tiles that have no terminal
/// to draw one — so the close button never moves between states.
class _PaneHeader extends StatelessWidget {
const _PaneHeader({required this.title, this.onClose, this.activity});
final String title;
final Widget? activity;
final VoidCallback? onClose;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
// The pane's head is a drag handle too: with the title bar hidden it is
// the top edge of the window.
return WindowDragArea(
child: SizedBox(
height: 46,
child: Padding(
padding: const EdgeInsets.symmetric(horizontal: 14),
child: Row(
children: [
Expanded(
child: Row(
children: [
Flexible(
child: Text(
title,
overflow: TextOverflow.ellipsis,
style: grid.AppType.monoLabel(
color: AppColors.text,
fontWeight: FontWeight.w600,
),
),
),
?activity,
],
),
),
if (onClose != null) PaneCloseButton(onPressed: onClose!),
],
),
),
),
);
}
}
class _PaneStatus extends StatelessWidget {
const _PaneStatus({
required this.title,
this.activity,
required this.icon,
required this.message,
this.onClose,
this.busy = false,
this.actionLabel,
this.onAction,
this.footer,
this.singleLine = false,
});
final String title;
final Widget? activity;
final IconData icon;
final String message;
/// The message on one line, ellipsized: it carries a string another
/// account chose, which may be as long as it likes.
final bool singleLine;
final VoidCallback? onClose;
final bool busy;
/// An optional way out of the state being described. A pane that is merely waiting has none; one
/// reporting a failure the user can retry does, and it reads the same as the error strip's RETRY.
final String? actionLabel;
final VoidCallback? onAction;
/// Anything more under the way out — a machine asking for its password:
/// a device list to review.
final Widget? footer;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
return Column(
children: [
_PaneHeader(title: title, onClose: onClose, activity: activity),
Divider(height: 1, color: AppColors.border),
Expanded(
child: Center(
child: Padding(
padding: const EdgeInsets.all(20),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
SizedBox(
width: 26,
height: 26,
child: busy
? const Center(
child: SizedBox(
width: 18,
height: 18,
child: CircularProgressIndicator(strokeWidth: 2),
),
)
: Icon(icon, size: 24, color: AppColors.mutedStrong),
),
const SizedBox(height: 10),
Flexible(
child: singleLine
? Text(
message,
textAlign: TextAlign.center,
maxLines: 1,
softWrap: false,
overflow: TextOverflow.ellipsis,
style: grid.AppType.body(
color: AppColors.mutedStrong,
),
)
: SingleChildScrollView(
child: Text(
message,
textAlign: TextAlign.center,
style: grid.AppType.body(
color: AppColors.mutedStrong,
),
),
),
),
if (actionLabel != null && onAction != null) ...[
const SizedBox(height: 4),
TextButton(onPressed: onAction, child: Text(actionLabel!)),
],
?footer,
],
),
),
),
),
],
);
}
}
/// Where a dragged rail row can land.
///
/// [paneId] null means "make a new tile"; otherwise the drop replaces what that
/// tile is showing. Hit-testable only while a drag is actually in flight, so an
/// ordinary click still reaches the terminal underneath.
class _DropZone extends StatelessWidget {
const _DropZone({
required this.notifier,
required this.paneId,
required this.dragging,
required this.child,
});
final AppNotifier notifier;
final int? paneId;
final AgentDragRef? dragging;
final Widget child;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
return Stack(
fit: StackFit.expand,
children: [
child,
Positioned.fill(
child: IgnorePointer(
ignoring:
notifier.activeSwarm.isCompanions ||
notifier.activeSwarm.isDevices ||
dragging == null,
child: DragTarget<AgentDragRef>(
onAcceptWithDetails: (details) => notifier.assignAgentToPane(
paneId,
details.data.machineId,
details.data.agentId,
),
builder: (context, candidate, _) => candidate.isEmpty
? const SizedBox.expand()
: Container(
color: AppColors.accent.withValues(alpha: 0.16),
child: Center(
child: Container(
padding: const EdgeInsets.symmetric(
horizontal: 12,
vertical: 8,
),
decoration: BoxDecoration(
color: grid.AppPalette.panelBg,
border: Border.all(color: AppColors.accent),
borderRadius: BorderRadius.circular(6),
),
child: Text(
paneId == null
? 'Open ${candidate.first?.name ?? 'harness'} here'
: 'Show ${candidate.first?.name ?? 'harness'} in this pane',
style: grid.AppType.mono(
fontWeight: FontWeight.w500,
color: AppColors.text,
),
),
),
),
),
),
),
),
],
);
}
}
class _AddSlot extends StatelessWidget {
const _AddSlot();
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
return DecoratedBox(
decoration: BoxDecoration(
color: grid.AppPalette.windowBg,
border: Border.all(color: AppColors.border),
),
child: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Icon(AppIcons.plus, size: 24, color: AppColors.mutedStrong),
const SizedBox(height: 8),
Text(
'Drop here for a new pane',
style: grid.AppType.body(color: AppColors.mutedStrong),
),
],
),
),
);
}
}
class _EmptyGrid extends StatelessWidget {
const _EmptyGrid({required this.notifier});
final AppNotifier notifier;
/// Which machine a new agent would be started on.
///
/// [AppNotifier.activeMachineState] answers for every case that has one —
/// an open terminal, a selected machine, the first expanded one. It reads
/// null only before any machine has been touched, which on a single-machine
/// install (this Mac, and nothing linked yet) is exactly the first launch
/// this button exists for; hence the fallback. With several machines and none
/// picked there is no honest answer, so the button is not drawn and the rail's
/// per-machine `+` stays the way in — a create that guessed the wrong machine
/// is worse than one more click.
String? get _machineId {
final active = notifier.activeMachineState;
if (active != null) return active.machine.machineId;
final states = notifier.machineStates.values;
return states.length == 1 ? states.first.machine.machineId : null;
}
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
final machineId = _machineId;
// Holds the keyboard while there is no terminal to hold it.
//
// App shortcuts are bound above this screen (swarm_screen.dart) and, like
// every Flutter shortcut, they are delivered along the focus chain — from
// whatever has focus up through its ancestors. With no pane open nothing
// inside the screen has any, so the chain starts at the route's own scope,
// which sits ABOVE the bindings: ⌘\, ⌘N, ⌘R and ⌘/ all did nothing until
// the first terminal took focus. This is the state that tells the user to
// press ⌘/ two lines below, so it had better answer.
//
// Safe here in a way it is not on the screen's own scope: this widget
// exists only while there is no terminal, so it can never be the node that
// keeps a focused pane from opening its TextInput connection.
return Focus(
autofocus: true,
skipTraversal: true,
child: ColoredBox(
color: grid.AppPalette.windowBg,
child: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Text(
'Select a harness, or drag one in from the left.',
style: grid.AppType.body(color: AppColors.mutedStrong),
),
// Selecting and dragging both need an agent to already exist. On a
// first launch none does, so the two sentences around this button
// are a dead end without it.
if (machineId != null) ...[
const SizedBox(height: 16),
FilledButton.icon(
key: const ValueKey('empty-grid-new-agent'),
icon: const Icon(AppIcons.plus, size: 16),
label: const Text('New Harness'),
onPressed: () => showNewAgentDialog(
context,
notifier,
machineId,
source: 'pane_empty',
),
),
],
const SizedBox(height: 8),
// The empty pane is the one screen a new user is guaranteed to
// look at, and it is doing nothing else. A sheet behind a key
// nobody has been told about is a sheet nobody opens.
Text(
'Press ${shortcutHintFor(ShortcutAction.showShortcuts)} for '
'keyboard shortcuts',
style: grid.AppType.body(color: grid.AppPalette.textFaint),
),
],
),
),
),
);
}
}
/// What a harness's viewer pane is called, so the harness's name is not printed twice beside its
/// terminal. The daemon's answer first; from a daemon that predates it, the shared viewer's name
/// from this machine's catalog ("3D Viewer"); else the harness's name and "Viewer"; else "Viewer".
String viewerPaneName(Agent? owner, Iterable<DshEntry> catalog) {
if (owner == null) return 'Viewer';
if (owner.viewerName case final name?) return name;
final entry = catalog.where((e) => e.id == owner.dsh).firstOrNull;
final used = entry?.viewerUse;
if (used != null) {
final viewer = catalog.where((e) => e.id == used).firstOrNull;
if (viewer != null && viewer.name.trim().isNotEmpty) {
return viewer.name.trim();
}
}
final harness = owner.dshName ?? entry?.name;
return harness == null || harness.trim().isEmpty
? 'Viewer'
: '${harness.trim()} Viewer';
}