Files
pipelines/app/notes/first-run-walkthrough.md
T
alan 30ba70ade8 Add first-run walkthrough
Guide new users through connecting a server, configuring an agent harness, starting runs, and chatting with agents. Persist completion per device and offer the walkthrough again for empty servers or from Settings, with widget coverage and implementation notes.
2026-11-12 02:23:15 +00:00

6.5 KiB
Raw Blame History

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 <agent> (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.