Skip to content

feat(first-run-tour): run the tour from a picked template - #14143

Merged
christian-byrne merged 168 commits into
mainfrom
feat/first-run-tour
Aug 4, 2026
Merged

christian-byrne merged 168 commits into
mainfrom
feat/first-run-tour

Conversation

@MaanilVerma

@MaanilVerma MaanilVerma commented Jul 27, 2026 •

Copy link
Copy Markdown
Collaborator

Stack — 4 of 6. Rebuilt from scratch after the review on #13725, split into short PRs.
Based on #13290 (coachmark engine); each PR stacks on the one before it.

  1. feat(onboarding): teach the coachmark engine canvas targets #14140 — engine: canvas targets for the coachmark tour
  2. feat(first-run-tour): add the Getting Started screen #14141 — Getting Started screen + entry gating
  3. feat(first-run-tour): resolve tour roles from pinned nodes #14142 — role pins + live drift guard
  4. feat(first-run-tour): run the tour from a picked template #14143 — the tour itself + e2e walk ← this PR
  5. feat(first-run-tour): offer templates once the tour ends #14144 — post-tour nudge
  6. feat(first-run-tour): read tour roles off an unpinned graph #14145 — unpinned workflows (share / template links)

Summary

The tour a new user actually walks: upload, prompt, run, result. Steps come from the resolved roles, targets are canvas nodes registered with the engine, and the engine renders and advances them. The parallel overlay stack from the previous attempt is conspicuously absent.

Changes

  • TOURS.firstRun builds real CoachSteps with coachIds and registered canvas targets, so the engine's spotlight, positioning, copy resolution and telemetry all apply.
  • Camera framing is a glide then a fit against a known duration. No settle detection, no watchdog — animateToBounds is wall-clock, so the end time is already known. Reduced motion frames instantly rather than skipping.
  • The Run step gates on the paywall, consuming the click so the underlying handler never queues a refused run.
  • Run outcomes are matched to the tour's own workflow through the execution store, so a job queued elsewhere can't speak for the tour.
  • The tour turns Nodes 2.0 on when it starts: every step names a [data-node-id], and a new user has no Comfy.InstalledVersion, so the versioned default never applies and the setting reads off. If no tour then starts, the switch is undone.
  • A Playwright walk: fresh profile → Getting Started → pick a template → steps → Run → result.

From the review round (c504c6a, 48358e6)

  • A rejecting tour resolver used to escape begin() and leave the engine stuck at resolving, refusing every later start. It now resolves to no steps.
  • beginTour consulted the engine only after persisting the renderer switch, mutating the tour registry and waiting out the preview. It bails first, and undoes only a switch it made itself.
  • The Run-button interceptor keyed on step.name === 'run', so renaming a translation key changed control flow. It reads selfAdvancing.
  • A registered tour can now carry the condition it runs under, so the first-run tour is torn down when the layout its coachmarks need goes away — same path as a trigger's, without the seen flag.
  • The Result step's spinner is gone. Its predicate was the same expression as the copy beside it, and it kept spinning when a run ended without a recorded status.

Review focus

No feature-layer RAF, no second overlay, no second i18n namespace, no inline telemetry — the engine owns all of it. Worth knowing: onboarding is one-shot by design. A run that fails still ends the tour; the user sees a "didn't finish" card and moves on.

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
@christian-byrne
christian-byrne added this pull request to the merge queue Aug 4, 2026
j0n4t pushed a commit to j0n4t/ComfyUI_frontend that referenced this pull request Aug 4, 2026
…#14142)

> **Stack — 3 of 6.** Rebuilt from scratch after the review on Comfy-Org#13725,
split into short PRs.
> Based on Comfy-Org#13290 (coachmark engine); each PR stacks on the one before
it.
>
> 1. Comfy-Org#14140 — engine: canvas targets for the coachmark tour
> 2. Comfy-Org#14141 — Getting Started screen + entry gating
> 3. Comfy-Org#14142 — role pins + live drift guard  ← this PR
> 4. Comfy-Org#14143 — the tour itself + e2e walk
> 5. Comfy-Org#14144 — post-tour nudge
> 6. Comfy-Org#14145 — unpinned workflows (share / template links)

## Summary

Given a loaded graph, which nodes does the tour point at? For the eight
templates the Getting Started grid can show, the answer is pinned by
hand — three node ids each. The previous attempt inferred this with a
544-line resolver that parsed serialized JSON; this is 161 lines that
read the live graph.

## Changes

- `TOUR_ROLE_PINS` maps each supported template to its source / prompt /
sink. The type is exhaustive over both grid id lists, so a card without
pins is a compile error.
- Pins carry the node type alongside the id, and resolution checks both
— a renumbered template degrades to null instead of spotlighting the
wrong node.
- All three roles host-map through the same path, so a pin inside a
subgraph resolves to the root node that hosts it.
- A Playwright guard fetches every pinned template from the backend and
asserts each pinned node still exists with its expected type.

## Review focus

No vendored fixtures. The old PR carried 12,723 lines of copied template
JSON; the drift guard replaces it by checking against what the backend
actually serves, so an upstream rename fails CI instead of silently
mis-targeting a spotlight.

---------

