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.

Make pane shading optional with Cmd+Shift+F (#731)

Deec3b22eaabd9f
diff --git a/desktop/design/terminal-workspace.md b/desktop/design/terminal-workspace.md
index c59d0ae0a..1950f11cb 100644
--- a/desktop/design/terminal-workspace.md
+++ b/desktop/design/terminal-workspace.md
@@ -75,8 +75,15 @@ behavior and data rules; the desktop design system controls presentation.
## Focused panes
-The selected pane stays at full contrast. Other visible panes receive the
-approved 30% neutral-gray veil; Graphite's inactive background is RGB 64,64,64.
+All panes stay at full contrast by default. **Cmd+Shift+F** toggles shading on
+and off while working (**Ctrl+Alt+F** on Linux; **Alt+Shift+F** in the browser).
+When enabled, panes outside the current focus receive the approved 30%
+neutral-gray veil; Graphite's inactive background is RGB 64,64,64.
+Customize Harness → Appearance → **Shade inactive panes** toggles this veil
+through the same saved preference and shows the current shortcut, including
+remaps. **Toggle pane shading** is also available in the command search and
+keyboard shortcuts. Turning it off leaves
+all panes at full contrast, with the existing focus and waiting-question borders.
A single or zoomed pane stays clear. Existing click and keyboard focus actions
own selection. Keep the current pane clear while a menu or the tab strip has
keyboard focus. Waiting-question borders remain visible above the veil.
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index c523ed21d..222091690 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -6391,6 +6391,11 @@ class _SwarmScreenState extends State<SwarmScreen> {
'pane.focus_$i': () => app.focusPaneByIndex(i - 1),
'navigation.commands': _showSearchCommands,
'app.customize': () => unawaited(_customize()),
+ 'pane.toggle_shading': () => unawaited(
+ appearancePrefsStore.setShadeInactivePanes(
+ !appearancePrefsStore.value.shadeInactivePanes,
+ ),
+ ),
'app.add_phone': () => unawaited(_addPhone()),
'app.store': _openStore,
'app.daemon': _openCompanions,
diff --git a/desktop/lib/settings/sections/appearance_section.dart b/desktop/lib/settings/sections/appearance_section.dart
index 6ae4370b4..e234607c8 100644
--- a/desktop/lib/settings/sections/appearance_section.dart
+++ b/desktop/lib/settings/sections/appearance_section.dart
@@ -1,8 +1,13 @@
+import 'dart:async';
+
import 'package:flutter/material.dart';
import '../../shared/theme/app_theme.dart' as grid;
import '../appearance/palette_section.dart';
import '../../shared/theme/appearance_prefs_store.dart';
+import '../../shared/widgets/setting_row.dart';
+import '../../shortcuts/app_keymap.dart';
+import '../../widgets/key_hints.dart';
/// Customize Harness ▸ Appearance: how the app looks on this Mac.
///
@@ -15,11 +20,35 @@ class AppearanceSection extends StatelessWidget {
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
+ final preferences = store ?? appearancePrefsStore;
+ final shortcut = KeyHints.visibleOf(context)
+ ? effectiveCommandHint(context, 'pane.toggle_shading')
+ : null;
return SingleChildScrollView(
padding: const EdgeInsets.all(20),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
+ ValueListenableBuilder<AppearancePrefs>(
+ valueListenable: preferences,
+ builder: (context, prefs, _) => SettingRow(
+ title: 'Shade inactive panes',
+ controlSemanticLabel: 'Shade inactive panes',
+ detail:
+ 'Add a gray shade to panes that aren’t selected.'
+ '${shortcut == null ? '' : ' Toggle with $shortcut.'}',
+ control: Align(
+ alignment: Alignment.centerLeft,
+ child: Switch(
+ key: const ValueKey('shade-inactive-panes'),
+ value: prefs.shadeInactivePanes,
+ onChanged: (enabled) =>
+ unawaited(preferences.setShadeInactivePanes(enabled)),
+ ),
+ ),
+ ),
+ ),
+ const SizedBox(height: 24),
PaletteSection(store: store),
// Room under the last card so a scrolled-to-bottom pane does not end
// flush against the window edge.
diff --git a/desktop/lib/shared/theme/appearance_prefs_store.dart b/desktop/lib/shared/theme/appearance_prefs_store.dart
index ca0ea9b6f..dbfe50eea 100644
--- a/desktop/lib/shared/theme/appearance_prefs_store.dart
+++ b/desktop/lib/shared/theme/appearance_prefs_store.dart
@@ -23,6 +23,7 @@ class AppearancePrefs {
this.background = HarnessBackground.plain,
this.custom = const CustomBackground(),
this.paneOpacity = paneOpacityDefault,
+ this.shadeInactivePanes = false,
this.prompt = const PromptPrefs(),
});
@@ -39,6 +40,9 @@ class AppearancePrefs {
static const double paneOpacityDefault = 0.5;
static const double paneOpacityMin = 0;
+ /// Whether panes outside the current focus receive a neutral-gray veil.
+ final bool shadeInactivePanes;
+
/// Whether a running harness tab paints the background at all: Blank has
/// nothing to show through.
bool get showsBackground => background != HarnessBackground.plain;
@@ -65,6 +69,7 @@ class AppearancePrefs {
HarnessBackground? background,
CustomBackground? custom,
double? paneOpacity,
+ bool? shadeInactivePanes,
PromptPrefs? prompt,
bool clearUiFamily = false,
}) => AppearancePrefs(
@@ -74,6 +79,7 @@ class AppearancePrefs {
background: background ?? this.background,
custom: custom ?? this.custom,
paneOpacity: paneOpacity ?? this.paneOpacity,
+ shadeInactivePanes: shadeInactivePanes ?? this.shadeInactivePanes,
prompt: prompt ?? this.prompt,
);
@@ -86,6 +92,7 @@ class AppearancePrefs {
other.background == background &&
other.custom == custom &&
other.paneOpacity == paneOpacity &&
+ other.shadeInactivePanes == shadeInactivePanes &&
other.prompt == prompt;
@override
@@ -96,6 +103,7 @@ class AppearancePrefs {
background,
custom,
paneOpacity,
+ shadeInactivePanes,
prompt,
);
}
@@ -121,12 +129,14 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
static const _customKey = 'harness_custom_background';
// Named for the retired on/off choice; it now holds only pane opacity.
static const _paneOpacityKey = 'harness_background_behind_harnesses';
+ static const _shadeInactivePanesKey = 'harness_shade_inactive_panes';
static const _promptKey = 'workspace_prompt_v1';
Future<void>? _promptSave;
Future<void>? _paletteSave;
Future<void>? _backgroundSave;
Future<void>? _customSave;
Future<void>? _paneOpacitySave;
+ Future<void>? _shadeInactivePanesSave;
final LocalKeyValueStore _storage;
final Directory? _backgroundsDirectory;
@@ -157,6 +167,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
_backgroundKey,
_customKey,
_paneOpacityKey,
+ _shadeInactivePanesKey,
_promptKey,
]);
final custom = _customFrom(saved[_customKey]);
@@ -172,6 +183,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
: background,
custom: custom,
paneOpacity: _paneOpacityFrom(saved[_paneOpacityKey]),
+ shadeInactivePanes: saved[_shadeInactivePanesKey] == 'true',
prompt: _promptFrom(saved[_promptKey]),
);
} catch (_) {
@@ -302,6 +314,29 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
}
}
+ /// Apply immediately and serialize writes so the final choice survives.
+ Future<void> setShadeInactivePanes(bool enabled) {
+ if (value.shadeInactivePanes == enabled) {
+ return _shadeInactivePanesSave ?? Future.value();
+ }
+ value = value.copyWith(shadeInactivePanes: enabled);
+ return _shadeInactivePanesSave ??= _saveShadeInactivePanes();
+ }
+
+ Future<void> _saveShadeInactivePanes() async {
+ try {
+ while (true) {
+ final enabled = value.shadeInactivePanes;
+ await _storage.write(_shadeInactivePanesKey, enabled.toString());
+ if (value.shadeInactivePanes == enabled) break;
+ }
+ } catch (_) {
+ // Keep the choice for this run if storage is unavailable.
+ } finally {
+ _shadeInactivePanesSave = null;
+ }
+ }
+
/// Older builds also saved an `on` flag here; it is ignored.
static double _paneOpacityFrom(String? raw) {
try {
@@ -394,6 +429,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
await _backgroundSave;
await _customSave;
await _paneOpacitySave;
+ await _shadeInactivePanesSave;
await _promptSave;
try {
await _storage.delete(_familyKey);
@@ -402,6 +438,7 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
await _storage.delete(_backgroundKey);
await _storage.delete(_customKey);
await _storage.delete(_paneOpacityKey);
+ await _storage.delete(_shadeInactivePanesKey);
await _storage.delete(_promptKey);
} catch (_) {
// See above.
diff --git a/desktop/lib/shortcuts/app_shortcuts.dart b/desktop/lib/shortcuts/app_shortcuts.dart
index 3c88be039..e7260535d 100644
--- a/desktop/lib/shortcuts/app_shortcuts.dart
+++ b/desktop/lib/shortcuts/app_shortcuts.dart
@@ -423,6 +423,8 @@ const linuxAltCommandKeys = <String, List<String>>{
'navigation.commands': ['ctrl+shift+p'],
'harnesses.list': ['alt+shift+p'],
'pane.split_down': ['alt+shift+d'],
+ // Alt-Shift-F already opens terminal Find on Linux.
+ 'pane.toggle_shading': ['ctrl+alt+f'],
'app.daemon_talk': ['alt+shift+a'],
};
diff --git a/desktop/lib/shortcuts/keymap_commands.dart b/desktop/lib/shortcuts/keymap_commands.dart
index 82e04602d..99791f5b8 100644
--- a/desktop/lib/shortcuts/keymap_commands.dart
+++ b/desktop/lib/shortcuts/keymap_commands.dart
@@ -509,6 +509,13 @@ final harnessCommands = <HarnessCommand>[
ShortcutGroup.actions,
nativeAction: 'customize',
),
+ const HarnessCommand(
+ 'pane.toggle_shading',
+ 'Toggle pane shading',
+ ShortcutGroup.panes,
+ extraKeys: ['cmd+shift+f'],
+ keywords: ['focus', 'shade', 'dim', 'appearance'],
+ ),
const HarnessCommand(
'app.store',
'Harness Store',
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index 682887518..ca7bdf042 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -15,6 +15,7 @@ import '../core/dsh_catalog.dart' show DshEntry;
import '../core/models.dart' show Agent, kUntitledPane;
import '../clipboard/native_clipboard.dart';
import '../shared/theme/app_theme.dart' as grid;
+import '../shared/theme/appearance_prefs_store.dart';
// `hide TerminalKey`: this file's own shortcut-label class, unused here, collides with xterm's
// `TerminalKey` (needed for the local image-drop Ctrl+V nudge — see `_dropImage`).
import '../shortcuts/app_shortcuts.dart' hide TerminalKey;
@@ -1271,22 +1272,28 @@ class _PaneCell extends StatelessWidget {
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return RepaintBoundary(
- child: LayoutBuilder(
- builder: (context, constraints) {
- if (visible) pane.lastViewSize = constraints.biggest;
- return _build(context);
- },
+ child: ValueListenableBuilder<AppearancePrefs>(
+ valueListenable: appearancePrefsStore,
+ builder: (context, prefs, _) => LayoutBuilder(
+ builder: (context, constraints) {
+ if (visible) pane.lastViewSize = constraints.biggest;
+ return _build(context, prefs);
+ },
+ ),
),
);
}
- Widget _build(BuildContext context) {
+ Widget _build(BuildContext context, AppearancePrefs prefs) {
grid.AppTheme.watch(context);
final focused = visible && notifier.isPaneFocused(pane.id);
final remote = notifier.stateOf(pane.machineId)?.isLocalMachine == false;
// Keep the selected harness's terminal and viewers clear, including while
// a menu owns input. This changes paint, never the keyboard's destination.
- final dimmed = !_single && !notifier.isPaneEmphasized(pane);
+ final dimmed =
+ prefs.shadeInactivePanes &&
+ !_single &&
+ !notifier.isPaneEmphasized(pane);
final agentId = pane.agentId;
final blocked =
agentId != null &&
diff --git a/desktop/test/appearance_prefs_store_test.dart b/desktop/test/appearance_prefs_store_test.dart
index 0b0403f7b..c9d85edfb 100644
--- a/desktop/test/appearance_prefs_store_test.dart
+++ b/desktop/test/appearance_prefs_store_test.dart
@@ -34,6 +34,7 @@ void main() {
const prefs = AppearancePrefs();
expect(prefs.uiFamily, isNull);
expect(prefs.uiSize, 14);
+ expect(prefs.shadeInactivePanes, isFalse);
// Legacy fields remain readable, but no longer control app typography.
});
diff --git a/desktop/test/keymap_host_test.dart b/desktop/test/keymap_host_test.dart
index f67c0021b..06a7ca989 100644
--- a/desktop/test/keymap_host_test.dart
+++ b/desktop/test/keymap_host_test.dart
@@ -101,6 +101,7 @@ void main() {
('cmd+m', 'machines.list'),
('cmd+i', 'models.list'),
('cmd+shift+l', 'pane.layout'),
+ ('cmd+shift+f', 'pane.toggle_shading'),
('cmd+b', 'task.route'),
('cmd+w', 'swarm.close'),
('cmd+shift+w', 'pane.close'),
diff --git a/desktop/test/pane_focus_test.dart b/desktop/test/pane_focus_test.dart
index f43cf406c..3b16eb212 100644
--- a/desktop/test/pane_focus_test.dart
+++ b/desktop/test/pane_focus_test.dart
@@ -5,6 +5,7 @@ import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/models.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shared/theme/appearance_prefs_store.dart';
import 'package:harness/state/pane_preset.dart';
import 'package:harness/state/terminal_pane.dart';
import 'package:harness/terminal/terminal_binary.dart';
@@ -19,6 +20,11 @@ import 'workspace_activity_test.dart' show captureWorkspace;
void main() {
final capture = Platform.environment['HARNESS_PANE_FOCUS_CAPTURE_DIR'];
+ setUp(() {
+ final previous = appearancePrefsStore.value;
+ addTearDown(() => appearancePrefsStore.value = previous);
+ appearancePrefsStore.value = previous.copyWith(shadeInactivePanes: true);
+ });
setUpAll(() async {
await loadRealFonts();
if (capture != null && Platform.isMacOS) {
diff --git a/desktop/test/startup_test.dart b/desktop/test/startup_test.dart
index bb4bda218..b51b09ceb 100644
--- a/desktop/test/startup_test.dart
+++ b/desktop/test/startup_test.dart
@@ -180,6 +180,7 @@ void main() {
'harness_start_background',
'harness_custom_background',
'harness_background_behind_harnesses',
+ 'harness_shade_inactive_panes',
'workspace_prompt_v1',
},
]);
@@ -189,10 +190,12 @@ void main() {
'app_ui_font_family': null,
'app_ui_font_size': '18',
'app_color_palette': 'midnight',
+ 'harness_shade_inactive_panes': 'true',
});
await Future<void>.delayed(Duration.zero);
expect(appearance.value.uiSize, 18);
expect(appearance.value.palette, HarnessPalette.midnight);
+ expect(appearance.value.shadeInactivePanes, isTrue);
expect(finished, isFalse);
fontStorage.ready.complete({
diff --git a/docs/keyboard.md b/docs/keyboard.md
index 4094ba8f1..fd0dfa8c6 100644
--- a/docs/keyboard.md
+++ b/docs/keyboard.md
@@ -31,6 +31,7 @@ The defaults, in the workspace:
| ⌘I | Models — subscriptions, local models, shared models, and APIs |
| ⇧⌘L | Layout palette |
| ⌘F · ⌘G · ⇧⌘G | Find in terminal · next · previous match |
+| ⇧⌘F / Ctrl+Alt+F (Linux) / Alt+Shift+F (browser) | Toggle inactive pane shading. Off by default; also available in Customize Harness → Appearance |
| ⇧⌘I | Harnesses needing input |
| ⌘, · ⌘/ | Settings · keyboard shortcuts |