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.

Keep search width stable and add keyboard preview paging

dee90b6f68d9cbe
diff --git a/desktop/lib/shortcuts/keymap_commands.dart b/desktop/lib/shortcuts/keymap_commands.dart
index 3038781e0..e1440f55f 100644
--- a/desktop/lib/shortcuts/keymap_commands.dart
+++ b/desktop/lib/shortcuts/keymap_commands.dart
@@ -358,6 +358,22 @@ final harnessCommands = <HarnessCommand>[
context: KeymapContext.picker,
repeatable: true,
),
+ const HarnessCommand(
+ 'picker.preview_page_up',
+ 'Scroll preview up',
+ ShortcutGroup.navigate,
+ extraKeys: ['pageup'],
+ context: KeymapContext.picker,
+ repeatable: true,
+ ),
+ const HarnessCommand(
+ 'picker.preview_page_down',
+ 'Scroll preview down',
+ ShortcutGroup.navigate,
+ extraKeys: ['pagedown'],
+ context: KeymapContext.picker,
+ repeatable: true,
+ ),
const HarnessCommand(
'picker.accept',
'Open the selected result',
@@ -408,6 +424,8 @@ List<String> describeKeyStrokeKeys(KeyStroke stroke) => [
'right': '→',
'up': '↑',
'down': '↓',
+ 'pageup': 'Page Up',
+ 'pagedown': 'Page Down',
'enter': '↵',
'escape': 'Esc',
'tab': '⇥',
diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
index 1fe23bfa8..472d3ca39 100644
--- a/desktop/lib/state/swarm_search.dart
+++ b/desktop/lib/state/swarm_search.dart
@@ -52,6 +52,15 @@ class SwarmSearchController extends ChangeNotifier {
bool get allowsCommands => split == null && history == null;
bool get isCommandMode =>
allowsCommands && (commandsOnly || query.trimLeft().startsWith('>'));
+ bool get hasPreview => !isCommandMode && history == null && selected != null;
+
+ // Paging the preview must not rebuild the result list or its text editor.
+ final _previewPage = ValueNotifier<int>(0);
+ ValueListenable<int> get previewPage => _previewPage;
+ void pagePreview(int pages) {
+ if (hasPreview) _previewPage.value += pages;
+ }
+
final String targetId, targetName;
// The workspace can retain normalized metadata across picker openings. Each
// read still validates its snapshot; query, selection and output stay local.
@@ -282,6 +291,7 @@ class SwarmSearchController extends ChangeNotifier {
void dispose() {
app.removeListener(_refresh);
projects?.removeListener(_refresh);
+ _previewPage.dispose();
super.dispose();
}
}
diff --git a/desktop/lib/widgets/harness_start_page.dart b/desktop/lib/widgets/harness_start_page.dart
index 2d6ccff6f..66a0834e1 100644
--- a/desktop/lib/widgets/harness_start_page.dart
+++ b/desktop/lib/widgets/harness_start_page.dart
@@ -112,9 +112,7 @@ class _HarnessStartPageState extends State<HarnessStartPage> {
),
child: Center(
child: ConstrainedBox(
- constraints: BoxConstraints(
- maxWidth: _showResults ? 1120 : 640,
- ),
+ constraints: const BoxConstraints(maxWidth: 1120),
child: Column(
children: [
const Text(
diff --git a/desktop/lib/widgets/swarm_search_preview.dart b/desktop/lib/widgets/swarm_search_preview.dart
index 977ae6241..71ca8c8f6 100644
--- a/desktop/lib/widgets/swarm_search_preview.dart
+++ b/desktop/lib/widgets/swarm_search_preview.dart
@@ -58,12 +58,18 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
Timer? _warm;
String? _selectedId;
final _scroll = ScrollController();
+ int _lastPage = 0;
+ int _pendingPages = 0;
+ String? _renderedId;
+ bool _pageScheduled = false;
AppNotifier get app => widget.search.app;
@override
void initState() {
super.initState();
widget.search.addListener(_changed);
+ _lastPage = widget.search.previewPage.value;
+ widget.search.previewPage.addListener(_pageChanged);
_changed();
}
@@ -72,7 +78,10 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
super.didUpdateWidget(oldWidget);
if (oldWidget.search != widget.search) {
oldWidget.search.removeListener(_changed);
+ oldWidget.search.previewPage.removeListener(_pageChanged);
widget.search.addListener(_changed);
+ _lastPage = widget.search.previewPage.value;
+ widget.search.previewPage.addListener(_pageChanged);
_selectedId = null;
_changed();
}
@@ -82,6 +91,7 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
final row = widget.search.selected;
if (_selectedId == row?.id) return;
_selectedId = row?.id;
+ _pendingPages = 0;
if (_scroll.hasClients) _scroll.jumpTo(0);
setState(() {});
_warm?.cancel();
@@ -101,10 +111,46 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
});
}
+ void _pageChanged() {
+ final page = widget.search.previewPage.value;
+ _pendingPages += page - _lastPage;
+ _lastPage = page;
+ if (_renderedId == _selectedId &&
+ _scroll.hasClients &&
+ _scroll.position.hasContentDimensions) {
+ _applyPage();
+ } else if (!_pageScheduled) {
+ // A new result can be selected and paged before its first layout. Apply
+ // against its own dimensions; a later selection clears the pending move.
+ _pageScheduled = true;
+ WidgetsBinding.instance.addPostFrameCallback((_) {
+ if (!mounted) return;
+ _pageScheduled = false;
+ _applyPage();
+ });
+ }
+ }
+
+ void _applyPage() {
+ if (_pendingPages == 0 || !_scroll.hasClients) return;
+ final position = _scroll.position;
+ if (!position.hasContentDimensions) return;
+ final pages = _pendingPages;
+ _pendingPages = 0;
+ // Keep a little overlap for reading, and respond directly to held keys.
+ _scroll.jumpTo(
+ (position.pixels + pages * position.viewportDimension * .8).clamp(
+ position.minScrollExtent,
+ position.maxScrollExtent,
+ ),
+ );
+ }
+
@override
void dispose() {
_warm?.cancel();
widget.search.removeListener(_changed);
+ widget.search.previewPage.removeListener(_pageChanged);
_scroll.dispose();
super.dispose();
}
@@ -115,6 +161,7 @@ class _SwarmSearchPreviewState extends State<SwarmSearchPreview> {
builder: (context, _) {
final row = widget.search.selected;
if (row == null) return const SizedBox.shrink();
+ _renderedId = row.id;
final agents = _agents(app, row);
return Semantics(
container: true,
diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
index ff1e6aebd..7f881bf03 100644
--- a/desktop/lib/widgets/swarm_switcher.dart
+++ b/desktop/lib/widgets/swarm_switcher.dart
@@ -168,6 +168,12 @@ class SwarmSearchKeys extends StatelessWidget {
'picker.add_here': () => choose(true),
'picker.next': () => move(1),
'picker.previous': () => move(-1),
+ if (search != null) ...{
+ 'picker.preview_page_up': () =>
+ run(() => search.pagePreview(-1)),
+ 'picker.preview_page_down': () =>
+ run(() => search.pagePreview(1)),
+ },
'picker.cancel': onClose,
if (search == null || search.allowsCommands)
'navigation.commands': () {
@@ -232,6 +238,12 @@ class SwarmSearchKeys extends StatelessWidget {
const SingleActivator(LogicalKeyboardKey.arrowDown): () =>
move(1),
const SingleActivator(LogicalKeyboardKey.arrowUp): () => move(-1),
+ if (search != null) ...{
+ const SingleActivator(LogicalKeyboardKey.pageUp): () =>
+ run(() => search.pagePreview(-1)),
+ const SingleActivator(LogicalKeyboardKey.pageDown): () =>
+ run(() => search.pagePreview(1)),
+ },
const SingleActivator(
LogicalKeyboardKey.keyN,
control: true,
@@ -590,8 +602,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
],
),
);
- final preview =
- !search.isCommandMode && search.history == null && selected != null
+ final preview = search.hasPreview
? SwarmSearchPreview(
key: const ValueKey('swarm-search-preview'),
search: search,
diff --git a/desktop/test/swarm_search_preview_test.dart b/desktop/test/swarm_search_preview_test.dart
index 003a2238b..0ee7509b2 100644
--- a/desktop/test/swarm_search_preview_test.dart
+++ b/desktop/test/swarm_search_preview_test.dart
@@ -7,8 +7,11 @@ import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/models.dart';
import 'package:harness/state/app_state.dart';
+import 'package:harness/terminal/terminal_binary.dart';
import 'package:harness/widgets/swarm_switcher.dart';
+import 'keymap_host_test.dart' show MemoryKeymap, key;
+import 'keymap_runtime_test.dart' as configured;
import 'swarm_interactions_test.dart' show chord;
import 'swarm_screen_test.dart' show mount, terminal;
import 'swarm_state_test.dart' show createApp;
@@ -115,6 +118,148 @@ void main() {
app.dispose();
});
for (final inline in [false, true]) {
+ for (final mapping in ['fallback', 'default', 'remapped']) {
+ testWidgets(
+ 'preview paging retains search input and selection (inline=$inline, $mapping)',
+ (tester) async {
+ final app = createApp();
+ await seedPreviews(app);
+ await app.handleEventForTest('m', {
+ 'type': 'text_delta',
+ 'payload': {
+ 'agentId': 'a0',
+ 'sessionId': 'session-a0',
+ 'content': List.generate(
+ 60,
+ (i) => 'Existing result line $i: the saved session details.',
+ ).join('\n'),
+ },
+ });
+ await app.handleEventForTest('m', {
+ 'type': 'turn_ended',
+ 'payload': {'agentId': 'a0', 'sessionId': 'session-a0'},
+ });
+ final frames = <TerminalBinaryFrame>[];
+ app.adoptSessionForTest(terminal('a69', frames));
+ app.newSwarm();
+ final map = MemoryKeymap();
+ final remapped = mapping == 'remapped';
+ if (remapped) {
+ map.apply('''{"bindings":[
+ {"keys":"pageup","command":null,"when":"picker"},
+ {"keys":"pagedown","command":null,"when":"picker"},
+ {"keys":"alt+j","command":"picker.preview_page_down","when":"picker"},
+ {"keys":"alt+k","command":"picker.preview_page_up","when":"picker"}
+ ]}''');
+ }
+ if (mapping == 'fallback') {
+ await mount(tester, app);
+ } else {
+ await configured.mount(tester, app, map);
+ }
+ final field = find.byKey(
+ ValueKey(inline ? 'harness-start-search' : 'swarm-search-input'),
+ );
+ if (inline) {
+ await tester.tap(field);
+ } else {
+ await chord(tester, LogicalKeyboardKey.keyO);
+ }
+ await tester.enterText(field, 'Checkout retries');
+ await tester.pump();
+ final search = tester
+ .widget<SwarmSearchResults>(find.byType(SwarmSearchResults))
+ .search;
+ ScrollPosition previewPosition() => tester
+ .widget<Scrollbar>(
+ find.descendant(
+ of: find.byKey(const ValueKey('swarm-search-preview')),
+ matching: find.byType(Scrollbar),
+ ),
+ )
+ .controller!
+ .position;
+ final editor = tester.widget<EditableText>(
+ find.descendant(of: field, matching: find.byType(EditableText)),
+ );
+ final value = editor.controller.value;
+ final selected = search.selected!.id;
+ final listPosition = tester
+ .widget<ListView>(
+ find.byKey(const ValueKey('swarm-search-result-list')),
+ )
+ .controller!
+ .position;
+ final listOffset = listPosition.pixels;
+ var notifications = 0;
+ search.addListener(() => notifications++);
+ expect(previewPosition().maxScrollExtent, greaterThan(0));
+ if (remapped) {
+ await key(tester, LogicalKeyboardKey.pageDown);
+ expect(previewPosition().pixels, 0);
+ }
+ Future<void> page({bool up = false, bool pump = true}) async {
+ final trigger = remapped
+ ? up
+ ? LogicalKeyboardKey.keyK
+ : LogicalKeyboardKey.keyJ
+ : up
+ ? LogicalKeyboardKey.pageUp
+ : LogicalKeyboardKey.pageDown;
+ if (remapped) {
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.altLeft);
+ }
+ await tester.sendKeyEvent(trigger);
+ if (remapped) {
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft);
+ }
+ if (pump) await tester.pump();
+ }
+
+ await page(pump: false);
+ expect(previewPosition().pixels, greaterThan(0));
+ expect(search.selected!.id, selected);
+ expect(editor.controller.value, value);
+ expect(editor.focusNode.hasPrimaryFocus, isTrue);
+ expect(listPosition.pixels, listOffset);
+ expect(notifications, 0);
+ await tester.pump();
+ await page(up: true);
+ expect(previewPosition().pixels, 0);
+
+ // The IME owns navigation during composition; no page or accept leaks.
+ editor.controller.value = value.copyWith(
+ composing: TextRange(start: 0, end: value.text.length),
+ );
+ await page();
+ expect(previewPosition().pixels, 0);
+ expect(search.selected!.id, selected);
+ editor.controller.value = value;
+ await page();
+ expect(previewPosition().pixels, greaterThan(0));
+
+ // Switching to a group and paging before its frame uses the new
+ // viewport and never retains the previous session's reading position.
+ await tester.enterText(field, 'Test host');
+ await page();
+ expect(search.selected!.agentId, isNull);
+ expect(previewPosition().pixels, greaterThan(0));
+ await page(up: true);
+ expect(previewPosition().pixels, 0);
+ await tester.enterText(field, 'Checkout retries');
+ await tester.pump();
+ expect(previewPosition().pixels, 0);
+ expect(editor.focusNode.hasPrimaryFocus, isTrue);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.panes.any((pane) => pane.agentId == 'a0'), isTrue);
+ expect(frames, isEmpty);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ },
+ );
+ }
testWidgets(
'existing content previews are immediate and preserve search focus (inline=$inline)',
(tester) async {
diff --git a/desktop/tool/keymap_native_checks.swift b/desktop/tool/keymap_native_checks.swift
index f0dc79946..1a6dd397b 100644
--- a/desktop/tool/keymap_native_checks.swift
+++ b/desktop/tool/keymap_native_checks.swift
@@ -49,6 +49,14 @@ try checkKeymap(changed.match([stroke("ctrl+j")], context: "picker").binding?.co
"Picker remapping wins")
try checkKeymap(defaults.match([stroke("cmd+i")], context: "picker").binding == nil,
"Always-on preview does not consume a hide-preview shortcut")
+for (key, command) in [("pageup", "picker.preview_page_up"), ("pagedown", "picker.preview_page_down")] {
+ try checkKeymap(defaults.match([stroke(key)], context: "picker").binding?.command == command,
+ "Preview paging follows the exported Search binding")
+ for context in ["workspace", "terminal"] {
+ try checkKeymap(defaults.match([stroke(key)], context: context).binding == nil,
+ "Preview paging leaves \(context) input alone")
+ }
+}
let dispatcher = HarnessNativeKeyDispatch(changed)
let field = NSObject(), otherField = NSObject()
@@ -82,6 +90,8 @@ try checkKeymap(send("cmd+o", executable: false).handled && send("cmd+o", execut
"An unavailable mapped action cannot fall through as input")
try checkKeymap(send("cmd+o", repeated: true).command == nil, "Search does not repeat")
try checkKeymap(send("ctrl+j", repeated: true).command == "picker.previous", "Result movement repeats")
+try checkKeymap(send("pagedown", repeated: true).command == "picker.preview_page_down",
+ "Holding a preview paging key continues scrolling")
_ = send("cmd+k")
dispatcher.suspend()
try checkKeymap(dispatcher.pending.isEmpty && !dispatcher.release(1), "Window blur clears pending and held keys")
@@ -94,6 +104,8 @@ try checkKeymap(HarnessKeyStroke.fromCharacters("1", modifiers: [.command, .shif
"Shift stays in modifiers after layout translation")
try checkKeymap(HarnessKeyStroke.fromCharacters("\u{f702}", modifiers: .command) == stroke("cmd+left"),
"AppKit arrow characters map to the same logical keys")
+try checkKeymap(HarnessKeyStroke.fromCharacters("\u{f72d}", modifiers: [.function, .numericPad]) == stroke("pagedown"),
+ "Mac Fn navigation maps to preview paging without an extra modifier")
try checkKeymap(HarnessKeyStroke.fromCharacters("木", modifiers: []) == nil,
"Unsupported composed text is not guessed as a QWERTY key")
try checkKeymap(stroke("cmd+shift+left").menuEquivalent == "\u{f702}" && stroke("f24").menuEquivalent == "\u{f71b}",
diff --git a/docs/harness-agent-first-tabs.md b/docs/harness-agent-first-tabs.md
index 6bdf1f701..9fcd88bb0 100644
--- a/docs/harness-agent-first-tabs.md
+++ b/docs/harness-agent-first-tabs.md
@@ -9,7 +9,8 @@ proposals in the progress log.
**Cmd-T / New Tab** and the tab-bar plus open the Harness start page. Its solid
background matches the selected tab. The centered title and search controls sit
-lower with generous empty space. The resting field is no wider than 640 logical pixels,
+lower with generous empty space. The search field keeps the same responsive width
+whether results are closed or open, capped at 1120 logical pixels,
with **Open Harness** and accented **+ New Harness** buttons underneath.
The field starts empty and focused so typing works immediately. Typing, clicking
@@ -68,6 +69,8 @@ surface can grow to 1120 logical pixels, placing the list and preview side by
side. Narrow windows stack them with a compact preview heading. Both sections
scroll independently; the start-page actions stay reachable. Hover selects a
preview without taking typing focus. Enter opens the highlighted result.
+Page Up/Down scrolls the preview while retaining the query, focus and selection.
+The bindings are configurable in the same Search keymap as result navigation.
Working sessions lead with the current observed request and latest activity.
Idle sessions lead with an existing saved response or the latest response seen
diff --git a/docs/harness-search-preview.md b/docs/harness-search-preview.md
index e0b16348f..e11caa218 100644
--- a/docs/harness-search-preview.md
+++ b/docs/harness-search-preview.md
@@ -4,6 +4,13 @@ Both Open Harness and inline start-page search now display existing session
content in a shared preview. This document records the content rules, data path,
and remaining coverage limits.
+The start-page search stays at one responsive width, capped at 1120 logical pixels;
+opening results reveals content below without widening or recentering the field.
+Page Up/Down scrolls the preview with overlap while the query keeps keyboard focus.
+Arrow keys still choose results, and Enter opens the selection. The two preview
+paging commands can be remapped or unbound in the Search keymap. Paging only moves
+the local viewport; it never refreshes content or rebuilds the search results.
+
**Content rule:** never generate a summary or start a model for previews. Display
only text and metadata already available from the session.
diff --git a/docs/harness-v2-handoff.md b/docs/harness-v2-handoff.md
index f26871b36..c1dbea084 100644
--- a/docs/harness-v2-handoff.md
+++ b/docs/harness-v2-handoff.md
@@ -46,8 +46,9 @@ are:
precedence. Cmd-R splits right and Cmd-D splits down. Native menus, help and actual
dispatch must agree; native menu and titlebar hover hints are removed.
- New Tab uses the Google-like page with a **solid selected-tab background**,
- lower centered controls and generous whitespace. Resting search is at most 640 logical
- pixels wide, blank and focused initially. Its expanded preview can grow to 1120 pixels.
+ lower centered controls and generous whitespace. Search is blank and focused
+ initially, retaining one responsive width (at most 1120 logical pixels) as
+ results and preview open beneath it.
Typing, clicking, or pressing an arrow
reveals the same results, selection, arrows and Enter behavior as Cmd-O.
Focus alone leaves results hidden and builds no catalog. Open Harness and
@@ -68,6 +69,8 @@ are:
events. No `session_get`, full-history read, or terminal attachment. Cached
selection is immediate; cold data fills asynchronously. Disconnected records
retain saved text without claiming a live working/waiting state.
+ Page Up/Down scrolls preview content without changing selection or typing focus;
+ both actions participate in the configurable Search keymap.
- Creation uses **New Harness** for its title and CTA, with no ordinary Cancel.
Escape or one outside click dismisses it directly. A pending launch cannot be
dismissed accidentally; an uncertain outcome retains Close and Check status.