Show a one-time welcome tour on the first desktop launch

[SunkenInTime]

The first desktop release with accounts opens straight into the library and says nothing about what changed. Someone updating from 4.6 sees a new Log In button and has to guess whether their strategies moved. This adds the welcome card Dara picked (mock 3, "Paged, with actions"): three steps, one at a time, each one something the user can act on.

Mock on the left, the release build on the right, one row per step:

Step 2, mock vs. build (unchanged since the first round):

The walkthrough GIF and the step 2 picture are from the first round. Since then, the step 1 tiles say "On this device" and the drawn Capture button is neutral.

What it does

• Your library is still here. Three small strategy tiles with the library's local badge, "On this device". Next.
• Sign in to sync and share. A tile moving to the cloud from the right-click menu, a synced tile, teammate avatars. Signed out: Sign in opens the existing AuthDialog on top of the card, and a successful sign-in moves on to step 3. Not now skips ahead. Signed in: only Next.
• Turn your matches into strategies. A replay tile with its players and a Capture button. Open Replays closes the card and switches the library to the Replays tab. Done closes it.

Back on steps 2 and 3. The dots show the step and jump on click, and only the current one is violet. The X closes it. Every step is laid out at once (an IndexedStack), so the card keeps the tallest step's height and the buttons never move. The pictures are small widgets built from the real map thumbnails, agent icons and Lucide icons, with the library's own dot grid behind them (welcome_tour_pictures.dart). All the copy is in WelcomeTourCopy at the top of welcome_tour_dialog.dart. The replay step's two strings sit in one marked block there, since what the release says about replays may still change (Icarus reads replays up to VALORANT 13.06 for now). The label says "New in this update", with no version number.

When it shows

showWelcomeTourAtLaunch runs once per app run, after the library's first frame. It shows nothing on the web beta (PlatformPolicy.isWebBeta), nothing once the install has seen it, and nothing on a launch that was asked to open a file or a link (main sets launchOpensFileOrLinkProvider from the launch arguments and the initial deep link, which covers .ica, .vrf, sign-in callbacks and share links). It waits for the update check (Store check, then the direct-install updater's first check, up to 10 s). If an update is waiting, or the check hasn't answered in time, it waits for the next launch instead of stacking on the update dialog. It also waits until the library's WebView warning, if there is one, has been closed. Then it checks the library is the top route, so it never opens over another dialog or the editor. A launch it skips leaves the flag unset, so the next plain launch shows it. Opening the tour from What's new also marks it seen. The launch path checks the flag again after its wait, so a tour the user has already viewed doesn't come back.

An install with no local strategies or folders skips step 1, because its claim is about existing work, so it gets two steps.

"Seen" is a new AppPreferences.welcomeTourSeen field (Hive index 20, default false), set as soon as the card is on screen. Stores written before this field read as false, so updating users see the card once. test/welcome_tour_test.dart writes a record without field 20 and reads it back. No library data changes.

WindowsDesktopUpdateController gains firstCheck, the future of the check it already starts in its constructor, so the tour can tell "no update" from "not known yet".

A way back

What's new gets one quiet link under its title, "Show the welcome tour" (muted, brighter on hover). It closes What's new and opens the tour in its place. It's hidden on the web beta.

Ground truth

Windows release build (--dart-define=ICARUS_CLOUD_ENVIRONMENT=development), each run on its own --hive-store-dir, driven from inside the app by a scratch driver that isn't in this PR:

• Store with local work, signed out. I imported three .ica files (including A site execute.ica), reset the flag, and relaunched. The card was up within about 1.5 s of launch on step 1. Next, then Sign in opened the AuthDialog over the card; closing it returned to step 2. Not now, Back, Not now, then Open Replays landed on the Replays tab (log: tab=replays). The flag read seen=true. On relaunch there was no card. What's new, then "Show the welcome tour", opened it again on step 1.
• Empty store, signed out. Two steps, opening on the account step with Not now and Sign in, then the replays step.
• Signed in (test account, dev deployment): step 2 shows only Next. I checked this twice: once with the session already restored at launch, and once after signing in while the card was open.

Every Icarus build on this PC shares one session file, and someone else's session was in it. To see the signed-out runs without signing anyone out, my scratch build gave Supabase an empty session store when an env var was set. That patch isn't in this PR.

Calls Dara might undo

• The picture on step 3 draws the Capture button as a neutral raised surface, not violet as in the mock. That departure is deliberate: nothing in a picture can be clicked, and DESIGN.md keeps violet for things that can. To bring the mock back, swap Settings.raisedSurface for Settings.raisedPrimary in _CaptureButton.
• The step 1 tiles say "On this device", the library's real local badge, where the mock said "On this computer". The step 1 paragraph keeps the mock's "saved on this computer".
• A fresh install also reads "New in this update", and step 2 mentions bringing "an older one" along. That's the mock's copy; I left it alone.

Review

Round 0: an Opus subagent read the diff statically. It found no blockers. It did find that two widget tests couldn't fail: they re-pumped an identical tree, so the stand-in library never mounted again. The restart test also read the flag back from Hive's cache, not from disk. All three are fixed. From the same review, the WebView warning could open after the tour, and the library now waits for it first.

Astra, round 1: no functional blockers. It confirmed Hive field 20 has no collision and that 4.6.3's reader ignores the unknown index. If someone rolls back and then upgrades again, the tour shows once more, which is acceptable. It found two things, both fixed in the third commit:

• Opening the tour from What's new didn't mark it seen. Marking now happens in the shared WelcomeTourDialog.show, and the launch path rechecks the flag after its wait. A new test opens the tour from What's new while the launch is still waiting on the update check, and checks the tour doesn't show again when the check answers.
• The drawn Capture button was violet. It's neutral now (see above).

A new test also covers an update check that never answers: after 10 s the tour waits for the next launch, and stays put when the check finally answers. For each guard (seen, opened file, once per run, the recheck after the wait, marking in show), I removed it and watched a test fail.

I left the spacing (18/20/6 px) and the 11 px picture text as they are, because they come from the mock.

Not covered

• I didn't see a real update dialog compete with the card. That path is covered by a widget test (update waiting means no card and the flag stays unset), not by a live update.
• macOS: the gate is the same code, but I didn't run it there.
• Something that opens after the card is already up can still stack on it: the auth incident prompt, or a second instance forwarding a share link.
• cloud_startup_test and web_beta_library_test pump the real library on desktop, where the card now appears over it. They now mark the tour as already decided, so they keep testing what they were written for.

ci: analyze test web desktop

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6b2b62ad-4526-425c-81fa-4637344c208b

📥 Commits

Reviewing files that changed from the base of the PR and between b360340 and 147dc00.

📒 Files selected for processing: 13

• lib/hive/hive_adapters.g.dart
• lib/hive/hive_adapters.g.yaml
• lib/main.dart
• lib/providers/user_preferences_provider.dart
• lib/providers/welcome_tour_provider.dart
• lib/services/windows_desktop_update_controller.dart
• lib/widgets/dialogs/release_notes_dialog.dart
• lib/widgets/dialogs/welcome_tour/welcome_tour_dialog.dart
• lib/widgets/dialogs/welcome_tour/welcome_tour_pictures.dart
• lib/widgets/folder_navigator.dart
• test/cloud_startup_test.dart
• test/welcome_tour_test.dart
• test/widgets/web_beta_library_test.dart

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}