diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index f3a52b45..b5da416b 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -28,6 +28,8 @@ import '../features/runs/ui/run_search_selection.dart'; import '../features/search/domain/search_target.dart'; import '../features/settings/settings_screen.dart'; import '../features/settings/settings_store.dart'; +import '../features/walkthrough/walkthrough_gate.dart'; +import '../features/walkthrough/walkthrough_store.dart'; import '../features/updates/app_updates.dart'; import '../features/updates/launch_update.dart'; import '../features/updates/launch_update_dialog.dart'; @@ -579,6 +581,10 @@ class _PipelinesAppState extends State _attentionCount.value = count; } + /// The device's first-run walkthrough record (per device, not per server). + final WalkthroughStore _walkthroughStore = + const SharedPreferencesWalkthroughStore(); + @override Widget build(BuildContext context) => widget.servers == null ? MyApp.router(routerConfig: _config) @@ -837,32 +843,40 @@ class _PipelinesAppState extends State _bodyRoutes[AppDestination.pipelines] ?? AppRoute.pipelines, ), destinationBodies: { - AppDestination.pipelines: (_) => PipelinesDestination( - session: _session, - server: widget.server, - active: _destinationOf(route.kind) == AppDestination.pipelines, - legacyPendingEndpoints: widget.legacyPendingEndpoints, - refreshToken: _pipelinesRefresh, - onRunStarted: _runStarted, - onViewPipelineRuns: (id) => - _delegate.goTo(AppRoute.runsForPipeline(id)), - onOpenSchedules: _delegate.openSchedules, - onOpenSettings: () => _delegate.goTo(AppRoute.settings), - // The open pipeline is part of the route, so Back steps out of it. - onSelectionChanged: (id) { - final current = _delegate.route; - if (current.kind != AppRouteKind.pipelines) return; - if (id == null) { - if (current.pipelineId != null) { - _delegate.goTo(AppRoute.pipelines); + AppDestination.pipelines: (_) => FirstRunWalkthroughGate( + store: _walkthroughStore, + enabled: _destinationOf(route.kind) == AppDestination.pipelines, + serverScope: _navigationScope, + connection: _session, + connected: () => _session.connected, + gateway: _session.client, + child: PipelinesDestination( + session: _session, + server: widget.server, + active: _destinationOf(route.kind) == AppDestination.pipelines, + legacyPendingEndpoints: widget.legacyPendingEndpoints, + refreshToken: _pipelinesRefresh, + onRunStarted: _runStarted, + onViewPipelineRuns: (id) => + _delegate.goTo(AppRoute.runsForPipeline(id)), + onOpenSchedules: _delegate.openSchedules, + onOpenSettings: () => _delegate.goTo(AppRoute.settings), + // The open pipeline is part of the route, so Back steps out of it. + onSelectionChanged: (id) { + final current = _delegate.route; + if (current.kind != AppRouteKind.pipelines) return; + if (id == null) { + if (current.pipelineId != null) { + _delegate.goTo(AppRoute.pipelines); + } + } else if (current.pipelineId != id) { + _delegate.goTo(AppRoute.pipeline(id)); } - } else if (current.pipelineId != id) { - _delegate.goTo(AppRoute.pipeline(id)); - } - }, - initialPipelineId: pipelinesRoute.pipelineId, - initialVersion: pipelinesRoute.version, - initialStageKey: pipelinesRoute.stageKey, + }, + initialPipelineId: pipelinesRoute.pipelineId, + initialVersion: pipelinesRoute.version, + initialStageKey: pipelinesRoute.stageKey, + ), ), // The one place a field or artifact hit's selection can be resolved: the // run detail owns the recorded visit and Summary section. diff --git a/app/lib/features/settings/settings_keys.dart b/app/lib/features/settings/settings_keys.dart index 337757ff..6c4e868b 100644 --- a/app/lib/features/settings/settings_keys.dart +++ b/app/lib/features/settings/settings_keys.dart @@ -13,4 +13,5 @@ abstract final class SettingsKeys { static const keyboardShortcuts = ValueKey( 'settings.keyboardShortcuts', ); + static const walkthrough = ValueKey('settings.walkthrough'); } diff --git a/app/lib/features/settings/settings_screen.dart b/app/lib/features/settings/settings_screen.dart index 1e63875d..ce8f097b 100644 --- a/app/lib/features/settings/settings_screen.dart +++ b/app/lib/features/settings/settings_screen.dart @@ -37,6 +37,7 @@ import 'server_connections.dart'; import 'saved_servers_section.dart'; import 'managed_connection_section.dart'; import 'settings_keyboard_shortcuts_section.dart'; +import 'settings_walkthrough_section.dart'; part 'settings_topic_pages.dart'; diff --git a/app/lib/features/settings/settings_topic_pages.dart b/app/lib/features/settings/settings_topic_pages.dart index 8d89bd49..7dee4895 100644 --- a/app/lib/features/settings/settings_topic_pages.dart +++ b/app/lib/features/settings/settings_topic_pages.dart @@ -85,7 +85,10 @@ extension _SettingsTopicPages on _SettingsScreenState { SettingsGroup( title: 'Help', leadingRows: true, - children: const [SettingsKeyboardShortcutsSection()], + children: const [ + SettingsKeyboardShortcutsSection(), + SettingsWalkthroughSection(), + ], ), if (widget.onOpenSchedules case final open?) SettingsGroup( diff --git a/app/lib/features/settings/settings_walkthrough_section.dart b/app/lib/features/settings/settings_walkthrough_section.dart new file mode 100644 index 00000000..5d31e398 --- /dev/null +++ b/app/lib/features/settings/settings_walkthrough_section.dart @@ -0,0 +1,23 @@ +import 'package:flutter/material.dart'; + +import '../walkthrough/first_run_walkthrough.dart'; +import 'settings_keys.dart'; +import 'settings_row.dart'; + +/// Reopens the first-run walkthrough. It only shows the walkthrough; it never +/// changes the device's seen record. +class SettingsWalkthroughSection extends StatelessWidget { + const SettingsWalkthroughSection({super.key}); + + @override + Widget build(BuildContext context) => SettingsRow( + key: SettingsKeys.walkthrough, + leading: const Icon(Icons.school_outlined), + title: const Text('Show the walkthrough'), + subtitle: const Text( + 'Four short steps: connect, set up an agent, run, chat.', + ), + chevron: true, + onTap: () => showFirstRunWalkthrough(context), + ); +} diff --git a/app/lib/features/walkthrough/first_run_walkthrough.dart b/app/lib/features/walkthrough/first_run_walkthrough.dart new file mode 100644 index 00000000..bedcbcac --- /dev/null +++ b/app/lib/features/walkthrough/first_run_walkthrough.dart @@ -0,0 +1,183 @@ +import 'package:flutter/material.dart'; + +import '../../ui/adaptive/app_popups.dart'; +import 'walkthrough_harness_command.dart'; +import 'walkthrough_steps.dart'; + +/// Opens the walkthrough as a Material details sheet on phones and a dialog on +/// wide windows. [onClosed] runs once however it closes (Skip, Done, the close +/// button or a tap outside), so the caller can record it as seen. +Future showFirstRunWalkthrough( + BuildContext context, { + Future Function()? onClosed, +}) async { + await showAppDetails( + context, + maxWidth: 560, + builder: (sheet) => + FirstRunWalkthrough(onClose: () => Navigator.of(sheet).pop()), + ); + await onClosed?.call(); +} + +/// The four-page stepper: Back and Next between pages, Skip on every page and +/// Done on the last. Every control is a standard Material button; the layout +/// wraps rather than clipping at large text scales. +class FirstRunWalkthrough extends StatefulWidget { + const FirstRunWalkthrough({ + super.key, + required this.onClose, + this.steps = walkthroughSteps, + }); + + /// Called by Skip, Done and the close button. + final VoidCallback onClose; + final List steps; + + @override + State createState() => _FirstRunWalkthroughState(); +} + +class _FirstRunWalkthroughState extends State { + int _index = 0; + + bool get _last => _index == widget.steps.length - 1; + + void _back() => setState(() => _index = _index > 0 ? _index - 1 : 0); + + void _next() => setState(() => _index = _last ? _index : _index + 1); + + @override + Widget build(BuildContext context) { + final step = widget.steps[_index]; + final theme = Theme.of(context); + final content = Semantics( + scopesRoute: true, + namesRoute: true, + explicitChildNodes: true, + label: 'Pipelines walkthrough', + child: Padding( + padding: const EdgeInsets.fromLTRB(24, 8, 24, 24), + child: Column( + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text( + 'Step ${_index + 1} of ${widget.steps.length}', + key: const ValueKey('walkthrough.progress'), + style: theme.textTheme.labelLarge, + ), + const SizedBox(height: 8), + LinearProgressIndicator(value: (_index + 1) / widget.steps.length), + const SizedBox(height: 20), + Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Icon(step.icon, color: theme.colorScheme.primary), + const SizedBox(width: 12), + Expanded( + child: Text( + step.title, + key: ValueKey('walkthrough.title.$_index'), + style: theme.textTheme.headlineSmall, + ), + ), + ], + ), + const SizedBox(height: 12), + Text(step.body, style: theme.textTheme.bodyLarge), + for (final point in step.points) ...[ + const SizedBox(height: 8), + _Point(text: point), + ], + if (step.showsHarnessCommand) ...[ + const SizedBox(height: 16), + const WalkthroughHarnessCommand(), + ], + const SizedBox(height: 24), + _Footer( + last: _last, + canGoBack: _index > 0, + onBack: _back, + onNext: _last ? widget.onClose : _next, + onSkip: widget.onClose, + ), + ], + ), + ), + ); + // A wide window wraps the sheet's content in its own scroll view; a phone + // sheet does not, so the page scrolls here at large text scales. + return usesDesktopPopups(context) + ? content + : SingleChildScrollView(child: content); + } +} + +class _Point extends StatelessWidget { + const _Point({required this.text}); + + final String text; + + @override + Widget build(BuildContext context) => Row( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + const Padding( + padding: EdgeInsets.only(top: 2), + child: Icon(Icons.circle, size: 6), + ), + const SizedBox(width: 12), + Expanded( + child: Text(text, style: Theme.of(context).textTheme.bodyMedium), + ), + ], + ); +} + +class _Footer extends StatelessWidget { + const _Footer({ + required this.last, + required this.canGoBack, + required this.onBack, + required this.onNext, + required this.onSkip, + }); + + final bool last; + final bool canGoBack; + final VoidCallback onBack; + final VoidCallback onNext; + final VoidCallback onSkip; + + @override + Widget build(BuildContext context) => Wrap( + alignment: WrapAlignment.spaceBetween, + crossAxisAlignment: WrapCrossAlignment.center, + spacing: 8, + runSpacing: 8, + children: [ + TextButton( + key: const ValueKey('walkthrough.skip'), + onPressed: onSkip, + child: const Text('Skip'), + ), + Wrap( + spacing: 8, + runSpacing: 8, + children: [ + TextButton( + key: const ValueKey('walkthrough.back'), + onPressed: canGoBack ? onBack : null, + child: const Text('Back'), + ), + FilledButton( + key: const ValueKey('walkthrough.next'), + onPressed: onNext, + child: Text(last ? 'Done' : 'Next'), + ), + ], + ), + ], + ); +} diff --git a/app/lib/features/walkthrough/walkthrough_gate.dart b/app/lib/features/walkthrough/walkthrough_gate.dart new file mode 100644 index 00000000..a560ece8 --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_gate.dart @@ -0,0 +1,200 @@ +import 'dart:async'; + +import 'package:flutter/widgets.dart'; + +import '../../core/api_gateway.dart'; +import 'first_run_walkthrough.dart'; +import 'walkthrough_store.dart'; + +/// Reports whether the server has no pipelines, runs or chats yet. Returns null +/// when any of the three lists cannot be read, so an unreadable server never +/// triggers the walkthrough. +Future serverHasNoWorkYet(ApiGateway? gateway) async { + if (gateway == null) return null; + try { + final replies = await Future.wait(>[ + gateway.call('list_pipelines', {'include_archived': true}), + gateway.call('list_runs'), + gateway.call('chat_sessions'), + ]); + final lists = [ + replies[0]['pipelines'], + replies[1]['runs'], + replies[2]['chat_sessions'], + ]; + if (lists.any((list) => list is! List)) return null; + return lists.every((list) => (list as List).isEmpty); + } catch (_) { + return null; + } +} + +/// Offers the walkthrough from the Pipelines page, which is the first screen a +/// new user sees. It is offered when: +/// +/// * the device has not finished or skipped it yet (first launch, once); or +/// * the device already has, and the connected server has no pipelines, runs +/// or chats, and that server has not been offered it before. +/// +/// The server check needs a connected session. While disconnected it waits, and +/// it runs again on each new connection until the server answers. A check that +/// cannot read the server leaves the gate open to retry; a decided check (the +/// walkthrough shown, or the server has work) ends it for this mount. +/// +/// Nothing is shown while the store cannot be read, because an unavailable +/// store reports "seen". The check runs only while [enabled] (the Pipelines tab +/// is the one showing). +class FirstRunWalkthroughGate extends StatefulWidget { + const FirstRunWalkthroughGate({ + super.key, + required this.child, + required this.store, + required this.enabled, + required this.serverScope, + required this.connection, + required this.connected, + this.gateway, + }); + + final Widget child; + final WalkthroughStore store; + + /// Whether the Pipelines page is the one showing. + final bool enabled; + + /// The connected server's scope, recorded when the walkthrough is offered. + final String serverScope; + + /// Notifies when the connection may have changed; the gate re-reads + /// [connected] on each notification. + final Listenable connection; + + /// Whether the server session is connected right now. + final bool Function() connected; + + /// The connected server's gateway, used for the empty-server check. + final ApiGateway? gateway; + + @override + State createState() => + _FirstRunWalkthroughGateState(); +} + +class _FirstRunWalkthroughGateState extends State { + /// The offer is decided for this mount: shown, or nothing left to offer. + bool _decided = false; + + /// An offer is in flight. + bool _running = false; + + /// A new connection arrived while an offer was in flight. + bool _connectedAgain = false; + late bool _wasConnected; + + @override + void initState() { + super.initState(); + _wasConnected = widget.connected(); + widget.connection.addListener(_onConnectionChanged); + _scheduleIfEnabled(); + } + + @override + void didUpdateWidget(FirstRunWalkthroughGate oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.connection != widget.connection) { + oldWidget.connection.removeListener(_onConnectionChanged); + widget.connection.addListener(_onConnectionChanged); + } + _scheduleIfEnabled(); + } + + @override + void dispose() { + widget.connection.removeListener(_onConnectionChanged); + super.dispose(); + } + + /// Acts only on a disconnected-to-connected transition, so frequent session + /// notifications while connected never repeat the server check. + void _onConnectionChanged() { + final connected = widget.connected(); + final became = connected && !_wasConnected; + _wasConnected = connected; + if (!became || _decided) return; + if (_running) { + _connectedAgain = true; + return; + } + _scheduleIfEnabled(); + } + + void _scheduleIfEnabled() { + if (_decided || _running || !widget.enabled) return; + _running = true; + // A connection can arrive between frames; the post-frame callback needs a + // frame, so request one explicitly. + WidgetsBinding.instance.addPostFrameCallback((_) { + if (!_active) { + // Pipelines is hidden (or the gate is gone): release the flag so a + // later enable reschedules the offer through didUpdateWidget. + _running = false; + return; + } + unawaited(_runOffer()); + }); + WidgetsBinding.instance.ensureVisualUpdate(); + } + + /// The gate may offer only while mounted and while the Pipelines page is the + /// one showing. Checked after every await and before every show. + bool get _active => mounted && widget.enabled; + + Future _runOffer() async { + try { + await _offer(); + } finally { + _running = false; + final again = _connectedAgain; + _connectedAgain = false; + if (again && !_decided) _scheduleIfEnabled(); + } + } + + Future _offer() async { + final seen = await widget.store.isSeen(); + if (!_active) return; + if (!seen) { + _decided = true; + await _showIfActive(); + return; + } + if (await widget.store.wasOffered(widget.serverScope)) { + if (!_active) return; + _decided = true; + return; + } + // Wait for a connection; the connection listener runs the check again. + if (!widget.connected()) return; + final empty = await serverHasNoWorkYet(widget.gateway); + if (!_active) return; + // Unreadable: stay open so the next connection retries the check. + if (empty == null) return; + _decided = true; + if (!empty) return; + await widget.store.markOffered(widget.serverScope); + await _showIfActive(); + } + + Future _showIfActive() async { + if (!_active) return; + await _show(); + } + + Future _show() async { + await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen); + } + + @override + Widget build(BuildContext context) => widget.child; +} diff --git a/app/lib/features/walkthrough/walkthrough_harness_command.dart b/app/lib/features/walkthrough/walkthrough_harness_command.dart new file mode 100644 index 00000000..7e560449 --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_harness_command.dart @@ -0,0 +1,86 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; + +import 'walkthrough_steps.dart'; + +/// The harness page's command: an agent picker and the one command it selects, +/// with a single copy button for that command. +class WalkthroughHarnessCommand extends StatefulWidget { + const WalkthroughHarnessCommand({super.key}); + + @override + State createState() => + _WalkthroughHarnessCommandState(); +} + +class _WalkthroughHarnessCommandState extends State { + String _agent = harnessAgents.first; + bool _copied = false; + + Future _copy(String command) async { + try { + await Clipboard.setData(ClipboardData(text: command)); + } catch (_) { + // The command stays selectable, so a failed copy never claims success. + return; + } + if (!mounted) return; + setState(() => _copied = true); + } + + @override + Widget build(BuildContext context) { + final scheme = Theme.of(context).colorScheme; + final command = harnessSetupCommand(_agent); + return Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text('Agent', style: Theme.of(context).textTheme.labelLarge), + const SizedBox(height: 8), + Wrap( + spacing: 8, + runSpacing: 8, + children: [ + for (final agent in harnessAgents) + ChoiceChip( + key: ValueKey('walkthrough.agent.$agent'), + label: Text(agent), + selected: agent == _agent, + onSelected: (_) => setState(() { + _agent = agent; + _copied = false; + }), + ), + ], + ), + const SizedBox(height: 12), + DecoratedBox( + decoration: BoxDecoration( + color: scheme.surfaceContainerHighest, + borderRadius: BorderRadius.circular(12), + ), + child: Padding( + padding: const EdgeInsets.only(left: 12, right: 4), + child: Row( + children: [ + Expanded( + child: SelectableText( + command, + key: const ValueKey('walkthrough.command'), + style: Theme.of(context).textTheme.bodyLarge, + ), + ), + IconButton( + key: const ValueKey('walkthrough.copy'), + tooltip: _copied ? 'Command copied' : 'Copy command', + onPressed: () => _copy(command), + icon: Icon(_copied ? Icons.check : Icons.copy_outlined), + ), + ], + ), + ), + ), + ], + ); + } +} diff --git a/app/lib/features/walkthrough/walkthrough_steps.dart b/app/lib/features/walkthrough/walkthrough_steps.dart new file mode 100644 index 00000000..aa45ea1c --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_steps.dart @@ -0,0 +1,79 @@ +import 'package:flutter/material.dart'; + +/// One page of the first-run walkthrough. Pure content: no widgets, so the +/// copy can be checked without pumping a tree. +class WalkthroughStep { + const WalkthroughStep({ + required this.icon, + required this.title, + required this.body, + this.points = const [], + this.showsHarnessCommand = false, + }); + + final IconData icon; + final String title; + final String body; + + /// Short labelled facts shown under the body, one per line. + final List points; + + /// Whether this page shows the harness setup command picker. + final bool showsHarnessCommand; +} + +/// The agents `pipelines harness setup` accepts, in the order they are offered. +const harnessAgents = ['claude', 'codex', 'opencode', 'pi']; + +/// The command for [agent], exactly as a terminal should run it. +String harnessSetupCommand(String agent) => 'pipelines harness setup $agent'; + +/// The four walkthrough pages, in order. +const walkthroughSteps = [ + WalkthroughStep( + icon: Icons.hub_outlined, + title: 'Welcome to Pipelines', + body: + 'Pipelines runs reusable AI workflows and holds chats with coding ' + 'agents. Both live on your server, so start by connecting this app ' + 'to it.', + points: [ + 'Pipelines: workflows you define once and run again.', + 'Chats: conversations with coding agents on the server.', + 'Connect: open Settings, then Connection, enter the Server URL and ' + 'choose Connect.', + ], + ), + WalkthroughStep( + icon: Icons.build_circle_outlined, + title: 'Set up an agent harness', + body: + 'A harness lets Pipelines drive a coding agent. Choose the agent you ' + 'use, then run its setup command in a terminal.', + showsHarnessCommand: true, + ), + WalkthroughStep( + icon: Icons.play_circle_outline, + title: 'Start a run', + body: + 'Pipelines shows your workflows. Runs shows every run with its ' + 'progress and results.', + points: [ + 'Pipelines tab: open a workflow and fill in its inputs.', + 'Runs tab: follow a run as it works, then read what it produced.', + 'Choose Run on a workflow to start one.', + ], + ), + WalkthroughStep( + icon: Icons.forum_outlined, + title: 'Chat with an agent', + body: + 'The Chat tab lists your conversations. Open one to read the thread ' + 'and reply.', + points: [ + 'Float: pop a chat into its own window while you work elsewhere.', + 'Terminal: open a terminal beside the Chat tab for direct commands.', + 'New chat starts a conversation with an agent.', + ], + ), +]; diff --git a/app/lib/features/walkthrough/walkthrough_store.dart b/app/lib/features/walkthrough/walkthrough_store.dart new file mode 100644 index 00000000..01332fda --- /dev/null +++ b/app/lib/features/walkthrough/walkthrough_store.dart @@ -0,0 +1,118 @@ +import 'package:shared_preferences/shared_preferences.dart'; + +/// The device-level key for "the first-run walkthrough was finished or skipped". +/// It is per device, not per server, so a new server never repeats it. +const String walkthroughSeenKey = 'pipelines.next.firstRunWalkthrough.v1'; + +/// The key listing the server scopes that were already offered the walkthrough +/// because they had no pipelines, runs or chats yet. +const String walkthroughOfferedKey = 'pipelines.next.walkthroughOffered.v1'; + +/// The persistence seam for the walkthrough. A store that cannot be read or +/// written reports "seen" and "offered", so an unavailable store never nags. +abstract interface class WalkthroughStore { + Future isSeen(); + + Future markSeen(); + + Future wasOffered(String serverScope); + + Future markOffered(String serverScope); +} + +Future _openPreferences() async { + try { + return await SharedPreferences.getInstance(); + } catch (_) { + return null; + } +} + +/// `shared_preferences`-backed storage under the `pipelines.next` keys. +/// +/// [open] is the seam for an unavailable platform store (tests pass one that +/// yields null); production opens the real preferences. +class SharedPreferencesWalkthroughStore implements WalkthroughStore { + const SharedPreferencesWalkthroughStore({this.open = _openPreferences}); + + final Future Function() open; + + Future _preferences() => open(); + + @override + Future isSeen() async { + final preferences = await _preferences(); + if (preferences == null) return true; + try { + return preferences.getBool(walkthroughSeenKey) ?? false; + } catch (_) { + return true; + } + } + + @override + Future markSeen() async { + final preferences = await _preferences(); + if (preferences == null) return; + try { + await preferences.setBool(walkthroughSeenKey, true); + } catch (_) { + // Nothing to report: the walkthrough is still dismissed for this run. + } + } + + @override + Future wasOffered(String serverScope) async { + final preferences = await _preferences(); + if (preferences == null) return true; + try { + final offered = preferences.getStringList(walkthroughOfferedKey); + return offered?.contains(serverScope) ?? false; + } catch (_) { + return true; + } + } + + @override + Future markOffered(String serverScope) async { + final preferences = await _preferences(); + if (preferences == null) return; + try { + final offered = { + ...?preferences.getStringList(walkthroughOfferedKey), + serverScope, + }; + await preferences.setStringList(walkthroughOfferedKey, offered.toList()); + } catch (_) { + // A failed write only means the offer may show again later. + } + } +} + +/// An in-memory store for tests and previews. It never touches the platform +/// store, so a fixture cannot mark a real device as seen. +class MemoryWalkthroughStore implements WalkthroughStore { + MemoryWalkthroughStore({this.seen = false, Set? offered}) + : _offered = {...?offered}; + + /// Whether the walkthrough is marked seen. + bool seen; + final Set _offered; + + /// The server scopes already offered the walkthrough. + Set get offered => Set.unmodifiable(_offered); + + @override + Future isSeen() async => seen; + + @override + Future markSeen() async => seen = true; + + @override + Future wasOffered(String serverScope) async => + _offered.contains(serverScope); + + @override + Future markOffered(String serverScope) async => + _offered.add(serverScope); +} diff --git a/app/notes/first-run-walkthrough.md b/app/notes/first-run-walkthrough.md new file mode 100644 index 00000000..679ac1d4 --- /dev/null +++ b/app/notes/first-run-walkthrough.md @@ -0,0 +1,117 @@ +# First-run walkthrough + +A short, skippable four-page walkthrough for new users of the Flutter app. + +## What it does + +- Shows once per device on first launch, from the Pipelines page. +- Is also offered once per server when the device has already seen it and the + connected server has no pipelines, runs or chats yet (the server is checked + with `list_pipelines`, `list_runs` and `chat_sessions`; an unreadable server + never triggers it). +- Pages: 1) what Pipelines is and how to connect to the server; 2) set up an + agent harness, with an agent picker and one copy button for + `pipelines harness setup ` (`claude`, `codex`, `opencode`, `pi`); + 3) the Pipelines and Runs tabs and how to start a run; 4) the Chat tab, float + and terminal. +- Every page has Skip; Back and Next move between pages; Done ends on the last. +- Closing by any route (Skip, Done, the close gesture, a tap outside) records the + device as seen. +- Settings reopens it from Tools → Help → "Show the walkthrough". Reopening + does not change the seen record. + +## Where it lives + +- `lib/features/walkthrough/` + - `walkthrough_store.dart`: the seen/offered records (`pipelines.next.*` keys; + a store that cannot be read reports "seen", so it never nags). + - `walkthrough_steps.dart`: the page copy and agent list (pure data). + - `first_run_walkthrough.dart`: the stepper and `showFirstRunWalkthrough` + (a Material bottom sheet on phones, a dialog on wide windows, via + `showAppDetails`). + - `walkthrough_harness_command.dart`: agent chips, the command and copy. + - `walkthrough_gate.dart`: the first-launch and empty-server check. +- `lib/application/pipelines_app.dart`: wraps the Pipelines destination body in + the gate (the Pipelines tab is the first screen). +- `lib/features/settings/settings_walkthrough_section.dart`: one row in the + Tools → Help group, plus `SettingsKeys.walkthrough`. + +## Focused tests + +- `test/features/walkthrough/walkthrough_gate_test.dart`: first launch shows + once; Done and Skip persist; a seen device on an empty server is offered once; + a seen device that starts disconnected makes no server call and is offered + after it connects; an unreadable check is retried on the next connection (and + a repeated notification while connected does not re-query); a server with + work, an unreadable server, a hidden Pipelines page, and an unavailable store + all stay quiet; hiding the Pipelines page while the first-launch read is + still pending keeps the walkthrough closed, and showing it again offers it + once. +- `test/features/walkthrough/first_run_walkthrough_test.dart`: phone bottom + sheet and wide dialog; Back disabled on page 1; four pages with Done on the + last and Skip throughout; the harness picker and copy; large text (2x) and + dark mode without overflow. +- `test/features/settings/settings_walkthrough_test.dart`: the Settings row + reopens the walkthrough on page 1. + +## Results + +- Focused run: `tool/memwatch/full.sh 'test/features/walkthrough/first_run_walkthrough_test.dart test/features/walkthrough/walkthrough_gate_test.dart test/features/settings/settings_walkthrough_test.dart'` + → PASS, 20 passed, 0 failed, peak 1031 MB, 16 s. The verdict named only these + three paths. +- Visibility fix (review must-fix, visit 2): the gate offered without checking + `enabled`, so a walkthrough could open over another destination if Pipelines + was hidden before the post-frame callback or during a pending read. The gate + now checks `mounted && enabled` in the callback, after each await, and before + each show. A skipped callback clears the in-flight flag, so re-enabling + Pipelines reschedules the offer. Covered by the new gate test + "hiding Pipelines while an offer is pending keeps the walkthrough closed". + That test was not run against the pre-fix code, so the failing-before claim + is by reasoning only. +- Lifecycle fix (review must-fix): the empty-server check used to run once + right after the first frame, before the session connected. A seen device + then got a `NotConnectedError`, and the check was never retried. The gate now + takes the session as its connection source (`connection` + `connected`), waits + while disconnected, re-runs on each new connection until the server answers, + and stays quiet on a repeated notification while connected. A connection that + arrives between frames requests a visual update, so the post-frame callback + runs. The fix is covered by the two new gate tests above. +- Two earlier runs failed and were fixed in the test code, not by weakening + expectations: the large-text test tapped Next before scrolling it into view, + and the "unavailable store" test awaited the real preferences plugin inside + `testWidgets` and hung. The store now takes an injectable opener, so that case + is a plain test with a null opener. +- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos). +- Not run here: `pipelines_app_test`, the Settings screen suites and the other + Pipelines suites. They belong to the land gate. + +## Affected states (checked by focused tests only; nothing captured) + +- Phone (390×844): bottom sheet; page 1 with Back disabled; all four pages; + Skip mid-walkthrough. +- Wide (1280×900): dialog; Next reaches page 2. +- Harness page: four agent chips; the command follows the selected agent; copy + copies the selected command and the button shows a check. +- Large text (2×) on a 360×740 phone and dark mode: every page builds with no + exception. +- Gate: first launch once; Done and Skip persist; a seen device on an empty + server is offered once per server; a server with runs, an unreadable server, + a hidden Pipelines page and an unavailable store stay quiet. +- Settings: "Show the walkthrough" reopens page 1 and does not change the seen + record. + +Nothing was built, run on a device or captured. `ui-review` owns the rendered +review. + +## Limitations + +- The gate is tested in isolation with fake stores and gateways. The Pipelines + wiring in `pipelines_app.dart` is not covered by a focused test. +- Narrow window: the empty-server offer marks the server as offered before it + shows. If Pipelines is hidden during that one store write, the server is + consumed without the walkthrough appearing. Fixing it needs the store write + to move to the dialog's close, which changes when the offer is recorded. +- On phones the walkthrough is a Material bottom sheet, not a full page. +- The harness command is shown as a picker with one copy button for the + selected agent, not four separate copy buttons. +- The "Show the walkthrough" test covers the row, not the whole Settings tree. diff --git a/app/test/features/settings/settings_walkthrough_test.dart b/app/test/features/settings/settings_walkthrough_test.dart new file mode 100644 index 00000000..a769479d --- /dev/null +++ b/app/test/features/settings/settings_walkthrough_test.dart @@ -0,0 +1,36 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/settings/settings_keys.dart'; +import 'package:pipelines_app/features/settings/settings_walkthrough_section.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; + +void main() { + testWidgets('Settings reopens the walkthrough on the first page', ( + tester, + ) async { + tester.view.devicePixelRatio = 1; + tester.view.physicalSize = const Size(390, 844); + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + + await tester.pumpWidget( + MaterialApp( + theme: appLightTheme(), + home: const Scaffold(body: SettingsWalkthroughSection()), + ), + ); + + expect(find.text('Show the walkthrough'), findsOneWidget); + expect(find.text('Welcome to Pipelines'), findsNothing); + + await tester.tap(find.byKey(SettingsKeys.walkthrough)); + await tester.pumpAndSettle(); + + expect(find.text('Welcome to Pipelines'), findsOneWidget); + expect(find.text('Step 1 of 4'), findsOneWidget); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + expect(find.text('Welcome to Pipelines'), findsNothing); + }); +} diff --git a/app/test/features/walkthrough/first_run_walkthrough_test.dart b/app/test/features/walkthrough/first_run_walkthrough_test.dart new file mode 100644 index 00000000..ddeaec1a --- /dev/null +++ b/app/test/features/walkthrough/first_run_walkthrough_test.dart @@ -0,0 +1,202 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/walkthrough/first_run_walkthrough.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_steps.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; + +const _nextKey = ValueKey('walkthrough.next'); +const _backKey = ValueKey('walkthrough.back'); +const _skipKey = ValueKey('walkthrough.skip'); +const _copyKey = ValueKey('walkthrough.copy'); +const _commandKey = ValueKey('walkthrough.command'); +const _launchKey = ValueKey('launch'); + +Widget _launcher({ThemeMode mode = ThemeMode.light, double textScale = 1}) => + MaterialApp( + theme: appLightTheme(), + darkTheme: appDarkTheme(), + themeMode: mode, + builder: (context, child) => MediaQuery( + data: MediaQuery.of( + context, + ).copyWith(textScaler: TextScaler.linear(textScale)), + child: child!, + ), + home: Scaffold( + body: Builder( + builder: (context) => Center( + child: FilledButton( + key: _launchKey, + onPressed: () => showFirstRunWalkthrough(context), + child: const Text('Open'), + ), + ), + ), + ), + ); + +Future _open(WidgetTester tester) async { + await tester.tap(find.byKey(_launchKey)); + await tester.pumpAndSettle(); +} + +void _useViewport(WidgetTester tester, Size size) { + tester.view.devicePixelRatio = 1; + tester.view.physicalSize = size; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); +} + +void main() { + group('phone layout', () { + testWidgets('opens as a bottom sheet with the first page', (tester) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(find.byType(BottomSheet), findsOneWidget); + expect(find.byType(Dialog), findsNothing); + expect(find.text('Step 1 of 4'), findsOneWidget); + expect(find.text(walkthroughSteps.first.title), findsOneWidget); + }); + + testWidgets('Back is disabled on the first page; Next advances', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(tester.widget(find.byKey(_backKey)).onPressed, isNull); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + expect(find.text('Step 2 of 4'), findsOneWidget); + expect( + tester.widget(find.byKey(_backKey)).onPressed, + isNotNull, + ); + + await tester.tap(find.byKey(_backKey)); + await tester.pumpAndSettle(); + expect(find.text('Step 1 of 4'), findsOneWidget); + }); + + testWidgets('walks four pages, Done on the last, Skip on every page', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + for (var page = 0; page < 3; page++) { + expect(find.byKey(_skipKey), findsOneWidget); + expect(find.text('Next'), findsOneWidget); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + } + expect(find.text('Step 4 of 4'), findsOneWidget); + expect(find.text('Done'), findsOneWidget); + expect(find.byKey(_skipKey), findsOneWidget); + expect(find.text(walkthroughSteps.last.title), findsOneWidget); + + await tester.tap(find.text('Done')); + await tester.pumpAndSettle(); + expect(find.text(walkthroughSteps.last.title), findsNothing); + }); + + testWidgets('Skip closes from the middle of the walkthrough', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + await tester.pumpWidget(_launcher()); + await _open(tester); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + + await tester.tap(find.byKey(_skipKey)); + await tester.pumpAndSettle(); + expect(find.byType(BottomSheet), findsNothing); + }); + }); + + testWidgets('wide windows open the walkthrough as a dialog', (tester) async { + _useViewport(tester, const Size(1280, 900)); + await tester.pumpWidget(_launcher()); + await _open(tester); + + expect(find.byType(Dialog), findsOneWidget); + expect(find.byType(BottomSheet), findsNothing); + expect(find.text('Step 1 of 4'), findsOneWidget); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + expect(find.text(walkthroughSteps[1].title), findsOneWidget); + }); + + testWidgets('the harness page offers each agent and copies its command', ( + tester, + ) async { + _useViewport(tester, const Size(390, 844)); + final copied = []; + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(SystemChannels.platform, (call) async { + if (call.method == 'Clipboard.setData') { + copied.add((call.arguments as Map)['text'] as String); + } + return null; + }); + addTearDown( + () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(SystemChannels.platform, null), + ); + + await tester.pumpWidget(_launcher()); + await _open(tester); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + + expect( + tester.widget(find.byKey(_commandKey)).data, + 'pipelines harness setup claude', + ); + await tester.tap( + find.byKey(const ValueKey('walkthrough.agent.pi')), + ); + await tester.pumpAndSettle(); + expect( + tester.widget(find.byKey(_commandKey)).data, + 'pipelines harness setup pi', + ); + + await tester.tap(find.byKey(_copyKey)); + await tester.pumpAndSettle(); + expect(copied, ['pipelines harness setup pi']); + expect( + find.descendant( + of: find.byKey(_copyKey), + matching: find.byIcon(Icons.check), + ), + findsOneWidget, + ); + }); + + testWidgets('large text and dark mode lay out without overflow', ( + tester, + ) async { + _useViewport(tester, const Size(360, 740)); + await tester.pumpWidget(_launcher(mode: ThemeMode.dark, textScale: 2)); + await _open(tester); + + for (var page = 0; page < walkthroughSteps.length; page++) { + expect(tester.takeException(), isNull, reason: 'page $page'); + expect(find.text(walkthroughSteps[page].title), findsOneWidget); + if (page < walkthroughSteps.length - 1) { + // At 2x text the phone sheet scrolls, so Next can start off screen. + await tester.ensureVisible(find.byKey(_nextKey)); + await tester.tap(find.byKey(_nextKey)); + await tester.pumpAndSettle(); + } + } + expect(tester.takeException(), isNull); + }); +} diff --git a/app/test/features/walkthrough/walkthrough_gate_test.dart b/app/test/features/walkthrough/walkthrough_gate_test.dart new file mode 100644 index 00000000..72dc748b --- /dev/null +++ b/app/test/features/walkthrough/walkthrough_gate_test.dart @@ -0,0 +1,341 @@ +import 'dart:async'; + +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_gate.dart'; +import 'package:pipelines_app/features/walkthrough/walkthrough_store.dart'; +import 'package:pipelines_app/ui/theme/app_theme.dart'; +import 'package:shared_preferences/shared_preferences.dart'; + +const _welcome = 'Welcome to Pipelines'; + +Future _noPreferences() async => null; + +/// A gateway that answers the three empty-server list calls from fixed lists. +class _FakeGateway implements ApiGateway { + _FakeGateway({this.runs = const [], this.failing = false}); + + /// Runs the server reports; pipelines and chats are always empty here. + final List runs; + bool failing; + final calls = []; + + @override + Future call(String type, [JsonMap fields = const {}]) async { + calls.add(type); + if (failing) throw StateError('offline'); + return switch (type) { + 'list_pipelines' => {'pipelines': const []}, + 'list_runs' => {'runs': runs}, + 'chat_sessions' => {'chat_sessions': const []}, + _ => {'type': 'error'}, + }; + } + + @override + Stream get frames => const Stream.empty(); +} + +/// Delegates to [inner], but holds [isSeen] until [release] so a test can +/// change the page visibility while an offer is still in flight. +class _HeldStore implements WalkthroughStore { + _HeldStore(this.inner); + + final MemoryWalkthroughStore inner; + Completer? _gate; + + void hold() => _gate = Completer(); + + void release() { + _gate?.complete(); + _gate = null; + } + + @override + Future isSeen() async { + await _gate?.future; + return inner.isSeen(); + } + + @override + Future markSeen() => inner.markSeen(); + + @override + Future wasOffered(String serverScope) => + inner.wasOffered(serverScope); + + @override + Future markOffered(String serverScope) => + inner.markOffered(serverScope); +} + +/// [link] stands in for the session: its value is whether the server connected, +/// and notifying it is the connection transition. Defaults to connected. +Widget _host({ + required WalkthroughStore store, + ApiGateway? gateway, + bool enabled = true, + ValueNotifier? link, +}) { + final session = link ?? ValueNotifier(true); + return MaterialApp( + theme: appLightTheme(), + darkTheme: appDarkTheme(), + home: Scaffold( + body: FirstRunWalkthroughGate( + store: store, + enabled: enabled, + serverScope: 'server-a', + connection: session, + connected: () => session.value, + gateway: gateway, + child: const Text('Pipelines page'), + ), + ), + ); +} + +Future _finishWalkthrough(WidgetTester tester) async { + for (var page = 0; page < 3; page++) { + await tester.tap(find.byKey(const ValueKey('walkthrough.next'))); + await tester.pumpAndSettle(); + } + await tester.tap(find.text('Done')); + await tester.pumpAndSettle(); +} + +void main() { + testWidgets('first launch shows the walkthrough once per device', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + + await _finishWalkthrough(tester); + expect(find.text(_welcome), findsNothing); + expect(store.seen, isTrue); + + // A later launch on the same device does not show it again. + await tester.pumpWidget(const SizedBox()); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + expect(find.text('Pipelines page'), findsOneWidget); + }); + + testWidgets('Done persists the seen record and no server query runs', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + final gateway = _FakeGateway(); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + await _finishWalkthrough(tester); + + expect(store.seen, isTrue); + expect( + gateway.calls, + isEmpty, + reason: 'first launch needs no server check', + ); + }); + + testWidgets('Skip on the first page persists the seen record', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store)); + await tester.pumpAndSettle(); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.seen, isTrue); + }); + + testWidgets('a seen device on an empty server is offered it once', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + expect( + gateway.calls, + containsAll(['list_pipelines', 'list_runs', 'chat_sessions']), + ); + + await tester.tap(find.byKey(const ValueKey('walkthrough.skip'))); + await tester.pumpAndSettle(); + + // The server was offered already, so a fresh mount stays quiet. + await tester.pumpWidget(const SizedBox()); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + }); + + testWidgets( + 'a seen device that starts disconnected is offered once it connects', + (tester) async { + // Startup order in the app: the Pipelines page mounts before the session + // has connected. The server must not be asked yet, and the offer must + // still happen after the connection arrives. + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(); + final link = ValueNotifier(false); + await tester.pumpWidget( + _host(store: store, gateway: gateway, link: link), + ); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect( + gateway.calls, + isEmpty, + reason: 'no server call while disconnected', + ); + expect(store.offered, isEmpty); + + link.value = true; + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + expect( + gateway.calls, + containsAll(['list_pipelines', 'list_runs', 'chat_sessions']), + ); + }, + ); + + testWidgets('an unreadable check is retried on the next connection', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway(failing: true); + final link = ValueNotifier(true); + await tester.pumpWidget(_host(store: store, gateway: gateway, link: link)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + final callsAfterFailure = gateway.calls.length; + + // A repeated notification while still connected does not re-query. + link.notifyListeners(); + await tester.pumpAndSettle(); + expect(gateway.calls.length, callsAfterFailure); + + // The server recovers; a fresh connection runs the check and offers it. + gateway.failing = false; + link.value = false; + await tester.pumpAndSettle(); + link.value = true; + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsOneWidget); + expect(store.offered, {'server-a'}); + }); + + testWidgets('a seen device on a server with work is not offered', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + final gateway = _FakeGateway( + runs: [ + {'id': 'run-1'}, + ], + ); + await tester.pumpWidget(_host(store: store, gateway: gateway)); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + }); + + testWidgets('an unreadable server never triggers the walkthrough', ( + tester, + ) async { + final store = MemoryWalkthroughStore(seen: true); + await tester.pumpWidget( + _host(store: store, gateway: _FakeGateway(failing: true)), + ); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(store.offered, isEmpty); + }); + + testWidgets('the Pipelines page being hidden defers the check', ( + tester, + ) async { + final store = MemoryWalkthroughStore(); + await tester.pumpWidget(_host(store: store, enabled: false)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsNothing); + expect(store.seen, isFalse); + + await tester.pumpWidget(_host(store: store, enabled: true)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsOneWidget); + }); + + testWidgets( + 'hiding Pipelines while an offer is pending keeps the walkthrough closed', + (tester) async { + final inner = MemoryWalkthroughStore(); + final store = _HeldStore(inner)..hold(); + await tester.pumpWidget(_host(store: store)); + await tester.pump(); + + // The Pipelines page is hidden while the offer is still reading the store. + await tester.pumpWidget(_host(store: store, enabled: false)); + store.release(); + await tester.pumpAndSettle(); + + expect(find.text(_welcome), findsNothing); + expect(inner.seen, isFalse); + + // Showing Pipelines again offers it once, on the same mount. + await tester.pumpWidget(_host(store: store, enabled: true)); + await tester.pumpAndSettle(); + expect(find.text(_welcome), findsOneWidget); + }, + ); + + test('an unavailable preference store reports seen and offered', () async { + // The opener yields no preferences, as when the platform store is absent: + // every read reports "seen" and every write is quietly dropped. + const store = SharedPreferencesWalkthroughStore(open: _noPreferences); + expect(await store.isSeen(), isTrue); + expect(await store.wasOffered('server-a'), isTrue); + await store.markSeen(); + await store.markOffered('server-a'); + expect(await store.isSeen(), isTrue); + }); + + test( + 'SharedPreferences store records seen and offered under the keys', + () async { + SharedPreferences.setMockInitialValues({}); + const store = SharedPreferencesWalkthroughStore(); + expect(await store.isSeen(), isFalse); + await store.markSeen(); + expect(await store.isSeen(), isTrue); + + expect(await store.wasOffered('server-a'), isFalse); + await store.markOffered('server-a'); + expect(await store.wasOffered('server-a'), isTrue); + expect(await store.wasOffered('server-b'), isFalse); + }, + ); +}