Skip to content

fix(onboarding): refuse the first-run tour when the canvas is hidden - #14673

Merged
christian-byrne merged 3 commits into
mainfrom
fix/14628-tour-holds-precondition
Aug 23, 2026
Merged

christian-byrne merged 3 commits into
mainfrom
fix/14628-tour-holds-precondition

Conversation

@christian-byrne

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

Copy link
Copy Markdown
Contributor

Closes #14628

The failure

Open /?template=image_z_image_turbo&mode=linear as a new cloud user.

GraphView puts v-show="!linearMode" on the canvas container, so the graph canvas is display:none and the Linear view covers the screen. A display:none element still yields a (all-zero) DOMRect, so the tour's targets read as mounted and the tour opens anyway. The user gets coach cards floating over the Linear view pointing at nothing, until the targets time out (~8s) and an error toast fires. Comfy.VueNodes.Enabled is left flipped on as well, since beginTour only reverts it when the engine turns the start down — and here it did not.

Why the existing guard did not catch it

tourContextHolds already contains !canvasStore.linearMode, and it correctly ends a tour when the user switches into linear mode mid-walk. But holds are a running-tour mechanism:

  • begin() has no holds precondition.
  • The holds watcher in onboardingTourStore.ts fires only on a change, and only ends a tour that is already activeTour.

If linear mode is already on when the tour is requested, holds are already false, nothing changes, and nothing fires.

Worth stating explicitly, since the issue raises it: adding { immediate: true } to that watcher would not have fixed this. It runs at store construction, when no tour is active, so it has nothing to end. The gap is the missing precondition, not the watcher's timing.

The fix

tourContextHolds was doing two jobs. This splits out the half that is meaningful before a tour exists:

const canvasContextHolds = computed(
  () => desktopLayout.value && !canvasStore.linearMode
)

const tourContextHolds = computed(
  () =>
    canvasContextHolds.value &&
    workflowStore.activeWorkflow === tourWorkflow.value
)

The workflow-identity half can only be evaluated once tourWorkflow is set, which beginTour itself does — so it cannot serve as a precondition. The canvas half can, and it is the half this bug is about. beginTour now checks it immediately after the already-running check, ahead of the Comfy.VueNodes.Enabled flip, so a refused tour leaves nothing behind to undo.

It is checked a second time after the 500 ms intro preview. That window is long enough for the user to switch into linear mode themselves, and the holds watcher cannot catch that either — it fires while activeTour is still null, so it has nothing to end, and engine.startTour does not consult holds on the way in. The re-check routes into the existing !started path, which already hands the renderer switch back. (Raised in review; the first version of this PR had the entry guard only.)

Why here and not in begin()

The issue notes a more general fix: a holds precondition inside begin() in onboardingTourStore.ts, which would close the class for every tour. I did not take it, deliberately:

  • It fails 26 store tests, which start tours in contexts whose holds are false. Making them pass means reworking the store test setup — a test-architecture change that should not ride along with a user-facing bug fix that is a backport candidate.
  • A guard in begin() refuses after beginTour has already flipped the renderer setting and burned the 500 ms intro delay. It would be reverted (started === false takes the revert path), but the guard here avoids the write entirely.
  • beginTour is where this tour's context is known and where tourContextHolds is constructed; checking your own precondition at the point you build the tour is local and obvious.

The general precondition in begin() remains worth doing as follow-up work, together with the store test setup it needs.

Test fallout, handled

Returning before registerTour means tourHolds('firstRun') stays at its unregistered default of true — correctly, since no tour is registered and there is nothing to hold. Two existing tests asserted registeredTourHolds() === false for linear mode and for narrow viewports. Rather than delete them, they now assert the stronger property that those contexts were always about: the tour never opens.

  • refuses to open over the linear view, which hides the canvas
  • refuses to open on a viewport below the desktop layout

Each asserts beginTour returns false, engine.startTour was never called, and settingStore.set was never called with ('Comfy.VueNodes.Enabled', true). They moved from the run outcome block to starting, where a refusal to open belongs.

A third test, refuses to open when the canvas goes away during the intro preview, covers the window described above. The setting mock is now a spy rather than a plain writer, so a refusal that flipped the renderer on and put it back can no longer read as one that never touched it — also raised in review.

The mid-walk test (ends the tour when the user switches into the linear view mid-walk) is unchanged and still passing — the end-condition behaviour is untouched.

