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.

Show the background behind harnesses whenever it isn't Blank

reinSPQR683557385c07
diff --git a/CONTEXT.md b/CONTEXT.md
index 44ce13d32..2a78c7d07 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -7,8 +7,8 @@ Harness runs and supervises coding agents across desktop, mobile, CLI and device
### Appearance
**Background**:
-The image or fill shown on an empty welcome or new-tab page and, when **Behind harnesses** is on, behind the panes of a running harness tab.
-_Avoid_: Wallpaper, start background
+The image or fill shown behind the panes of a running harness tab, seen through them. Blank shows nothing.
+_Avoid_: Wallpaper, start background, behind harnesses
**Built-in background**:
A background that ships with Harness, including the default Blank.
@@ -19,17 +19,13 @@ The single background the user supplies from their own image; Harness keeps its
_Avoid_: Custom wallpaper, user image, uploaded background
**Dim**:
-How much a custom background is darkened so the welcome text stays readable.
+How much a custom background is darkened so the panes in front of it stay readable.
_Avoid_: Overlay, opacity, brightness
**Fit**:
-How a custom background is sized to the page: fill, fit, center or tile.
+How a custom background is sized to the tab: fill, fit, center or tile.
_Avoid_: Scale mode, crop
-**Behind harnesses**:
-The choice to also show a non-Blank background behind a running harness tab's panes, seen through them. Off by default.
-_Avoid_: Running-tab background, transparent terminals
-
**Pane opacity**:
-How solid a harness tab's panes are while **Behind harnesses** is on; lower lets more of the background through.
+How solid a harness tab's panes are over a non-Blank **Background**; lower lets more of it through.
_Avoid_: Transparency, terminal opacity, Dim (which darkens the background itself)
diff --git a/desktop/design/wallpapers.md b/desktop/design/wallpapers.md
index 0983b2c78..a7c872f6e 100644
--- a/desktop/design/wallpapers.md
+++ b/desktop/design/wallpapers.md
@@ -1,6 +1,6 @@
-# New-tab wallpapers
+# Backgrounds
-Blank remains the default and uses the selected tab's workspace color. Choose artwork under Customize Harness → Background. It appears only on empty welcome/new-tab pages. The welcome text and wallpaper stay mounted at their original position while the New Harness and Open Harness panels overlay the page.
+Blank remains the default and uses the selected tab's workspace color. Choose artwork under Customize Harness → Background. Any background but Blank shows behind the panes of a running harness tab, seen through them; there is no separate switch. **Pane opacity** (0–100%, default 50%) sets how solid the panes stay over it. Settings shows the slider only while a background other than Blank is chosen. Older builds saved a Behind harnesses on/off flag beside the opacity; it is ignored. Empty welcome and new-tab pages are plain.
The four images below were created with the built-in image generation tool. The PNG outputs were copied into the app without retouching. They are bundled locally; changing wallpaper does not make a network request. The center is deliberately quiet so the terminal-font welcome message remains readable.
@@ -43,7 +43,7 @@ Use case: stylized-concept. Asset type: minimal full-bleed 16:9 desktop wallpape
The last card in the picker takes the user's own image: click it to choose a file, or drop one on it. PNG, JPEG and WebP up to 20 MB are accepted. Harness keeps its own copy in `~/.harness/desktop-app-v2/backgrounds/`, scaled so the longest side is at most 3840px and flattened to one frame, so moving or deleting the original changes nothing. There is one slot: a new image replaces the copy, and Remove deletes it. Choosing a built-in background keeps the copy for a one-click return.
-While the custom background is selected, **Dim** (0–80%, default 40%) darkens it so the light welcome text stays readable, and **Fit** chooses fill (default), fit, center or tile. Center and tile show the image at real size, one image pixel per device pixel. A new image keeps both settings. If the copy goes missing, the page shows Blank and the card says "Image missing, choose again". The browser build has no folder to keep a copy in, so it hides the card. `test/custom_background_test.dart` covers import, persistence and the card.
+While the custom background is selected, **Dim** (0–80%, default 40%) darkens it so the panes in front of it stay readable, and **Fit** chooses fill (default), fit, center or tile. Center and tile show the image at real size, one image pixel per device pixel. A new image keeps both settings. If the copy goes missing, the page shows Blank and the card says "Image missing, choose again". The browser build has no folder to keep a copy in, so it hides the card. `test/custom_background_test.dart` covers import, persistence and the card.
Rendered app previews: [welcome with terminal wallpaper](review/welcome-terminal-wallpaper.png) and [keyboard shortcut popup](review/keyboard-shortcuts-browser.png).
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 763abc9fd..530d0204c 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -6551,11 +6551,9 @@ class _SwarmScreenState extends State<SwarmScreen> {
if (app.panes.isEmpty
? !newHarnessOpensInBox &&
!app.activeSwarm.isNewTabPage
- // Behind harnesses: seen through the panes and
- // their gutters, on harness tabs only.
- : appearancePrefsStore
- .value
- .showsBehindHarnesses &&
+ // Seen through the panes and their gutters, on
+ // harness tabs only.
+ : appearancePrefsStore.value.showsBackground &&
!app.activeSwarm.isUtility &&
!app.activeSwarm.isOrchestrator)
const RepaintBoundary(
diff --git a/desktop/lib/settings/appearance/wallpaper_section.dart b/desktop/lib/settings/appearance/wallpaper_section.dart
index 15a651883..4ee78eabc 100644
--- a/desktop/lib/settings/appearance/wallpaper_section.dart
+++ b/desktop/lib/settings/appearance/wallpaper_section.dart
@@ -35,7 +35,7 @@ class WallpaperSection extends StatelessWidget {
),
const SizedBox(height: 8),
Text(
- 'Shown on new tabs, and behind your harnesses if you like.',
+ 'Shown behind the panes of running harness tabs.',
style: grid.AppType.body(color: grid.AppPalette.textSecondary),
),
const SizedBox(height: 16),
@@ -85,10 +85,10 @@ class WallpaperSection extends StatelessWidget {
const SizedBox(height: 20),
_CustomControls(prefs: prefs, custom: value.custom),
],
- // Blank has nothing to show through; the choice is kept for later.
- if (value.background != HarnessBackground.plain) ...[
+ // Blank has nothing to show through.
+ if (value.showsBackground) ...[
const SizedBox(height: 20),
- _BehindHarnessesControls(prefs: prefs, value: value),
+ _PaneOpacityControl(prefs: prefs, value: value),
],
],
),
@@ -412,9 +412,9 @@ class _CustomControls extends StatelessWidget {
}
}
-/// Behind harnesses, and how solid the panes stay while it shows through them.
-class _BehindHarnessesControls extends StatelessWidget {
- const _BehindHarnessesControls({required this.prefs, required this.value});
+/// How solid the panes stay while the background shows through them.
+class _PaneOpacityControl extends StatelessWidget {
+ const _PaneOpacityControl({required this.prefs, required this.value});
final AppearancePrefsStore prefs;
final AppearancePrefs value;
@@ -425,46 +425,29 @@ class _BehindHarnessesControls extends StatelessWidget {
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
- SwitchListTile(
- key: const ValueKey('background-behind-harnesses'),
- contentPadding: EdgeInsets.zero,
- value: value.behindHarnesses,
- onChanged: (on) => prefs.setBehindHarnesses(on: on),
- title: Text('Behind harnesses', style: label),
- subtitle: Text(
- 'Show it through the panes of running tabs.',
- style: grid.AppType.label(color: grid.AppPalette.textSecondary),
- ),
- ),
- if (value.behindHarnesses) ...[
- const SizedBox(height: 8),
- Text('Pane opacity', style: label),
- Row(
- children: [
- Expanded(
- child: Slider(
- key: const ValueKey('background-pane-opacity'),
- value: value.paneOpacity,
- min: AppearancePrefs.paneOpacityMin,
- divisions: 20,
- label: percent,
- onChanged: (opacity) =>
- prefs.setBehindHarnesses(opacity: opacity),
- ),
+ Text('Pane opacity', style: label),
+ Row(
+ children: [
+ Expanded(
+ child: Slider(
+ key: const ValueKey('background-pane-opacity'),
+ value: value.paneOpacity,
+ min: AppearancePrefs.paneOpacityMin,
+ divisions: 20,
+ label: percent,
+ onChanged: prefs.setPaneOpacity,
),
- SizedBox(
- width: 44,
- child: Text(
- percent,
- textAlign: TextAlign.end,
- style: grid.AppType.label(
- color: grid.AppPalette.textSecondary,
- ),
- ),
+ ),
+ SizedBox(
+ width: 44,
+ child: Text(
+ percent,
+ textAlign: TextAlign.end,
+ style: grid.AppType.label(color: grid.AppPalette.textSecondary),
),
- ],
- ),
- ],
+ ),
+ ],
+ ),
],
);
}
diff --git a/desktop/lib/shared/theme/appearance_prefs_store.dart b/desktop/lib/shared/theme/appearance_prefs_store.dart
index e4f7018a7..ca0ea9b6f 100644
--- a/desktop/lib/shared/theme/appearance_prefs_store.dart
+++ b/desktop/lib/shared/theme/appearance_prefs_store.dart
@@ -22,7 +22,6 @@ class AppearancePrefs {
this.palette = HarnessPalette.graphite,
this.background = HarnessBackground.plain,
this.custom = const CustomBackground(),
- this.behindHarnesses = false,
this.paneOpacity = paneOpacityDefault,
this.prompt = const PromptPrefs(),
});
@@ -35,23 +34,18 @@ class AppearancePrefs {
/// click.
final CustomBackground custom;
- /// Also paint the background behind a running harness tab's panes. Kept
- /// while Blank is selected, so choosing an image again brings it back.
- final bool behindHarnesses;
-
- /// How solid the panes are while [behindHarnesses] shows through them.
+ /// How solid the panes are while the background shows through them.
final double paneOpacity;
static const double paneOpacityDefault = 0.5;
static const double paneOpacityMin = 0;
/// Whether a running harness tab paints the background at all: Blank has
/// nothing to show through.
- bool get showsBehindHarnesses =>
- behindHarnesses && background != HarnessBackground.plain;
+ bool get showsBackground => background != HarnessBackground.plain;
/// The opacity panes paint their own fill at; 1 unless the background is
/// showing behind them.
- double get effectivePaneOpacity => showsBehindHarnesses ? paneOpacity : 1;
+ double get effectivePaneOpacity => showsBackground ? paneOpacity : 1;
/// Legacy fields, retained for settings compatibility with older builds.
final String? uiFamily;
@@ -70,7 +64,6 @@ class AppearancePrefs {
HarnessPalette? palette,
HarnessBackground? background,
CustomBackground? custom,
- bool? behindHarnesses,
double? paneOpacity,
PromptPrefs? prompt,
bool clearUiFamily = false,
@@ -80,7 +73,6 @@ class AppearancePrefs {
palette: palette ?? this.palette,
background: background ?? this.background,
custom: custom ?? this.custom,
- behindHarnesses: behindHarnesses ?? this.behindHarnesses,
paneOpacity: paneOpacity ?? this.paneOpacity,
prompt: prompt ?? this.prompt,
);
@@ -93,7 +85,6 @@ class AppearancePrefs {
other.palette == palette &&
other.background == background &&
other.custom == custom &&
- other.behindHarnesses == behindHarnesses &&
other.paneOpacity == paneOpacity &&
other.prompt == prompt;
@@ -104,7 +95,6 @@ class AppearancePrefs {
palette,
background,
custom,
- behindHarnesses,
paneOpacity,
prompt,
);
@@ -129,13 +119,14 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
static const _paletteKey = 'app_color_palette';
static const _backgroundKey = 'harness_start_background';
static const _customKey = 'harness_custom_background';
- static const _behindKey = 'harness_background_behind_harnesses';
+ // Named for the retired on/off choice; it now holds only pane opacity.
+ static const _paneOpacityKey = 'harness_background_behind_harnesses';
static const _promptKey = 'workspace_prompt_v1';
Future<void>? _promptSave;
Future<void>? _paletteSave;
Future<void>? _backgroundSave;
Future<void>? _customSave;
- Future<void>? _behindSave;
+ Future<void>? _paneOpacitySave;
final LocalKeyValueStore _storage;
final Directory? _backgroundsDirectory;
@@ -165,10 +156,9 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
_paletteKey,
_backgroundKey,
_customKey,
- _behindKey,
+ _paneOpacityKey,
_promptKey,
]);
- final (behind, opacity) = _behindFrom(saved[_behindKey]);
final custom = _customFrom(saved[_customKey]);
final background = HarnessBackground.fromId(saved[_backgroundKey]);
value = AppearancePrefs(
@@ -181,8 +171,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
? HarnessBackground.plain
: background,
custom: custom,
- behindHarnesses: behind,
- paneOpacity: opacity,
+ paneOpacity: _paneOpacityFrom(saved[_paneOpacityKey]),
prompt: _promptFrom(saved[_promptKey]),
);
} catch (_) {
@@ -290,48 +279,39 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
}
}
- /// Behind harnesses and pane opacity. Opacity changes are clamped to
- /// [AppearancePrefs.paneOpacityMin]…1 rather than rejected.
- Future<void> setBehindHarnesses({bool? on, double? opacity}) {
- final next = value.copyWith(
- behindHarnesses: on,
- paneOpacity: opacity == null ? null : _clampOpacity(opacity),
- );
- if (next == value) return _behindSave ?? Future.value();
+ /// Pane opacity, clamped to [AppearancePrefs.paneOpacityMin]…1 rather than
+ /// rejected.
+ Future<void> setPaneOpacity(double opacity) {
+ final next = value.copyWith(paneOpacity: _clampOpacity(opacity));
+ if (next == value) return _paneOpacitySave ?? Future.value();
value = next;
- return _behindSave ??= _saveBehind();
+ return _paneOpacitySave ??= _savePaneOpacity();
}
- Future<void> _saveBehind() async {
+ Future<void> _savePaneOpacity() async {
try {
while (true) {
- final on = value.behindHarnesses, opacity = value.paneOpacity;
- await _storage.write(
- _behindKey,
- jsonEncode({'on': on, 'opacity': opacity}),
- );
- if (value.behindHarnesses == on && value.paneOpacity == opacity) break;
+ final opacity = value.paneOpacity;
+ await _storage.write(_paneOpacityKey, jsonEncode({'opacity': opacity}));
+ if (value.paneOpacity == opacity) break;
}
} catch (_) {
// Keep the choice for this run if storage is unavailable.
} finally {
- _behindSave = null;
+ _paneOpacitySave = null;
}
}
- static (bool, double) _behindFrom(String? raw) {
+ /// Older builds also saved an `on` flag here; it is ignored.
+ static double _paneOpacityFrom(String? raw) {
try {
final json = raw == null ? null : jsonDecode(raw);
- if (json is! Map) return (false, AppearancePrefs.paneOpacityDefault);
- final on = json['on'], opacity = json['opacity'];
- return (
- on == true,
- opacity is num
- ? _clampOpacity(opacity.toDouble())
- : AppearancePrefs.paneOpacityDefault,
- );
+ final opacity = json is Map ? json['opacity'] : null;
+ return opacity is num
+ ? _clampOpacity(opacity.toDouble())
+ : AppearancePrefs.paneOpacityDefault;
} catch (_) {
- return (false, AppearancePrefs.paneOpacityDefault);
+ return AppearancePrefs.paneOpacityDefault;
}
}
@@ -413,7 +393,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
await _paletteSave;
await _backgroundSave;
await _customSave;
- await _behindSave;
+ await _paneOpacitySave;
await _promptSave;
try {
await _storage.delete(_familyKey);
@@ -421,7 +401,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
await _storage.delete(_paletteKey);
await _storage.delete(_backgroundKey);
await _storage.delete(_customKey);
- await _storage.delete(_behindKey);
+ await _storage.delete(_paneOpacityKey);
await _storage.delete(_promptKey);
} catch (_) {
// See above.
diff --git a/desktop/lib/widgets/box_chrome.dart b/desktop/lib/widgets/box_chrome.dart
index fd790aa4e..e2fd189ad 100644
--- a/desktop/lib/widgets/box_chrome.dart
+++ b/desktop/lib/widgets/box_chrome.dart
@@ -18,7 +18,7 @@ BorderSide terminalPaneBorder({bool focused = false}) => BorderSide(
const double kWorkspaceInset = 9.5;
/// How solid the workspace's panes paint their own fill: below 1 while the
-/// background shows through them (Behind harnesses). Only fills turn
+/// background shows through them (any Background but Blank). Only fills turn
/// translucent — text, colored cells, banners and the composer stay solid.
class PaneOpacity extends InheritedWidget {
const PaneOpacity({super.key, required this.opacity, required super.child});
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index 673b9e80d..3ddc9c164 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -1258,7 +1258,7 @@ class _PaneCell extends StatelessWidget {
// What changes to make the gaps visible is the field BEHIND the grid
// (see _GridField), which is the part the gaps actually show.
//
- // Behind harnesses: a terminal paints its own translucent fills, so
+ // Over a Background: a terminal paints its own translucent fills, so
// the frame adds none (two would stack); a status pane has only this.
color: PaneOpacity.of(context) < 1 && pane.session != null
? null
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index d04e9a8a1..190b7fb3c 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -2115,7 +2115,7 @@ class _TerminalPanelState extends State<TerminalPanel>
final machineState = widget.notifier.stateOf(session.machineId);
final remote = machineState != null && !machineState.isLocalMachine;
final showComposer = _showsComposer;
- // Behind harnesses: each part paints its own fill at this opacity (the
+ // Over a Background: each part paints its own fill at this opacity (the
// header, the screen) or solid (the composer), over nothing — a fill
// underneath them all would stack with theirs.
final paneOpacity = PaneOpacity.of(context);
diff --git a/desktop/test/background_behind_harnesses_test.dart b/desktop/test/background_pane_opacity_test.dart
similarity index 71%
rename from desktop/test/background_behind_harnesses_test.dart
rename to desktop/test/background_pane_opacity_test.dart
index e815b2a2e..5ae1181f8 100644
--- a/desktop/test/background_behind_harnesses_test.dart
+++ b/desktop/test/background_pane_opacity_test.dart
@@ -24,9 +24,9 @@ HarnessBackground get _artwork => HarnessBackground.gallery.firstWhere(
void main() {
group('prefs', () {
- test('off by default, at 50%', () {
+ test('Blank by default, at 50%', () {
const prefs = AppearancePrefs();
- expect(prefs.behindHarnesses, isFalse);
+ expect(prefs.showsBackground, isFalse);
expect(prefs.paneOpacity, 0.5);
expect(prefs.effectivePaneOpacity, 1);
});
@@ -34,60 +34,66 @@ void main() {
test('round-trips through storage', () async {
final storage = _Storage();
final store = AppearancePrefsStore(storage: storage);
- await store.setBehindHarnesses(on: true, opacity: 0.6);
+ await store.setPaneOpacity(0.6);
final reloaded = AppearancePrefsStore(storage: storage);
await reloaded.load();
- expect(reloaded.value.behindHarnesses, isTrue);
expect(reloaded.value.paneOpacity, 0.6);
});
- test('opacity is clamped, and garbage lands on the defaults', () async {
+ test('an older build\'s off switch is ignored', () async {
+ final storage = _Storage()
+ ..values[_key] = '{"on": false, "opacity": 0.3}';
+ final store = AppearancePrefsStore(storage: storage);
+ await store.load();
+ await store.setBackground(_artwork);
+ expect(store.value.showsBackground, isTrue);
+ expect(store.value.effectivePaneOpacity, 0.3);
+ });
+
+ test('opacity is clamped, and garbage lands on the default', () async {
final storage = _Storage();
final store = AppearancePrefsStore(storage: storage);
- await store.setBehindHarnesses(opacity: -1);
+ await store.setPaneOpacity(-1);
expect(store.value.paneOpacity, AppearancePrefs.paneOpacityMin);
- await store.setBehindHarnesses(opacity: 7);
+ await store.setPaneOpacity(7);
expect(store.value.paneOpacity, 1);
- storage.values[_key] = '{"on": "yes", "opacity": "NaN"}';
+ storage.values[_key] = '{"opacity": "NaN"}';
await store.load();
- expect(store.value.behindHarnesses, isFalse);
expect(store.value.paneOpacity, AppearancePrefs.paneOpacityDefault);
storage.values[_key] = 'not json';
await store.load();
- expect(store.value.behindHarnesses, isFalse);
+ expect(store.value.paneOpacity, AppearancePrefs.paneOpacityDefault);
});
- test('Blank shows nothing behind harnesses, but keeps the choice', () async {
+ test('any Background but Blank shows through the panes', () async {
final store = AppearancePrefsStore(storage: _Storage());
- await store.setBehindHarnesses(on: true, opacity: 0.7);
- expect(store.value.showsBehindHarnesses, isFalse);
+ await store.setPaneOpacity(0.7);
+ expect(store.value.showsBackground, isFalse);
expect(store.value.effectivePaneOpacity, 1);
await store.setBackground(_artwork);
- expect(store.value.showsBehindHarnesses, isTrue);
+ expect(store.value.showsBackground, isTrue);
expect(store.value.effectivePaneOpacity, 0.7);
await store.setBackground(HarnessBackground.plain);
- expect(store.value.behindHarnesses, isTrue);
+ expect(store.value.showsBackground, isFalse);
expect(store.value.effectivePaneOpacity, 1);
});
test('reset forgets it', () async {
final storage = _Storage();
final store = AppearancePrefsStore(storage: storage);
- await store.setBehindHarnesses(on: true);
+ await store.setPaneOpacity(0.2);
await store.reset();
- expect(store.value.behindHarnesses, isFalse);
+ expect(store.value.paneOpacity, AppearancePrefs.paneOpacityDefault);
expect(storage.values.containsKey(_key), isFalse);
});
});
- testWidgets('the switch shows for artwork and reveals pane opacity', (
- tester,
- ) async {
+ testWidgets('pane opacity shows for artwork only', (tester) async {
final store = AppearancePrefsStore(storage: _Storage());
await tester.pumpWidget(
MaterialApp(
@@ -96,19 +102,11 @@ void main() {
),
),
);
- final toggle = find.byKey(const ValueKey('background-behind-harnesses'));
final slider = find.byKey(const ValueKey('background-pane-opacity'));
- expect(toggle, findsNothing, reason: 'Blank has nothing to show');
+ expect(slider, findsNothing, reason: 'Blank has nothing to show');
await store.setBackground(_artwork);
await tester.pumpAndSettle();
- expect(toggle, findsOneWidget);
- expect(slider, findsNothing);
-
- await tester.ensureVisible(toggle);
- await tester.tap(toggle);
- await tester.pumpAndSettle();
- expect(store.value.behindHarnesses, isTrue);
expect(slider, findsOneWidget);
expect(find.text('50%'), findsOneWidget);
});