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.

Guide New Tab onboarding and add Models shortcut (#299)

Deec9993f3fd71a
diff --git a/.github/assets/new-tab/everyday.png b/.github/assets/new-tab/everyday.png
new file mode 100644
index 000000000..2ace55ee2
Binary files /dev/null and b/.github/assets/new-tab/everyday.png differ
diff --git a/.github/assets/new-tab/first.png b/.github/assets/new-tab/first.png
new file mode 100644
index 000000000..8ff53ea16
Binary files /dev/null and b/.github/assets/new-tab/first.png differ
diff --git a/.github/assets/new-tab/progress.png b/.github/assets/new-tab/progress.png
new file mode 100644
index 000000000..7c8a6d97a
Binary files /dev/null and b/.github/assets/new-tab/progress.png differ
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 1e4534feb..09a0ce2b4 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -241,7 +241,11 @@ class _SwarmScreenState extends State<SwarmScreen>
String? _commandCatalogMachine;
final _newTabSources = <String, TerminalPane>{};
- Widget _startGuide() => WorkspaceWelcome(onCommand: _runShortcut);
+ Widget _startGuide() => WorkspaceWelcome(
+ key: ValueKey('welcome:${app.activeSwarmId}'),
+ onboarding: _onboarding,
+ onCommand: _runShortcut,
+ );
void _showKeyboardShortcuts() {
if (_newHarness?.requestDismiss() == false) return;
@@ -449,7 +453,9 @@ class _SwarmScreenState extends State<SwarmScreen>
_machinesPanel?.close(restoreFocus: false);
}
if (_sessionsOverlay != null) _closeSessions(restoreFocus: false);
- if (_modelsOverlay != null) _closeModels(restoreFocus: false);
+ if (id != 'models.list' && _modelsOverlay != null) {
+ _closeModels(restoreFocus: false);
+ }
if (id != 'navigation.command_bar') _closeCommandBar();
if (id == 'agent.new' && _search != null) {
final target = _search!.targetId;
@@ -2354,16 +2360,19 @@ class _SwarmScreenState extends State<SwarmScreen>
),
],
),
- child: ModelsPanel(
- newModelIds: _toolbarNotices.newModelIds,
- showOnboarding: _onboarding.next == OnboardingStep.models,
- onDismissOnboarding: () =>
- _onboarding.dismiss(OnboardingStep.models),
- controller: app.modelManager,
- subscriptions: _modelsMenu!,
- initialTab: initialTab,
- onClose: _closeModels,
- onManage: () => unawaited(_openModelManager()),
+ child: KeymapProvider(
+ keymap: _keymap,
+ child: ModelsPanel(
+ newModelIds: _toolbarNotices.newModelIds,
+ showOnboarding: _onboarding.next == OnboardingStep.models,
+ onDismissOnboarding: () =>
+ _onboarding.dismiss(OnboardingStep.models),
+ controller: app.modelManager,
+ subscriptions: _modelsMenu!,
+ initialTab: initialTab,
+ onClose: _closeModels,
+ onManage: () => unawaited(_openModelManager()),
+ ),
),
),
),
@@ -2453,37 +2462,41 @@ class _SwarmScreenState extends State<SwarmScreen>
),
child: Padding(
padding: const EdgeInsets.all(1),
- child: HarnessSessionManager(
- app: app,
- introduction: _onboarding.next == OnboardingStep.harnesses
- ? OnboardingCard(
- title: 'Run your first harness',
- description:
- 'Give an agent a task. Watch it get to work.',
- action: 'New harness',
- onAction: () {
- _closeSessions(restoreFocus: false);
- _runShortcut('agent.new');
- },
- onDismiss: () =>
- _onboarding.dismiss(OnboardingStep.harnesses),
- )
- : null,
- initialFilter: filter ?? SessionFilter.all,
- recent: _navigation.recent,
- onClose: _closeSessions,
- onOpen: (row) async {
- final destination = swarmDestinations(app)
- .where((item) => item.id == row.id)
- .firstOrNull;
- if (destination == null) return false;
- final opened = await activateSwarmDestination(
- app,
- destination,
- destinationSwarmId: app.activeSwarmId,
- );
- return opened;
- },
+ child: KeymapProvider(
+ keymap: _keymap,
+ child: HarnessSessionManager(
+ app: app,
+ introduction:
+ _onboarding.next == OnboardingStep.harnesses
+ ? OnboardingCard(
+ title: 'Run your first harness',
+ description: 'Give an agent a task. Watch it get to work.',
+ action: 'New harness',
+ onAction: () {
+ _closeSessions(restoreFocus: false);
+ _runShortcut('agent.new');
+ },
+ onDismiss: () => _onboarding.dismiss(
+ OnboardingStep.harnesses,
+ ),
+ )
+ : null,
+ initialFilter: filter ?? SessionFilter.all,
+ recent: _navigation.recent,
+ onClose: _closeSessions,
+ onOpen: (row) async {
+ final destination = swarmDestinations(app)
+ .where((item) => item.id == row.id)
+ .firstOrNull;
+ if (destination == null) return false;
+ final opened = await activateSwarmDestination(
+ app,
+ destination,
+ destinationSwarmId: app.activeSwarmId,
+ );
+ return opened;
+ },
+ ),
),
),
),
@@ -3179,6 +3192,7 @@ class _SwarmScreenState extends State<SwarmScreen>
'machine.link': _openMachines,
'machines.manage': _manageMachines,
'machines.list': _openMachines,
+ 'models.list': _toggleModels,
'project.add': _addProject,
'keyboard.open_config': () => openKeyboardConfig(context),
'keyboard.quick_start': _startQuickStart,
@@ -4073,7 +4087,7 @@ class _SwarmScreenState extends State<SwarmScreen>
),
IconButton(
key: const ValueKey('swarm-models-button'),
- tooltip: 'Models',
+ tooltip: 'Models ${_keymap.hint('models.list') ?? ''}'.trim(),
onPressed: _toggleModels,
isSelected: _modelsOverlay != null,
style: _toolbarIconStyle(_toolbarNotices.modelCount),
diff --git a/desktop/lib/shortcuts/keymap_commands.dart b/desktop/lib/shortcuts/keymap_commands.dart
index 9680f2de3..4283145c5 100644
--- a/desktop/lib/shortcuts/keymap_commands.dart
+++ b/desktop/lib/shortcuts/keymap_commands.dart
@@ -301,11 +301,7 @@ final harnessCommands = <HarnessCommand>[
nativeAction: 'addAgent',
keywords: ['resume', 'existing', 'pane'],
),
- const HarnessCommand(
- 'agent.add',
- 'New Pane',
- ShortcutGroup.actions,
- ),
+ const HarnessCommand('agent.add', 'New Pane', ShortcutGroup.actions),
const HarnessCommand(
'agent.new',
'New Harness',
@@ -353,6 +349,14 @@ final harnessCommands = <HarnessCommand>[
nativeAction: 'machineList',
extraKeys: ['cmd+m'],
),
+ const HarnessCommand(
+ 'models.list',
+ 'Open Models',
+ ShortcutGroup.actions,
+ nativeAction: 'models',
+ extraKeys: ['cmd+i'],
+ keywords: ['local', 'AI', 'model', 'intelligence'],
+ ),
const HarnessCommand(
'machine.link',
'Connect another machine',
diff --git a/desktop/lib/state/workspace_onboarding.dart b/desktop/lib/state/workspace_onboarding.dart
index 8eb42cea4..7eceaaa11 100644
--- a/desktop/lib/state/workspace_onboarding.dart
+++ b/desktop/lib/state/workspace_onboarding.dart
@@ -22,6 +22,9 @@ class WorkspaceOnboarding extends ChangeNotifier {
Set<OnboardingStep> _observed = {};
Future<void> _saving = Future.value();
+ String? get scope => _scope;
+ bool get loaded => _loaded;
+ bool get complete => _loaded && OnboardingStep.values.every(completed);
bool completed(OnboardingStep step) => _completed.contains(step);
OnboardingStep? get next {
if (!_loaded) return null;
diff --git a/desktop/lib/widgets/workspace_welcome.dart b/desktop/lib/widgets/workspace_welcome.dart
index 90acffd0f..00038b024 100644
--- a/desktop/lib/widgets/workspace_welcome.dart
+++ b/desktop/lib/widgets/workspace_welcome.dart
@@ -7,32 +7,82 @@ import 'swarm_wallpaper.dart';
import '../shortcuts/app_keymap.dart';
import '../shortcuts/keymap.dart';
import '../shortcuts/keymap_commands.dart';
+import '../state/workspace_onboarding.dart';
import '../terminal/terminal_text.dart';
/// A quiet terminal welcome. Opening a command is always an explicit action.
-class WorkspaceWelcome extends StatelessWidget {
- const WorkspaceWelcome({super.key, required this.onCommand});
+class WorkspaceWelcome extends StatefulWidget {
+ const WorkspaceWelcome({super.key, required this.onCommand, this.onboarding});
final ValueChanged<String> onCommand;
+ final WorkspaceOnboarding? onboarding;
- static const _actions = [
- ('agent.new', 'New Harness', 'to start a new harness'),
- ('agent.open', 'Open Harness', 'to open a harness'),
- ('machines.list', 'Machines', 'to connect your machines'),
- ('app.store', 'Harness Store', 'to browse the harness store'),
+ @override
+ State<WorkspaceWelcome> createState() => _WorkspaceWelcomeState();
+}
+
+class _WorkspaceWelcomeState extends State<WorkspaceWelcome> {
+ // Keep the last check visible for this visit. A new tab gets a new widget
+ // key and chooses its everyday shortcuts after all milestones are complete.
+ bool? _showOnboarding;
+ String? _scope;
+
+ static const _onboardingActions = [
+ (
+ 'agent.new',
+ 'New Harness',
+ 'to start your first harness',
+ OnboardingStep.harnesses,
+ ),
+ (
+ 'machines.list',
+ 'Machines',
+ 'to manage it from anywhere',
+ OnboardingStep.machines,
+ ),
+ (
+ 'models.list',
+ 'Models',
+ 'to power it with a local model',
+ OnboardingStep.models,
+ ),
+ ];
+ static const _everydayActions = [
+ ('agent.new', 'New Harness', 'to start a new harness', null),
+ ('agent.open', 'Open Harness', 'to open a harness', null),
+ ('app.store', 'Harness Store', 'to browse the harness store', null),
];
+ @override
+ void didUpdateWidget(WorkspaceWelcome oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ if (oldWidget.onboarding != widget.onboarding) _showOnboarding = null;
+ }
+
@override
Widget build(BuildContext context) {
TerminalFontScope.watch(context);
return ListenableBuilder(
- listenable: Listenable.merge([terminalFontStore, appearancePrefsStore]),
+ listenable: Listenable.merge([
+ terminalFontStore,
+ appearancePrefsStore,
+ widget.onboarding,
+ ]),
builder: (context, _) => _buildWelcome(context),
);
}
Widget _buildWelcome(BuildContext context) {
grid.AppTheme.watch(context);
+ final onboarding = widget.onboarding;
+ if (_scope != onboarding?.scope) {
+ _scope = onboarding?.scope;
+ _showOnboarding = null;
+ }
+ if (onboarding?.loaded == true) {
+ _showOnboarding ??= !onboarding!.complete;
+ }
+ final showOnboarding = onboarding != null && (_showOnboarding ?? true);
final palette = grid.AppTheme.palette.value;
final background = appearancePrefsStore.value.background;
final hasArtwork = background != HarnessBackground.plain;
@@ -51,11 +101,14 @@ class WorkspaceWelcome extends StatelessWidget {
);
final keymap = KeymapTheme.of(context)?.current ?? harnessDefaultKeymap;
final rows = [
- for (final (command, label, description) in _actions)
+ for (final (command, label, description, step)
+ in showOnboarding ? _onboardingActions : _everydayActions)
(
command: command,
label: label,
description: description,
+ step: step,
+ completed: step != null && onboarding?.completed(step) == true,
hint: keymap
.bindingsFor(KeymapContext.workspace)
.where((binding) => binding.command == command)
@@ -74,6 +127,7 @@ class WorkspaceWelcome extends StatelessWidget {
return width;
}
+ final progressWidth = showOnboarding ? widthOf('✓ ') : 0.0;
final prefixWidth = widthOf('press ');
final keyWidth = rows
.map((row) => widthOf('${row.hint ?? row.label} '))
@@ -82,6 +136,7 @@ class WorkspaceWelcome extends StatelessWidget {
.map((row) => widthOf(row.description))
.reduce((a, b) => a > b ? a : b);
final line = MediaQuery.textScalerOf(context).scale(style.fontSize!) * 1.5;
+ final footerInset = line + 52;
return Material(
key: const ValueKey('workspace-welcome'),
color: grid.AppPalette.swarmWelcome,
@@ -93,72 +148,101 @@ class WorkspaceWelcome extends StatelessWidget {
child: SwarmWallpaper(background: background),
),
LayoutBuilder(
- builder: (context, constraints) => SingleChildScrollView(
- padding: const EdgeInsets.all(24),
- child: ConstrainedBox(
- constraints: BoxConstraints(
- minHeight: (constraints.maxHeight - 48).clamp(
- 0,
- double.infinity,
+ // Keep the text centered when it fits, but let large text scroll
+ // above the fixed Customize button rather than underneath it.
+ builder: (context, constraints) => Padding(
+ padding: EdgeInsets.only(bottom: footerInset),
+ child: SingleChildScrollView(
+ key: const ValueKey('welcome-scroll'),
+ padding: EdgeInsets.fromLTRB(24, footerInset + 24, 24, 24),
+ child: ConstrainedBox(
+ constraints: BoxConstraints(
+ minHeight: (constraints.maxHeight - footerInset * 2 - 48)
+ .clamp(0, double.infinity),
),
- ),
- child: Center(
- child: ConstrainedBox(
- constraints: BoxConstraints(
- maxWidth: prefixWidth + keyWidth + descriptionWidth,
- ),
- child: DefaultTextStyle(
- style: style,
- textAlign: TextAlign.center,
- child: Column(
- key: const ValueKey('workspace-welcome-text'),
- mainAxisSize: MainAxisSize.min,
- children: [
- const Text('HARNESS'),
- SizedBox(height: line),
- const Text('Follow your curiosity.'),
- SizedBox(height: line),
- for (final row in rows)
- TextButton(
- key: ValueKey('welcome-${row.command}'),
- onPressed: () => onCommand(row.command),
- style: TextButton.styleFrom(
- foregroundColor: ink,
- textStyle: style,
- padding: const EdgeInsets.symmetric(
- vertical: 2,
+ child: Center(
+ child: ConstrainedBox(
+ constraints: BoxConstraints(
+ maxWidth:
+ progressWidth +
+ prefixWidth +
+ keyWidth +
+ descriptionWidth,
+ ),
+ child: DefaultTextStyle(
+ style: style,
+ textAlign: TextAlign.center,
+ child: Column(
+ key: const ValueKey('workspace-welcome-text'),
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Text(
+ showOnboarding
+ ? 'Harness like a boss.'
+ : 'Follow your curiosity.',
+ key: const ValueKey('welcome-tagline'),
+ ),
+ SizedBox(height: line),
+ for (final row in rows)
+ TextButton(
+ key: ValueKey('welcome-${row.command}'),
+ onPressed: () => widget.onCommand(row.command),
+ style: TextButton.styleFrom(
+ foregroundColor: ink,
+ textStyle: style,
+ padding: const EdgeInsets.symmetric(
+ vertical: 2,
+ ),
+ minimumSize: Size.zero,
+ tapTargetSize:
+ MaterialTapTargetSize.shrinkWrap,
+ shape: const RoundedRectangleBorder(),
),
- minimumSize: Size.zero,
- tapTargetSize: MaterialTapTargetSize.shrinkWrap,
- shape: const RoundedRectangleBorder(),
- ),
- child: Row(
- crossAxisAlignment: CrossAxisAlignment.start,
- children: [
- SizedBox(
- width: prefixWidth,
- child: Text(
- row.hint == null ? 'click' : 'press',
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ if (row.step != null)
+ SizedBox(
+ width: progressWidth,
+ child: Text(
+ row.completed ? '✓' : '○',
+ key: ValueKey(
+ 'welcome-progress-${row.step!.name}',
+ ),
+ semanticsLabel: row.completed
+ ? 'Completed'
+ : 'Not completed',
+ textAlign: TextAlign.left,
+ style: TextStyle(
+ color: row.completed ? accent : ink,
+ ),
+ ),
+ ),
+ SizedBox(
+ width: prefixWidth,
+ child: Text(
+ row.hint == null ? 'click' : 'press',
+ ),
),
- ),
- SizedBox(
- width: keyWidth,
- child: Text(
- row.hint ?? row.label,
- style: TextStyle(color: accent),
- textAlign: TextAlign.left,
+ SizedBox(
+ width: keyWidth,
+ child: Text(
+ row.hint ?? row.label,
+ style: TextStyle(color: accent),
+ textAlign: TextAlign.left,
+ ),
),
- ),
- Expanded(
- child: Text(
- row.description,
- textAlign: TextAlign.left,
+ Expanded(
+ child: Text(
+ row.description,
+ textAlign: TextAlign.left,
+ ),
),
- ),
- ],
+ ],
+ ),
),
- ),
- ],
+ ],
+ ),
),
),
),
@@ -171,7 +255,7 @@ class WorkspaceWelcome extends StatelessWidget {
bottom: 16,
child: TextButton.icon(
key: const ValueKey('welcome-customize'),
- onPressed: () => onCommand('app.customize'),
+ onPressed: () => widget.onCommand('app.customize'),
icon: const Icon(Icons.edit_outlined, size: 18),
label: const Text('Customize Harness'),
style: TextButton.styleFrom(
diff --git a/desktop/macos/Runner/SwarmTitlebar.swift b/desktop/macos/Runner/SwarmTitlebar.swift
index 5fb703648..8772b9687 100644
--- a/desktop/macos/Runner/SwarmTitlebar.swift
+++ b/desktop/macos/Runner/SwarmTitlebar.swift
@@ -166,6 +166,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
// Mouse controls teach the effective shortcuts, including user remaps.
strip.newButton.toolTip = "New Tab " + (map.hint(for: "swarm.new", context: "workspace") ?? "")
strip.machinesButton.toolTip = "Machines " + (map.hint(for: "machines.list", context: "workspace") ?? "")
+ strip.modelsButton.toolTip = "Models " + (map.hint(for: "models.list", context: "workspace") ?? "")
strip.storeButton.toolTip = "Harness Store " + (map.hint(for: "app.store", context: "workspace") ?? "")
if let main = NSApp.mainMenu, let window {
let menu = main as? HarnessKeymapMenu ?? HarnessKeymapMenu.replacing(main)
@@ -1535,7 +1536,6 @@ private final class SwarmTabStrip: NSView {
modelsButton.isEnabled = actionsEnabled
modelsButton.state = state["modelsOpen"] as? Bool == true ? .on : .off
modelsButton.attention = max(0, state["modelNotices"] as? Int ?? 0)
- modelsButton.toolTip = "Models"
let modelExpanded = modelsButton.state == .on ? "Expanded" : "Collapsed"
modelsButton.setAccessibilityValue(modelsButton.attention > 0
? "\(modelExpanded), \(modelsButton.attention) \(modelsButton.attention == 1 ? "model" : "models") ready to use" : modelExpanded)
diff --git a/desktop/test/keymap_host_test.dart b/desktop/test/keymap_host_test.dart
index 1dc976444..af58046b8 100644
--- a/desktop/test/keymap_host_test.dart
+++ b/desktop/test/keymap_host_test.dart
@@ -77,6 +77,7 @@ void main() {
('cmd+shift+j', 'navigation.command_bar'),
('cmd+s', 'app.store'),
('cmd+m', 'machines.list'),
+ ('cmd+i', 'models.list'),
('cmd+shift+l', 'pane.layout'),
('cmd+b', 'task.route'),
('cmd+shift+w', 'pane.close'),
diff --git a/desktop/test/machines_panel_test.dart b/desktop/test/machines_panel_test.dart
index 312095d98..9994b8ded 100644
--- a/desktop/test/machines_panel_test.dart
+++ b/desktop/test/machines_panel_test.dart
@@ -17,6 +17,7 @@ import 'package:harness/shared/theme/app_theme.dart' as grid;
import 'package:harness/shortcuts/app_keymap.dart';
import 'package:harness/shortcuts/keymap_host.dart';
import 'package:harness/state/app_state.dart';
+import 'package:harness/state/workspace_onboarding.dart';
import 'package:harness/widgets/machines_panel.dart';
import 'package:harness/widgets/toolbar_icon.dart';
import 'package:harness/widgets/workspace_welcome.dart';
@@ -1119,12 +1120,23 @@ void main() {
) async {
final map = MemoryKeymap();
addTearDown(map.dispose);
+ final onboarding = WorkspaceOnboarding();
+ addTearDown(onboarding.dispose);
+ onboarding.sync(
+ scope: 'welcome-test',
+ observed: {},
+ otherComputer: false,
+ modelsAvailable: true,
+ );
final commands = <String>[];
await tester.pumpWidget(
MaterialApp(
home: KeymapProvider(
keymap: map,
- child: WorkspaceWelcome(onCommand: commands.add),
+ child: WorkspaceWelcome(
+ onboarding: onboarding,
+ onCommand: commands.add,
+ ),
),
),
);
diff --git a/desktop/test/terminal_ui_typography_test.dart b/desktop/test/terminal_ui_typography_test.dart
index 165cd935a..d72fefa92 100644
--- a/desktop/test/terminal_ui_typography_test.dart
+++ b/desktop/test/terminal_ui_typography_test.dart
@@ -129,10 +129,10 @@ void main() {
/// The welcome page is terminal text: the terminal's face at its size.
void checkWelcome(WidgetTester tester) {
- final line = tester.widget<Text>(find.text('Follow your curiosity.'));
- final style = DefaultTextStyle.of(
- tester.element(find.text('Follow your curiosity.')),
- ).style.merge(line.style);
+ final tagline = find.byKey(const ValueKey('welcome-tagline'));
+ final line = tester.widget<Text>(tagline);
+ final style = DefaultTextStyle.of(tester.element(tagline)).style
+ .merge(line.style);
expect(style.fontSize, terminalFontStore.size);
expect(style.fontFamily, terminalFontStore.value.fontFamily);
}
diff --git a/desktop/test/toolbar_onboarding_test.dart b/desktop/test/toolbar_onboarding_test.dart
index f26e87787..4e3fc3c09 100644
--- a/desktop/test/toolbar_onboarding_test.dart
+++ b/desktop/test/toolbar_onboarding_test.dart
@@ -6,15 +6,17 @@ import 'package:harness/core/models.dart';
import 'package:harness/models/models_panel.dart';
import 'package:harness/screens/swarm_screen.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shortcuts/app_keymap.dart';
import 'package:harness/state/app_state.dart';
import 'package:harness/state/new_harness.dart';
import 'package:harness/state/workspace_onboarding.dart';
import 'package:harness/widgets/new_harness_form.dart';
import 'package:harness/widgets/onboarding_card.dart';
-import 'keymap_host_test.dart' show key;
+import 'keymap_host_test.dart' show MemoryKeymap, key;
import 'support/model_manager.dart';
import 'swarm_screen_test.dart' show terminal;
+import 'swarm_state_test.dart' show MemoryStore;
class _App extends ModelManagerTestApp {
_App() : super(ModelManagerConnection()) {
@@ -69,17 +71,25 @@ void main() {
app.dispose();
journey.dispose();
});
- Future<void> mount(WidgetTester tester) async {
- journey = WorkspaceOnboarding();
+ Future<void> mount(
+ WidgetTester tester, {
+ AppKeymap? keymap,
+ bool native = false,
+ MemoryStore? storage,
+ }) async {
+ journey = WorkspaceOnboarding(storage: storage);
tester.view.devicePixelRatio = 1;
tester.view.physicalSize = const Size(1280, 800);
addTearDown(tester.view.reset);
await tester.pumpWidget(
MaterialApp(
theme: grid.buildAppTheme(brightness: Brightness.dark),
+ builder: (context, child) => keymap == null
+ ? child!
+ : KeymapProvider(keymap: keymap, child: child!),
home: SwarmScreen(
notifier: app,
- nativeTabs: false,
+ nativeTabs: native,
onboarding: journey,
),
),
@@ -104,6 +114,255 @@ void main() {
app.adoptSessionForTest(terminal('work', []));
}
+ for (var completed = 1; completed <= 3; completed++) {
+ testWidgets(
+ 'returning welcome restores $completed completed steps with working actions',
+ (tester) async {
+ final storage = MemoryStore();
+ final previous = WorkspaceOnboarding(storage: storage);
+ previous.sync(
+ scope: 'account:[email protected]',
+ observed: OnboardingStep.values.take(completed).toSet(),
+ otherComputer: false,
+ modelsAvailable: true,
+ );
+ await tester.pump();
+ expect(previous.loaded, isTrue);
+ await previous.flush();
+ previous.dispose();
+
+ // A new tracker and screen restore only saved history; no harnesses
+ // are open to supply these milestones again.
+ await mount(tester, storage: storage);
+ expect(app.allPanes, isEmpty);
+ expect(journey.scope, 'account:[email protected]');
+ expect(
+ OnboardingStep.values.where(journey.completed),
+ OnboardingStep.values.take(completed),
+ );
+ if (completed < 3) {
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ for (final (index, step) in OnboardingStep.values.indexed) {
+ expect(
+ tester
+ .widget<Text>(
+ find.byKey(ValueKey('welcome-progress-${step.name}')),
+ )
+ .data,
+ index < completed ? '✓' : '○',
+ );
+ }
+ } else {
+ expect(find.text('Follow your curiosity.'), findsOneWidget);
+ expect(find.text('○'), findsNothing);
+ expect(find.text('✓'), findsNothing);
+ }
+
+ final destinations = completed < 3
+ ? ['agent.new', 'machines.list', 'models.list']
+ : ['agent.new', 'agent.open', 'app.store'];
+ for (final command in destinations) {
+ await tap(tester, find.byKey(ValueKey('welcome-$command')));
+ switch (command) {
+ case 'agent.new':
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ case 'machines.list':
+ expect(
+ find.byKey(const ValueKey('machines-panel')),
+ findsOneWidget,
+ );
+ case 'models.list':
+ expect(find.byType(ModelsPanel), findsOneWidget);
+ case 'agent.open':
+ expect(
+ find.byKey(const ValueKey('swarm-search-input')),
+ findsOneWidget,
+ );
+ case 'app.store':
+ expect(app.activeSwarm.isStore, isTrue);
+ }
+ if (command == 'app.store') {
+ await key(tester, LogicalKeyboardKey.keyT, cmd: true);
+ } else {
+ await key(tester, LogicalKeyboardKey.escape);
+ }
+ await tester.pumpAndSettle();
+ }
+ for (final shortcut in [
+ LogicalKeyboardKey.keyN,
+ if (completed == 3) ...[
+ LogicalKeyboardKey.keyO,
+ LogicalKeyboardKey.keyS,
+ ],
+ LogicalKeyboardKey.keyM,
+ LogicalKeyboardKey.keyI,
+ ]) {
+ await key(tester, shortcut, cmd: true);
+ await tester.pumpAndSettle();
+ if (shortcut == LogicalKeyboardKey.keyN) {
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ } else if (shortcut == LogicalKeyboardKey.keyO) {
+ expect(
+ find.byKey(const ValueKey('swarm-search-input')),
+ findsOneWidget,
+ );
+ } else if (shortcut == LogicalKeyboardKey.keyS) {
+ expect(app.activeSwarm.isStore, isTrue);
+ } else if (shortcut == LogicalKeyboardKey.keyM) {
+ expect(
+ find.byKey(const ValueKey('machines-panel')),
+ findsOneWidget,
+ );
+ } else {
+ expect(find.byType(ModelsPanel), findsOneWidget);
+ }
+ await key(
+ tester,
+ shortcut == LogicalKeyboardKey.keyS
+ ? LogicalKeyboardKey.keyT
+ : LogicalKeyboardKey.escape,
+ cmd: shortcut == LogicalKeyboardKey.keyS,
+ );
+ await tester.pumpAndSettle();
+ }
+ expect(
+ OnboardingStep.values.where(journey.completed),
+ OnboardingStep.values.take(completed),
+ reason:
+ 'Opening or cancelling actions must not change saved progress.',
+ );
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+ }
+
+ for (final native in [false, true]) {
+ testWidgets(
+ 'welcome clicks and keyboard open real panels (native=$native)',
+ (tester) async {
+ await mount(tester, native: native);
+ final models = find.byType(ModelsPanel);
+ final machines = find.byKey(const ValueKey('machines-panel'));
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ expect(models, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ expect(models, findsNothing);
+
+ if (!native) {
+ await tap(tester, find.byTooltip('Harnesses'));
+ expect(find.byKey(const ValueKey('session-manager')), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('session-manager')), findsNothing);
+ expect(models, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ }
+
+ await tap(tester, find.byKey(const ValueKey('welcome-models.list')));
+ expect(models, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyM, cmd: true);
+ await tester.pumpAndSettle();
+ expect(models, findsNothing);
+ expect(machines, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ expect(machines, findsNothing);
+ expect(models, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyN, cmd: true);
+ await tester.pumpAndSettle();
+ expect(models, findsNothing);
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ await tap(tester, find.byKey(const ValueKey('welcome-machines.list')));
+ expect(machines, findsOneWidget);
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ await tap(tester, find.byKey(const ValueKey('welcome-agent.new')));
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ expect(OnboardingStep.values.any(journey.completed), isFalse);
+ expect(app.actions, isEmpty);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+ }
+
+ testWidgets('Models shortcut, welcome hint and toolbar follow a live remap', (
+ tester,
+ ) async {
+ final map = MemoryKeymap();
+ addTearDown(map.dispose);
+ await mount(tester, keymap: map);
+ expect(find.byTooltip('Models ⌘I'), findsOneWidget);
+ map.apply('''{"bindings":[
+ {"keys":"cmd+i","command":null},
+ {"keys":"cmd+u","command":"models.list"}
+ ]}''');
+ await tester.pumpAndSettle();
+ expect(find.byTooltip('Models ⌘U'), findsOneWidget);
+ expect(find.text('⌘U'), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ expect(find.byType(ModelsPanel), findsNothing);
+ await key(tester, LogicalKeyboardKey.keyU, cmd: true);
+ await tester.pumpAndSettle();
+ expect(find.byType(ModelsPanel), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ await key(tester, LogicalKeyboardKey.keyP, cmd: true);
+ await tester.enterText(
+ find.byKey(const ValueKey('swarm-search-input')),
+ '> Open Models',
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('Open Models'), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(find.byType(ModelsPanel), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ });
+
+ testWidgets(
+ 'completed welcome switches on New Tab and everyday clicks open their destinations',
+ (tester) async {
+ await mount(tester);
+ journey.sync(
+ scope: journey.scope!,
+ observed: OnboardingStep.values.toSet(),
+ otherComputer: true,
+ modelsAvailable: true,
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('✓'), findsNWidgets(3));
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.keyT, cmd: true);
+ await tester.pumpAndSettle();
+ expect(find.text('Follow your curiosity.'), findsOneWidget);
+ expect(find.text('✓'), findsNothing);
+ await tap(tester, find.byKey(const ValueKey('welcome-agent.open')));
+ expect(find.byKey(const ValueKey('swarm-search-input')), findsOneWidget);
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ await tap(tester, find.byKey(const ValueKey('welcome-app.store')));
+ expect(app.activeSwarm.isStore, isTrue);
+ await key(tester, LogicalKeyboardKey.keyT, cmd: true);
+ await tester.pumpAndSettle();
+ await key(tester, LogicalKeyboardKey.keyS, cmd: true);
+ await tester.pumpAndSettle();
+ expect(app.activeSwarm.isStore, isTrue);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ expect(find.byType(ModelsPanel), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+
testWidgets(
'first invitation opens real creation and survives merely viewing',
(tester) async {
diff --git a/desktop/test/workspace_start_guide_test.dart b/desktop/test/workspace_start_guide_test.dart
index 038fb1230..1daed26bd 100644
--- a/desktop/test/workspace_start_guide_test.dart
+++ b/desktop/test/workspace_start_guide_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
import 'dart:io';
import 'package:flutter/material.dart';
@@ -18,14 +19,18 @@ import 'package:harness/state/app_state.dart';
import 'package:harness/state/harness_placement.dart';
import 'package:harness/state/new_harness.dart';
import 'package:harness/state/pane_arrangement.dart';
+import 'package:harness/state/workspace_onboarding.dart';
+import 'package:harness/terminal/terminal_binary.dart';
import 'package:harness/widgets/new_harness_form.dart';
import 'package:harness/widgets/harness_customize_pane.dart';
import 'package:harness/settings/appearance/wallpaper_section.dart';
import 'package:harness/widgets/workspace_start_guide.dart';
import 'package:harness/widgets/workspace_welcome.dart';
+import 'package:harness/ws/local_cli_discovery.dart';
import 'package:xterm/xterm.dart';
import 'keymap_host_test.dart' show MemoryKeymap, key;
+import 'support/launch_menu.dart';
import 'swarm_screen_test.dart' show terminal;
class _FirstApp extends AppNotifier {
@@ -44,10 +49,18 @@ class _FirstApp extends AppNotifier {
machines = [local];
machineStates['m'] = MachineState(local)
..localOnly = true
+ ..localEndpoint = LocalCliEndpoint(
+ computerId: 'test-computer',
+ wsUri: Uri.parse('ws://fixture.invalid'),
+ protocolVersion: 1,
+ terminalProtocolVersion: 3,
+ )
..nodeOnline = true
..agentLoadStatus = AgentLoadStatus.loaded;
}
List<String> installed = ['codex'];
+ Completer<String?>? creation;
+ final input = <TerminalBinaryFrame>[];
final launches =
<
({
@@ -98,7 +111,18 @@ class _FirstApp extends AppNotifier {
project: projectFolder,
placement: placement,
));
- adoptSessionForTest(terminal('first', []));
+ final failure = await creation?.future;
+ if (failure != null) return failure;
+ machineStates[machineId]!.agents = [
+ Agent(
+ id: 'first',
+ name: 'First harness',
+ engine: engine,
+ terminalAvailable: true,
+ ),
+ ];
+ adoptSessionForTest(terminal('first', input)..engineId = engine);
+ notifyListeners();
return null;
}
}
@@ -107,6 +131,7 @@ Future<void> _mount(
WidgetTester tester,
_FirstApp app, {
bool nativeTabs = false,
+ WorkspaceOnboarding? onboarding,
}) async {
tester.view.devicePixelRatio = 1;
tester.view.physicalSize = const Size(1280, 800);
@@ -115,7 +140,11 @@ Future<void> _mount(
await tester.pumpWidget(
MaterialApp(
theme: grid.buildAppTheme(brightness: Brightness.dark),
- home: SwarmScreen(notifier: app, nativeTabs: nativeTabs),
+ home: SwarmScreen(
+ notifier: app,
+ nativeTabs: nativeTabs,
+ onboarding: onboarding,
+ ),
),
);
await tester.pump();
@@ -128,6 +157,123 @@ void main() {
});
tearDown(() => newHarnessOpensInBox = false);
+ for (final keyboard in [false, true]) {
+ testWidgets(
+ 'first welcome starts one usable harness and records progress (keyboard=$keyboard)',
+ (tester) async {
+ final app = _FirstApp()
+ ..installed = keyboard ? [] : ['claude', 'codex'];
+ final journey = WorkspaceOnboarding();
+ addTearDown(app.dispose);
+ addTearDown(journey.dispose);
+ await _mount(tester, app, onboarding: journey);
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ expect(find.text('○'), findsNWidgets(3));
+ expect(app.panes, isEmpty);
+
+ if (keyboard) {
+ await key(tester, LogicalKeyboardKey.keyN, cmd: true);
+ } else {
+ await tester.tap(find.byKey(const ValueKey('welcome-agent.new')));
+ }
+ await tester.pumpAndSettle();
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ expect(app.launches, isEmpty);
+ expect(journey.completed(OnboardingStep.harnesses), isFalse);
+ if (keyboard) {
+ await startHarness(tester);
+ } else {
+ await tester.tap(
+ find.byKey(const ValueKey('new-harness-field-start')),
+ );
+ }
+ await tester.pumpAndSettle();
+ expect(app.launches, hasLength(1));
+ expect(app.launches.single.project?.isGenerated, isTrue);
+ expect(find.byType(NewHarnessForm), findsNothing);
+ expect(find.byType(TerminalView), findsOneWidget);
+ expect(
+ tester.widget<TerminalView>(find.byType(TerminalView)).readOnly,
+ isFalse,
+ );
+ expect(app.focusedPane?.session?.acceptsInput, isTrue);
+ expect(journey.completed(OnboardingStep.harnesses), isTrue);
+ expect(journey.completed(OnboardingStep.machines), isFalse);
+ expect(journey.completed(OnboardingStep.models), isFalse);
+ expect(app.input, isEmpty);
+ // The launch action must hand focus to the terminal without a click.
+ expect(
+ tester
+ .widget<TerminalView>(find.byType(TerminalView))
+ .focusNode!
+ .hasFocus,
+ isTrue,
+ );
+ expect(tester.testTextInput.hasAnyClients, isTrue);
+ tester.testTextInput.enterText('h');
+ await tester.pump();
+ expect(app.input.single.bytes, [104]);
+
+ await key(tester, LogicalKeyboardKey.keyT, cmd: true);
+ await tester.pumpAndSettle();
+ expect(find.byType(WorkspaceWelcome), findsOneWidget);
+ expect(find.text('✓'), findsOneWidget);
+ expect(find.text('○'), findsNWidgets(2));
+ expect(app.launches, hasLength(1));
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+ }
+
+ testWidgets('a failed first start stays actionable and retries once', (
+ tester,
+ ) async {
+ final app = _FirstApp()..creation = Completer<String?>();
+ final journey = WorkspaceOnboarding();
+ addTearDown(app.dispose);
+ addTearDown(journey.dispose);
+ await _mount(tester, app, onboarding: journey);
+ await key(tester, LogicalKeyboardKey.keyN, cmd: true);
+ await tester.pumpAndSettle();
+ final start = find.byKey(const ValueKey('new-harness-field-start'));
+ await startHarness(tester);
+ await tester.pump();
+ expect(find.text('Starting harness…'), findsOneWidget);
+ await tester.tap(start);
+ await key(tester, LogicalKeyboardKey.enter);
+ expect(app.launches, hasLength(1));
+ expect(app.panes, isEmpty);
+ expect(journey.completed(OnboardingStep.harnesses), isFalse);
+
+ app.creation!.complete('Could not start the harness. Try again.');
+ await tester.pumpAndSettle();
+ expect(
+ find.text('Could not start the harness. Try again.'),
+ findsOneWidget,
+ );
+ expect(find.byType(NewHarnessForm), findsOneWidget);
+ expect(journey.completed(OnboardingStep.harnesses), isFalse);
+ final project = app.launches.single.project;
+ await key(tester, LogicalKeyboardKey.escape);
+ await tester.pumpAndSettle();
+ expect(find.byType(NewHarnessForm), findsNothing);
+ expect(find.text('○'), findsNWidgets(3));
+
+ await tester.tap(find.byKey(const ValueKey('welcome-agent.new')));
+ await tester.pumpAndSettle();
+ app.creation = null;
+ await tester.tap(start);
+ await tester.pumpAndSettle();
+ expect(app.launches, hasLength(2));
+ expect(app.launches.last.project?.name, project?.name);
+ expect(find.byType(NewHarnessForm), findsNothing);
+ expect(find.byType(TerminalView), findsOneWidget);
+ expect(journey.completed(OnboardingStep.harnesses), isTrue);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ });
+
testWidgets('welcome and New Tab stay quiet until an action is chosen', (
tester,
) async {
@@ -136,7 +282,7 @@ void main() {
await _mount(tester, app);
final search = find.byKey(const ValueKey('swarm-search-input'));
expect(find.byType(WorkspaceWelcome), findsOneWidget);
- expect(find.text('Follow your curiosity.'), findsOneWidget);
+ expect(find.text('Harness like a boss.'), findsOneWidget);
expect(find.byType(NewHarnessForm), findsNothing);
expect(search, findsNothing);
await key(tester, LogicalKeyboardKey.keyN, cmd: true);
@@ -146,9 +292,9 @@ void main() {
await key(tester, LogicalKeyboardKey.keyT, cmd: true);
final tab = app.activeSwarmId;
expect(find.byType(WorkspaceWelcome), findsOneWidget);
- expect(find.text('Follow your curiosity.'), findsOneWidget);
+ expect(find.text('Harness like a boss.'), findsOneWidget);
expect(search, findsNothing);
- await tester.tap(find.byKey(const ValueKey('welcome-agent.open')));
+ await key(tester, LogicalKeyboardKey.keyO, cmd: true);
await tester.pump();
expect(search, findsOneWidget);
await key(tester, LogicalKeyboardKey.escape);
diff --git a/desktop/test/workspace_welcome_test.dart b/desktop/test/workspace_welcome_test.dart
new file mode 100644
index 000000000..296faa115
--- /dev/null
+++ b/desktop/test/workspace_welcome_test.dart
@@ -0,0 +1,258 @@
+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/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shortcuts/app_keymap.dart';
+import 'package:harness/state/workspace_onboarding.dart';
+import 'package:harness/terminal/terminal_text.dart';
+import 'package:harness/widgets/workspace_welcome.dart';
+import 'package:xterm/xterm.dart';
+
+import 'keymap_host_test.dart' show MemoryKeymap;
+import 'support/real_fonts.dart';
+import 'swarm_state_test.dart' show MemoryStore;
+
+class _HeldStore extends MemoryStore {
+ final reads = <String, Completer<String?>>{};
+ @override
+ Future<String?> read(String key) =>
+ (reads[key] = Completer<String?>()).future;
+}
+
+void main() {
+ late WorkspaceOnboarding journey;
+ late MemoryKeymap keymap;
+ late TerminalStyle savedFont;
+ late Brightness savedBrightness;
+ final commands = <String>[];
+ final boundary = GlobalKey();
+
+ setUpAll(() async {
+ if (Platform.isMacOS) {
+ final bytes = await File('/System/Library/Fonts/Menlo.ttc').readAsBytes();
+ await (FontLoader(
+ 'Menlo',
+ )..addFont(Future.value(ByteData.sublistView(bytes)))).load();
+ } else {
+ await loadRealFonts();
+ }
+ await (FontLoader(
+ 'MaterialIcons',
+ )..addFont(rootBundle.load('fonts/MaterialIcons-Regular.otf'))).load();
+ });
+ setUp(() {
+ keymap = MemoryKeymap();
+ commands.clear();
+ savedFont = terminalFontStore.value;
+ savedBrightness = grid.AppTheme.brightness.value;
+ terminalFontStore.value = const TerminalStyle(
+ fontFamily: 'Menlo',
+ fontSize: 18,
+ );
+ });
+ tearDown(() {
+ journey.dispose();
+ keymap.dispose();
+ terminalFontStore.value = savedFont;
+ grid.AppTheme.brightness.value = savedBrightness;
+ });
+
+ void observe(Set<OnboardingStep> steps, {String scope = 'review'}) {
+ journey.sync(
+ scope: scope,
+ observed: steps,
+ otherComputer: false,
+ modelsAvailable: true,
+ );
+ }
+
+ Future<void> mount(
+ WidgetTester tester, {
+ String tab = 'first',
+ Size size = const Size(1120, 700),
+ double scale = 1,
+ Brightness brightness = Brightness.dark,
+ }) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = size;
+ addTearDown(tester.view.reset);
+ grid.AppTheme.brightness.value = brightness;
+ await tester.pumpWidget(
+ MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: brightness),
+ builder: (context, child) => KeymapProvider(
+ keymap: keymap,
+ child: MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(textScaler: TextScaler.linear(scale)),
+ child: child!,
+ ),
+ ),
+ home: RepaintBoundary(
+ key: boundary,
+ child: WorkspaceWelcome(
+ key: ValueKey(tab),
+ onboarding: journey,
+ onCommand: commands.add,
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ expect(tester.takeException(), isNull);
+ }
+
+ Future<void> capture(WidgetTester tester, String name) async {
+ final directory = Platform.environment['HARNESS_WELCOME_CAPTURE_DIR'];
+ if (directory == null) return;
+ await tester.runAsync(() async {
+ final image =
+ await (boundary.currentContext!.findRenderObject()
+ as RenderRepaintBoundary)
+ .toImage();
+ 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();
+ });
+ }
+
+ testWidgets('actual progress stays visible until the next new tab', (
+ tester,
+ ) async {
+ journey = WorkspaceOnboarding();
+ observe({});
+ await mount(tester);
+ expect(find.text('HARNESS'), findsNothing);
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ expect(find.text('○'), findsNWidgets(3));
+ for (final hint in ['⌘N', '⌘M', '⌘I']) {
+ expect(find.text(hint), findsOneWidget);
+ }
+ await capture(tester, 'new-tab-first');
+ for (final command in ['agent.new', 'machines.list', 'models.list']) {
+ await tester.tap(find.byKey(ValueKey('welcome-$command')));
+ }
+ expect(commands, ['agent.new', 'machines.list', 'models.list']);
+ journey.acknowledge(OnboardingStep.harnesses);
+ await tester.pump();
+ expect(find.text('✓'), findsNothing);
+ observe({OnboardingStep.harnesses});
+ await tester.pump();
+ expect(find.text('✓'), findsOneWidget);
+ expect(find.text('○'), findsNWidgets(2));
+ await capture(tester, 'new-tab-progress');
+ observe({OnboardingStep.machines, OnboardingStep.models});
+ await tester.pump();
+ expect(find.text('✓'), findsNWidgets(3));
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ await capture(tester, 'new-tab-completed');
+
+ // A regular rebuild does not remove the user's last check.
+ await mount(tester);
+ expect(find.text('✓'), findsNWidgets(3));
+ await mount(tester, tab: 'next');
+ expect(find.text('Follow your curiosity.'), findsOneWidget);
+ expect(find.text('✓'), findsNothing);
+ expect(find.text('○'), findsNothing);
+ for (final hint in ['⌘N', '⌘O', '⌘S']) {
+ expect(find.text(hint), findsOneWidget);
+ }
+ commands.clear();
+ for (final command in ['agent.new', 'agent.open', 'app.store']) {
+ await tester.tap(find.byKey(ValueKey('welcome-$command')));
+ }
+ expect(commands, ['agent.new', 'agent.open', 'app.store']);
+ await capture(tester, 'new-tab-everyday');
+ });
+
+ testWidgets(
+ 'saved progress loads before choosing the visit and stays account scoped',
+ (tester) async {
+ final storage = _HeldStore();
+ journey = WorkspaceOnboarding(storage: storage);
+ observe({});
+ await mount(tester);
+ storage.reads[WorkspaceOnboarding.storageKey('review')]!.complete(
+ '{"completed":["harnesses","machines","models"]}',
+ );
+ await tester.pumpAndSettle();
+ expect(find.text('Follow your curiosity.'), findsOneWidget);
+
+ observe({}, scope: 'another-account');
+ await tester.pump();
+ expect(find.text('✓'), findsNothing);
+ storage.reads[WorkspaceOnboarding.storageKey('another-account')]!
+ .complete('{"completed":["harnesses"]}');
+ await tester.pumpAndSettle();
+ expect(find.text('Harness like a boss.'), findsOneWidget);
+ expect(find.text('✓'), findsOneWidget);
+ expect(find.text('○'), findsNWidgets(2));
+ },
+ );
+
+ testWidgets('live remaps and unbinding keep the displayed actions honest', (
+ tester,
+ ) async {
+ journey = WorkspaceOnboarding();
+ observe({});
+ await mount(tester);
+ keymap.apply('''{"bindings":[
+ {"keys":"cmd+i","command":null},
+ {"keys":"cmd+u","command":"models.list"}
+ ]}''');
+ await tester.pump();
+ expect(find.text('⌘I'), findsNothing);
+ expect(find.text('⌘U'), findsOneWidget);
+ await tester.tap(find.byKey(const ValueKey('welcome-models.list')));
+ expect(commands, ['models.list']);
+
+ keymap.apply('{"bindings":[{"keys":"cmd+i","command":null}]}');
+ await tester.pump();
+ expect(find.text('click'), findsOneWidget);
+ expect(find.text('Models'), findsOneWidget);
+ await tester.tap(find.byKey(const ValueKey('welcome-models.list')));
+ expect(commands, ['models.list', 'models.list']);
+ expect(tester.takeException(), isNull);
+ });
+
+ for (final brightness in Brightness.values) {
+ testWidgets(
+ 'onboarding fits a narrow window with large text ($brightness)',
+ (tester) async {
+ journey = WorkspaceOnboarding();
+ observe({OnboardingStep.harnesses});
+ await mount(
+ tester,
+ size: const Size(600, 500),
+ scale: 1.7,
+ brightness: brightness,
+ );
+ expect(find.text('✓'), findsOneWidget);
+ for (final command in ['agent.new', 'machines.list', 'models.list']) {
+ final row = find.byKey(ValueKey('welcome-$command'));
+ await tester.ensureVisible(row);
+ await tester.pumpAndSettle();
+ expect(row.hitTestable(), findsOneWidget);
+ await tester.tap(row);
+ }
+ expect(commands, ['agent.new', 'machines.list', 'models.list']);
+ final scroll = tester.getRect(
+ find.byKey(const ValueKey('welcome-scroll')),
+ );
+ final customize = tester.getRect(
+ find.byKey(const ValueKey('welcome-customize')),
+ );
+ expect(scroll.bottom, lessThan(customize.top));
+ await capture(tester, 'new-tab-narrow-${brightness.name}');
+ },
+ );
+ }
+}
diff --git a/desktop/tool/keymap_native_checks.swift b/desktop/tool/keymap_native_checks.swift
index 0c766ea7f..113d6453a 100644
--- a/desktop/tool/keymap_native_checks.swift
+++ b/desktop/tool/keymap_native_checks.swift
@@ -31,6 +31,7 @@ for (key, command) in [
("cmd+r", "pane.split_right"), ("cmd+d", "pane.split_down"),
("cmd+n", "agent.new"),
("cmd+m", "machines.list"),
+ ("cmd+i", "models.list"),
("cmd+h", "pane.focus_left"), ("cmd+j", "pane.focus_below"),
("cmd+k", "pane.focus_above"), ("cmd+l", "pane.focus_right"),
] {
@@ -46,6 +47,9 @@ try checkKeymap(defaults.viewerOrchestratorCommand(stroke("cmd+p")) == nil,
for context in HarnessNativeKeymap.contexts {
try checkKeymap(defaults.match([stroke("cmd+m")], context: context).binding?.command == "machines.list",
"Command-M opens Machines from \(context)")
+ let models = defaults.match([stroke("cmd+i")], context: context).binding
+ try checkKeymap(models?.command == "models.list" && models?.menuAction == "models" && models?.hint == "⌘I",
+ "Command-I opens Models with the matching native action and hint from \(context)")
try checkKeymap(defaults.match([stroke("cmd+u")], context: context).binding == nil,
"The former Machines shortcut is unbound")
try checkKeymap(defaults.match([stroke("cmd+shift+p")], context: context).binding == nil,
@@ -74,8 +78,8 @@ try checkKeymap(changed.match([stroke("down")], context: "picker").binding == ni
"Picker unbinding removes the original arrow action")
try checkKeymap(changed.match([stroke("ctrl+j")], context: "picker").binding?.command == "picker.previous",
"Picker remapping wins")
-try checkKeymap(defaults.match([stroke("cmd+i")], context: "picker").binding == nil,
- "Always-on preview does not consume a hide-preview shortcut")
+try checkKeymap(defaults.match([stroke("ctrl+slash")], context: "picker").binding?.command == "picker.toggle_preview",
+ "Preview visibility stays on Control-/ while Command-I opens Models")
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")
diff --git a/desktop/tool/swarm_titlebar_checks.swift b/desktop/tool/swarm_titlebar_checks.swift
index 990aa8476..a84c99db1 100644
--- a/desktop/tool/swarm_titlebar_checks.swift
+++ b/desktop/tool/swarm_titlebar_checks.swift
@@ -587,6 +587,10 @@ private extension SwarmTitlebar {
try checkTitlebar(!main.defersToInput(event("p", 35, [.command, .shift])), "Command-Shift-P is unbound")
try checkTitlebar(main.defersToInput(event("o", 31, .command)), "Command-O reaches Open Harness")
try checkTitlebar(strip.machinesButton.toolTip == "Machines ⌘M", "Machines advertises its effective shortcut")
+ try checkTitlebar(strip.modelsButton.toolTip == "Models ⌘I", "Models advertises its effective shortcut")
+ try checkTitlebar(main.defersToInput(event("i", 34, .command)) &&
+ !main.performKeyEquivalent(with: event("i", 34, .command)),
+ "Command-I reaches Flutter exactly once")
try checkTitlebar(main.defersToInput(event("m", 46, .command)) &&
!main.performKeyEquivalent(with: event("m", 46, .command)),
"Command-M reaches Flutter exactly once instead of invoking a native window action")
diff --git a/docs/keyboard.md b/docs/keyboard.md
index b1777c24d..061c5a37a 100644
--- a/docs/keyboard.md
+++ b/docs/keyboard.md
@@ -23,11 +23,18 @@ The defaults, in the workspace:
| ⇧⌘arrows | Move the focused pane |
| ⌘⏎ · ⌘; · ⇧⌘W | Zoom or restore · last pane · close pane |
| ⌘S | Harness Store |
+| ⌘M | Machines — connect another computer or set this computer's password |
+| ⌘I | Models — subscriptions, local models, shared models, and APIs |
| ⇧⌘L | Layout palette |
| ⌘F · ⌘G · ⇧⌘G | Find in terminal · next · previous match |
| ⇧⌘I | Agents needing input |
| ⌘, · ⌘/ | Settings · keyboard shortcuts |
+New Tab starts with three clickable shortcuts: ⌘N to start your first harness,
+⌘M to manage it from another computer, and ⌘I to power it with a local model.
+Checkmarks record actual use and persist per account on this device. After all
+three are complete, the next New Tab shows the everyday ⌘N, ⌘O, and ⌘S shortcuts.
+
In the harness picker, New agent is selected when the query is empty. Typing selects the best matching existing harness; the creation row stays pinned above it and carries the query into the first task. Projects and machines filter individual harnesses rather than opening whole groups. The destination is shown in the picker and carried into creation. A harness can have views in several tabs, with one view per tab; closing a pane only removes that view.
Hover near a pane’s right or bottom edge to reveal its **+** button, or use **File → Split Right… / Split Down…**. The picker shows **New Pane to the Right** or **New Pane Below**. The split is applied after choosing or creating a harness; Escape leaves the layout unchanged.