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.

Add Customize Harness with backgrounds and appearance controls

dee60a95d549261
diff --git a/desktop/assets/swarm-wallpapers/swarm-welcome-abstract.jpg b/desktop/assets/swarm-wallpapers/swarm-welcome-abstract.jpg
new file mode 100644
index 000000000..0c86f7a2f
Binary files /dev/null and b/desktop/assets/swarm-wallpapers/swarm-welcome-abstract.jpg differ
diff --git a/desktop/assets/swarm-wallpapers/swarm-welcome-ai.jpg b/desktop/assets/swarm-wallpapers/swarm-welcome-ai.jpg
new file mode 100644
index 000000000..ff251b0c8
Binary files /dev/null and b/desktop/assets/swarm-wallpapers/swarm-welcome-ai.jpg differ
diff --git a/desktop/assets/swarm-wallpapers/swarm-welcome-associative-memory.jpg b/desktop/assets/swarm-wallpapers/swarm-welcome-associative-memory.jpg
new file mode 100644
index 000000000..dd3f520e4
Binary files /dev/null and b/desktop/assets/swarm-wallpapers/swarm-welcome-associative-memory.jpg differ
diff --git a/desktop/assets/swarm-wallpapers/swarm-welcome-dusk.jpg b/desktop/assets/swarm-wallpapers/swarm-welcome-dusk.jpg
new file mode 100644
index 000000000..35e6edf1b
Binary files /dev/null and b/desktop/assets/swarm-wallpapers/swarm-welcome-dusk.jpg differ
diff --git a/desktop/lib/settings/appearance/typography_section.dart b/desktop/lib/settings/appearance/typography_section.dart
index 1bb361080..75d066f54 100644
--- a/desktop/lib/settings/appearance/typography_section.dart
+++ b/desktop/lib/settings/appearance/typography_section.dart
@@ -53,10 +53,10 @@ class _SelectSkeleton extends StatelessWidget {
}
}
-/// Settings ▸ Appearance ▸ Typography — the face the app is set in, and how big.
+/// Customize Harness ▸ Appearance ▸ Typography — the face the app is set in, and how big.
///
/// ⚠️ The APP's type, not the terminal's. The terminal keeps its own face and
-/// size in Settings ▸ Terminal, because what it renders is a grid a remote
+/// size in Customize Harness ▸ Terminal, because what it renders is a grid a remote
/// program draws into rather than a label this app writes — and the UI scale is
/// fenced out of it at five seams, guarded by
/// `test/terminal_ui_scale_isolation_test.dart`.
diff --git a/desktop/lib/settings/sections/appearance_section.dart b/desktop/lib/settings/sections/appearance_section.dart
index 00f19f54b..fa47312e3 100644
--- a/desktop/lib/settings/sections/appearance_section.dart
+++ b/desktop/lib/settings/sections/appearance_section.dart
@@ -5,10 +5,10 @@ import '../../shared/widgets/section_scaffold.dart';
import '../appearance/typography_section.dart';
import '../appearance/palette_section.dart';
-/// Settings ▸ Appearance: how the app looks on this Mac.
+/// Customize Harness ▸ Appearance: how the app looks on this Mac.
///
/// Palettes coordinate the workspace and terminal defaults. UI typography stays
-/// separate from the agent terminal's font and size in Settings ▸ Terminal.
+/// separate from the agent terminal's font and size in Customize Harness ▸ Terminal.
class AppearanceSection extends StatelessWidget {
const AppearanceSection({super.key});
diff --git a/desktop/lib/settings/sections/terminal_section.dart b/desktop/lib/settings/sections/terminal_section.dart
index 479d188e1..3a405c02a 100644
--- a/desktop/lib/settings/sections/terminal_section.dart
+++ b/desktop/lib/settings/sections/terminal_section.dart
@@ -12,7 +12,7 @@ import '../../terminal/terminal_font_store.dart';
import '../../terminal/terminal_theme.dart';
import '../../terminal/terminal_theme_store.dart';
-/// Settings ▸ Terminal: the colours and the face the agent's output is drawn in.
+/// Customize Harness ▸ Terminal: the colours and the face the agent's output is drawn in.
///
/// Laid out in the app's own [SettingRow]s rather than in bare Material, for
/// the same reason Appearance is: a preference reads as a preference here or it
@@ -28,10 +28,7 @@ class TerminalSection extends StatelessWidget {
grid.AppTheme.watch(context);
return SectionScaffold(
title: 'Terminal',
- subtitle:
- "The colours and font every terminal pane is drawn in, at its own "
- "size — the app's UI scale never reaches it. ⌘+ and ⌘- resize "
- "without leaving this screen.",
+ subtitle: 'Colors and fonts for your agent terminals.',
// A SingleChildScrollView, never a ListView — same reason as Appearance:
// a lazy list keeps children across a rebuild and strands them on the
// palette they first mounted with.
@@ -75,9 +72,7 @@ class _Controls extends StatelessWidget {
const SizedBox(height: 10),
SettingRow(
title: 'Font',
- detail:
- 'Monospaced faces only — a proportional one misaligns '
- 'every column an agent draws',
+ detail: 'Font for agent output',
control: _FamilyField(family: terminalFontStore.family),
),
const SizedBox(height: 10),
@@ -85,8 +80,7 @@ class _Controls extends StatelessWidget {
title: 'Size',
detail:
'${TerminalFontStore.minSize.round()}–'
- '${TerminalFontStore.maxSize.round()}pt. A change '
- "re-derives the grid and resizes the agent's terminal",
+ '${TerminalFontStore.maxSize.round()}pt. Resize with ⌘+ and ⌘−',
control: _SizeStepper(size: style.fontSize),
),
const SizedBox(height: 14),
@@ -267,11 +261,13 @@ class _Preview extends StatelessWidget {
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
- Row(
+ Wrap(
+ alignment: WrapAlignment.spaceBetween,
+ crossAxisAlignment: WrapCrossAlignment.center,
+ spacing: 12,
+ runSpacing: 4,
children: [
- Expanded(
- child: Text('Preview', style: theme.textTheme.titleSmall),
- ),
+ Text('Preview', style: theme.textTheme.titleSmall),
// What the pick costs in geometry. This is the number that turns
// into a `terminal_resize` frame and a SIGWINCH at the far end,
// so the screen says it out loud rather than leaving the user to
@@ -370,15 +366,17 @@ class _ResetRow extends StatelessWidget {
// own: its default is a named option the user can pick straight from the
// list ('Match app appearance').
final atDefault = terminalFontStore.isDefault;
- return Row(
- mainAxisAlignment: MainAxisAlignment.end,
+ return Wrap(
+ alignment: WrapAlignment.end,
+ crossAxisAlignment: WrapCrossAlignment.center,
+ spacing: 10,
+ runSpacing: 8,
children: [
Text(
'⌘0',
style: Theme.of(context).textTheme.bodySmall
?.copyWith(color: grid.AppPalette.textFaint),
),
- const SizedBox(width: 10),
OutlinedButton(
key: const Key('terminal-settings-reset-button'),
// Dead at the default, because that is what pressing it would leave
diff --git a/desktop/lib/settings/settings_screen.dart b/desktop/lib/settings/settings_screen.dart
index ce8501373..8b5faa23a 100644
--- a/desktop/lib/settings/settings_screen.dart
+++ b/desktop/lib/settings/settings_screen.dart
@@ -6,11 +6,9 @@ import '../state/app_state.dart';
import '../widgets/window_chrome.dart';
import 'sections/about_section.dart';
import 'sections/account_section.dart';
-import 'sections/appearance_section.dart';
import 'sections/debug_section.dart';
import 'sections/devices_section.dart';
import 'sections/shortcuts_section.dart';
-import 'sections/terminal_section.dart';
import 'sections/tracking_section.dart';
import 'sections/usage_section.dart';
import 'settings_nav.dart';
@@ -155,8 +153,6 @@ class _SettingsBody extends StatelessWidget {
Widget build(BuildContext context) {
final screen = switch (section) {
SettingsSection.account => AccountSection(notifier: notifier),
- SettingsSection.appearance => const AppearanceSection(),
- SettingsSection.terminal => const TerminalSection(),
SettingsSection.usage => const UsageSection(),
SettingsSection.devices => const DevicesSection(),
SettingsSection.shortcuts => const ShortcutsSection(),
diff --git a/desktop/lib/settings/settings_section.dart b/desktop/lib/settings/settings_section.dart
index 5ab5e69f5..3c5de11ef 100644
--- a/desktop/lib/settings/settings_section.dart
+++ b/desktop/lib/settings/settings_section.dart
@@ -10,8 +10,6 @@ import '../logging/debug_surface.dart';
/// be listed without a screen behind it or reachable without a row.
enum SettingsSection {
account(LucideIcons.user300, 'Account'),
- appearance(LucideIcons.sun300, 'Appearance'),
- terminal(LucideIcons.terminal300, 'Terminal'),
usage(LucideIcons.chartNoAxesColumn300, 'Usage'),
devices(LucideIcons.zap300, 'Autonomous devices'),
shortcuts(LucideIcons.keyboard300, 'Keyboard shortcuts'),
@@ -83,8 +81,6 @@ const _kSettingsGroups = [
// a run titled "what you change" by carrying the three switches that decide
// which logs are read at all — the pane is off until somebody sets it.
SettingsGroup('Preferences', [
- SettingsSection.appearance,
- SettingsSection.terminal,
SettingsSection.usage,
SettingsSection.devices,
SettingsSection.account,
diff --git a/desktop/lib/shared/theme/appearance_prefs_store.dart b/desktop/lib/shared/theme/appearance_prefs_store.dart
index 18d94af35..5a32f9e88 100644
--- a/desktop/lib/shared/theme/appearance_prefs_store.dart
+++ b/desktop/lib/shared/theme/appearance_prefs_store.dart
@@ -4,12 +4,13 @@ import '../../core/harness_file_store.dart';
import '../../core/local_key_value_store.dart';
import 'app_theme.dart';
import 'color_palette.dart';
+import 'harness_background.dart';
/// The app's coordinated palette and UI typography on this computer.
///
/// This does not change the terminal's type. The terminal renders a grid a remote
/// program draws into, so it keeps its own face and its own size in
-/// [TerminalFontStore], reached from Settings ▸ Terminal — and the app's UI
+/// [TerminalFontStore], reached from Customize Harness ▸ Terminal — and the app's UI
/// scale is fenced out of it at five seams (see the notes in
/// `terminal_panel.dart` and `terminal_composer.dart`, and the regression test
/// in `test/terminal_ui_scale_isolation_test.dart`).
@@ -19,9 +20,11 @@ class AppearancePrefs {
this.uiFamily,
this.uiSize = uiSizeDefault,
this.palette = HarnessPalette.graphite,
+ this.background = HarnessBackground.plain,
});
final HarnessPalette palette;
+ final HarnessBackground background;
/// The face the app's chrome is set in. `null` means the system font, which is
/// what [AppFont.sans] falls back to.
@@ -52,11 +55,13 @@ class AppearancePrefs {
String? uiFamily,
double? uiSize,
HarnessPalette? palette,
+ HarnessBackground? background,
bool clearUiFamily = false,
}) => AppearancePrefs(
uiFamily: clearUiFamily ? null : (uiFamily ?? this.uiFamily),
uiSize: uiSize ?? this.uiSize,
palette: palette ?? this.palette,
+ background: background ?? this.background,
);
@override
@@ -64,10 +69,11 @@ class AppearancePrefs {
other is AppearancePrefs &&
other.uiFamily == uiFamily &&
other.uiSize == uiSize &&
- other.palette == palette;
+ other.palette == palette &&
+ other.background == background;
@override
- int get hashCode => Object.hash(uiFamily, uiSize, palette);
+ int get hashCode => Object.hash(uiFamily, uiSize, palette, background);
}
/// The user's appearance choices, remembered across launches.
@@ -85,7 +91,9 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
static const _familyKey = 'app_ui_font_family';
static const _sizeKey = 'app_ui_font_size';
static const _paletteKey = 'app_color_palette';
+ static const _backgroundKey = 'harness_start_background';
Future<void>? _paletteSave;
+ Future<void>? _backgroundSave;
final LocalKeyValueStore _storage;
@@ -100,11 +108,13 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
_familyKey,
_sizeKey,
_paletteKey,
+ _backgroundKey,
]);
value = AppearancePrefs(
uiFamily: _familyFrom(saved[_familyKey]),
uiSize: _sizeFrom(saved[_sizeKey]),
palette: HarnessPalette.fromId(saved[_paletteKey]),
+ background: HarnessBackground.fromId(saved[_backgroundKey]),
);
} catch (_) {
value = const AppearancePrefs();
@@ -133,6 +143,28 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
}
}
+ Future<void> setBackground(HarnessBackground background) {
+ if (value.background == background) {
+ return _backgroundSave ?? Future.value();
+ }
+ value = value.copyWith(background: background);
+ return _backgroundSave ??= _saveBackground();
+ }
+
+ Future<void> _saveBackground() async {
+ try {
+ while (true) {
+ final id = value.background.name;
+ await _storage.write(_backgroundKey, id);
+ if (value.background.name == id) break;
+ }
+ } catch (_) {
+ // Keep the selected background for this run if storage is unavailable.
+ } finally {
+ _backgroundSave = null;
+ }
+ }
+
/// Choose a face, or pass `null` for the system font.
Future<void> setUiFamily(String? family) async {
final next = _familyFrom(family);
@@ -169,10 +201,12 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
Future<void> reset() async {
value = const AppearancePrefs();
await _paletteSave;
+ await _backgroundSave;
try {
await _storage.delete(_familyKey);
await _storage.delete(_sizeKey);
await _storage.delete(_paletteKey);
+ await _storage.delete(_backgroundKey);
} catch (_) {
// See above.
}
diff --git a/desktop/lib/shared/theme/harness_background.dart b/desktop/lib/shared/theme/harness_background.dart
new file mode 100644
index 000000000..f21e1e059
--- /dev/null
+++ b/desktop/lib/shared/theme/harness_background.dart
@@ -0,0 +1,18 @@
+/// Built-in backgrounds for empty Harness pages. Wallpaper never covers agents.
+enum HarnessBackground {
+ plain('Default'),
+ aurora('Aurora'),
+ lake('Lake', 'swarm-welcome-dusk.jpg'),
+ silk('Silk', 'swarm-welcome-abstract.jpg'),
+ threads('Threads', 'swarm-welcome-associative-memory.jpg'),
+ constellation('Constellation', 'swarm-welcome-ai.jpg');
+
+ const HarnessBackground(this.label, [this.fileName]);
+ final String label;
+ final String? fileName;
+ String? get asset =>
+ fileName == null ? null : 'assets/swarm-wallpapers/$fileName';
+
+ static HarnessBackground fromId(String? id) =>
+ values.where((value) => value.name == id).firstOrNull ?? plain;
+}
diff --git a/desktop/lib/shared/widgets/setting_row.dart b/desktop/lib/shared/widgets/setting_row.dart
index 75e2c7879..38776fdca 100644
--- a/desktop/lib/shared/widgets/setting_row.dart
+++ b/desktop/lib/shared/widgets/setting_row.dart
@@ -57,7 +57,9 @@ class SettingRow extends StatelessWidget {
),
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
child: LayoutBuilder(
- builder: (context, constraints) => constraints.maxWidth < _stackBelow
+ builder: (context, constraints) =>
+ constraints.maxWidth <
+ MediaQuery.textScalerOf(context).scale(_stackBelow)
? Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [text, const SizedBox(height: 10), control],
diff --git a/desktop/lib/terminal/terminal_theme_store.dart b/desktop/lib/terminal/terminal_theme_store.dart
index 58b590e0a..6abd63755 100644
--- a/desktop/lib/terminal/terminal_theme_store.dart
+++ b/desktop/lib/terminal/terminal_theme_store.dart
@@ -20,11 +20,8 @@ import '../core/local_key_value_store.dart';
/// scheme later is one value here and one `const` in `terminal_theme.dart`.
enum TerminalThemeChoice {
/// Today's behaviour, and still the default: ground and cursor follow the
- /// palette chosen in Settings ▸ Appearance, ANSI ramp from `darkTerminalTheme`.
- matchApp(
- 'Match app appearance',
- 'Ground and cursor follow Settings ▸ Appearance',
- ),
+ /// palette chosen in Customize Harness ▸ Appearance, ANSI ramp from `darkTerminalTheme`.
+ matchApp('Match app appearance', 'Matches your app palette'),
/// ⚠️ Named for the PALETTE, not for the distribution that popularised it.
/// These sixteen colours are the Tango Desktop Project's, which GNOME
diff --git a/desktop/lib/widgets/harness_customize_pane.dart b/desktop/lib/widgets/harness_customize_pane.dart
new file mode 100644
index 000000000..206135000
--- /dev/null
+++ b/desktop/lib/widgets/harness_customize_pane.dart
@@ -0,0 +1,200 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+import '../settings/sections/appearance_section.dart';
+import '../settings/sections/terminal_section.dart';
+import '../shared/theme/app_theme.dart' as grid;
+import '../shared/theme/appearance_prefs_store.dart';
+import '../shared/theme/harness_background.dart';
+import 'swarm_wallpaper.dart';
+
+/// Page-local customization. Appearance and Terminal use their existing stores
+/// and controls, so moving them here keeps the user's saved choices intact.
+class HarnessCustomizePane extends StatelessWidget {
+ const HarnessCustomizePane({super.key, required this.onClose, this.store});
+ final VoidCallback onClose;
+ final AppearancePrefsStore? store;
+
+ @override
+ Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
+ return Material(
+ key: const ValueKey('harness-customize-pane'),
+ color: grid.AppPalette.panelBg,
+ shape: Border(left: BorderSide(color: grid.AppPalette.divider)),
+ child: FocusScope(
+ child: CallbackShortcuts(
+ bindings: {const SingleActivator(LogicalKeyboardKey.escape): onClose},
+ child: DefaultTabController(
+ length: 3,
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Padding(
+ padding: const EdgeInsets.fromLTRB(20, 12, 8, 8),
+ child: Row(
+ children: [
+ Expanded(
+ child: Text(
+ 'Customize Harness',
+ style: Theme.of(context).textTheme.titleMedium
+ ?.copyWith(fontWeight: FontWeight.w600),
+ ),
+ ),
+ IconButton(
+ key: const ValueKey('harness-customize-close'),
+ autofocus: true,
+ tooltip: 'Close customization',
+ onPressed: onClose,
+ icon: const Icon(Icons.close, size: 20),
+ ),
+ ],
+ ),
+ ),
+ TabBar(
+ isScrollable: true,
+ tabAlignment: TabAlignment.start,
+ labelColor: grid.AppPalette.swarmAccent,
+ unselectedLabelColor: grid.AppPalette.textSecondary,
+ indicatorColor: grid.AppPalette.swarmAccent,
+ dividerColor: grid.AppPalette.divider,
+ tabs: const [
+ Tab(
+ key: ValueKey('customize-background'),
+ text: 'Background',
+ ),
+ Tab(
+ key: ValueKey('customize-appearance'),
+ text: 'Appearance',
+ ),
+ Tab(key: ValueKey('customize-terminal'), text: 'Terminal'),
+ ],
+ ),
+ Expanded(
+ child: TabBarView(
+ children: [
+ _Backgrounds(store: store ?? appearancePrefsStore),
+ const AppearanceSection(),
+ const TerminalSection(),
+ ],
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+class _Backgrounds extends StatelessWidget {
+ const _Backgrounds({required this.store});
+ final AppearancePrefsStore store;
+
+ @override
+ Widget build(BuildContext context) => SingleChildScrollView(
+ padding: const EdgeInsets.all(20),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ 'Change background',
+ style: Theme.of(context).textTheme.titleLarge,
+ ),
+ const SizedBox(height: 8),
+ Text(
+ 'For your New Harness page. Default matches the selected tab.',
+ style: Theme.of(context).textTheme.bodySmall,
+ ),
+ const SizedBox(height: 20),
+ ValueListenableBuilder<AppearancePrefs>(
+ valueListenable: store,
+ builder: (context, prefs, _) => LayoutBuilder(
+ builder: (context, constraints) => Wrap(
+ spacing: 12,
+ runSpacing: 12,
+ children: [
+ for (final choice in HarnessBackground.values)
+ SizedBox(
+ width: (constraints.maxWidth - 12) / 2,
+ child: _BackgroundChoice(
+ choice: choice,
+ selected: prefs.background == choice,
+ onChoose: () => unawaited(store.setBackground(choice)),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ ),
+ );
+}
+
+class _BackgroundChoice extends StatelessWidget {
+ const _BackgroundChoice({
+ required this.choice,
+ required this.selected,
+ required this.onChoose,
+ });
+ final HarnessBackground choice;
+ final bool selected;
+ final VoidCallback onChoose;
+
+ @override
+ Widget build(BuildContext context) => Semantics(
+ selected: selected,
+ button: true,
+ label: '${choice.label} background',
+ onTap: onChoose,
+ child: ExcludeSemantics(
+ child: TextButton(
+ key: ValueKey('background-${choice.name}'),
+ onPressed: onChoose,
+ style: TextButton.styleFrom(
+ padding: const EdgeInsets.all(6),
+ foregroundColor: grid.AppPalette.textPrimary,
+ backgroundColor: grid.AppPalette.cardBg,
+ side: BorderSide(
+ color: selected
+ ? grid.AppPalette.swarmAccent
+ : grid.AppPalette.divider,
+ width: 1.5,
+ ),
+ shape: RoundedRectangleBorder(
+ borderRadius: BorderRadius.circular(12),
+ ),
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ ClipRRect(
+ borderRadius: BorderRadius.circular(7),
+ child: AspectRatio(
+ aspectRatio: 1.6,
+ child: SwarmWallpaper(background: choice, thumbnail: true),
+ ),
+ ),
+ Padding(
+ padding: const EdgeInsets.fromLTRB(4, 8, 4, 4),
+ child: Row(
+ children: [
+ Expanded(child: Text(choice.label)),
+ const SizedBox(width: 4),
+ SizedBox(
+ width: 16,
+ child: selected ? const Icon(Icons.check, size: 16) : null,
+ ),
+ ],
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+}
diff --git a/desktop/lib/widgets/harness_start_page.dart b/desktop/lib/widgets/harness_start_page.dart
index ff3b2433e..e744d12da 100644
--- a/desktop/lib/widgets/harness_start_page.dart
+++ b/desktop/lib/widgets/harness_start_page.dart
@@ -5,6 +5,7 @@ import '../shared/theme/app_theme.dart' as grid;
import '../state/swarm_navigation.dart';
import '../state/swarm_search.dart';
import 'harness_entry_actions.dart';
+import 'harness_customize_pane.dart';
import 'swarm_search_input.dart';
import 'swarm_switcher.dart';
@@ -34,10 +35,22 @@ class _HarnessStartPageState extends State<HarnessStartPage> {
canRequestFocus: false,
);
final _searchGroup = Object();
+ final _customizeButtonFocus = FocusNode(debugLabel: 'Customize Harness');
+ bool _customizing = false;
SwarmSearchController? _search;
SwarmSearchDraft? _draft;
bool get _showResults => _search != null;
+ void _customize() {
+ _close();
+ setState(() => _customizing = true);
+ }
+
+ void _closeCustomization() {
+ setState(() => _customizing = false);
+ _customizeButtonFocus.requestFocus();
+ }
+
void _open() {
// Commands can replace the editor value without a TextField onChanged.
// Reveal results for the visible text, including on keyboard-only entry.
@@ -262,16 +275,70 @@ class _HarnessStartPageState extends State<HarnessStartPage> {
_search?.dispose();
_query.dispose();
_pickerFocus.dispose();
+ _customizeButtonFocus.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
+ return LayoutBuilder(
+ builder: (context, constraints) {
+ final paneWidth = constraints.maxWidth.clamp(0.0, 420.0);
+ final sideBySide = constraints.maxWidth >= 1000;
+ return Row(
+ children: [
+ Expanded(
+ child: Stack(
+ fit: StackFit.expand,
+ children: [
+ _page(),
+ Positioned(
+ right: 20,
+ bottom: 16,
+ child: FilledButton.icon(
+ key: const ValueKey('harness-customize-button'),
+ focusNode: _customizeButtonFocus,
+ onPressed: _customizing
+ ? _closeCustomization
+ : _customize,
+ icon: const Icon(Icons.edit_outlined, size: 16),
+ label: const Text('Customize Harness'),
+ style: FilledButton.styleFrom(
+ backgroundColor: grid.AppPalette.swarmAccent,
+ foregroundColor: grid.AppPalette.swarmTabBar,
+ minimumSize: const Size(0, 36),
+ shape: const StadiumBorder(),
+ ),
+ ),
+ ),
+ if (_customizing && !sideBySide)
+ Positioned(
+ top: 0,
+ bottom: 0,
+ right: 0,
+ width: paneWidth,
+ child: HarnessCustomizePane(onClose: _closeCustomization),
+ ),
+ ],
+ ),
+ ),
+ if (_customizing && sideBySide)
+ SizedBox(
+ width: paneWidth,
+ child: HarnessCustomizePane(onClose: _closeCustomization),
+ ),
+ ],
+ );
+ },
+ );
+ }
+
+ Widget _page() {
return LayoutBuilder(
builder: (context, constraints) {
return Padding(
- padding: const EdgeInsets.fromLTRB(24, 0, 24, 32),
+ padding: const EdgeInsets.fromLTRB(24, 0, 24, 80),
child: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 1120),
diff --git a/desktop/lib/widgets/swarm_wallpaper.dart b/desktop/lib/widgets/swarm_wallpaper.dart
index 5360df0bc..31b861a07 100644
--- a/desktop/lib/widgets/swarm_wallpaper.dart
+++ b/desktop/lib/widgets/swarm_wallpaper.dart
@@ -3,29 +3,55 @@ import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import '../shared/theme/app_theme.dart' as grid;
+import '../shared/theme/appearance_prefs_store.dart';
+import '../shared/theme/harness_background.dart';
import 'engine_identity.dart';
-/// The ground behind the empty new-swarm canvas (mockup/swarm-background.html,
-/// "9 · Aurora mesh").
-///
-/// It used to be a photograph — a lake at dusk under a gradient — and it was
-/// the one surface in the app with a subject. Every other screen stands on the
-/// same near-black panel with Geist on it; that one said "mountains", warmed
-/// the white headline orange at the top, and made the accent button compete
-/// with a sunset. A ground should be a ground.
-///
-/// This is the panel colour with three very dim washes at the corners, in the
-/// three colours the app already owns — the accent, and the marks Claude and
-/// Codex wear in the rail — meeting in the middle as plain ground. Each stays
-/// under 15%, which is what keeps it a tinted room rather than a poster, and
-/// what keeps the New agent button the only real blue on screen. Drawn, not
-/// scaled, so it holds at any window size and costs no asset.
+/// Empty pages default to the selected tab's fill. An explicit background is
+/// used for picker thumbnails; the page follows the saved appearance choice.
class SwarmWallpaper extends StatelessWidget {
- const SwarmWallpaper({super.key});
+ const SwarmWallpaper({super.key, this.background, this.thumbnail = false});
+ final HarnessBackground? background;
+ final bool thumbnail;
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
+ if (background case final choice?) return _paint(choice);
+ return ValueListenableBuilder<AppearancePrefs>(
+ valueListenable: appearancePrefsStore,
+ builder: (context, prefs, _) => _paint(prefs.background),
+ );
+ }
+
+ Widget _paint(HarnessBackground choice) {
+ if (choice == HarnessBackground.plain) {
+ return ColoredBox(color: grid.AppPalette.swarmField);
+ }
+ if (choice.asset case final asset?) {
+ return Stack(
+ fit: StackFit.expand,
+ children: [
+ Image.asset(
+ asset,
+ fit: BoxFit.cover,
+ cacheWidth: thumbnail ? 360 : 1920,
+ excludeFromSemantics: true,
+ errorBuilder: (_, _, _) =>
+ ColoredBox(color: grid.AppPalette.swarmField),
+ ),
+ const DecoratedBox(
+ decoration: BoxDecoration(
+ gradient: LinearGradient(
+ begin: Alignment.topCenter,
+ end: Alignment.bottomCenter,
+ colors: [Color(0x1211111c), Color(0x750c111e)],
+ ),
+ ),
+ ),
+ ],
+ );
+ }
// Lighter in light mode: a wash that reads as a tint on charcoal reads as
// a stain on white.
final strength = grid.AppTheme.pick(0.6, 1.0);
diff --git a/desktop/pubspec.yaml b/desktop/pubspec.yaml
index 1282f3967..fd7e4207e 100644
--- a/desktop/pubspec.yaml
+++ b/desktop/pubspec.yaml
@@ -97,6 +97,7 @@ flutter:
# the mark the Dock shows, not a stand-in drawn in Dart.
- assets/app_icon.png
- assets/harness_device.png
+ - assets/swarm-wallpapers/
# To add assets to your application, add an assets section, like this:
# assets:
diff --git a/desktop/test/harness_customize_test.dart b/desktop/test/harness_customize_test.dart
new file mode 100644
index 000000000..acbb0d5d2
--- /dev/null
+++ b/desktop/test/harness_customize_test.dart
@@ -0,0 +1,237 @@
+import 'dart:async';
+import 'dart:io';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/local_key_value_store.dart';
+import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shared/theme/appearance_prefs_store.dart';
+import 'package:harness/shared/theme/color_palette.dart';
+import 'package:harness/shared/theme/harness_background.dart';
+import 'package:harness/widgets/harness_customize_pane.dart';
+
+import 'support/real_fonts.dart';
+import 'swarm_state_test.dart' show createApp;
+
+class _Storage implements LocalKeyValueStore {
+ final values = <String, String>{};
+ Completer<void>? gate;
+ @override
+ Future<String?> read(String key) async => values[key];
+ @override
+ Future<void> delete(String key) async => values.remove(key);
+ @override
+ Future<void> write(String key, String value) async {
+ await gate?.future;
+ values[key] = value;
+ }
+}
+
+Future<void> _capture(WidgetTester tester, GlobalKey key, String name) async {
+ final directory = Platform.environment['HARNESS_CUSTOMIZE_CAPTURE_DIR'];
+ if (directory == null) return;
+ await tester.runAsync(() async {
+ final boundary =
+ key.currentContext!.findRenderObject()! as RenderRepaintBoundary;
+ final image = await boundary.toImage(pixelRatio: 1);
+ final bytes = await image.toByteData(format: ui.ImageByteFormat.png);
+ await Directory(directory).create(recursive: true);
+ await File('$directory/$name.png')
+ .writeAsBytes(bytes!.buffer.asUint8List());
+ image.dispose();
+ });
+}
+
+void main() {
+ setUpAll(() async {
+ await loadRealFonts();
+ await (FontLoader(
+ 'MaterialIcons',
+ )..addFont(rootBundle.load('fonts/MaterialIcons-Regular.otf'))).load();
+ await (FontLoader('packages/lucide_icons_flutter/Lucide300')..addFont(
+ rootBundle.load(
+ 'packages/lucide_icons_flutter/assets/build_font/LucideVariable-w300.ttf',
+ ),
+ ))
+ .load();
+ });
+
+ test(
+ 'background persists without replacing palette or type choices',
+ () async {
+ final storage = _Storage()..gate = Completer<void>();
+ final store = AppearancePrefsStore(storage: storage);
+ addTearDown(store.dispose);
+ store.value = const AppearancePrefs(
+ palette: HarnessPalette.forest,
+ uiFamily: 'Menlo',
+ uiSize: 16,
+ );
+ final saving = store.setBackground(HarnessBackground.lake);
+ store.setBackground(HarnessBackground.threads);
+ expect(store.value.palette, HarnessPalette.forest);
+ expect(store.value.uiFamily, 'Menlo');
+ expect(store.value.uiSize, 16);
+ storage.gate!.complete();
+ await saving;
+ final restored = AppearancePrefsStore(storage: storage);
+ addTearDown(restored.dispose);
+ await restored.load();
+ expect(restored.value.background, HarnessBackground.threads);
+ storage.values['harness_start_background'] = 'unknown-background';
+ await restored.load();
+ expect(restored.value.background, HarnessBackground.plain);
+ await restored.setBackground(HarnessBackground.silk);
+ await restored.reset();
+ expect(storage.values.containsKey('harness_start_background'), isFalse);
+ },
+ );
+
+ testWidgets(
+ 'background choices support keyboard selection and survive reopening',
+ (tester) async {
+ final storage = _Storage();
+ final store = AppearancePrefsStore(storage: storage);
+ addTearDown(store.dispose);
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: Scaffold(
+ body: SizedBox(
+ width: 420,
+ child: HarnessCustomizePane(store: store, onClose: () {}),
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ final choice = find.byKey(const ValueKey('background-lake'));
+ await tester.ensureVisible(choice);
+ await tester.tap(choice);
+ await tester.pumpAndSettle();
+ expect(store.value.background, HarnessBackground.lake);
+ final silk = find.descendant(
+ of: find.byKey(const ValueKey('background-silk')),
+ matching: find.text('Silk'),
+ );
+ for (var i = 0; i < 10 && !Focus.of(tester.element(silk)).hasFocus; i++) {
+ await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+ await tester.pump();
+ }
+ expect(Focus.of(tester.element(silk)).hasFocus, isTrue);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(store.value.background, HarnessBackground.silk);
+ final reopened = AppearancePrefsStore(storage: storage);
+ addTearDown(reopened.dispose);
+ await reopened.load();
+ expect(reopened.value.background, HarnessBackground.silk);
+ expect(tester.takeException(), isNull);
+ },
+ );
+
+ for (final (width, height, scale) in [
+ (1280.0, 800.0, 1.0),
+ (880.0, 560.0, 1.0),
+ (600.0, 680.0, 1.7),
+ ]) {
+ testWidgets('customization fits $width at $scale and returns to the page', (
+ tester,
+ ) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = Size(width, height);
+ addTearDown(tester.view.reset);
+ final previous = appearancePrefsStore.value;
+ addTearDown(() => appearancePrefsStore.value = previous);
+ appearancePrefsStore.value = const AppearancePrefs();
+ final app = createApp();
+ addTearDown(app.dispose);
+ final boundary = GlobalKey();
+ await tester.pumpWidget(
+ RepaintBoundary(
+ key: boundary,
+ child: MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ builder: (context, child) => grid.BrightnessScope(
+ child: MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(textScaler: TextScaler.linear(scale)),
+ child: child!,
+ ),
+ ),
+ home: SwarmScreen(notifier: app, nativeTabs: false),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ final start = find.byKey(const ValueKey('harness-start-search'));
+ final background = find.byKey(const ValueKey('harness-start-background'));
+ final fill = find.descendant(
+ of: background,
+ matching: find.byType(ColoredBox),
+ );
+ expect(tester.widget<ColoredBox>(fill).color, grid.AppPalette.swarmField);
+ expect(
+ find.byKey(const ValueKey('harness-customize-pane')),
+ findsNothing,
+ );
+ await _capture(tester, boundary, '${width.toInt()}-default');
+
+ await tester.enterText(start, 'Keep my query');
+ await tester.pump();
+ await tester.tap(find.byKey(const ValueKey('harness-customize-button')));
+ await tester.pumpAndSettle();
+ final pane = find.byKey(const ValueKey('harness-customize-pane'));
+ expect(pane, findsOneWidget);
+ expect(tester.getRect(pane).right, width);
+ expect(find.byKey(const ValueKey('harness-start-results')), findsNothing);
+ expect(tester.widget<TextField>(start).controller!.text, 'Keep my query');
+ expect(tester.takeException(), isNull);
+ await _capture(tester, boundary, '${width.toInt()}-background');
+
+ await tester.tap(find.byKey(const ValueKey('customize-appearance')));
+ await tester.pumpAndSettle();
+ expect(find.text('Color palette'), findsOneWidget);
+ expect(find.byKey(const ValueKey('palette-graphite')), findsOneWidget);
+ expect(find.byKey(const Key('appearance-ui-size-field')), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ await _capture(tester, boundary, '${width.toInt()}-appearance');
+
+ await tester.tap(find.byKey(const ValueKey('customize-terminal')));
+ await tester.pumpAndSettle();
+ expect(
+ find.byKey(const Key('terminal-font-family-dropdown')),
+ findsOneWidget,
+ );
+ expect(
+ find.byKey(const Key('terminal-colour-scheme-dropdown')),
+ findsOneWidget,
+ );
+ expect(tester.takeException(), isNull);
+ await _capture(tester, boundary, '${width.toInt()}-terminal');
+ final schemes = find.byKey(const Key('terminal-colour-scheme-dropdown'));
+ await tester.ensureVisible(schemes);
+ await tester.tap(schemes);
+ await tester.pumpAndSettle();
+ await tester.sendKeyEvent(LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ expect(pane, findsOneWidget);
+ await tester.sendKeyEvent(LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ expect(pane, findsNothing);
+ final button = tester.widget<FilledButton>(
+ find.byKey(const ValueKey('harness-customize-button')),
+ );
+ expect(button.focusNode!.hasFocus, isTrue);
+ expect(tester.widget<TextField>(start).controller!.text, 'Keep my query');
+ expect(app.panes, isEmpty);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ });
+ }
+}
diff --git a/desktop/test/navigation_events_test.dart b/desktop/test/navigation_events_test.dart
index 7542e17d7..11d6d23ac 100644
--- a/desktop/test/navigation_events_test.dart
+++ b/desktop/test/navigation_events_test.dart
@@ -102,17 +102,17 @@ void main() {
await openSettings(
tester,
source: 'account_menu',
- initialSection: SettingsSection.appearance,
+ initialSection: SettingsSection.shortcuts,
);
- await tester.tap(find.text('Terminal'));
+ await tester.tap(find.text('Account'));
await tester.pumpAndSettle();
// Two visits, two sources: the door into Settings, then the rail. A
// second view that inherited `account_menu` would report every pane a
// reader wandered through as having been opened from the account menu.
expect(tracked.allOf('screen_view'), [
- {'screen': 'settings_appearance', 'source': 'account_menu'},
- {'screen': 'settings_terminal', 'source': 'rail'},
+ {'screen': 'settings_shortcuts', 'source': 'account_menu'},
+ {'screen': 'settings_account', 'source': 'rail'},
]);
});
});
diff --git a/desktop/test/settings_screen_test.dart b/desktop/test/settings_screen_test.dart
index 2bf700d61..9d1826f31 100644
--- a/desktop/test/settings_screen_test.dart
+++ b/desktop/test/settings_screen_test.dart
@@ -17,7 +17,6 @@ import 'package:harness/core/config.dart';
import 'package:harness/settings/settings_screen.dart';
import 'package:harness/shared/theme/app_theme.dart';
import 'package:harness/state/app_state.dart';
-import 'package:harness/terminal/terminal_font_store.dart';
void main() {
TestWidgetsFlutterBinding.ensureInitialized();
@@ -66,68 +65,25 @@ void main() {
return notifier;
}
- testWidgets('opens on Appearance, with every section in the rail', (
- tester,
- ) async {
- await openSettings(tester);
-
- // The rail: every group caption and every row.
- expect(find.text('Preferences'), findsOneWidget);
- expect(find.text('Help'), findsOneWidget);
- expect(find.text('Terminal'), findsOneWidget);
- expect(find.text('Keyboard shortcuts'), findsOneWidget);
- expect(find.text('About'), findsOneWidget);
- expect(find.text('Back to app'), findsOneWidget);
-
- // Appearance is the section it opens on, so its name is both the rail row
- // and the pane's title.
- expect(find.text('Appearance'), findsNWidgets(2));
- });
-
- testWidgets('the Appearance pane is the typography controls', (tester) async {
- await openSettings(tester);
-
- // Typography is the whole pane now that there is no theme to choose —
- // Harness Desktop is dark-only.
- expect(find.text('Typography'), findsOneWidget);
- expect(find.text('UI font'), findsOneWidget);
- expect(find.text('UI font size'), findsOneWidget);
- expect(find.byKey(const Key('appearance-ui-size-field')), findsOneWidget);
- });
-
- testWidgets('picking Terminal swaps the pane for the font controls', (
- tester,
- ) async {
- await openSettings(tester);
-
- await tester.tap(find.text('Terminal'));
- await tester.pumpAndSettle();
-
- expect(find.text('Terminal'), findsNWidgets(2));
- expect(
- find.byKey(const Key('terminal-font-family-dropdown')),
- findsOneWidget,
- );
- expect(
- find.text(TerminalFontChoice.defaultForPlatform.label),
- findsOneWidget,
- );
- expect(find.text('13pt'), findsOneWidget);
- expect(
- find.byKey(const Key('terminal-font-size-decrease')),
- findsOneWidget,
- );
- expect(
- find.byKey(const Key('terminal-font-size-increase')),
- findsOneWidget,
- );
- expect(
- find.byKey(const Key('terminal-settings-reset-button')),
- findsOneWidget,
- );
- // The Appearance controls are gone with their pane.
- expect(find.byKey(const Key('appearance-ui-size-field')), findsNothing);
- });
+ testWidgets(
+ 'Settings lists its remaining sections after customization moves',
+ (tester) async {
+ await openSettings(tester);
+ expect(find.text('Preferences'), findsOneWidget);
+ expect(find.text('Help'), findsOneWidget);
+ expect(find.text('Usage'), findsNWidgets(2));
+ expect(find.text('Keyboard shortcuts'), findsOneWidget);
+ expect(find.text('About'), findsOneWidget);
+ expect(find.text('Back to app'), findsOneWidget);
+ expect(find.text('Appearance'), findsNothing);
+ expect(find.text('Terminal'), findsNothing);
+ expect(find.byKey(const Key('appearance-ui-size-field')), findsNothing);
+ expect(
+ find.byKey(const Key('terminal-font-family-dropdown')),
+ findsNothing,
+ );
+ },
+ );
testWidgets('About prints the running version', (tester) async {
await openSettings(tester);
@@ -158,9 +114,8 @@ void main() {
await tester.pumpAndSettle();
expect(find.text('Keyboard shortcuts'), findsOneWidget);
- // Rail rows gone; the open pane's own title is what remains of
- // 'Appearance'.
- expect(find.text('Appearance'), findsOneWidget);
+ // Filtering the rail preserves the open pane.
+ expect(find.text('Usage'), findsOneWidget);
expect(find.text('Terminal'), findsNothing);
expect(find.text('Preferences'), findsNothing);
diff --git a/desktop/test/settings_section_test.dart b/desktop/test/settings_section_test.dart
index 5b5e6adf3..21c2c2c21 100644
--- a/desktop/test/settings_section_test.dart
+++ b/desktop/test/settings_section_test.dart
@@ -23,13 +23,11 @@ void main() {
test('Settings opens on a row the rail actually shows', () {
expect(sectionsOf(settingsGroups), contains(kDefaultSettingsSection));
final shipped = settingsGroupsFor(debugSurface: false);
- expect(shipped.first.sections.first, SettingsSection.appearance);
+ expect(shipped.first.sections.first, SettingsSection.usage);
});
test('everything outside the gate is always listed', () {
expect(sectionsOf(settingsGroupsFor(debugSurface: false)), [
- SettingsSection.appearance,
- SettingsSection.terminal,
// Usage carries no gate of its own: it reads only this machine's own
// files, and it reads nothing at all until a provider is switched on, so
// there is nothing here for a shipped build to hide.
diff --git a/desktop/test/welcome_entry_layout_test.dart b/desktop/test/welcome_entry_layout_test.dart
index 4afa81cb6..39b166182 100644
--- a/desktop/test/welcome_entry_layout_test.dart
+++ b/desktop/test/welcome_entry_layout_test.dart
@@ -114,7 +114,7 @@ void main() {
expect(createRect.left, greaterThan(openRect.right));
expect(fieldRect.center.dx, closeTo(width / 2, 1));
expect(deviceRect.left, closeTo(fieldRect.left, 1));
- expect(deviceRect.bottom, closeTo(height - 32, 1));
+ expect(deviceRect.bottom, closeTo(height - 80, 1));
expect(find.text('Meet the Harness device'), findsOneWidget);
expect(create.hitTestable(), findsOneWidget);
expect(open.hitTestable(), findsOneWidget);
diff --git a/docs/harness-agent-first-tabs.md b/docs/harness-agent-first-tabs.md
index b597ef63a..bd7f1c268 100644
--- a/docs/harness-agent-first-tabs.md
+++ b/docs/harness-agent-first-tabs.md
@@ -10,6 +10,36 @@ New Agent, Stop Agent, Restart Agent, and Find an agent. Harness
also names the tab container, application, CLI and device. Custom saved names
and protocol identifiers are unchanged.
+## Customize Harness
+
+The New Harness page defaults to the selected tab's solid fill, using the same
+workspace palette color. **Customize Harness** is a pill at the bottom right.
+It opens a right-hand pane with **Background / Appearance / Terminal** sections.
+Wide windows keep the page beside it; narrow windows overlay the pane without
+squeezing the search controls. Closing it restores focus to the Customize button
+and preserves the query. Escape closes an open settings menu before the pane.
+
+Background offers **Default, Aurora, Lake, Silk, Threads and Constellation**.
+The lake and generated images are restored from the existing asset history;
+Aurora reuses the existing mesh. Choices apply immediately, persist under
+`harness_start_background`, and affect only empty Harness pages. Default stays
+in step with palette changes. Unknown saved choices fall back to Default.
+
+Appearance and Terminal move out of Settings into this pane, reusing their
+existing palette, UI font/size, terminal scheme, font/size, preview and reset
+controls and stores. Settings now starts at Usage. The device footer stays fixed
+above the bottom-right button while search opens and closes. No uploads,
+background downloads, theme editor or new dependency is added.
+
+Validation: 46 affected Flutter tests pass, including wallpaper persistence and
+keyboard selection, focus restoration, dropdown dismissal, existing-agent entry,
+moved settings, palette propagation, terminal scale isolation and narrow-window
+rendering. All 17 changed Dart/test files analyze cleanly. Captures at 1280×800,
+880×560 and 600×680 with 1.7× text are in
+`/private/tmp/harness-customize-captures`.
+The macOS Release build and deep/strict signature verification pass; all four
+restored image assets are present in the bundle.
+
## Open and New Agent
**New Agent (Cmd-N)** opens the dedicated creation dialog. **Open Agent (Cmd-O)**
@@ -27,8 +57,8 @@ at 1120 logical pixels, has a 64-pixel minimum height and shows **Find an agent*
Its position, width and 32-pixel outer corners stay fixed when results open.
Results and preview share the space above the fixed device footer. Typing,
clicking or pressing an arrow opens search; focus alone does not build its catalog.
-Escape closes results and retains the query. The Aurora mesh ground and device
-product strip are preserved. New without a linked machine opens machine linking.
+Escape closes results and retains the query. The default background matches the selected tab, and the device
+product strip stays above the customization button. New without a linked machine opens machine linking.
Open Agent has a large **Find an agent** heading, a blank rounded input and an
almost-black surface over a 90% black canvas veil. Results appear immediately;
diff --git a/docs/harness-v2-handoff.md b/docs/harness-v2-handoff.md
index 6144d1248..e4c91e072 100644
--- a/docs/harness-v2-handoff.md
+++ b/docs/harness-v2-handoff.md
@@ -34,7 +34,21 @@ user for a benchmark window.
## Current product contract
-### Latest: separate New Agent and Open Agent
+### Latest: Customize Harness
+
+New Harness defaults to the selected tab's solid color. The bottom-right
+**Customize Harness** button opens Background, Appearance and Terminal in a
+right-hand pane. Appearance/Terminal have moved out of Settings and keep their
+existing stores and controls. Background offers Default, Aurora, Lake, Silk,
+Threads and Constellation, reusing existing generated assets and the mesh.
+Choices apply immediately and persist; only empty Harness pages get wallpaper.
+Forty-six affected checks and analysis of all 17 changed Dart/test units pass.
+Logs: `/private/tmp/harness-customize-final-tests.log`,
+`/private/tmp/harness-customize-analyze.log`. Captures:
+`/private/tmp/harness-customize-captures`. The incoming edge New/Open actions
+remain a separate feature and push.
+
+### Separate New Agent and Open Agent — pushed aa327c0
The user rejected combined Add Agent. **Cmd-N / New Agent** now opens the dedicated
creation dialog; **Cmd-O / Open Agent** opens search/results/preview only. Both
@@ -51,8 +65,8 @@ Logs: `/private/tmp/harness-separate-entry-final-tests.log`,
`/private/tmp/harness-separate-entry-final-analyze.log`.
Captures: `/private/tmp/harness-separate-entry-picker`.
The installed preview is still **8873f27** until the next build/install.
-Push this rollback first. The user then requested Customize Harness, followed by
-distinct New/Open edge actions; implement and push each feature separately.
+The rollback was pushed first as **aa327c0**. The user requests one feature per
+commit and push; Customize Harness and distinct edge New/Open actions follow separately.
### Earlier September 15 checkpoint (combined form superseded)
@@ -244,16 +258,16 @@ are:
Cmd-H/J/K/L and Cmd-arrows focus panes; Cmd-1…9 select tabs. User bindings take
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 Harness preserves incoming **fea77a8**: an Aurora mesh background in the
- app/accent/agent colours and a glass product strip with the device cutout.
+- New Harness defaults to the selected tab fill. Customize Harness offers the
+ prior Aurora mesh and restored images. The device cutout remains in its product strip.
The long search field is capped at 1120 logical pixels with a 64-pixel minimum
height and **Find an agent** hint. It starts blank and focused, with results
hidden until typing, clicking or pressing an arrow. Open Agent and New Agent
sit underneath at the same left edge; the Open button is outlined here.
Search retains its position and width; results and preview are side by side
from 700 pixels. Escape restores the actions and query. The product strip stays
- 32 pixels above the bottom while search opens and closes, with a compact form
- for short windows. The old lake screenshot is no longer the current background.
+ above the bottom-right Customize button while search opens and closes, with
+ a compact form for short windows. Wallpaper is now an explicit saved choice.
- Search is single-choice. Session names appear above **project · branch ·
machine**, without repeated workspace titles. Only the highlighted row shows
**Open Agent / Open N Agents**, or the explicit split action. The modal