Co-authored-by: pythongosssss <125205205+pythongosssss@users.noreply.github.com>
Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: AustinMroz <austin@comfy.org>
Merged via the queue into main with commit e9d2bd7 Aug 4, 2026
74 checks passed
@christian-byrne
christian-byrne deleted the feat/first-run-tour branch August 4, 2026 00:55
@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

@comfy-pr-bot

Copy link
Copy Markdown
Member

@MaanilVerma Successfully backported to #14637

@comfy-pr-bot

Copy link
Copy Markdown
Member

@MaanilVerma Successfully backported to #14638

@github-actions github-actions Bot removed the needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch label Aug 4, 2026
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Aug 4, 2026
…4144)

> **Stack — 5 of 6.** Rebuilt from scratch after the review on Comfy-Org#13725,
split into short PRs.
> Based on Comfy-Org#13290 (coachmark engine); each PR stacks on the one before
it.
>
> 1. Comfy-Org#14140 — engine: canvas targets for the coachmark tour
> 2. Comfy-Org#14141 — Getting Started screen + entry gating
> 3. Comfy-Org#14142 — role pins + live drift guard
> 4. Comfy-Org#14143 — the tour itself + e2e walk
> 5. Comfy-Org#14144 — post-tour nudge  ← this PR
> 6. Comfy-Org#14145 — unpinned workflows (share / template links)

## Summary

A card that slides up after the tour ends, pointing the user at the rest
of the template library. Deliberately outcome-blind: it shows whether
the run succeeded, failed, or the user skipped — whoever just finished
needs somewhere to go next either way.

## Changes

- `FirstRunTourNudge`, armed when the tour deactivates and shown after a
short delay.
- "Armed" and "no dialog is covering me" are folded together in the
watch getter and watched with `immediate: true`. Mounting when the nudge
is already due still shows it — the previous attempt waited for an edge
and could strand it permanently.
- Two telemetry stages added to the engine's existing funnel; nothing
re-implemented.

## Review focus

The reconcile-at-setup shape is the fix worth checking. Both regression
tests mount with pre-populated store state, which is the case that used
to fail.

---------

Co-authored-by: pythongosssss <125205205+pythongosssss@users.noreply.github.com>
Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: AustinMroz <austin@comfy.org>
Co-authored-by: bymyself <cbyrne@comfy.org>
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Aug 4, 2026
…g#14145)

> **Stack — 6 of 6.** Rebuilt from scratch after the review on Comfy-Org#13725,
split into short PRs.
> Based on Comfy-Org#13290 (coachmark engine); each PR stacks on the one before
it.
>
> 1. Comfy-Org#14140 — engine: canvas targets for the coachmark tour
> 2. Comfy-Org#14141 — Getting Started screen + entry gating
> 3. Comfy-Org#14142 — role pins + live drift guard
> 4. Comfy-Org#14143 — the tour itself + e2e walk
> 5. Comfy-Org#14144 — post-tour nudge
> 6. Comfy-Org#14145 — unpinned workflows (share / template links)  ← this PR

## Summary

Pins cover the eight templates the grid can show. This covers everything
else — a shared workflow, or a template URL nobody curated — by reading
the roles off the graph itself. Simon asked that any-workflow generality
land as its own stacked PR with adversarial tests rather than riding
along untested; this is that PR.

## Changes

- `heuristicRoles` finds the source, prompt and sink on an unpinned
graph. Pins still win where they exist; anything else falls through to
here, so the heuristics are the default path rather than dead code.
- Prompt selection is ranked, not matched: labels are normalised for
case and separators, wiring to a `positive` input outranks a label
saying so, and `negative` / `system` disqualify. A tie returns nothing
rather than guessing.
- `?share=` and `?template=` links offer the tour once their workflow is
actually on canvas.

## Review focus

The tests are adversarial by design — negative-before-positive ports, a
node carrying both boxes, disagreeing sinks, bypassed nodes, ties, a
50-node graph — all built on real `LGraph` instances rather than copied
templates. That was the condition for bringing heuristics back at all.

---------

Co-authored-by: pythongosssss <125205205+pythongosssss@users.noreply.github.com>
Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: AustinMroz <austin@comfy.org>
Co-authored-by: Maanil Verma <maanil@comfy.org>
Co-authored-by: bymyself <cbyrne@comfy.org>
comfy-pr-bot added a commit that referenced this pull request Aug 4, 2026
… template (#14637)

Backport of #14143 to `core/1.49`

Automatically created by backport workflow.

Co-authored-by: Maanil Verma <vermaMaanil97@gmail.com>
Co-authored-by: pythongosssss <125205205+pythongosssss@users.noreply.github.com>
Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: AustinMroz <austin@comfy.org>
Co-authored-by: bymyself <cbyrne@comfy.org>
comfy-pr-bot added a commit that referenced this pull request Aug 4, 2026
…d template (#14638)

Backport of #14143 to `cloud/1.49`

Automatically created by backport workflow.

Co-authored-by: Maanil Verma <vermaMaanil97@gmail.com>
Co-authored-by: pythongosssss <125205205+pythongosssss@users.noreply.github.com>
Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: AustinMroz <austin@comfy.org>
Co-authored-by: bymyself <cbyrne@comfy.org>
@comfy-pr-bot comfy-pr-bot added the released:cloud PR has been released to cloud label Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released:cloud PR has been released to cloud size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants