Skip to content

feat(onboarding): first-run graph tour on curated templates - #14298

Closed
deepme987 wants to merge 138 commits into
mainfrom
deepme987/onboarding/graph-tour-lite
Closed

deepme987 wants to merge 138 commits into
mainfrom
deepme987/onboarding/graph-tour-lite

Conversation

@deepme987

@deepme987 deepme987 commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR

  • New cloud users get a Getting Started takeover (4 curated templates) on their first launch instead of the template browser.
  • Picking a card loads the template and runs a guided tour on the live graph: upload → prompt → run → result, ending on an Explore templates hand-off.
  • Fully flag-gated (onboarding_tour_enabled, internal comfy.org rollout); everyone else keeps today's behavior exactly.
  • Dark until the companion backend PR deploys: Comfy-Org/cloud#5849.

What this does

  • Startup now reports what it did (restored | fresh | url-intent) instead of silently burning Comfy.TutorialCompleted — the flag is only ever written on a real user action (pick, dismiss, or the browse-once fallback).
  • Takeover (fresh startup + candidate only): full-screen four-card grid; Escape or "start blank" exits to canvas; empty catalog falls back to the template browser; everyone non-candidate gets the template browser once, as before.
  • The tour:
    • steps come from per-template role pins ({id, type} per role), re-validated against the live graph — subgraph pins resolve to their root host node; a drifted pin drops its step, never a wrong spotlight
    • the camera flies to each node (instant under reduced-motion / DisableAnimations); tour start waits for the Nodes 2.0 mount to settle so the first flight isn't janky
    • canvas is locked during the tour, but node interiors stay fully usable through the spotlight hole (swap the upload image, type the prompt)
    • run step: the card's primary button is Run and drives the real run button — funded click queues and advances; out-of-runs click opens the pricing dialog and postpones the tour (re-offers after subscribing); a refused prompt flips the result copy to failure
    • result step: "Hang tight" + spinner while generating → image/video copy on success → Explore templates CTA opens the template library
  • Engine additions (platform/onboarding): onEnter(signal), lazy sync tour definitions + registerTour, interactive / selfAdvancing / busy / primaryAction step fields, postpone().

Quick flowchart

image

Rollout

  • PostHog onboarding_tour_enabled in prod (789788) + staging (789789), email icontains comfy.org @ 100%.
  • cloud#5849 registers the flag in /api/features — required for the frontend to see it.

Video

Onboarding.mp4

Testing

  • 164 unit tests across entry gating, role resolution, tour definition, run controller, camera framing, and the tour store.
  • QA: comfy.org account + fresh browser profile → first launch shows the takeover. Dev builds also honor localStorage['ff:onboarding_tour_enabled']='true'.

Known gaps

pythongosssss and others added 30 commits June 29, 2026 14:48
- add blank canvas (demo) and app mode (wip) tours
- overlay with target highlight, landing card, step state handling, step card
- v-coachmark directive updating registry for mount/unmount
- frame settling watcher for animated targets (dialogs)
- focus trap for the target plus the coachmark element
- add telemetry for each step
- move tour trigger to linear controls section
- onboardingTours: use 'auto' placement for assets panel so the card follows the sidebar side
- TourOverlay: clamp no-target card left to the viewport margin so it never goes off-screen
- useCoachmarkTour: catch onPrimary action failures, surface a toast, and only advance on success
- useCoachmarkTour: claim the single-instance guard synchronously so a duplicate mount stays inert
- useFocusTrap: send Shift+Tab from outside the trap to the last item instead of skipping it
- telemetry: drop dead run-button imports left over from the rebase (superseded by getRunButtonTelemetryProperties)
- Open the tour only via the help button or ?coach= param (no auto-open
  when entering app mode)
- Drop the loadTemplate step tech and the demo card image — the tour runs
  on the user's existing app
- Skip the assets-button step at tour start when the assets panel is
  already open; step indicator counts 4 instead of 5
- Open the app-mode tour when entering an app with linear controls
  visible (mode === 'app' && hasOutputs), including when the overlay
  mounts into one already (immediate watch)
- Respect the seen-flag, so it won't reopen once completed or skipped;
  skip the empty/welcome state and arrange (builder) mode
- Move test target DOM cleanup into afterEach so appended nodes are
  removed even if a test fails early
- Track the spotlight target with VueUse useElementBounding instead of a
  hand-rolled measure/RAF/ResizeObserver loop; keep a capture-phase scroll
  listener so it still follows targets inside scrollable panels
- Fold the spotlight ring into the dim element (CSS outline + box-shadow),
  dropping the separate SVG; the idle pulse now animates outline-color
