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.

feat(desktop): embed Linux Harness viewer (#1387)

Ed. Abdiel Rodriguez18b9ccd1de5b
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index 3a22d1a07..b4898995d 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -348,7 +348,7 @@ jobs:
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
- clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-12-dev
+ clang cmake ninja-build pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev liblzma-dev libstdc++-12-dev
# Flutter has no Linux ARM64 SDK archive. Its action installs the same
# pinned SDK from Git, verifies the revision, and reuses main's native cache.
diff --git a/desktop/RELEASE.md b/desktop/RELEASE.md
index 2ea82c011..8bf8c56c5 100644
--- a/desktop/RELEASE.md
+++ b/desktop/RELEASE.md
@@ -497,6 +497,33 @@ matrix job; running by hand, fetch one yourself from the
and none is needed: the trust boundary is the same sha256-verified manifest entry `DesktopUpdater`
already checks on every platform.
+The Linux viewer uses the host's WebKitGTK 4.1 runtime (`libwebkit2gtk-4.1-0`). The AppImage
+contains Harness and its Flutter bundle, but does not bundle WebKitGTK. The Linux plugin is loaded
+optionally: if the host runtime or plugin is unavailable, Harness still launches and viewer panes
+show the URL placeholder (recordings offer browser playback). Install the runtime package and
+restart Harness to enable embedded viewing. Linux release builds also need
+`libwebkit2gtk-4.1-dev` on the build host.
+
+`webview_all_linux` is deliberately pinned to `1.2.1`: its published manifest uses
+`webview_flutter_platform_interface`, while `1.3.0` switched to the separate
+`webview_platform_interface` package. A caret constraint would allow that incompatible
+interface change. The lockfile records the source archive hash; upgrading the plugin
+requires reviewing its native code and rerunning Linux integration tests. The pin
+neither freezes the distribution's WebKitGTK security updates nor establishes that
+the plugin has been security-audited or endorsed by Flutter. It is MIT-licensed;
+retain its attribution in Flutter's bundled notices.
+
+The official [`webview_flutter`](https://pub.dev/packages/webview_flutter/versions/4.14.1)
+currently lists Android, iOS and macOS implementations, with no endorsed Linux
+implementation. [`webview_flutter_linux`](https://pub.dev/packages/webview_flutter_linux)
+is an experimental, non-endorsed WPE WebKit implementation requiring WPE WebKit 2.52+,
+so it is not a drop-in endorsed replacement for this GTK integration.
+
+GTK views are detached while registered Flutter transient overlays are open,
+including pane menus, the agent picker and resize help. All native viewers are
+hidden for that interval because a popup may cross pane boundaries; their controllers
+retain the loaded pages. Dismissal restores them without navigation or reload.
+
**Packaged as a single-file AppImage**, not a tarball. The script stages an AppDir
(`usr/bin/` = the Flutter `bundle/` verbatim, plus a hand-written `harness.desktop` and the
`harness.png` icon CMake already installs at the bundle root) and hands it to `appimagetool` with
diff --git a/desktop/integration_test/linux_webview_native_test.dart b/desktop/integration_test/linux_webview_native_test.dart
new file mode 100644
index 000000000..629940ca9
--- /dev/null
+++ b/desktop/integration_test/linux_webview_native_test.dart
@@ -0,0 +1,82 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/linux_webview_runtime.dart';
+import 'package:harness/widgets/native_webview_host.dart';
+import 'package:harness/widgets/pane_menu.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+// Run on Linux with WebKitGTK installed using flutter test -d linux.
+void main() {
+ IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+ testWidgets('optional Linux runtime and retained native page', (
+ tester,
+ ) async {
+ await LinuxWebViewRuntime.initialize();
+ expect(LinuxWebViewRuntime.available, isTrue);
+
+ final loaded = Completer<void>();
+ final controller = WebViewController();
+ await controller.setJavaScriptMode(JavaScriptMode.unrestricted);
+ await controller.setNavigationDelegate(
+ NavigationDelegate(
+ onPageFinished: (_) {
+ if (!loaded.isCompleted) loaded.complete();
+ },
+ ),
+ );
+ await controller.loadHtmlString(
+ '<html><body>Linux viewer<script>window.retained = 42;</script></body></html>',
+ );
+ Widget page(bool visible) => MaterialApp(
+ home: Scaffold(
+ body: NativeWebViewHost(
+ visible: visible,
+ child: WebViewWidget(controller: controller),
+ ),
+ ),
+ );
+ await tester.pumpWidget(page(true));
+ await tester.runAsync(
+ () => loaded.future.timeout(const Duration(seconds: 30)),
+ );
+ expect(
+ await controller.runJavaScriptReturningResult('window.retained'),
+ 42,
+ );
+ final context = tester.element(find.byType(NativeWebViewHost));
+ final menu = showPaneMenu<void>(
+ context: context,
+ position: const RelativeRect.fromLTRB(20, 20, 20, 0),
+ children: (close) => [
+ paneMenuItem(
+ onTap: () => close(null),
+ child: const Text('Close native test menu'),
+ ),
+ ],
+ );
+ await tester.pumpAndSettle();
+ expect(find.byType(WebViewWidget), findsNothing);
+ await tester.tap(find.text('Close native test menu'));
+ await menu;
+ await tester.pumpAndSettle();
+ expect(find.byType(WebViewWidget), findsOneWidget);
+ expect(
+ await controller.runJavaScriptReturningResult('window.retained'),
+ 42,
+ );
+ await tester.pumpWidget(page(false));
+ await tester.pump();
+ await tester.pumpWidget(page(true));
+ await tester.pump();
+ expect(
+ await controller.runJavaScriptReturningResult('window.retained'),
+ 42,
+ );
+ await tester.pumpWidget(const SizedBox.shrink());
+ await controller.loadHtmlString('<html></html>');
+ });
+}
diff --git a/desktop/lib/core/linux_webview_runtime.dart b/desktop/lib/core/linux_webview_runtime.dart
new file mode 100644
index 000000000..3f782560e
--- /dev/null
+++ b/desktop/lib/core/linux_webview_runtime.dart
@@ -0,0 +1,20 @@
+import 'package:flutter/services.dart';
+
+import 'runtime_platform.dart';
+
+/// The Dart plugin registers even when its optional native library cannot load.
+class LinuxWebViewRuntime {
+ static const channel = MethodChannel('harness/linux_webview');
+ static bool available = false;
+
+ static Future<void> initialize() async {
+ if (!RuntimePlatform.isLinux) return;
+ try {
+ available = await channel.invokeMethod<bool>('isAvailable') ?? false;
+ } on PlatformException {
+ available = false;
+ } on MissingPluginException {
+ available = false;
+ }
+ }
+}
diff --git a/desktop/lib/main.dart b/desktop/lib/main.dart
index 56fe3fcf5..41a0fb8c6 100644
--- a/desktop/lib/main.dart
+++ b/desktop/lib/main.dart
@@ -4,6 +4,7 @@ import 'package:flutter/widgets.dart';
import 'app_shell.dart';
import 'core/connected_semantics.dart';
+import 'core/linux_webview_runtime.dart';
import 'ws/ws_conn.dart' show rememberAppVersionForSockets;
import 'update/started_marker.dart';
import 'desktop_workspace.dart'
@@ -19,6 +20,7 @@ import 'desktop_workspace.dart'
Future<void> main() async {
HarnessWidgetsBinding();
prepareConsole();
+ await LinuxWebViewRuntime.initialize();
unawaited(rememberAppVersionForSockets());
await startHarness(
authenticatedScreen: authenticatedWorkspace,
diff --git a/desktop/lib/store/store_demo_dialog.dart b/desktop/lib/store/store_demo_dialog.dart
index e2037a8ad..28202384c 100644
--- a/desktop/lib/store/store_demo_dialog.dart
+++ b/desktop/lib/store/store_demo_dialog.dart
@@ -7,9 +7,12 @@ import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
import '../core/dsh_catalog.dart';
+import '../core/linux_webview_runtime.dart';
+import '../core/runtime_platform.dart';
import '../shared/theme/app_theme.dart' as grid;
import '../shared/widgets/app_dialog.dart';
import '../terminal/terminal_text.dart';
+import '../widgets/native_webview_host.dart';
Future<void> showStoreDemo(
BuildContext context, {
@@ -75,11 +78,17 @@ class _StoreDemoDialogState extends State<StoreDemoDialog>
bool _loading = true;
bool _openingBrowser = false;
+ bool get _webviewAvailable =>
+ WebViewPlatform.instance != null &&
+ (!RuntimePlatform.isLinux || LinuxWebViewRuntime.available);
+
@override
void initState() {
super.initState();
WidgetsBinding.instance.addObserver(this);
- if (WebViewPlatform.instance != null) _start();
+ if (_webviewAvailable) {
+ _start();
+ }
}
Future<void> _start() async {
@@ -208,7 +217,7 @@ class _StoreDemoDialogState extends State<StoreDemoDialog>
Expanded(
child: ColoredBox(
color: const Color(0xFF111316),
- child: _failed || WebViewPlatform.instance == null
+ child: _failed || !_webviewAvailable
? Center(
child: Padding(
padding: const EdgeInsets.all(24),
@@ -243,7 +252,9 @@ class _StoreDemoDialogState extends State<StoreDemoDialog>
children: [
if (_controller != null)
Positioned.fill(
- child: WebViewWidget(controller: _controller!),
+ child: NativeWebViewHost(
+ child: WebViewWidget(controller: _controller!),
+ ),
),
if (_loading)
const Center(child: CircularProgressIndicator()),
diff --git a/desktop/lib/widgets/agent_picker.dart b/desktop/lib/widgets/agent_picker.dart
index 4732022c2..67fe1be4d 100644
--- a/desktop/lib/widgets/agent_picker.dart
+++ b/desktop/lib/widgets/agent_picker.dart
@@ -9,6 +9,7 @@ import '../shared/theme/app_theme.dart' as grid;
import '../shortcuts/app_keymap.dart';
import '../shortcuts/keymap.dart';
import 'box_chrome.dart';
+import 'transient_menus.dart';
import 'search_result_text.dart';
import 'swarm_search_input.dart';
import 'swarm_switcher.dart' show SwarmSearchActionLabel, swarmSearchRowHeight;
@@ -132,6 +133,7 @@ class _AgentPickerState extends State<AgentPicker> {
String get _hint =>
widget.label == 'Agent' ? AgentPicker.hint : 'Search harnesses';
final _portal = OverlayPortalController();
+ VoidCallback? _unregisterMenu;
final _query = TextEditingController();
final _inputFocus = FocusNode(debugLabel: 'Agent search input');
final _ownBarFocus = FocusNode(debugLabel: 'Agent search');
@@ -178,6 +180,7 @@ class _AgentPickerState extends State<AgentPicker> {
@override
void dispose() {
+ _unregisterMenu?.call();
_inputFocus.removeListener(_inputFocusChanged);
_barFocus.removeListener(_barFocusChanged);
_query.dispose();
@@ -266,6 +269,7 @@ class _AgentPickerState extends State<AgentPicker> {
_cursor = 0;
if (_scroll.hasClients) _scroll.jumpTo(0);
_portal.show();
+ _unregisterMenu ??= registerTransientMenu(() => _close(refocus: false));
setState(() {});
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted && _open) _inputFocus.requestFocus();
@@ -275,6 +279,8 @@ class _AgentPickerState extends State<AgentPicker> {
void _close({bool refocus = true}) {
if (!_open) return;
_portal.hide();
+ _unregisterMenu?.call();
+ _unregisterMenu = null;
_query.clear();
setState(() {});
if (refocus) _barFocus.requestFocus();
diff --git a/desktop/lib/widgets/native_webview_host.dart b/desktop/lib/widgets/native_webview_host.dart
new file mode 100644
index 000000000..488547fb5
--- /dev/null
+++ b/desktop/lib/widgets/native_webview_host.dart
@@ -0,0 +1,31 @@
+import 'package:flutter/material.dart';
+
+import '../core/runtime_platform.dart';
+import 'transient_menus.dart';
+
+/// Detaches GTK's overlay widget while Flutter draws above it. The controller
+/// stays with its owner, retaining the loaded page until the widget returns.
+class NativeWebViewHost extends StatelessWidget {
+ const NativeWebViewHost({
+ super.key,
+ required this.child,
+ this.visible = true,
+ });
+
+ final Widget child;
+ final bool visible;
+
+ @override
+ Widget build(BuildContext context) {
+ if (!RuntimePlatform.isLinux) return child;
+ final routeCovered = ModalRoute.isCurrentOf(context) == false;
+ return ValueListenableBuilder<bool>(
+ valueListenable: transientMenusVisible,
+ builder: (_, menuVisible, child) =>
+ !visible || routeCovered || menuVisible
+ ? const SizedBox.shrink()
+ : child!,
+ child: child,
+ );
+ }
+}
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index 17bc7c3db..c43aa6ecc 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -16,6 +16,7 @@ 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';
@@ -47,6 +48,7 @@ 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';
@@ -312,6 +314,14 @@ class _SwarmCanvasState extends State<_SwarmCanvas> {
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;
@@ -371,9 +381,10 @@ class _SwarmCanvasState extends State<_SwarmCanvas> {
_resizeRequest = app.paneResizeRequest;
_resizeFocus.requestFocus();
_resizeHelp.show();
+ _unregisterResizeHelp ??= registerTransientMenu(_hideResizeHelp);
}
if (_activeId != app.activeSwarmId) {
- if (_resizeHelp.isShowing) _resizeHelp.hide();
+ _hideResizeHelp();
_offsets[_activeId] = Offset(
_horizontalScroll.hasClients ? _horizontalScroll.offset : 0,
_scroll.hasClients ? _scroll.offset : 0,
@@ -482,6 +493,7 @@ class _SwarmCanvasState extends State<_SwarmCanvas> {
@override
void dispose() {
widget.notifier.removeListener(_onAppChanged);
+ _unregisterResizeHelp?.call();
terminalFontStore.removeListener(_onFontChanged);
_resizeFocus.dispose();
_idleFocus.dispose();
@@ -769,7 +781,7 @@ class _SwarmCanvasState extends State<_SwarmCanvas> {
),
child: FocusScope(
onFocusChange: (focused) {
- if (!focused && _resizeHelp.isShowing) _resizeHelp.hide();
+ if (!focused) _hideResizeHelp();
},
child: Stack(
children: [
@@ -1432,6 +1444,18 @@ class _PaneCell extends StatelessWidget {
);
}
+ 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(_paneRadius - 1),
+ child: child,
+ );
+ }
+
Widget _frame(
AppearancePrefs prefs, {
required bool focused,
@@ -1478,18 +1502,7 @@ class _PaneCell extends StatelessWidget {
// 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: ClipRRect(
- // Clipped HERE rather than through Container's own clipBehavior.
- //
- // Both clip, but they clip to different shapes: Container's is the
- // decoration's OUTER edge, so the child fills the full radius and
- // paints under the rim, leaving a square-shouldered corner peeking
- // through the 1px the rim occupies. This one takes the rim's pixel
- // off the radius, so the fill stops exactly where the rim starts.
- //
- // TerminalPanel opens with a ColoredBox across its whole box, and
- // that is what was reaching the corners.
- borderRadius: BorderRadius.circular(_paneRadius - 1),
+ child: _clipContent(
child: RepaintBoundary(
child: _FileDropZone(
notifier: notifier,
diff --git a/desktop/lib/widgets/pane_menu.dart b/desktop/lib/widgets/pane_menu.dart
index e457bb309..c8f61fd5a 100644
--- a/desktop/lib/widgets/pane_menu.dart
+++ b/desktop/lib/widgets/pane_menu.dart
@@ -95,6 +95,7 @@ Future<T?> showPaneMenu<T>({
delegate: _PaneMenuPosition(position, minWidth, maxWidth),
child: _PaneMenuFocus(
close: () => close(null),
+ onDispose: deregister,
focusFirst: focusFirst,
// A row list sizes itself to its widest row ([IntrinsicWidth]) and scrolls as one
// column. A BODY does neither: it is handed the menu's box and lays itself out, which
@@ -192,10 +193,12 @@ class _PaneMenuPosition extends SingleChildLayoutDelegate {
class _PaneMenuFocus extends StatefulWidget {
const _PaneMenuFocus({
required this.close,
+ required this.onDispose,
required this.focusFirst,
required this.child,
});
final VoidCallback close;
+ final VoidCallback onDispose;
final bool focusFirst;
final Widget child;
@@ -219,6 +222,7 @@ class _PaneMenuFocusState extends State<_PaneMenuFocus> {
@override
void dispose() {
+ widget.onDispose();
_scope.dispose();
super.dispose();
}
diff --git a/desktop/lib/widgets/transient_menus.dart b/desktop/lib/widgets/transient_menus.dart
index 35fa7366f..dddc52ef1 100644
--- a/desktop/lib/widgets/transient_menus.dart
+++ b/desktop/lib/widgets/transient_menus.dart
@@ -9,13 +9,38 @@
/// [dismissTransientMenus], the same way it already closes the search field.
library;
+import 'package:flutter/foundation.dart';
+import 'package:flutter/scheduler.dart';
+
+final _visible = ValueNotifier<bool>(false);
+
+/// GTK views cannot composite below Flutter popups, including across panes.
+ValueListenable<bool> get transientMenusVisible => _visible;
+
+void _publishVisibility() {
+ // A portal can disappear during its owner's disposal in a build.
+ if (SchedulerBinding.instance.schedulerPhase ==
+ SchedulerPhase.persistentCallbacks) {
+ SchedulerBinding.instance.addPostFrameCallback((_) => _publishVisibility());
+ } else {
+ _visible.value = _open.isNotEmpty;
+ }
+}
+
/// Close callbacks for every overlay menu currently on screen.
final List<void Function()> _open = <void Function()>[];
/// Register [close] while a menu is showing. The returned callback deregisters it.
void Function() registerTransientMenu(void Function() close) {
_open.add(close);
- return () => _open.remove(close);
+ _publishVisibility();
+ var registered = true;
+ return () {
+ if (!registered) return;
+ registered = false;
+ _open.remove(close);
+ _publishVisibility();
+ };
}
/// Close every overlay menu. Safe to call when none are open.
diff --git a/desktop/lib/widgets/web_pane_panel.dart b/desktop/lib/widgets/web_pane_panel.dart
index 8c4b4d6b3..3d6865a31 100644
--- a/desktop/lib/widgets/web_pane_panel.dart
+++ b/desktop/lib/widgets/web_pane_panel.dart
@@ -9,6 +9,7 @@ import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
import '../core/open_in_browser.dart';
+import '../core/linux_webview_runtime.dart';
import '../core/runtime_platform.dart';
import '../core/models.dart' show AgentVerdict;
import '../core/test_run.dart';
@@ -27,6 +28,7 @@ import 'engine_identity.dart';
import 'harness_activity_mark.dart';
import '../terminal/terminal_text.dart';
import 'verdict_marks.dart';
+import 'native_webview_host.dart';
/// A domain harness's viewer, in a tile beside its agent's terminal.
///
@@ -38,8 +40,8 @@ import 'verdict_marks.dart';
///
/// 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
+/// under `flutter test`, and on Linux without WebKitGTK. There the body shows
+/// 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({
@@ -86,7 +88,10 @@ class WebPanePanel extends StatefulWidget {
/// 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 =>
- webviewAvailableForTest ?? (!kUnderTest && RuntimePlatform.isMacOS);
+ webviewAvailableForTest ??
+ (!kUnderTest &&
+ (RuntimePlatform.isMacOS ||
+ (RuntimePlatform.isLinux && LinuxWebViewRuntime.available)));
/// A test that installs a fake `WebViewPlatform` mounts the real webview path.
@visibleForTesting
@@ -401,7 +406,12 @@ class _WebPanePanelState extends State<WebPanePanel> {
children: [
_header(context),
Divider(height: 1, color: AppColors.border),
- Expanded(child: _body(context)),
+ Expanded(
+ child: NativeWebViewHost(
+ visible: widget.visible,
+ child: _body(context),
+ ),
+ ),
],
),
);
diff --git a/desktop/linux/CMakeLists.txt b/desktop/linux/CMakeLists.txt
index bbf4b872d..d245c3399 100644
--- a/desktop/linux/CMakeLists.txt
+++ b/desktop/linux/CMakeLists.txt
@@ -74,6 +74,15 @@ set_target_properties(${BINARY_NAME}
# them to the application.
include(flutter/generated_plugins.cmake)
+# Build and bundle the Linux WebView, but load it optionally at runtime. Linking
+# it here would make a missing host WebKitGTK runtime prevent Harness startup.
+get_target_property(HARNESS_PLUGIN_LINKS ${BINARY_NAME} LINK_LIBRARIES)
+list(REMOVE_ITEM HARNESS_PLUGIN_LINKS webview_all_linux_plugin)
+set_property(TARGET ${BINARY_NAME} PROPERTY LINK_LIBRARIES "${HARNESS_PLUGIN_LINKS}")
+target_include_directories(${BINARY_NAME} PRIVATE
+ "${CMAKE_CURRENT_SOURCE_DIR}/flutter/ephemeral/.plugin_symlinks/webview_all_linux/linux/include")
+target_link_libraries(${BINARY_NAME} PRIVATE ${CMAKE_DL_LIBS})
+
# === Installation ===
# By default, "installing" just makes a relocatable bundle in the build
diff --git a/desktop/linux/flutter/generated_plugin_registrant.cc b/desktop/linux/flutter/generated_plugin_registrant.cc
index ba30a6e34..81af9798c 100644
--- a/desktop/linux/flutter/generated_plugin_registrant.cc
+++ b/desktop/linux/flutter/generated_plugin_registrant.cc
@@ -10,6 +10,7 @@
#include <file_selector_linux/file_selector_plugin.h>
#include <screen_retriever_linux/screen_retriever_linux_plugin.h>
#include <url_launcher_linux/url_launcher_plugin.h>
+#include <webview_all_linux/webview_all_linux_plugin.h>
#include <window_manager/window_manager_plugin.h>
void fl_register_plugins(FlPluginRegistry* registry) {
@@ -25,6 +26,9 @@ void fl_register_plugins(FlPluginRegistry* registry) {
g_autoptr(FlPluginRegistrar) url_launcher_linux_registrar =
fl_plugin_registry_get_registrar_for_plugin(registry, "UrlLauncherPlugin");
url_launcher_plugin_register_with_registrar(url_launcher_linux_registrar);
+ g_autoptr(FlPluginRegistrar) webview_all_linux_registrar =
+ fl_plugin_registry_get_registrar_for_plugin(registry, "WebviewAllLinuxPlugin");
+ webview_all_linux_plugin_register_with_registrar(webview_all_linux_registrar);
g_autoptr(FlPluginRegistrar) window_manager_registrar =
fl_plugin_registry_get_registrar_for_plugin(registry, "WindowManagerPlugin");
window_manager_plugin_register_with_registrar(window_manager_registrar);
diff --git a/desktop/linux/flutter/generated_plugins.cmake b/desktop/linux/flutter/generated_plugins.cmake
index 8e8962b39..e60b8fdf4 100644
--- a/desktop/linux/flutter/generated_plugins.cmake
+++ b/desktop/linux/flutter/generated_plugins.cmake
@@ -7,6 +7,7 @@ list(APPEND FLUTTER_PLUGIN_LIST
file_selector_linux
screen_retriever_linux
url_launcher_linux
+ webview_all_linux
window_manager
)
diff --git a/desktop/linux/runner/CMakeLists.txt b/desktop/linux/runner/CMakeLists.txt
index e97dabc70..23cbc2f05 100644
--- a/desktop/linux/runner/CMakeLists.txt
+++ b/desktop/linux/runner/CMakeLists.txt
@@ -9,6 +9,7 @@ project(runner LANGUAGES CXX)
add_executable(${BINARY_NAME}
"main.cc"
"my_application.cc"
+ "optional_webview.cc"
"${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)
diff --git a/desktop/linux/runner/my_application.cc b/desktop/linux/runner/my_application.cc
index 7965b30e6..af8ce0d7f 100644
--- a/desktop/linux/runner/my_application.cc
+++ b/desktop/linux/runner/my_application.cc
@@ -268,7 +268,12 @@ static void my_application_activate(GApplication* application) {
gdk_rgba_parse(&background_color, "#000000");
fl_view_set_background_color(view, &background_color);
gtk_widget_show(GTK_WIDGET(view));
- gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(view));
+ // Install the WebView host before FlView is realized: reparenting a live
+ // Flutter GL surface can leave it blank when the first viewer opens.
+ GtkWidget* viewer_overlay = gtk_overlay_new();
+ gtk_container_add(GTK_CONTAINER(viewer_overlay), GTK_WIDGET(view));
+ gtk_container_add(GTK_CONTAINER(window), viewer_overlay);
+ gtk_widget_show(viewer_overlay);
g_signal_connect(view, "key-press-event", G_CALLBACK(super_as_meta_cb),
nullptr);
g_signal_connect(view, "key-release-event", G_CALLBACK(super_as_meta_cb),
diff --git a/desktop/linux/runner/optional_webview.cc b/desktop/linux/runner/optional_webview.cc
new file mode 100644
index 000000000..2e7dce796
--- /dev/null
+++ b/desktop/linux/runner/optional_webview.cc
@@ -0,0 +1,45 @@
+#include <flutter_linux/flutter_linux.h>
+#include <dlfcn.h>
+#include <unistd.h>
+
+#include <webview_all_linux/webview_all_linux_plugin.h>
+
+// Keep the plugin and its WebKitGTK dependency out of the executable's DT_NEEDED.
+// Resolve beside the actual executable, independent of cwd and LD_LIBRARY_PATH.
+void webview_all_linux_plugin_register_with_registrar(
+ FlPluginRegistrar* registrar) {
+ g_autofree gchar* executable = g_file_read_link("/proc/self/exe", nullptr);
+ g_autofree gchar* directory = executable ? g_path_get_dirname(executable) : nullptr;
+ g_autofree gchar* path = directory
+ ? g_build_filename(directory, "lib", "libwebview_all_linux_plugin.so", nullptr)
+ : nullptr;
+ void* library = path ? dlopen(path, RTLD_NOW | RTLD_LOCAL) : nullptr;
+ using RegisterPlugin = void (*)(FlPluginRegistrar*);
+ auto register_plugin = library ? reinterpret_cast<RegisterPlugin>(
+ dlsym(library, "webview_all_linux_plugin_register_with_registrar")) : nullptr;
+ const bool available = register_plugin != nullptr;
+ if (available) {
+ register_plugin(registrar);
+ // The plugin's callbacks remain live for the lifetime of the process.
+ } else if (library) {
+ dlclose(library);
+ }
+
+ g_autoptr(FlStandardMethodCodec) codec = fl_standard_method_codec_new();
+ g_autoptr(FlMethodChannel) channel = fl_method_channel_new(
+ fl_plugin_registrar_get_messenger(registrar), "harness/linux_webview",
+ FL_METHOD_CODEC(codec));
+ fl_method_channel_set_method_call_handler(
+ channel,
+ [](FlMethodChannel*, FlMethodCall* call, gpointer data) {
+ g_autoptr(FlMethodResponse) response = nullptr;
+ if (g_strcmp0(fl_method_call_get_name(call), "isAvailable") == 0) {
+ response = FL_METHOD_RESPONSE(fl_method_success_response_new(
+ fl_value_new_bool(GPOINTER_TO_INT(data))));
+ } else {
+ response = FL_METHOD_RESPONSE(fl_method_not_implemented_response_new());
+ }
+ fl_method_call_respond(call, response, nullptr);
+ },
+ GINT_TO_POINTER(available), nullptr);
+}
diff --git a/desktop/pubspec.lock b/desktop/pubspec.lock
index fa2e1bf7b..b81dbc78b 100644
--- a/desktop/pubspec.lock
+++ b/desktop/pubspec.lock
@@ -820,6 +820,14 @@ packages:
url: "https://pub.dev"
source: hosted
version: "3.2.0"
+ webview_all_linux:
+ dependency: "direct main"
+ description:
+ name: webview_all_linux
+ sha256: "8303b57455ed4ac646102cbdb46a5f69c23cca0d1bd6e27adb76b5afc4dec679"
+ url: "https://pub.dev"
+ source: hosted
+ version: "1.2.1"
webview_flutter:
dependency: "direct main"
description:
diff --git a/desktop/pubspec.yaml b/desktop/pubspec.yaml
index 864d34325..6e7a0ddcb 100644
--- a/desktop/pubspec.yaml
+++ b/desktop/pubspec.yaml
@@ -90,13 +90,16 @@ dependencies:
# 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.
+ # the macOS SPM package list and GeneratedPluginRegistrant. Linux support
+ # is added separately below; it falls back to the URL when WebKitGTK is
+ # unavailable. See CLAUDE.md on what a plugin costs.
webview_flutter: ^4.14.1
# Named directly for the WebKit creation params (muted autoplay in viewer panes).
webview_flutter_platform_interface: ^2.15.1
webview_flutter_wkwebview: ^3.26.1
+ # Keep exact: 1.3+ uses a different platform interface. This pin controls
+ # plugin updates, not the host WebKitGTK engine. See RELEASE.md.
+ webview_all_linux: 1.2.1
# The Finder tile's code editor and its highlighter (lib/finder/): pure
# Dart, no native plugin, so the macOS SPM package list is unchanged.
re_editor: ^0.10.0
diff --git a/desktop/test/linux_webview_runtime_test.dart b/desktop/test/linux_webview_runtime_test.dart
new file mode 100644
index 000000000..f2cfde342
--- /dev/null
+++ b/desktop/test/linux_webview_runtime_test.dart
@@ -0,0 +1,72 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/linux_webview_runtime.dart';
+import 'package:harness/core/runtime_platform.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/store/store_demo_dialog.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+import 'support/fake_webview.dart';
+import 'support/real_fonts.dart';
+
+void main() {
+ setUpAll(loadRealFonts);
+ TestWidgetsFlutterBinding.ensureInitialized();
+ final messenger =
+ TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger;
+
+ tearDown(() {
+ messenger.setMockMethodCallHandler(LinuxWebViewRuntime.channel, null);
+ LinuxWebViewRuntime.available = false;
+ });
+
+ for (final available in [true, false]) {
+ test(
+ 'native availability $available controls Linux viewer support',
+ () async {
+ messenger.setMockMethodCallHandler(LinuxWebViewRuntime.channel, (
+ call,
+ ) async {
+ expect(call.method, 'isAvailable');
+ return available;
+ });
+ await LinuxWebViewRuntime.initialize();
+ expect(LinuxWebViewRuntime.available, available);
+ },
+ skip: !RuntimePlatform.isLinux,
+ );
+ }
+
+ test('missing native plugin keeps Harness usable', () async {
+ await LinuxWebViewRuntime.initialize();
+ expect(LinuxWebViewRuntime.available, isFalse);
+ });
+
+ test('native initialization errors disable the viewer', () async {
+ messenger.setMockMethodCallHandler(LinuxWebViewRuntime.channel, (_) async {
+ throw PlatformException(code: 'unavailable');
+ });
+ await LinuxWebViewRuntime.initialize();
+ expect(LinuxWebViewRuntime.available, isFalse);
+ });
+ testWidgets('Linux recordings offer browser playback without WebKitGTK', (
+ tester,
+ ) async {
+ final platform = FakeWebViewPlatform();
+ WebViewPlatform.instance = platform;
+ LinuxWebViewRuntime.available = false;
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: const StoreDemoDialog(
+ name: 'Example',
+ video: 'https://example.com/run.mp4',
+ ),
+ ),
+ );
+ expect(find.text('Watch this recording in your browser.'), findsOneWidget);
+ expect(platform.controllers, isEmpty);
+ await tester.pumpWidget(const SizedBox.shrink());
+ }, skip: !RuntimePlatform.isLinux);
+}
diff --git a/desktop/test/native_webview_host_test.dart b/desktop/test/native_webview_host_test.dart
new file mode 100644
index 000000000..c2a4616da
--- /dev/null
+++ b/desktop/test/native_webview_host_test.dart
@@ -0,0 +1,109 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/runtime_platform.dart';
+import 'package:harness/widgets/agent_picker.dart';
+import 'package:harness/widgets/native_webview_host.dart';
+import 'package:harness/widgets/pane_menu.dart';
+import 'package:harness/widgets/transient_menus.dart';
+
+import 'support/agent_picker.dart';
+
+void main() {
+ testWidgets('nested overlays release visibility only after the last close', (
+ tester,
+ ) async {
+ await tester.pumpWidget(
+ const MaterialApp(home: NativeWebViewHost(child: Text('Native surface'))),
+ );
+ final first = registerTransientMenu(() {});
+ final second = registerTransientMenu(() {});
+ await tester.pump();
+ if (RuntimePlatform.isLinux) {
+ expect(find.text('Native surface'), findsNothing);
+ }
+ first();
+ first();
+ await tester.pump();
+ expect(transientMenusVisible.value, isTrue);
+ if (RuntimePlatform.isLinux) {
+ expect(find.text('Native surface'), findsNothing);
+ }
+ second();
+ await tester.pump();
+ expect(transientMenusVisible.value, isFalse);
+ expect(find.text('Native surface'), findsOneWidget);
+ });
+
+ testWidgets('agent picker hides native views and releases them on disposal', (
+ tester,
+ ) async {
+ final pickerVisible = ValueNotifier<bool>(true);
+ addTearDown(pickerVisible.dispose);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: Column(
+ children: [
+ ValueListenableBuilder<bool>(
+ valueListenable: pickerVisible,
+ builder: (_, visible, _) => visible
+ ? AgentPicker(
+ value: 'test',
+ choices: [
+ AgentChoice(
+ id: 'test',
+ label: 'Test agent',
+ mark: (size) => SizedBox.square(dimension: size),
+ ),
+ ],
+ onChanged: (_) {},
+ )
+ : const SizedBox.shrink(),
+ ),
+ const Expanded(
+ child: NativeWebViewHost(child: Text('Native surface')),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ await openAgentSearch(tester);
+ expect(transientMenusVisible.value, isTrue);
+ if (RuntimePlatform.isLinux) {
+ expect(find.text('Native surface'), findsNothing);
+ }
+ dismissTransientMenus();
+ await tester.pumpAndSettle();
+ expect(transientMenusVisible.value, isFalse);
+ expect(find.text('Native surface'), findsOneWidget);
+ await openAgentSearch(tester);
+ pickerVisible.value = false;
+ await tester.pump();
+ await tester.pump();
+ expect(transientMenusVisible.value, isFalse);
+ expect(find.text('Native surface'), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ });
+
+ testWidgets('removing the overlay owner releases pane menu visibility', (
+ tester,
+ ) async {
+ await tester.pumpWidget(
+ const MaterialApp(home: Scaffold(body: Text('Owner'))),
+ );
+ showPaneMenu<void>(
+ context: tester.element(find.text('Owner')),
+ position: const RelativeRect.fromLTRB(20, 20, 20, 0),
+ children: (close) => [
+ paneMenuItem(onTap: () => close(null), child: const Text('Menu')),
+ ],
+ );
+ await tester.pumpAndSettle();
+ expect(transientMenusVisible.value, isTrue);
+ await tester.pumpWidget(const SizedBox.shrink());
+ await tester.pump();
+ expect(transientMenusVisible.value, isFalse);
+ expect(tester.takeException(), isNull);
+ });
+}
diff --git a/desktop/test/swarm_resize_test.dart b/desktop/test/swarm_resize_test.dart
index 482a47166..6812ce9b7 100644
--- a/desktop/test/swarm_resize_test.dart
+++ b/desktop/test/swarm_resize_test.dart
@@ -1,3 +1,5 @@
+import 'package:harness/widgets/transient_menus.dart';
+
import 'dart:convert';
import 'dart:io';
import 'dart:ui' as ui;
@@ -237,6 +239,7 @@ void main() {
await tester.sendKeyEvent(LogicalKeyboardKey.enter);
await tester.pump();
expect(find.byKey(const ValueKey('pane-resize-hint')), findsOneWidget);
+ expect(transientMenusVisible.value, isTrue);
await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight);
await tester.pump();
expect(
@@ -258,6 +261,7 @@ void main() {
expect(app.focusedPaneId, left.id);
expect(frames, isEmpty);
expect(find.byKey(const ValueKey('pane-resize-hint')), findsNothing);
+ expect(transientMenusVisible.value, isFalse);
await tester.sendKeyEvent(LogicalKeyboardKey.arrowUp);
await tester.pump(const Duration(milliseconds: 10));
expect(frames.single.bytes, [27, 91, 65]);
diff --git a/desktop/test/web_pane_test.dart b/desktop/test/web_pane_test.dart
index fe123acdf..4b8d007eb 100644
--- a/desktop/test/web_pane_test.dart
+++ b/desktop/test/web_pane_test.dart
@@ -8,12 +8,15 @@ import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/open_in_browser.dart';
+import 'package:harness/core/runtime_platform.dart';
import 'package:harness/state/app_state.dart';
import 'package:harness/state/harness_monitor_controller.dart';
import 'package:harness/state/pane_arrangement.dart';
import 'package:harness/state/terminal_pane.dart';
import 'package:harness/terminal/terminal_binary.dart';
import 'package:harness/widgets/web_pane_panel.dart';
+import 'package:harness/widgets/pane_menu.dart';
+import 'package:harness/widgets/transient_menus.dart';
import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
import 'support/fake_webview.dart';
@@ -333,6 +336,43 @@ void main() {
expect(app.panes.map((p) => p.isWeb), [true, false]);
});
+ testWidgets(
+ 'Linux viewer hides beneath dialogs and returns after dismissal',
+ (tester) async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ app.stateOf('m')!.nodeOnline = true;
+ app.adoptSessionForTest(terminal('a0', <TerminalBinaryFrame>[]));
+ await mount(tester, app);
+ await _synced(app, 'a0', viewerUrl: 'http://127.0.0.1:4179/');
+ await tester.pump();
+ final context = tester.element(find.byType(WebPanePanel));
+ final placeholder = find.byKey(const ValueKey('web-pane-placeholder'));
+ expect(placeholder, findsOneWidget);
+ final dialog = showDialog<void>(
+ context: context,
+ builder: (_) => const AlertDialog(title: Text('Close tab?')),
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('Close tab?'), findsOneWidget);
+ if (RuntimePlatform.isLinux) {
+ expect(placeholder, findsNothing);
+ expect(
+ find.byKey(
+ const ValueKey('web-pane-placeholder'),
+ skipOffstage: false,
+ ),
+ findsNothing,
+ );
+ }
+ Navigator.of(tester.element(find.text('Close tab?'))).pop();
+ await dialog;
+ await tester.pumpAndSettle();
+ expect(placeholder, findsOneWidget);
+ expect(tester.takeException(), isNull);
+ },
+ );
+
testWidgets('the tile renders a header and, under test, the URL in words', (
tester,
) async {
@@ -346,6 +386,24 @@ void main() {
await tester.pump();
expect(WebPanePanel.webviewAvailable, isFalse);
expect(find.byType(WebPanePanel), findsOneWidget);
+ if (RuntimePlatform.isLinux) {
+ // The native GTK overlay hides itself under any rounded ancestor clip.
+ expect(
+ find.ancestor(
+ of: find.byType(WebPanePanel),
+ matching: find.byType(ClipRRect),
+ ),
+ findsNothing,
+ );
+ expect(
+ find.ancestor(
+ of: find.byType(WebPanePanel),
+ matching: find.byType(ClipRect),
+ ),
+ findsWidgets,
+ );
+ }
+
expect(find.byKey(const ValueKey('web-pane-placeholder')), findsOneWidget);
expect(find.textContaining('http://127.0.0.1:4179/'), findsOneWidget);
// With no embedded webview the page opens in the browser instead
@@ -546,6 +604,79 @@ void main() {
return app;
}
+ testWidgets('Linux pane menu detaches the viewer and restores its page', (
+ tester,
+ ) async {
+ await open(tester);
+ final controller = platform.controllers.single;
+ controller.delegate!.onPageFinished!(controller.loads.single.toString());
+ await tester.pump();
+ final initialLoads = controller.loads.length;
+ final context = tester.element(find.byType(WebPanePanel));
+ final menu = showPaneMenu<String>(
+ context: context,
+ position: const RelativeRect.fromLTRB(20, 100, 20, 0),
+ children: (close) => [
+ paneMenuItem(
+ onTap: () => close('keep'),
+ child: const Text('Keep viewer open'),
+ ),
+ ],
+ );
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('pane-menu-surface')), findsOneWidget);
+ expect(transientMenusVisible.value, isTrue);
+ if (RuntimePlatform.isLinux) {
+ expect(find.byKey(const ValueKey('fake-webview')), findsNothing);
+ }
+ await tester.tap(find.text('Keep viewer open'));
+ expect(await menu, 'keep');
+ await tester.pumpAndSettle();
+ expect(transientMenusVisible.value, isFalse);
+ expect(find.byKey(const ValueKey('fake-webview')), findsOneWidget);
+ expect(platform.controllers, [controller]);
+ expect(controller.loads, hasLength(initialLoads));
+ expect(tester.takeException(), isNull);
+ });
+
+ testWidgets('Linux dialogs and routes preserve the loaded controller', (
+ tester,
+ ) async {
+ await open(tester);
+ final controller = platform.controllers.single;
+ controller.delegate!.onPageFinished!(controller.loads.single.toString());
+ await tester.pump();
+ final initialLoads = controller.loads.length;
+ final context = tester.element(find.byType(WebPanePanel));
+ final navigator = Navigator.of(context);
+ final dialog = showDialog<void>(
+ context: context,
+ builder: (_) => const AlertDialog(title: Text('Close tab?')),
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('Close tab?'), findsOneWidget);
+ if (RuntimePlatform.isLinux) {
+ expect(find.byKey(const ValueKey('fake-webview')), findsNothing);
+ }
+ navigator.pop();
+ await dialog;
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('fake-webview')), findsOneWidget);
+ final route = navigator.push<void>(
+ MaterialPageRoute<void>(
+ builder: (_) => const Scaffold(body: Text('Other page')),
+ ),
+ );
+ await tester.pumpAndSettle();
+ navigator.pop();
+ await route;
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('fake-webview')), findsOneWidget);
+ expect(platform.controllers, [controller]);
+ expect(controller.loads, hasLength(initialLoads));
+ expect(tester.takeException(), isNull);
+ });
+
testWidgets(
'Harness Monitor loads its page once, though the tile rebuilds while its channel is added',
(tester) async {