Verified

  • pnpm install --frozen-lockfile, pnpm format:check, pnpm lint, pnpm typecheck — all clean.
  • pnpm test:unit src/renderer/extensions/firstRunTour src/platform/onboarding — 356 passed, 23 files. No test outside the two rewritten ones changed behaviour.
  • Full pnpm test:unit — 1095 files, 14954 passed, 8 skipped, 1 failed: onboardingCloudRoutes.test.ts > lazily resolves the /oauth layout and consent view components times out at 5 s. Unrelated and flaky — it comes and goes between runs on this worktree and on a sibling worktree that does not contain these changes, and it is a lazy dynamic-import timing flake in this environment.
  • Mutation check. Each guard was removed in turn and the controller suite re-run:
Mutation Result
remove if (!canvasContextHolds.value) return false refuses to open over the linear view and refuses to open on a viewport below the desktop layout fail (2 failed, 38 passed)
remove the canvasContextHolds.value && re-check before startTour refuses to open when the canvas goes away during the intro preview fails (1 failed, 39 passed)
both restored 40 passed

Each guard is gated by its own tests, and neither is carrying the other.

Not verified

  • No browser/e2e run against a live ?template=X&mode=linear boot. The reproduction path (v-show on the canvas container, zero-DOMRect targets reading as mounted) is taken from the issue and reasoned about, not re-observed in a browser.
  • The GettingStartedScreen call site (await beginTour(id)) now has one more way to get false back. It already handled a refusal — the engine could always turn a start down — so no change was made there, but that path was reasoned about rather than exercised.
  • Only the firstRun tour is fixed. appMode still has no precondition on its holds; in practice it is shielded because its autoOpen condition is a subset of its holds, but the class of bug remains open there.

@christian-byrne
christian-byrne requested a review from a team August 4, 2026 05:31
@dosubot dosubot Bot added the size:S This PR changes 10-29 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/12/2026, 12:37:05 AM UTC

Links

🎭 Playwright: ✅ 1800 passed, 0 failed · 4 flaky

📊 Browser Reports
  • chromium: View Report (✅ 1781 / ❌ 0 / ⚠️ 3 / ⏭️ 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.69 MB gzip 🔴 +155 B

Details

Summary

  • Raw size: 36.7 MB baseline 36.7 MB — 🔴 +463 B
  • Gzip: 8.69 MB baseline 8.69 MB — 🔴 +155 B
  • Brotli: 6.06 MB baseline 6.06 MB — 🔴 +181 B
  • Bundles: 436 current • 436 baseline • 3 added / 3 removed

Category Glance
Graph Workspace 🔴 +463 B (1.36 MB) · Vendor & Third-Party ⚪ 0 B (16.3 MB) · Other ⚪ 0 B (14 MB) · Data & Services ⚪ 0 B (3.5 MB) · Panels & Settings ⚪ 0 B (565 kB) · Utilities & Hooks ⚪ 0 B (550 kB) · + 5 more

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

Main entry bundles and manifests

File Before After Δ Raw Δ Gzip Δ Brotli
assets/index-Bw8D_dZO.js (new) — 3.67 kB 🔴 +3.67 kB 🔴 +1.84 kB 🔴 +1.57 kB
assets/index-DLgMF484.js (removed) 3.67 kB — 🟢 -3.67 kB 🟢 -1.84 kB 🟢 -1.56 kB

Status: 1 added / 1 removed

Graph Workspace — 1.36 MB (baseline 1.36 MB) • 🔴 +463 B

Graph editor runtime, canvas, workflow orchestration

File Before After Δ Raw Δ Gzip Δ Brotli
assets/GraphView-DHlkhCQk.js (new) — 1.35 MB 🔴 +1.35 MB 🔴 +294 kB 🔴 +221 kB
assets/GraphView-CfycDflh.js (removed) 1.35 MB — 🟢 -1.35 MB 🟢 -294 kB 🟢 -221 kB

Status: 1 added / 1 removed / 2 unchanged

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

Top-level views, pages, and routed surfaces

Status: 17 unchanged

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

Configuration panels, inspectors, and settings screens

Status: 26 unchanged

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

Authentication, profile, and account management bundles

Status: 10 unchanged

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

Modals, dialogs, drawers, and in-app editors

Status: 8 unchanged

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

Reusable component library chunks

Status: 14 unchanged

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

Stores, services, APIs, and repositories

Status: 17 unchanged

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

Helpers, composables, and utility bundles

Status: 38 unchanged

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

External libraries and shared vendor chunks

Status: 17 unchanged

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

Bundles that do not match a named category

File Before After Δ Raw Δ Gzip Δ Brotli
assets/main-BQdZpBLY.js (new) — 45.1 kB 🔴 +45.1 kB 🔴 +13.1 kB 🔴 +11.4 kB
assets/main-CHr9Db-9.js (removed) 45.1 kB — 🟢 -45.1 kB 🟢 -13.1 kB 🟢 -11.4 kB

Status: 1 added / 1 removed / 284 unchanged

⚡ Performance

⏳ Performance tests in progress…

@coderabbitai

coderabbitai Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 3 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ca41f564-7c72-4142-b0e8-2443974248ae

📥 Commits

Reviewing files that changed from the base of the PR and between b2d6e41 and f87b230.

📒 Files selected for processing (2)
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts
📝 Walkthrough

Walkthrough

The first-run tour now checks for desktop layout and non-linear mode before startup. It rechecks the canvas context after the preview delay. Invalid contexts prevent engine startup and renderer side effects.

Changes

First-run tour startup gating

Layer / File(s) Summary
Canvas context startup guard
src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts
The controller centralizes desktop and non-linear canvas requirements. beginTour returns false before changing renderer settings or registering the tour when the context is invalid. It rechecks the context after the preview delay.
Startup behavior validation
src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
Tests cover linear mode, narrow viewports, and linear mode activation during the preview delay. They verify that the engine does not start and renderer state remains correct. Obsolete hold-level tests were removed.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

Suggested reviewers: maanilverma


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 are shown, but the PR title and commit subjects are unavailable, so the required bug-fix signal cannot be verified from the permitted metadata. Provide the PR title and commit subjects, then reassess whether the missing browser_tests/ regression and E2E rationale trigger a failure.
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the primary change: preventing the first-run tour from opening when the canvas is hidden.
Description check ✅ Passed The description is complete and covers the failure, fix, scope, tests, verification results, and remaining limitations.
Linked Issues check ✅ Passed The changes satisfy issue #14628 by blocking invalid starts, rechecking after the preview delay, and preserving mid-tour behavior.
Out of Scope Changes check ✅ Passed The changes remain focused on first-run tour startup guards, related tests, and renderer-state behavior required by issue #14628.
Adr Compliance For Entity/Litegraph Changes ✅ Passed The changed files are under src/renderer/extensions/firstRunTour and do not modify litegraph, ECS, or graph-entity files; the ADR check is not applicable.
✨ 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/14628-tour-holds-precondition

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: 2

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/tour/useFirstRunTourController.test.ts (1)

494-494: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep regression coverage for mid-tour context loss.

The controller still uses tourContextHolds after a tour starts, and the PR objective requires that behavior to remain unchanged. Line 494 removes the tests for Linear mode and narrow viewports during an active tour.

Retain both tests, or add equivalent tests that start the tour and then change each context. Otherwise, a regression in the existing hold path can pass CI.

As per path instructions, tests should cover relevant edge cases while exercising real code. Based on the PR objective, existing mid-tour hold behavior must remain unchanged.

🤖 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/tour/useFirstRunTourController.test.ts`
at line 494, Restore regression coverage in the first-run tour controller tests
for both context-loss cases: switching to Linear view and entering a narrow
viewport after the tour starts. Ensure each test starts an active tour, changes
the relevant context, and verifies the existing tourContextHolds behavior
remains intact, using the real controller flow.

Source: Path instructions

🤖 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/tour/useFirstRunTourController.test.ts`:
- Around line 302-313: Update both refusal-case tests around the starting
assertions to verify the mocked settingStore.set was not called with
('Comfy.VueNodes.Enabled', true), while retaining the existing final
mocks.vueNodesEnabled false assertions and real startup-code execution.

In `@src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts`:
- Around line 151-155: In the pending-tour startup flow around
settingStore.set(), delay(), and engine.startTour(), re-check
canvasContextHolds.value after all awaited setup and before starting the tour.
If the hold is no longer active, restore Comfy.VueNodes.Enabled and return false
without calling engine.startTour(), preserving the existing hold-watcher cleanup
behavior.

---

Outside diff comments:
In `@src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts`:
- Line 494: Restore regression coverage in the first-run tour controller tests
for both context-loss cases: switching to Linear view and entering a narrow
viewport after the tour starts. Ensure each test starts an active tour, changes
the relevant context, and verifies the existing tourContextHolds behavior
remains intact, using the real controller flow.
🪄 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: 226629f6-d413-4091-8c0c-901c5f37c74e

📥 Commits

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

📒 Files selected for processing (2)
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts

@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   #14673      +/-   ##
==========================================
+ Coverage   81.29%   81.32%   +0.02%     
==========================================
  Files        1873     1873              
  Lines      106900   106703     -197     
  Branches    32977    33376     +399     
==========================================
- Hits        86902    86773     -129     
+ Misses      19641    19574      -67     
+ Partials      357      356       -1     
Flag Coverage Δ
unit 72.52% <100.00%> (+<0.01%) ⬆️

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

Files with missing lines Coverage Δ
...ons/firstRunTour/tour/useFirstRunTourController.ts 100.00% <100.00%> (ø)

... and 16 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.

christian-byrne added a commit that referenced this pull request Aug 4, 2026
Review feedback on #14673.

The entry guard runs before `beginTour` awaits the renderer write and the
500 ms intro preview, so a switch into linear mode inside that window
still opened the tour: the holds watcher fires while `activeTour` is
still null, so it has nothing to end, and `engine.startTour` does not
consult holds on the way in. Re-check before starting; the existing
`!started` path already hands the renderer switch back.

Also spy on `settingStore.set` rather than only reading the resulting
value, so a refusal that flipped `Comfy.VueNodes.Enabled` and put it back
can no longer pass as one that never touched it.

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

Copy link
Copy Markdown
Contributor Author

Outside diff range, useFirstRunTourController.test.ts:494 — Keep regression coverage for mid-tour context loss.

Not restoring these two, and I don't think equivalent tests are worth adding. Reasons, in order:

1. The deleted tests were not mid-tour tests. Both set the context before tourOnRunStep():

it('refuses to hold a tour on a viewport below the desktop layout', async () => {
  setViewportWidth(500)
  await tourOnRunStep()          // ← beginTour now refuses here
  expect(registeredTourHolds()).toBe(false)
})

With the precondition this PR adds, beginTour returns false at the door, so no tour is ever registered and registeredTourHolds() reads a tour that does not exist. They could not be kept as written — they were replaced by the two refusal tests, which assert strictly more (return value, engine.startTour not called, and the renderer setting never written).

2. Mid-tour linear-mode loss is still covered, at ends the tour when the user switches into the linear view mid-walk — starts a real tour, flips linearMode, asserts the hold drops.

3. Mid-tour viewport narrowing is not reachable in this harness. desktopLayout is useBreakpoints(breakpointsTailwind).greaterOrEqual('md'), i.e. VueUse useMediaQuery, which tracks the change event on the MediaQueryList. happy-dom updates .matches on setViewport but never dispatches change. Probed directly:

{"before":true,"after":false,"fired":0,"innerWidth":500}

fired: 0 — the listener never runs, so desktopLayout stays stale and the hold cannot flip after mount. That is exactly why the original test set the width before constructing the controller. I wrote the test you asked for and it fails for this reason, not because of a product bug.

4. Every term of the hold is still pinned. tourContextHolds = canvasContextHolds && workflowMatches, canvasContextHolds = desktopLayout && !linearMode:

removed term test that fails
canvasContextHolds && ends the tour when the user switches into the linear view mid-walk
desktopLayout && refuses to open on a viewport below the desktop layout
!linearMode refuses to open over the linear view / mid-walk linear test
workflow identity ends the tour when the user swaps to a workflow its ids do not describe

So a regression in the hold path cannot pass CI. Happy to revisit if the viewport case becomes drivable.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

MaanilVerma
MaanilVerma previously approved these changes Aug 5, 2026
christian-byrne added a commit that referenced this pull request Aug 9, 2026
Review feedback on #14673.

The entry guard runs before `beginTour` awaits the renderer write and the
500 ms intro preview, so a switch into linear mode inside that window
still opened the tour: the holds watcher fires while `activeTour` is
still null, so it has nothing to end, and `engine.startTour` does not
consult holds on the way in. Re-check before starting; the existing
`!started` path already hands the renderer switch back.

Also spy on `settingStore.set` rather than only reading the resulting
value, so a refusal that flipped `Comfy.VueNodes.Enabled` and put it back
can no longer pass as one that never touched it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@christian-byrne
christian-byrne force-pushed the fix/14628-tour-holds-precondition branch from a38d5d2 to 3d36326 Compare August 9, 2026 02:51
@coderabbitai

coderabbitai Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

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

🤖 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/tour/useFirstRunTourController.test.ts`:
- Around line 374-381: Update the test around beginTour to flush the initial
setup and arm the intro-preview timer before setting mocks.linearMode.value to
true, then use async timer advancement through INTRO_PREVIEW_MS. Ensure the test
specifically verifies that losing the canvas context during the intro delay
prevents the tour from opening, rather than losing it while beginTour is still
awaiting setup.
🪄 Autofix

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: f3057dff-558e-4acd-bfbe-2a4a492dde5a

📥 Commits

Reviewing files that changed from the base of the PR and between e544b2a and 3d36326.

📒 Files selected for processing (2)
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Both CodeRabbit points checked against the code. One is answered by evidence,
one is real but not reachable from this harness — details so neither has to be
re-derived later.

1. "the test may be losing the canvas during setup, not during the intro preview"

The test does exercise the new path. Proof by mutation — reverting only the
re-check:

-    const started =
-      canvasContextHolds.value && (await engine.startTour('firstRun'))
+    const started = await engine.startTour('firstRun')
 ✕ refuses to open when the canvas goes away during the intro preview
   Tests  1 failed | 50 passed (51)

Exactly one test fails, and it is that one. Restoring the guard returns 51/51.
The early if (!canvasContextHolds.value) return false at the top of
beginTour has already run and passed by the time the flag flips, so it cannot
be what makes the test green. No change made.

2. "keep regression coverage for mid-tour context loss"

Half of this is already there — ends the tour when the user switches into the linear view mid-walk covers the linearMode limb of canvasContextHolds.

The viewport limb genuinely has no mid-tour test, and you are right that it
should. I wrote one and it fails, for a reason that is worth recording:

ends the tour when the viewport drops below the desktop layout mid-walk
AssertionError: expected true to be false

desktopLayout is useBreakpoints(breakpointsTailwind).greaterOrEqual('md'),
which is vueuse's useMediaQuery — it updates its ref from the
MediaQueryList change event. happy-dom does not dispatch that event.
Probed directly:

after happyDOM.setViewport({width: 500})
mql.matches false — correctly updated
change listeners fired 0
fresh matchMedia(...).matches false

So matches is right but nothing is notified, and vueuse's ref stays stale.
That is why the existing refuses to open on a viewport below the desktop layout test works — it sets the width before the controller is constructed,
so the value is read once at the correct size — and why the mid-walk case
cannot be expressed the same way.

Reaching it would mean either stubbing @vueuse/core in this file (which would
weaken the open-time test, the one that actually guards user-visible behaviour)
or moving it to e2e. Neither belongs in a PR scoped to the intro-preview race,
so I have not added a passing-by-construction test in its place — a test
that stubs the very thing it claims to verify would be worse than the gap.

Recording the gap here rather than filing it silently: mid-tour viewport
shrink below md is untested, and is untestable in the unit harness as it
stands.

christian-byrne and others added 2 commits August 11, 2026 17:27
`?template=X&mode=linear` boots straight into the Linear view, which
`display:none`s the graph canvas. The tour opened over it anyway: coach
cards floated above the Linear view pointing at nothing until their
targets timed out (~8s), then an error toast — and `Comfy.VueNodes.Enabled`
was left flipped on, because it is only reverted when the engine turns
the start down.

`tourContextHolds` already knew about linear mode, but holds are a
running-tour mechanism: the engine's watcher only ends a tour that is
already active, and only when holds *change*. A context that was already
lost when the tour was requested produces no change, so nothing fired.

Split the canvas half of the predicate out as `canvasContextHolds` — the
part that is meaningful before a tour exists — and check it at the top of
`beginTour`, ahead of the renderer switch so there is nothing to undo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review feedback on #14673.

The entry guard runs before `beginTour` awaits the renderer write and the
500 ms intro preview, so a switch into linear mode inside that window
still opened the tour: the holds watcher fires while `activeTour` is
still null, so it has nothing to end, and `engine.startTour` does not
consult holds on the way in. Re-check before starting; the existing
`!started` path already hands the renderer switch back.

Also spy on `settingStore.set` rather than only reading the resulting
value, so a refusal that flipped `Comfy.VueNodes.Enabled` and put it back
can no longer pass as one that never touched it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@christian-byrne
christian-byrne force-pushed the fix/14628-tour-holds-precondition branch from 3d36326 to c27d65b Compare August 12, 2026 00:28
coderabbitai[bot]
coderabbitai Bot previously approved these changes Aug 12, 2026
`beginTour` awaits the renderer switch before `delay(INTRO_PREVIEW_MS)`, so
flipping `linearMode` immediately after calling it changed the value while
setup was still running rather than during the preview the test names.

The test was already mutation-proof either way - removing the post-delay
re-check fails it and nothing else - because no check sits between the
setting write and the delay. But that is a property of today's code, not of
the test, so a later check added there would have quietly made this pass for
the wrong reason.

Flushes setup with a zero-length tick first.

Addresses #14673 (comment)
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Done in f87b23015e — you were right about the mechanism, and I want to be
precise about what it did and didn't affect.

What you spotted is real. beginTour awaits the renderer switch
(settingStore.set('Comfy.VueNodes.Enabled', true)) before
delay(INTRO_PREVIEW_MS), so flipping mocks.linearMode on the line after the
call changed it while setup was still running — not during the preview the test
is named for. Fixed by flushing with a zero-length tick first.

What it did not affect: the test was already mutation-proof. Removing the
post-delay re-check fails that test and only that test, before and after this
change:

 ✕ refuses to open when the canvas goes away during the intro preview
   Tests  1 failed | 50 passed (51)

That is because no check currently sits between the setting write and the
delay, so there was nothing else that could have been making it green. Your
sharper point stands though: that is a property of today's code rather than
of the test, and a check added there later would have made this pass for the
wrong reason without anyone noticing. Worth fixing on those grounds alone.

Still 51/51 unmutated.

@christian-byrne christian-byrne added the needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch label Aug 12, 2026
@christian-byrne christian-byrne removed needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch core/1.49 labels Aug 23, 2026
@christian-byrne
christian-byrne merged commit 21ca5a3 into main Aug 23, 2026
79 of 80 checks passed
@christian-byrne
christian-byrne deleted the fix/14628-tour-holds-precondition branch August 23, 2026 01:00
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Follow-up opened: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16598\n\n

Full context for agent readers\n\nThe follow-up adds the deferred general holds precondition in the tour store, updates the store harness to use valid context, and adds real-browser coverage for mid-tour viewport narrowing.\n\n
\n\n

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Follow-up #16598 carries the deferred tour-hold coverage.

Full context for agent readers
Review item Disposition
Keep mid-tour Linear-mode and narrow-viewport regression coverage Fixed: Linear-mode coverage remains on main; c0b1cb5f adds real-browser coverage for mid-tour viewport narrowing in #16598.
Unit-harness viewport limitation Fixed in the appropriate layer: 60015bad enforces the general hold precondition in the tour store, while the viewport transition is tested in Playwright.

The mandatory dedupe check found #16598 before another PR was opened. Its body links the source review records, it has the default FE assignees, and roster reviewer benceruleanlu is requested.

xmarre pushed a commit to xmarre/ComfyUI_frontend that referenced this pull request Sep 2, 2026
…n and viewport coverage (Comfy-Org#16598)

Follow-up to Comfy-Org#14673

## Summary

- refuse registered tours before state mutation when their context
already fails
- make store tests start from a valid app-mode context
- cover active-tour teardown when a real browser viewport drops below
desktop size

Follow-up to Comfy-Org#14673.

Addressed review records:
-
Comfy-Org#14673 (comment)
-
Comfy-Org#14673 (comment)

## Verification

- `pnpm typecheck`
- `pnpm typecheck:browser`
- `pnpm test:unit src/platform/onboarding` (188 passed)
- `pnpm test:unit src/renderer/extensions/firstRunTour
src/platform/onboarding` (435 passed; one unrelated timing test failed
under parallel load and passed alone)
- browser test authored and typechecked; local execution unavailable
because no frontend was running on localhost:5173

<!-- authored-by:agent addr-drain -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:S This PR changes 10-29 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

First-run tour: ?template=X&mode=linear opens a tour over a hidden canvas

3 participants