- Remove the unused CoachStep `elevated` field and its plumbing
Reka's built-in Escape dismissal proved unreliable for this dialog in
e2e (Skip, which sets open=false directly, works); close via the same
model path on Escape so the welcome landing reliably dismisses.
Trimming the graph-mode anchors earlier removed the templates-button
click that loadTemplate relied on to open the browser; open it via the
Comfy.BrowseTemplates command instead.
Extract TourSpotlight, rendered only while a spotlight step is shown, so the
geometry/scroll, focus-trap and click-to-advance listeners (plus z-index and the
stall pulse) register for the active step rather than the whole graph-view
session. useCoachmarkTour slims to the state machine; the registry-query helpers
(targetMounted/waitForTarget) move to coachmarkRegistry and useCoachmarkTarget
becomes geometry-only and self-measuring.

Also from review feedback:
- read the ?coach= force in setup, before the immediate auto-open watcher, so an
  already-populated app no longer drops a ?coach=any replay
- harden isEntryPath against prototype keys (Object.hasOwn)
- decouple each tour's auto-open condition into useTourTriggers, keeping the
  engine tour-agnostic
Conflict in LinearControls.vue: main refactored the run-button test id into a
named constant (linearRunButtonTestId, same 'linear-run-button' value), while
this branch added the v-coachmark anchor and a static test id to the same
sections. Kept the coachmark directive and adopted main's :data-testid binding,
dropping the now-redundant static id.
Raise useCoachmarkTour.ts to full line coverage and TourSpotlight.vue escape handling with behavioral tests.
- Replace the hand-rolled card-placement math (resolvePlacement /
  cardCorner / clampCardPosition) and the manual target tracking (scroll
  listener + useElementBounding + rAF settle loop) with @floating-ui/vue
  (offset/flip/shift + autoUpdate); promote it from a transitive to a
  direct dependency.
- Keep vertically-centred (leftCenter) cards on-screen with
  shift({ crossAxis: true }), and centre the card when its target hasn't
  laid out, so a step never renders off-screen or invisible.
- Make targetMounted/waitForTarget layout-aware (poll per frame) so a
  deferred target that registers before it sizes resolves only once
  measurable, matching what the spotlight actually displays.
- Shrink the spotlight glow (pad 8->4) so it no longer spills onto an
  adjacent control the user might click.
- Label the spotlight dialog with aria-labelledby pointing at its heading
  instead of a duplicated aria-label.
- Drop the unused isActive option from useFocusTrap.
- Add an e2e guard that walks every app-mode spotlight step and asserts
  each card sits fully within the viewport; add unit coverage for
  last-step Skip hiding, modal z-index reclaim, and all four onboarding
  telemetry stages.
- Drive Floating UI autoUpdate manually so animationFrame polling runs
  only while a deferred target is still moving, then fall back to
  scroll/resize listeners instead of polling every frame for the whole step
- Set aria-modal to false on interaction steps where the user must click
  outside the card
- Ignore unrecognized ?coach= values; keep `any` as the replay keyword
- Align the spotlight scrim with the landing backdrop (0.62 -> 0.6) to
  avoid a dim shift on landing -> spotlight
- Export COACH_IDS and import it in the drift guard instead of a hardcoded
  in-sync list
- Clarify why the landing needs an explicit Escape listener (Reka's
  DismissableLayer doesn't fire update:open here)
- Test that the started telemetry event omits step_index/coach_id while
  per-step events include them

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Report the timed-out deferred step in skip telemetry by advancing the
  step index before ending the tour, instead of logging the prior step
- Make the ?coach= override one-shot: named paths force-start only via the
  delayed timer (respecting START_DELAY_MS) and re-entry honors the
  seen-flag again, rather than bypassing it all session
- Resolve waitForTarget to false immediately when the signal is already
  aborted, so it can't hang until timeout
- Reuse the cached dialog locator in Tour.cardForStep
- Drop the ?coach= query param: remove the forced-entry/replay-any override
  and delayed force-start; tours now start only via auto-open or an explicit
  request. E2E replays via the in-app help button after entering app mode
- Flatten coachmarkController to plain requestTour/onTourRequested exports
  instead of a useCoachmarkController composable
- Derive the top-bar safe inset from the --comfy-topbar-height token plus
  CARD_GAP instead of hardcoding 56
- Remove the landing Start button's fixed width
- Document the real cause of the landing Escape workaround (global keybinding
  preventDefaults Escape before Reka's DismissableLayer dismisses)
- Trim verbose comments in coachmarkRegistry and TourOverlay tests
- Show public/assets/images/app-mode-landing.png on the welcome landing's
  left panel
…otes

- clear the spotlight's previous ZIndex entry before re-raising, so step
  changes stop leaking entries into the shared modal stacking sequence
- report tour telemetry as the user-visible numbering: 1-based step_number
  within counted spotlight steps, omitted for the landing
- seed the e2e seen-tours setting from TOURS so future tours can't
  auto-open under unrelated suites
- derive step translation keys from a step `name`
  (onboardingCoachmarks.<tour>.<name>.*), with te()-checked
  primary/skip label overrides falling back to Next/Done/Skip
- move all tour i18n into the engine; TourOverlay and TourSpotlight
  now receive translated title/body strings
- replace the landing's required open model with a skip emit and
  drop the landingOpen writable computed
- simplify TourOverlay.test.ts mocks with fromPartial
- replace SCRIM_COLOR with Tailwind classes (bg-black/60,
  spotlight spread shadow)
- narrow the app-run-button anchor so the spotlight excludes the
  run error warning
- key the e2e tour fixture's replay button by tour name
- drop the tour spec's template loading; the test server's default
  workflow already populates the graph (locally: pnpm dev:test)
- prune comments that restated code
- tour step keys are built as onboardingCoachmarks.<tour>.<name>.*, so
  the literal-key scan can't see them
- a single sync() replaces the per-hook register/unregister logic;
  mounted/updated/unmounted all reconcile desired vs current id
- drops the oldValue bookkeeping and its explanatory comment

@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.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue (1)

114-119: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not complete onboarding until beginTour() succeeds.

beginTour() returns Promise<boolean> and returns false when the tour engine cannot start. Lines 117-118 currently persist dismissal before ignoring that result, so a failed start hides the picker and prevents retrying the tour. Check the result before persisting completion and keep the picker visible or show an actionable error on failure.

Proposed fix
-    await dismissGettingStarted()
-    await useFirstRunTourController().beginTour(id)
+    const started = await useFirstRunTourController().beginTour(id)
+    if (!started) return
+    await dismissGettingStarted()
🤖 Prompt for 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.

In `@src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue`
around lines 114 - 119, Update pick so it awaits and checks the boolean result
from useFirstRunTourController().beginTour(id) before calling
dismissGettingStarted(). Only persist onboarding dismissal and complete the flow
when beginTour succeeds; when it returns false, leave the picker visible or
surface an actionable error so the user can retry.
🤖 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.

Outside diff comments:
In
`@src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue`:
- Around line 114-119: Update pick so it awaits and checks the boolean result
from useFirstRunTourController().beginTour(id) before calling
dismissGettingStarted(). Only persist onboarding dismissal and complete the flow
when beginTour succeeds; when it returns false, leave the picker visible or
surface an actionable error so the user can retry.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7a2e85bc-6d32-4429-ac59-d7b912ea6108

📥 Commits

Reviewing files that changed from the base of the PR and between de03d38 and 4475c8f.

📒 Files selected for processing (2)
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts

@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: 4

🤖 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/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.test.ts`:
- Around line 65-76: Make cleanup of the ff:force_first_run localStorage flag
unconditional in the forces-the-takeover test, using try/finally or the test
suite’s afterEach hook so it runs even when assertions or setup fail. Preserve
the existing test behavior and assertions while preventing localStorage state
from leaking into later tests.

In `@src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts`:
- Around line 51-52: In the first-run entry flow, update the ordering around
useSettingStore().set and useCommandStore().execute so Comfy.BrowseTemplates
completes successfully before persisting Comfy.TutorialCompleted. Allow
execute() failures to propagate without marking the tutorial complete,
preserving retry behavior when the command is unavailable or its handler fails.

In
`@src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue`:
- Line 115: Update the empty-template handling near templates.value to call
fallBackToBrowse() instead of hideGettingStarted(). Preserve the existing
behavior for non-empty curated templates while ensuring users with no resolved
templates are routed to Comfy.BrowseTemplates.

In `@src/services/useNewUserService.ts`:
- Around line 8-12: Update the parsed.entries validation to reject arrays and
accept only non-null object maps. Before evaluating history in the surrounding
onboarding logic, validate every entry is a non-null, non-array object whose
isTemporary property is absent or boolean; return false for any malformed entry,
and preserve the existing some() behavior for valid entries.
🪄 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: 30570076-f3a5-4788-bef8-5c2c3d0a155c

📥 Commits

Reviewing files that changed from the base of the PR and between 4475c8f and c8495a3.

📒 Files selected for processing (4)
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.test.ts
  • src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts
  • src/services/useNewUserService.ts

Comment thread src/services/useNewUserService.ts Resolved
@deepme987
deepme987 force-pushed the deepme987/onboarding/graph-tour-lite branch from 21705ae to 7567dca Compare July 30, 2026 02:37
…graph-tour-lite

# Conflicts:
#	src/platform/workflow/persistence/composables/useWorkflowPersistenceV2.ts
@deepme987
deepme987 marked this pull request as ready for review July 30, 2026 03:57
@deepme987
deepme987 requested a review from a team July 30, 2026 03:57
@dosubot dosubot Bot added the size:XL This PR changes 500-999 lines, ignoring generated files. label Jul 30, 2026
@dosubot

dosubot Bot commented Jul 30, 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-08-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

Comment thread src/views/GraphView.vue
<UnloadWindowConfirmDialog v-if="!isDesktop" />
<MenuHamburger />
<TourOverlay v-if="graphReady" />
<GettingStartedScreen v-if="gettingStartedVisible" />

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

note: this is a known tech-debt. will fast-follow. We want to make non-graph views be easily used while keeping the other layout same. For eg: home page, recent, potentially, agent only view, etc

coderabbitai[bot]
coderabbitai Bot previously approved these changes Jul 30, 2026
@deepme987 deepme987 closed this Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants