Skip to content

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.

desktop: a web pane for a harness's viewer

deec6ebed79a8c2
diff --git a/desktop/lib/state/terminal_pane.dart b/desktop/lib/state/terminal_pane.dart
index ceab4b648..54e37a404 100644
--- a/desktop/lib/state/terminal_pane.dart
+++ b/desktop/lib/state/terminal_pane.dart
@@ -2,6 +2,16 @@ import 'package:flutter/widgets.dart';
import '../terminal/terminal_session.dart';
+/// What a tile shows.
+///
+/// A [web] tile is a domain harness's viewer — the board, the part, the
+/// episode — served on the agent's machine and drawn beside that agent's
+/// terminal. It is DERIVED from the agent (the daemon says where the viewer
+/// is, and the tile follows) and never persisted: a restored layout re-opens
+/// it from the agent's next frame, so a stale URL from a previous run can
+/// never be loaded.
+enum PaneKind { terminal, web }
+
/// One tile in the terminal grid.
///
/// The INTENT (which agent this tile is for) and the live [session] are kept
@@ -12,7 +22,30 @@ import '../terminal/terminal_session.dart';
/// machine going offline and coming back without the grid reshuffling around
/// it.
class TerminalPane {
- TerminalPane({required this.id, required this.machineId, this.agentId});
+ TerminalPane({
+ required this.id,
+ required this.machineId,
+ this.agentId,
+ this.kind = PaneKind.terminal,
+ this.url,
+ this.ownerAgentId,
+ }) : assert(
+ kind == PaneKind.terminal || (agentId == null && ownerAgentId != null),
+ 'a web tile belongs to an agent through ownerAgentId, never agentId',
+ );
+
+ final PaneKind kind;
+ bool get isWeb => kind == PaneKind.web;
+
+ /// [PaneKind.web] only: what the tile loads. Changes when the agent's frame
+ /// names a new viewer URL; the panel navigates rather than remounts.
+ String? url;
+
+ /// [PaneKind.web] only: the agent whose viewer this is. Kept OFF [agentId]
+ /// on purpose — everything that attaches a terminal, persists a layout or
+ /// remembers a closed agent keys on [agentId] being set, and none of that
+ /// applies to a viewer.
+ final String? ownerAgentId;
/// Stable for the tile's whole life, including across a machine going away
/// and returning. Widget keys hang off this: keying on the agent id instead
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index 3643508c4..cea9d7617 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -26,6 +26,7 @@ import 'new_agent_dialog.dart';
import 'delete_agent_dialog.dart';
import 'restart_agent_action.dart';
import 'terminal_panel.dart';
+import 'web_pane_panel.dart';
import 'pane_resize_handle.dart';
import 'pane_split_edges.dart';
@@ -1262,13 +1263,38 @@ class _PaneContent extends StatelessWidget {
@override
Widget build(BuildContext context) {
final machine = notifier.stateOf(pane.machineId);
+ void close() => notifier.closePane(pane.id);
+ // 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,
+ ownerName: owner?.name ?? pane.ownerAgentId ?? 'Viewer',
+ ownerEngine: owner?.identityEngine,
+ ownerDisplayName: owner?.identityDisplayName,
+ onClose: close,
+ compactHeader: swarmMode,
+ zoomed: notifier.zoomedPaneId == pane.id,
+ onToggleZoom: swarmMode && (!single || notifier.zoomedPaneId == pane.id)
+ ? () {
+ notifier.focusPane(pane.id);
+ notifier.toggleZoomPane();
+ }
+ : null,
+ );
+ }
final session = pane.session;
final wantedAgentId = pane.agentId;
final agent = machine?.agents
.where((agent) => agent.id == wantedAgentId)
.firstOrNull;
final agentName = agent?.name;
- void close() => notifier.closePane(pane.id);
final needsLink =
machine != null &&
machine.isRemote &&
diff --git a/desktop/lib/widgets/web_pane_panel.dart b/desktop/lib/widgets/web_pane_panel.dart
new file mode 100644
index 000000000..e9d2ed637
--- /dev/null
+++ b/desktop/lib/widgets/web_pane_panel.dart
@@ -0,0 +1,361 @@
+import 'dart:io' show Platform;
+
+import 'package:flutter/material.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+import '../core/test_run.dart';
+import '../shared/theme/app_theme.dart' as grid;
+import '../state/app_state.dart';
+import '../state/terminal_pane.dart';
+import '../theme/app_theme.dart';
+import 'engine_identity.dart';
+import 'pane_header_actions.dart';
+
+/// A domain harness's viewer, in a tile beside its agent's terminal.
+///
+/// The page is the harness's own — Circuit's board workspace, Workshop's 3D
+/// view — served by a process the daemon runs on the agent's machine. This
+/// panel only frames it: a header in the terminal's own idiom, a webview
+/// that follows [TerminalPane.url] when the daemon names a new one, and a
+/// small notice while the viewer is not answering yet.
+///
+/// The webview is a native view (WKWebView through `webview_flutter`), and a
+/// native view cannot exist where no platform implementation is registered:
+/// under `flutter test`, and on Linux today. There the body is the URL in
+/// words, so every layout around it still builds and the tests can prove the
+/// tile is placed, sized and closed correctly without instantiating it.
+class WebPanePanel extends StatefulWidget {
+ const WebPanePanel({
+ super.key,
+ required this.notifier,
+ required this.pane,
+ required this.ownerName,
+ required this.ownerEngine,
+ this.ownerDisplayName,
+ this.onClose,
+ this.onToggleZoom,
+ this.zoomed = false,
+ this.compactHeader = false,
+ });
+
+ final AppNotifier notifier;
+ final TerminalPane pane;
+
+ /// The agent this viewer belongs to, for the header.
+ final String ownerName;
+ final String? ownerEngine;
+ final String? ownerDisplayName;
+ final VoidCallback? onClose;
+ final VoidCallback? onToggleZoom;
+ final bool zoomed;
+ final bool compactHeader;
+
+ /// Whether this build can put a real webview on screen. One place, so the
+ /// panel and its tests agree on when the placeholder is the right answer.
+ static bool get webviewAvailable => !kUnderTest && Platform.isMacOS;
+
+ @override
+ State<WebPanePanel> createState() => _WebPanePanelState();
+}
+
+class _WebPanePanelState extends State<WebPanePanel> {
+ WebViewController? _controller;
+ String? _loadedUrl;
+ bool _loading = false;
+ String? _failure;
+
+ @override
+ void initState() {
+ super.initState();
+ if (WebPanePanel.webviewAvailable) _mountController();
+ }
+
+ void _mountController() {
+ final controller = WebViewController()
+ ..setJavaScriptMode(JavaScriptMode.unrestricted)
+ ..setBackgroundColor(grid.AppPalette.windowBg)
+ ..setNavigationDelegate(
+ NavigationDelegate(
+ onPageStarted: (_) => _set(() {
+ _loading = true;
+ _failure = null;
+ }),
+ onPageFinished: (_) => _set(() => _loading = false),
+ onWebResourceError: (error) {
+ // Only the page itself: a harness's viewer pulls fonts, models
+ // and images of its own, and one of those failing is its business
+ // to show, not ours to call a dead viewer.
+ if (error.isForMainFrame == false) return;
+ _set(() {
+ _loading = false;
+ _failure = error.description.isNotEmpty
+ ? error.description
+ : 'The viewer did not answer.';
+ });
+ },
+ ),
+ );
+ _controller = controller;
+ _load();
+ }
+
+ void _set(VoidCallback change) {
+ if (mounted) setState(change);
+ }
+
+ void _load() {
+ final url = widget.pane.url;
+ final controller = _controller;
+ if (url == null || controller == null) return;
+ final uri = Uri.tryParse(url);
+ if (uri == null) return;
+ _loadedUrl = url;
+ _failure = null;
+ controller.loadRequest(uri);
+ }
+
+ void _reload() {
+ if (_controller == null) return;
+ if (_loadedUrl != widget.pane.url) {
+ _load();
+ } else {
+ _failure = null;
+ _controller!.reload();
+ }
+ setState(() {});
+ }
+
+ @override
+ void didUpdateWidget(WebPanePanel oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ // The daemon named a different page — the newest artifact, a viewer
+ // restarted on another port. Navigate in place; the tile stays.
+ if (widget.pane.url != _loadedUrl) _load();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
+ return ColoredBox(
+ color: grid.AppPalette.windowBg,
+ child: Column(
+ children: [
+ _header(context),
+ Divider(height: 1, color: AppColors.border),
+ Expanded(child: _body(context)),
+ ],
+ ),
+ );
+ }
+
+ Widget _header(BuildContext context) {
+ final compact = widget.compactHeader;
+ return PaneHeaderHover(
+ child: SizedBox(
+ height: compact ? 38 : 46,
+ child: Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 14),
+ child: Row(
+ children: [
+ EngineMark(
+ engine: widget.ownerEngine,
+ displayName: widget.ownerDisplayName,
+ size: 17,
+ ),
+ const SizedBox(width: 10),
+ Expanded(
+ child: Tooltip(
+ message: widget.pane.url ?? '',
+ waitDuration: const Duration(milliseconds: 700),
+ child: Text.rich(
+ TextSpan(
+ children: [
+ TextSpan(text: widget.ownerName),
+ TextSpan(
+ text: ' · Viewer',
+ style: TextStyle(
+ color: AppColors.mutedStrong,
+ fontWeight: FontWeight.w500,
+ ),
+ ),
+ ],
+ ),
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(
+ color: AppColors.text,
+ fontFamily: AppFonts.sans,
+ fontSize: 13,
+ fontWeight: FontWeight.w600,
+ ),
+ ),
+ ),
+ ),
+ const SizedBox(width: 8),
+ if (_loading)
+ const Padding(
+ padding: EdgeInsets.symmetric(horizontal: 6),
+ child: SizedBox(
+ width: 12,
+ height: 12,
+ child: CircularProgressIndicator(strokeWidth: 1.5),
+ ),
+ ),
+ _ViewerActions(
+ zoomed: widget.zoomed,
+ onReload: _controller == null ? null : _reload,
+ onZoom: widget.onToggleZoom,
+ onClose: widget.onClose,
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+
+ Widget _body(BuildContext context) {
+ final controller = _controller;
+ final url = widget.pane.url;
+ if (controller == null) {
+ return _Notice(
+ key: const ValueKey('web-pane-placeholder'),
+ icon: LucideIcons.globe,
+ title: 'Viewer',
+ detail: url ?? 'No viewer yet.',
+ );
+ }
+ return Stack(
+ fit: StackFit.expand,
+ children: [
+ WebViewWidget(controller: controller),
+ if (_failure != null)
+ ColoredBox(
+ color: grid.AppPalette.windowBg,
+ child: _Notice(
+ icon: LucideIcons.unplug,
+ title: 'Waiting for the viewer',
+ detail: _failure!,
+ action: TextButton(
+ onPressed: _reload,
+ child: const Text('Retry'),
+ ),
+ ),
+ ),
+ ],
+ );
+ }
+}
+
+/// Reload, zoom, close — the terminal header's controls, minus the one that
+/// ends an agent, because a viewer has no agent to end. Same 28px buttons,
+/// same hover reveal ([PaneHeaderHover]), so the two headers read as one kind.
+class _ViewerActions extends StatelessWidget {
+ const _ViewerActions({
+ required this.zoomed,
+ this.onReload,
+ this.onZoom,
+ this.onClose,
+ });
+
+ final bool zoomed;
+ final VoidCallback? onReload, onZoom, onClose;
+
+ @override
+ Widget build(BuildContext context) {
+ Widget action(String tooltip, IconData icon, VoidCallback? callback) =>
+ IconButton(
+ tooltip: tooltip,
+ onPressed: callback,
+ icon: Icon(icon, size: 16),
+ style: ButtonStyle(
+ fixedSize: const WidgetStatePropertyAll(Size(28, 28)),
+ minimumSize: const WidgetStatePropertyAll(Size(28, 28)),
+ padding: const WidgetStatePropertyAll(EdgeInsets.zero),
+ tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+ visualDensity: VisualDensity.standard,
+ shape: WidgetStatePropertyAll(
+ RoundedRectangleBorder(borderRadius: BorderRadius.circular(6)),
+ ),
+ foregroundColor: WidgetStateProperty.resolveWith((states) {
+ if (states.contains(WidgetState.disabled)) {
+ return grid.AppPalette.textFaint;
+ }
+ if (states.contains(WidgetState.hovered) ||
+ states.contains(WidgetState.focused)) {
+ return AppColors.text;
+ }
+ return AppColors.mutedStrong.withValues(alpha: .8);
+ }),
+ overlayColor: WidgetStatePropertyAll(grid.AppSurface.hoverFill),
+ ),
+ );
+ return Row(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ action('Reload viewer', LucideIcons.refreshCw, onReload),
+ const SizedBox(width: 2),
+ action(
+ zoomed ? 'Restore agents' : 'Zoom viewer',
+ zoomed ? LucideIcons.minimize : LucideIcons.maximize,
+ onZoom,
+ ),
+ const SizedBox(width: 2),
+ action('Close viewer', LucideIcons.x, onClose),
+ ],
+ );
+ }
+}
+
+class _Notice extends StatelessWidget {
+ const _Notice({
+ super.key,
+ required this.icon,
+ required this.title,
+ required this.detail,
+ this.action,
+ });
+
+ final IconData icon;
+ final String title;
+ final String detail;
+ final Widget? action;
+
+ @override
+ Widget build(BuildContext context) => Center(
+ child: Padding(
+ padding: const EdgeInsets.all(20),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Icon(icon, size: 26, color: AppColors.mutedStrong),
+ const SizedBox(height: 10),
+ Text(
+ title,
+ style: TextStyle(
+ color: AppColors.text,
+ fontFamily: AppFonts.sans,
+ fontSize: 12.5,
+ fontWeight: FontWeight.w600,
+ ),
+ ),
+ const SizedBox(height: 4),
+ Text(
+ detail,
+ textAlign: TextAlign.center,
+ maxLines: 3,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(
+ color: AppColors.mutedStrong,
+ fontFamily: AppFonts.mono,
+ fontFamilyFallback: AppFonts.monoFallback,
+ fontSize: 11,
+ ),
+ ),
+ if (action != null) ...[const SizedBox(height: 8), action!],
+ ],
+ ),
+ ),
+ );
+}
diff --git a/desktop/macos/Flutter/GeneratedPluginRegistrant.swift b/desktop/macos/Flutter/GeneratedPluginRegistrant.swift
index c79bbf4a5..d3e11baa8 100644
--- a/desktop/macos/Flutter/GeneratedPluginRegistrant.swift
+++ b/desktop/macos/Flutter/GeneratedPluginRegistrant.swift
@@ -10,6 +10,7 @@ import file_selector_macos
import package_info_plus
import screen_retriever_macos
import url_launcher_macos
+import webview_flutter_wkwebview
import window_manager
func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
@@ -18,5 +19,6 @@ func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
FPPPackageInfoPlusPlugin.register(with: registry.registrar(forPlugin: "FPPPackageInfoPlusPlugin"))
ScreenRetrieverMacosPlugin.register(with: registry.registrar(forPlugin: "ScreenRetrieverMacosPlugin"))
UrlLauncherPlugin.register(with: registry.registrar(forPlugin: "UrlLauncherPlugin"))
+ WebViewFlutterPlugin.register(with: registry.registrar(forPlugin: "WebViewFlutterPlugin"))
WindowManagerPlugin.register(with: registry.registrar(forPlugin: "WindowManagerPlugin"))
}
diff --git a/desktop/pubspec.lock b/desktop/pubspec.lock
index 63fb6b771..bd07cc942 100644
--- a/desktop/pubspec.lock
+++ b/desktop/pubspec.lock
@@ -700,6 +700,38 @@ packages:
url: "https://pub.dev"
source: hosted
version: "3.1.0"
+ webview_flutter:
+ dependency: "direct main"
+ description:
+ name: webview_flutter
+ sha256: d53e1ccf5516f25017e3c9d44c39034db352d20fa34fe200674270242c2c5111
+ url: "https://pub.dev"
+ source: hosted
+ version: "4.14.1"
+ webview_flutter_android:
+ dependency: transitive
+ description:
+ name: webview_flutter_android
+ sha256: "4de8b3d1ff4ebe1bdb42e68a5e4f809194a3cb0117a8f495f590004f00da3964"
+ url: "https://pub.dev"
+ source: hosted
+ version: "4.14.1"
+ webview_flutter_platform_interface:
+ dependency: transitive
+ description:
+ name: webview_flutter_platform_interface
+ sha256: "1221c1b12f5278791042f2ec2841743784cf25c5a644e23d6680e5d718824f04"
+ url: "https://pub.dev"
+ source: hosted
+ version: "2.15.1"
+ webview_flutter_wkwebview:
+ dependency: transitive
+ description:
+ name: webview_flutter_wkwebview
+ sha256: fe359c7fac1002124b5b9e2ba3a41906bbb9b2d029ccb4a0067404d8f3704730
+ url: "https://pub.dev"
+ source: hosted
+ version: "3.26.1"
win32:
dependency: transitive
description:
diff --git a/desktop/pubspec.yaml b/desktop/pubspec.yaml
index b039dd859..bf9104c5c 100644
--- a/desktop/pubspec.yaml
+++ b/desktop/pubspec.yaml
@@ -62,6 +62,13 @@ dependencies:
sqlite3: ^2.4.0
desktop_drop: ^0.8.4
path: ^1.9.1
+ # The web pane: a domain harness's viewer (Circuit's board, Workshop's part)
+ # drawn beside its agent's terminal. THE one native plugin this feature adds
+ # — WKWebView via the endorsed `webview_flutter_wkwebview`, which lands in
+ # the macOS SPM package list and GeneratedPluginRegistrant. macOS only for
+ # now; the pane shows the URL as text where no implementation is registered
+ # (Linux, and every `flutter test`). See CLAUDE.md on what a plugin costs.
+ webview_flutter: ^4.14.1
dev_dependencies:
flutter_test: