Skip to content

fix(onboarding): arm the first-run nudge on the tour's ending, not on a start - #14672

Closed
christian-byrne wants to merge 3 commits into
mainfrom
fix/tour-nudge-outcome
Closed

christian-byrne wants to merge 3 commits into
mainfrom
fix/tour-nudge-outcome

Conversation

@christian-byrne

@christian-byrne christian-byrne commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

Closes #14622

The failure

The post-tour nudge decided its copy from whether a tour started, not from how it ended. useFirstRunTourController set tourWasShown = await engine.startTour('firstRun'), and FirstRunTourNudge.vue rendered the congratulatory ran copy — "That was one of hundreds — You just made your first." — for any truthy value.

So every ending that followed a started tour was congratulated:

  • a tour abandoned because a deferred target never mounted (abandonStep → finish('skipped', { skipReason: 'target_timeout' })) also raises the onboardingCoachmarks.loadError toast. The user got an error toast and a congratulation for the same event.
  • a tour skipped on step 1 was congratulated for a first result the user never made.
  • a tour postponed by the paywall, or ended because its trigger was lost, likewise.

Separately, nudge_shown fired with only { tour: 'firstRun' }, so the funnel could not tell the users the tour never reached from the users who saw one.

The fix

finish() already computes outcome and skipReason but kept them to itself. The store now records them:

export interface TourEnding {
  tour: EntryPath
  outcome: 'completed' | 'skipped'
  skipReason?: OnboardingTourSkipReason
}

exposed as lastEnding, cleared when a new run is requested so a stale ending cannot speak for the run in progress. The controller arms the nudge off that instead of off started.

What each ending shows, and why

ending nudge copy
completed shown ran — there is a first result to congratulate
skipped, skip_reason: user shown noTour
skipped, postponed (paywall) shown noTour
skipped, trigger_lost shown noTour
skipped, target_timeout not shown —
never resolved a step (no ending recorded) shown noTour (unchanged)

Every ending still leaves the user somewhere to go next, so the nudge keeps appearing. What changes is that ran — "You just made your first" — is now reserved for the one ending that made a first result.

The single suppression is the case the issue reported: a tour abandoned because a target never mounted already raises the loadError toast, and a panel arriving beside an error to celebrate it is the sharp case.

I got this wrong first and the cloud e2e caught it. My initial rule suppressed the nudge for every ending finish() calls with markSeen: false, which swept in postponed and trigger_lost too. gettingStartedTour.spec.ts > "leaves the nudge until the upgrade dialog closes" failed, and it was right to: a paywalled tour is parked on a button that will never run, so the templates are the only place left to send that user. The rule is now narrowed to the one ending that raises an error toast of its own. Those two endings keep their nudge and lose only the congratulation.

The judgement call — a deliberate skip. Nudge kept, congratulation dropped. Waving the tour away rejects guidance, not the product; a pointer at the templates is still the right next offer, and it is the one thing the nudge exists to do. What was wrong was claiming the user made something. noTour's copy — "Hundreds more where that came from / Browse the templates and pick something to build" — reads correctly for a skipper, so no new locale key was added (only en carries these keys today; a new one would sit untranslated in the other 11 locales).

Second half — nudge_shown for a tour that never started

Handled. OnboardingTourNudgeMetadata gains a required tour_outcome: 'completed' | 'skipped' | 'not_started', carried by both nudge_shown and explore_templates_clicked. The two populations are now separable downstream, and because both ends of the funnel carry it, conversion is readable per population rather than only in aggregate. I chose the outcome over a ran/noTour copy flag because the copy is derivable from it and the outcome is not derivable from the copy.

Verified

  • pnpm test:unit src/renderer/extensions/firstRunTour/ src/platform/onboarding/ — 23 files, 368 tests, green.
  • New tests gate each ending: five in useFirstRunTourController.test.ts (completed / user-skip / target_timeout / postponed / trigger_lost / never-resolved), three in FirstRunTourNudge.test.ts for the copy each outcome renders, one for the telemetry field, and five in onboardingTourStore.test.ts for lastEnding itself (including that a new run drops the previous ending).
  • Mutation-checked. Reverting armNudge() to the pre-fix behaviour (arm unconditionally; outcome from started) turns 4 of the new controller tests red — congratulates nobody for a tour the user skipped, stays away from a tour a missing target tore down, and both still offers somewhere to go ... cases. Restored, green again.
  • playwright-tests (cloud): red on the first attempt (leaves the nudge until the upgrade dialog closes), which is what drove the narrowing above. Re-running on the fix.
  • pnpm format:check, pnpm lint, pnpm typecheck, pnpm knip all clean.

Not verified

  • The target_timeout suppression has no browser coverage — it needs an 8 s deferred-target timeout to reproduce, and the only e2e that touches the nudge is the paywall one. Unit-level only.
  • CodeRabbit's review (discriminated TourEnding, typed mock ref, per-outcome telemetry matrix) is applied in follow-up commits.
  • tour_outcome is a new property on two existing Mixpanel events. Nothing downstream is updated here; existing dashboards keep working on the untouched tour property, but a dashboard that wants the split needs the new field added.

… a start

`tourWasShown` was set from whether `startTour` returned true, so every
ending that followed a started tour got the `ran` copy — including a tour
the user skipped on step 1 and a tour torn down by a target that never
mounted, which raises a `loadError` toast at the same moment.

`finish()` already computes `outcome` and `skipReason`; the store now
records them as `lastEnding` and the controller reads the ending rather
than the start:

- completed        -> nudge, `ran` copy
- skipped by user  -> nudge, `noTour` copy (no congratulation)
- target_timeout   -> no nudge (the error toast owns that moment)
- postponed        -> no nudge
- trigger_lost     -> no nudge
- never resolved   -> nudge, `noTour` copy (unchanged)

`nudge_shown` and `explore_templates_clicked` now carry `tour_outcome`,
so the population the tour never reached is separable from the one that
saw a tour.

Closes #14622

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@christian-byrne
christian-byrne requested a review from a team August 4, 2026 05:27
@dosubot dosubot Bot added the size:M This PR changes 30-99 lines, ignoring generated files. label Aug 4, 2026
@dosubot

dosubot Bot commented Aug 4, 2026

Copy link
Copy Markdown

📄 Knowledge review

Dosu skipped reviewing this PR because your organization has used its 200 included credits for the month. Your usage will reset on 2026-09-01. To have Dosu review this PR before then, ask your organization admin to upgrade to a pro account.


Leave Feedback Ask Dosu about ComfyUI_frontend Add Dosu to your team

@github-actions

github-actions Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 08/04/2026, 05:53:58 AM UTC

Links

🎭 Playwright: ✅ 1784 passed, 0 failed · 3 flaky

📊 Browser Reports
  • chromium: View Report (✅ 1765 / ❌ 0 / ⚠️ 2 / ⏭️ 5)
  • chromium-2x: View Report (✅ 2 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • chromium-0.5x: View Report (✅ 1 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • mobile-chrome: View Report (✅ 16 / ❌ 0 / ⚠️ 1 / ⏭️ 0)

📦 Bundle: 8.24 MB gzip 🔴 +483 B

Details

Summary

  • Raw size: 34.6 MB baseline 34.6 MB — 🔴 +1.41 kB
  • Gzip: 8.24 MB baseline 8.24 MB — 🔴 +483 B
  • Brotli: 5.71 MB baseline 5.71 MB — 🔴 +413 B
  • Bundles: 427 current • 427 baseline • 3 added / 3 removed

Category Glance
Graph Workspace 🔴 +1.41 kB (1.35 MB) · Vendor & Third-Party ⚪ 0 B (15.7 MB) · Other ⚪ 0 B (12.8 MB) · Data & Services ⚪ 0 B (3.47 MB) · Panels & Settings ⚪ 0 B (551 kB) · Utilities & Hooks ⚪ 0 B (386 kB) · + 5 more

App Entry Points — 3.64 kB (baseline 3.64 kB) • ⚪ 0 B

Main entry bundles and manifests

File Before After Δ Raw Δ Gzip Δ Brotli
assets/index-CCZYl0Bx.js (removed) 3.64 kB — 🟢 -3.64 kB 🟢 -1.82 kB 🟢 -1.58 kB
assets/index-DxiH49d6.js (new) — 3.64 kB 🔴 +3.64 kB 🔴 +1.81 kB 🔴 +1.59 kB

Status: 1 added / 1 removed

Graph Workspace — 1.35 MB (baseline 1.35 MB) • 🔴 +1.41 kB

Graph editor runtime, canvas, workflow orchestration

File Before After Δ Raw Δ Gzip Δ Brotli
assets/GraphView-C-geHh8Z.js (new) — 1.35 MB 🔴 +1.35 MB 🔴 +294 kB 🔴 +221 kB
assets/GraphView-CM-OFHJT.js (removed) 1.35 MB — 🟢 -1.35 MB 🟢 -293 kB 🟢 -221 kB

Status: 1 added / 1 removed / 1 unchanged

Views & Navigation — 111 kB (baseline 111 kB) • ⚪ 0 B

Top-level views, pages, and routed surfaces

Status: 16 unchanged

Panels & Settings — 551 kB (baseline 551 kB) • ⚪ 0 B

Configuration panels, inspectors, and settings screens

Status: 26 unchanged

User & Accounts — 28.7 kB (baseline 28.7 kB) • ⚪ 0 B

Authentication, profile, and account management bundles

Status: 10 unchanged

Editors & Dialogs — 124 kB (baseline 124 kB) • ⚪ 0 B

Modals, dialogs, drawers, and in-app editors

Status: 7 unchanged

UI Components — 70 kB (baseline 70 kB) • ⚪ 0 B

Reusable component library chunks

Status: 15 unchanged

Data & Services — 3.47 MB (baseline 3.47 MB) • ⚪ 0 B

Stores, services, APIs, and repositories

Status: 17 unchanged

Utilities & Hooks — 386 kB (baseline 386 kB) • ⚪ 0 B

Helpers, composables, and utility bundles

Status: 36 unchanged

Vendor & Third-Party — 15.7 MB (baseline 15.7 MB) • ⚪ 0 B

External libraries and shared vendor chunks

Status: 16 unchanged

Other — 12.8 MB (baseline 12.8 MB) • ⚪ 0 B

Bundles that do not match a named category

File Before After Δ Raw Δ Gzip Δ Brotli
assets/main-BXqkoWrp.js (removed) 47 kB — 🟢 -47 kB 🟢 -13.9 kB 🟢 -12 kB
assets/main-D6V52-wd.js (new) — 47 kB 🔴 +47 kB 🔴 +13.9 kB 🔴 +12 kB

Status: 1 added / 1 removed / 280 unchanged

⚡ Performance

⏳ Performance tests in progress…

@coderabbitai

coderabbitai Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The onboarding store now records the last tour ending. The first-run controller exposes tourOutcome and filters nudge activation by ending reason. The nudge selects copy and includes the outcome in telemetry.

Changes

Onboarding tour outcome tracking

Layer / File(s) Summary
Tour ending state
src/platform/onboarding/onboardingTourStore.ts, src/platform/onboarding/onboardingTourStore.test.ts
The store exposes lastEnding, records completed and skipped endings, and clears stale ending data when a new tour starts.
Outcome-aware nudge control
src/platform/telemetry/types.ts, src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts, src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
The controller replaces tourWasShown with tourOutcome and distinguishes completed, skipped, not-started, target-timeout, postponed, and trigger-lost endings.
Nudge copy and telemetry
src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue, src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts
Only completed tours use congratulatory copy. Nudge display and template exploration telemetry include tour_outcome.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant onboardingTourStore
  participant useFirstRunTourController
  participant FirstRunTourNudge
  participant Telemetry
  onboardingTourStore->>useFirstRunTourController: provide lastEnding
  useFirstRunTourController->>useFirstRunTourController: derive tourOutcome
  useFirstRunTourController->>FirstRunTourNudge: provide tourOutcome
  FirstRunTourNudge->>Telemetry: record tour_outcome
Loading

Possibly related PRs

Suggested labels: core/1.49, cloud/1.49

Suggested reviewers: drjkl


Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
End-To-End Regression Coverage For Fixes ❓ Inconclusive The changed files and description are available, but the PR title and commit subjects are not provided, so the required bug-fix signal cannot be verified. Provide the PR title and commit subjects, then reassess whether the end-to-end regression-test requirement applies.
✅ Passed checks (5 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The changes address both residuals in issue #14622 by using tour endings for nudge behavior and adding outcome telemetry.
Out of Scope Changes check ✅ Passed The store, controller, nudge, telemetry, and test changes directly support the linked issue objectives with no unrelated code changes.
Adr Compliance For Entity/Litegraph Changes ✅ Passed The changed files are under onboarding and telemetry paths. None are under src/lib/litegraph/, src/ecs/, or graph-entity-related files.
Title check ✅ Passed The title clearly describes changing first-run nudge arming from tour start to tour ending.
Description check ✅ Passed The description clearly covers the problem, implementation, outcome rules, telemetry changes, testing, and remaining verification limits.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/tour-nudge-outcome

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/platform/onboarding/onboardingTourStore.ts`:
- Around line 36-40: Update TourEnding from a single interface into a
discriminated union keyed by outcome: require skipReason for skipped endings and
disallow it for completed endings. Adjust finish() to construct the appropriate
explicit union branch so completed results omit skipReason while skipped results
include it.

In `@src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts`:
- Line 18: Update the mock tourOutcome declaration in FirstRunTourNudge.test.ts
to import OnboardingTourNudgeOutcome from `@/platform/telemetry/types` and use it
as the ref generic, replacing the duplicated string union while preserving the
existing initial value.
- Around line 184-211: Expand the FirstRunTourNudge telemetry tests around the
existing “says which population it was shown to” coverage by adding
parameterized cases for completed, skipped, and not_started outcomes. Verify
each outcome is reported correctly for both nudge_shown and
explore_templates_clicked, reusing the existing test setup and tracking symbols
such as mocks.tourOutcome, mocks.trackOnboardingTour, and renderNudge; preserve
the current assertions for the nudge copy and include the required
interruption/timeout coverage if those outcomes are supported by the test
fixtures.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0ecfbea3-93e2-4732-b179-d0bcd8790218

📥 Commits

Reviewing files that changed from the base of the PR and between 3988850 and 483f1ae.

📒 Files selected for processing (7)
  • src/platform/onboarding/onboardingTourStore.test.ts
  • src/platform/onboarding/onboardingTourStore.ts
  • src/platform/telemetry/types.ts
  • src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts
  • src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts

Addresses CodeRabbit review on #14672:

- `skipReason` is now required on `skipped` and absent on `completed`,
  so a writer cannot record a skip without saying why. `finish()` builds
  the two branches explicitly.
- the nudge test's mock ref uses `OnboardingTourNudgeOutcome` rather than
  a duplicated inline union.
- both `nudge_shown` and `explore_templates_clicked` are now covered for
  all three outcomes (`it.for`, per the repo's consistent-each-for rule)
  so a hard-coded or stale outcome is caught.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
coderabbitai[bot]
coderabbitai Bot previously approved these changes Aug 4, 2026
@codecov

codecov Bot commented Aug 4, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main   #14672   +/-   ##
=======================================
  Coverage   78.46%   78.46%           
=======================================
  Files        1790     1790           
  Lines      105382   105395   +13     
  Branches    33052    33059    +7     
=======================================
+ Hits        82683    82696   +13     
+ Misses      22264    22257    -7     
- Partials      435      442    +7     
Flag Coverage Δ
unit 70.79% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/platform/onboarding/onboardingTourStore.ts 97.11% <100.00%> (+0.08%) ⬆️
src/platform/telemetry/types.ts 100.00% <ø> (ø)
...xtensions/firstRunTour/nudge/FirstRunTourNudge.vue 97.43% <100.00%> (ø)
...ons/firstRunTour/tour/useFirstRunTourController.ts 100.00% <100.00%> (ø)

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The cloud e2e caught this: `gettingStartedTour.spec.ts` > "leaves the
nudge until the upgrade dialog closes" asserts the nudge appears after a
paywall-parked tour, and it is right to. That tour is stuck on a button
that will never run, so the templates are the only place left to send
the user.

Suppressing on `markSeen: false` swept up `postponed` and `trigger_lost`
along with the case the issue actually reported. Narrowed to the one
ending that raises an error toast of its own — `target_timeout` — which
is the "error toast and a congratulation for the same event" in #14622.

`postponed` and `trigger_lost` keep their nudge and now get the `noTour`
copy instead of the congratulation they used to get.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@christian-byrne

Copy link
Copy Markdown
Contributor Author

@MaanilVerma you are right and I am withdrawing the visibility half of this.

Your decision that the nudge is outcome-blind is deliberate and documented — your #14144 comment says it directly: "a user who saw no tour is the one who most needs somewhere to go next, so suppressing it there removes the way forward. What was wrong was the copy claiming they'd made something." And you had already shipped exactly that: main reads ${tourWasShown.value ? 'ran' : 'noTour'}.

So this PR suppressing the nudge on target_timeout / postponed / trigger_lost contradicts a call you had already made, tested, and explained. I re-litigated it without reading your response first. My reasoning was that an error toast plus a congratulation for the same event reads badly — but that is a copy problem, which you had already fixed, not a reason to take away the way forward. Your framing is better.

Reduced to the one piece that is genuinely additive, if you want it: tour_outcome on the nudge telemetry. OnboardingTourNudgeMetadata is currently { tour: string }, so nudge_shown and explore_templates_clicked cannot be split by how the tour ended — a completed-tour conversion and a never-started one land in the same bucket. Adding a required tour_outcome: 'completed' | 'skipped' | 'not_started' makes the funnel readable per population without changing a single visibility rule.

If that is useful, say so and I will strip this branch to just that. If not, close it — no argument from me on the visibility behaviour.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Follow-up — the branch narrowed since my last comment, and the repo's own e2e is what forced it. Worth recording because it argues partly against me.

My first version suppressed the nudge for every ending finish() marks markSeen: false. That swept in postponed (paywall) and trigger_lost along with the abandoned case. gettingStartedTour.spec.ts > "leaves the nudge until the upgrade dialog closes" went red, and it was right to — a paywalled tour is parked on a button that will never run, so templates are the only remaining place to send that user. That expectation was already written down here with a reasoned comment, and I overrode it.

The mistake was conflating two different questions: markSeen: false is about whether the tour gets re-offered, not about whether the user needs a next step.

So the branch is now down to one ending — target_timeout, the only one that fires an error toast of its own. That is exactly the "error toast and a congratulation for the same event" case. Everything else keeps its nudge and loses only the congratulation:

ending nudge copy
completed shown ran
skipped / user · postponed · trigger_lost shown noTour
skipped / target_timeout suppressed —
never resolved shown noTour

@MaanilVerma that reduces the disagreement to a single question, and it is yours to settle: when the tour dies with a "something went wrong" toast on screen, should the nudge still appear? Everything else now matches your outcome-blind rule.

If your answer is still "always visible", say so and I will strip this to the tour_outcome telemetry only — that changes no visibility rule at all. I am not going to argue it past your call.

373 unit tests green; typecheck, lint, format, knip clean; mutation check still turns 4 controller tests red.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Closing — @MaanilVerma's call that the nudge stays outcome-blind, and he'd already documented why on #14144: "a user who saw no tour is the one who most needs somewhere to go next." He'd also already fixed the real bug, the copy — main reads tourWasShown ? 'ran' : 'noTour'.

Recording two things that came out of this so they aren't lost with the branch:

The repo's own e2e caught my agent overreaching. The first rule suppressed the nudge for every ending marked markSeen: false, which swept in the paywall case. gettingStartedTour.spec.ts > "leaves the nudge until the upgrade dialog closes" went red — correctly. markSeen: false is about whether the tour gets re-offered, not whether the user needs a next step; those are different questions and I conflated them.

The one genuinely additive piece, if anyone wants it later: OnboardingTourNudgeMetadata is { tour: string }, so nudge_shown and explore_templates_clicked can't be split by how the tour ended — a completed-tour conversion and a never-started one land in the same bucket. A tour_outcome field would make the funnel readable per population without touching any visibility rule. Not opening a PR for it unasked.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Correcting myself on the reason I gave for closing this.

I wrote that the copy bug was already fixed on main because it reads tourWasShown ? 'ran' : 'noTour'. That is wrong. tourWasShown is assigned from started (useFirstRunTourController.ts:158) — the return of engine.startTour(), i.e. a tour began, not the user completed one. So on main today:

ending tourWasShown copy shown
never appeared false noTour ✓
skipped on step 1 true ran — "You just made your first"
abandoned (target_timeout) true ran — alongside the loadError toast

So the sharp case from the original issue — an error toast and a congratulation for the same event — is still live. @MaanilVerma's fix covered the never-started case, which is the one his probe reproduced.

Closing this PR was still right: it changed visibility, and outcome-blind is his call. But the copy half is orthogonal to that call and is the thing he himself named as the actual defect — "What was wrong was the copy claiming they'd made something."

Opening a narrow follow-up that keeps the nudge always visible and only chooses ran vs noTour from the ending. That contradicts nothing and fixes what's left.

pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Aug 5, 2026
…ded (Comfy-Org#14677)

## Summary

The first-run nudge picked its copy from whether a tour _started_, so a
user who skipped on step 1 — or one whose tour was torn down by a target
that never mounted — was congratulated for a first result they never
made. This makes the copy follow how the tour actually ended. **The
nudge's visibility is unchanged: every ending still shows it.**

## The defect

`FirstRunTourNudge.vue` chose its copy with `` `…nudge.${tourWasShown ?
'ran' : 'noTour'}` ``, and `tourWasShown` was assigned from `started` —
the return of `engine.startTour()` in `useFirstRunTourController.ts` —
which means _a tour began_, not _the user completed one_:

| ending | copy before | copy now |
| -------------------------------- |
------------------------------------------------ | -------- |
| completed | `ran` | `ran` |
| never appeared | `noTour` ✓ | `noTour` |
| **skipped on step 1** | **`ran`** — "You just made your first" |
`noTour` |
| **abandoned (`target_timeout`)** | **`ran`**, shown alongside the
`loadError` toast | `noTour` |
| postponed (paywall) | `ran` | `noTour` |
| `trigger_lost` | `ran` | `noTour` |

The abandoned case is the sharp one: the same event raises an error
toast and a congratulation.

## Changes

- **What**: `finish()` in `onboardingTourStore.ts` already computes
`outcome` and `skipReason`; the store now hands that on as `lastEnding`
(a discriminated union, cleared when a new run is requested so the
previous ending cannot speak for it). `useFirstRunTourController`
derives `tourWasCompleted` from it in place of `tourWasShown`, and the
nudge reserves the `ran` copy for `completed`. Every other ending gets
`noTour`, which reads as "here's where to go next" for a skipper or an
abandoner.
- **Breaking**: none. `lastEnding` is additive; `tourWasShown` had
exactly one consumer (the nudge).

## Visibility is deliberately unchanged

Every ending still arms the nudge, including the ones that now read as
`noTour`. That is @MaanilVerma's product decision in Comfy-Org#14144: _"a user
who saw no tour is the one who most needs somewhere to go next, so
suppressing it there removes the way forward."_ Comfy-Org#14672 tried to suppress
the nudge on the abandoned ending and was closed for exactly this reason
— this PR treats the copy, not the visibility, as the defect.

The regression guard for that is `still offers the nudge after a tour
$named` in `useFirstRunTourController.test.ts`, which asserts
`nudgeArmed` for all five endings, plus a sixth test for the
never-started case and a component-level check that the nudge renders
whether or not the tour finished.

## Tests

New coverage, 19 tests:

- `onboardingTourStore.test.ts` (6) — the ending recorded for a user
skip, a `target_timeout` teardown, a `trigger_lost` teardown, a
walked-to-the-end tour; that a running tour has no ending; that a new
run drops the last one.
- `useFirstRunTourController.test.ts` (10, plus an existing
never-started test extended to assert visibility) — `completed` →
congratulation; `user` / `target_timeout` / `postponed` / `trigger_lost`
→ none; **all five endings still arm the nudge**; never-started arms it
too, with no congratulation.
- `FirstRunTourNudge.test.ts` (3) — completed → `ran`, unfinished →
`noTour`, and the nudge appears either way.

### Mutation evidence

- Revert the rule to the old semantics (`tourWasCompleted = ending?.tour
=== 'firstRun'`, i.e. "a tour ran"): **4 failed | 45 passed**. The four
are the skipped/abandoned/postponed/lost-context copy cases. The five
visibility tests stayed green, confirming they are not coupled to the
copy rule.
- Pin the component's copy key to `ran`: **1 failed | 10 passed**. Pin
it to `noTour`: **1 failed | 10 passed**.
- Restored: **374 passed (23 files)** across
`src/renderer/extensions/firstRunTour` and `src/platform/onboarding`.

`pnpm install --frozen-lockfile`, `format:check`, `lint`, `typecheck`
and `knip` all clean.

## Review Focus

- `lastEnding` carries `skipReason` although no production code reads it
today — the tests name each ending, so the reason has to be observable,
and it is the shape `finish()` already computes. Say the word if you
would rather it be trimmed to `{ tour, outcome }`.
- The controller latches `tourWasCompleted` when the nudge arms rather
than deriving it live, so a later tour ending cannot rewrite the copy of
a nudge already on screen.
- Not verified: no e2e run. `gettingStartedTour.spec.ts` → "leaves the
nudge until the upgrade dialog closes" asserts visibility only
(postponed still arms), and no e2e or unit test elsewhere asserts the
nudge's copy strings — checked by grep, not by running Playwright.
- Telemetry is untouched: `nudge_shown` and `explore_templates_clicked`
still report only `{ tour: 'firstRun' }`, so the funnel still cannot
tell a toured user from a tour-less one. That is a real gap, and
deliberately out of scope here.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

First-run tour nudge: congratulates users whose tour was abandoned or skipped, and appears for tours that never started

2 participants