Skip to content

feat(onboarding): first-run tour on curated templates (lean) - #14238

Closed
deepme987 wants to merge 2 commits into
mainfrom
deepme987/onboarding/first-run-tour-lean
Closed

deepme987 wants to merge 2 commits into
mainfrom
deepme987/onboarding/first-run-tour-lean

Conversation

@deepme987

Copy link
Copy Markdown
Contributor

Summary

A first-run guided tour for new cloud users, built as a single change off main: pick a curated template on the Getting Started screen, then get walked through upload, prompt, run, and result, spotlit on the canvas.

Changes

  • What: A first-run tour on the shared coachmark engine. The Getting Started screen (curated templates + tutorials, gated to new cloud users behind onboardingTourEnabled) hands a picked template to a tour controller. Roles (source / prompt / sink) resolve from a per-template pin map, drive a step sequence, and are spotlit as canvas targets while the camera frames each node. The Run step passes clicks through to the real Run button, handles the paywall, and the Result step reports the run outcome. Reuses the existing template catalog/loader, litegraph's animateToBounds/fitToBounds camera, and Floating UI positioning; the only new engine capability is a canvas-node coachmark target (a VirtualElement rect provider).
  • Scope: The tour runs only on templates it pins. An id it does not pin, or pins the live graph no longer satisfies, yields no steps and the engine reports it did not start. There is deliberately no arbitrary-graph role inference (heuristically guessing prompt/source/sink off an uncurated graph) and no post-tour nudge in this PR.
  • Breaking: None. New-user startup still falls back to the existing template browser (Comfy.BrowseTemplates) for anyone who is not a tour candidate.

Review Focus

  • This is a leaner, consolidated take on the #14140–#14145 stack: same engine foundation and much of the same tour/controller/camera logic, minus the speculative arbitrary-graph inference and the nudge, landed as one PR instead of six. Reviewing the scope cut (curated-pins-only) is the main call: it trades shared-workflow / uncurated-URL tours for a far smaller, less fragile surface.
  • Curated coverage is guarded by an e2e check (firstRunTourRolePins.spec.ts) that fails if any pinned node is missing or changed type in a served template, so template drift surfaces in CI rather than as a dead step.
  • resolveTourRoles degrades any individual unmet pin to null (the step is omitted) rather than dropping the whole tour, and host-maps pins that live inside subgraphs to their root-graph node.
  • Tests kept thorough (unit + e2e across roles, camera framing, canvas targets, the controller's run/result/paywall states, and the Getting Started entry gating).

Screenshots (if applicable)

Adds a first-run guided tour as a single change off main. A new cloud user
picks a pinned template from the Getting Started screen and is walked
through upload, prompt, run, and result, spotlit on the canvas.

Builds on the shared coachmark engine and reuses the existing template
catalog/loader and litegraph's camera. Roles resolve from a curated pin map
per template, so the tour runs only on templates it pins; an id it does not
pin (or pins the live graph no longer satisfies) yields no steps and the
engine reports it did not start.

Scoped deliberately: no arbitrary-graph role inference and no post-tour
nudge, keeping the surface small while the feature and its tests stay
intact.
@github-actions

github-actions Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: 🕵🏻 0 passed, 0 failed

📊 Browser Reports
  • chromium: ❌ Deployment failed
  • chromium-2x: ❌ Deployment failed
  • chromium-0.5x: ❌ Deployment failed
  • mobile-chrome: ❌ Deployment failed

🎨 Storybook: ❌ Failed

Details

⏰ Completed at: 07/29/2026, 04:34:27 AM UTC

Links

📦 Bundle Size

⚠️ Size data collection failed. Check the CI workflow logs.

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

@coderabbitai

coderabbitai Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Changes

The PR adds a feature-flagged first-run onboarding experience with a Getting Started dialog, curated template cards, dynamic workflow role resolution, guided canvas framing, interactive coachmarks, execution-state handling, paywall behavior, startup outcome routing, telemetry updates, and Playwright/Vitest coverage.

First-run entry and startup flow

Layer / File(s) Summary
Startup and tour contracts
src/platform/onboarding/onboardingTours.ts, src/platform/onboarding/onboardingTourStore.ts, src/platform/workflow/persistence/..., src/composables/useFeatureFlags.ts, src/platform/telemetry/types.ts
Adds first-run entry paths, runtime-resolved tour definitions, startup outcome types, onboarding feature-flag support, and updated telemetry contracts.
Getting Started entry and execution controller
src/renderer/extensions/firstRunTour/..., src/views/GraphView.vue, src/components/actionbar/ComfyActionbar.vue
Adds the Getting Started dialog, curated tutorial cards, first-run eligibility, tour startup, execution result handling, and subscription gating.
Workflow roles and camera targets
src/renderer/extensions/firstRunTour/roles/*, src/renderer/extensions/firstRunTour/tour/*
Resolves pinned template roles, builds conditional tour steps, registers moving canvas targets, and frames nodes during navigation.
Spotlight behavior
src/platform/onboarding/TourSpotlight.vue, src/platform/onboarding/coachmark*.ts, src/platform/onboarding/useCoachmarkTarget.ts
Adds interactive masking, opening-state behavior, virtual targets, cursor placement, card gliding, and related lifecycle tests.
Startup integration and browser validation
src/components/graph/GraphCanvas.vue, browser_tests/tests/*, browser_tests/fixtures/ComfyPage.ts
Routes startup and URL outcomes into first-run handling and validates successful, failed, paywalled, blank-canvas, deep-link, and role-pin scenarios.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

Suggested labels: size:XXL, cloud/1.48

Suggested reviewers: christian-byrne, pythongosssss


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 PR title and commit subjects aren’t available here, so I can’t verify whether a bug-fix signal exists from metadata alone. Please provide the PR title and commit subjects (or confirm none use fix/bugfix/hotfix language) so I can assess the check.
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title is concise and accurately summarizes the main change: a first-run onboarding tour for curated templates.
Description check ✅ Passed The description follows the required sections and covers the core scope, though the optional Breaking and Dependencies lines are omitted.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Adr Compliance For Entity/Litegraph Changes ✅ Passed No src/lib/litegraph or src/ecs changes, and the graph-related edits add app-side tour logic only; no ADR 0003/0008 entity mutations or core API growth found.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Fix failing CI checks
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch deepme987/onboarding/first-run-tour-lean

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

Caution

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

⚠️ Outside diff range comments (1)
src/composables/useFeatureFlags.ts (1)

18-42: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Keep supportsModelTypeTags until its callers are migrated.
ServerFeatureFlag.SUPPORTS_MODEL_TYPE_TAGS and flags.supportsModelTypeTags are still referenced in multiple asset files and tests, so removing them here will break the build. If this flag is being renamed, update all call sites in the same change; otherwise keep the alias for compatibility.

🤖 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/composables/useFeatureFlags.ts` around lines 18 - 42, Retain
ServerFeatureFlag.SUPPORTS_MODEL_TYPE_TAGS and the flags.supportsModelTypeTags
property in useFeatureFlags until all asset-file and test callers are migrated.
If the intended change is a rename, update every caller in the same change;
otherwise preserve the existing alias for compatibility.
🤖 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 `@browser_tests/tests/firstRunTourRolePins.spec.ts`:
- Line 18: Update the first-run tour test around pinnedTemplates and the
assertions near the curated-template count check to verify exact ID coverage:
assert that the pinned template IDs match CURATED_TEMPLATE_IDS in both
directions or as an equivalent set comparison. Preserve the existing count
assertion only if useful, and ensure the test would fail when a curated ID is
unpinned and an unrelated extra pin is added.

In `@browser_tests/tests/gettingStartedTour.spec.ts`:
- Around line 228-252: Add an assertion immediately after the existing
upgradeDialog visibility check in the test “leaves the nudge until the upgrade
dialog closes” to verify the first-run nudge is hidden while the dialog is open,
while preserving the existing post-Escape visibility assertion.

In `@src/platform/onboarding/coachmarkRegistry.virtualTarget.test.ts`:
- Around line 12-14: Expand the tests around isMovingTarget to cover both
positive and negative cases: a target with a callable onMove should be
recognized as moving, while an HTMLElement and a virtualTarget without onMove
should be treated as static; also cover a target whose onMove property is
non-callable to verify the predicate’s type check.

In `@src/platform/onboarding/onboardingTourStore.registeredTour.test.ts`:
- Around line 49-55: Update mountStore to use createTestingPinia with
stubActions set to false instead of createPinia, while preserving setActivePinia
and useOnboardingTourStore so the test exercises real store actions.
- Around line 66-76: Replace the vi.resetModules workaround in the onboarding
tour tests with a test-visible registry reset or unregister API exported from
onboardingTours.ts. Invoke that reset in afterEach so module-level TOURS is
cleared between tests, and keep onboardingTourStore imported through the normal
single module graph.

In `@src/platform/onboarding/useCoachmarkTarget.virtualTarget.test.ts`:
- Around line 41-49: Update the test “follows a target that reports its own
motion” to use a mutable target rectangle, trigger the registered motion
callback after changing that rectangle, and assert that the observed target
rectangle or floating position reflects the change. Remove the listenerCount
assertion so the test verifies behavior rather than subscription or
change-detector implementation details.

In `@src/platform/telemetry/types.ts`:
- Around line 189-192: Restore the removed telemetry exports
normalizeExecutionTriggerSource, trackBillingEvent, trackWorkspaceInviteFailed,
trackWidgetFavoriteToggled, and trackExecutionOutcome so existing callers
continue to typecheck. Also restore SubscriptionSuccessMetadata with the shape
required by subscriptionCheckoutTracker and its telemetry providers, keeping the
existing subscription checkout flow aligned.

In `@src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts`:
- Around line 28-35: Move the
useBreakpoints(breakpointsTailwind).greaterOrEqual('md') composable creation
from isFirstRunCandidate into the createSharedComposable setup scope, cache its
returned ref, and have isFirstRunCandidate read the cached ref’s value. Preserve
the existing candidate checks and ordering while ensuring repeated calls from
handleStartupOutcome and handleUrlWorkflow do not create new listeners.

In
`@src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue`:
- Line 11: Update the Escape key handler and blank-canvas button invoking
dismissGettingStarted() to explicitly mark the asynchronous call with void,
matching the existing fire-and-forget promise handling in loadCatalog() and
onMounted. Keep the awaited invocation elsewhere unchanged.

In `@src/renderer/extensions/firstRunTour/tour/firstRunTourDefinition.test.ts`:
- Around line 165-177: Extend the test case around buildSteps and
releaseFirstRunTargets to assert that the FIRST_RUN_COACH_IDS.prompt target is
mounted before release and unmounted afterward, alongside the existing source
and sink assertions. Use the same targetMounted checks and preserve the current
finished-tour cleanup behavior.

In `@src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts`:
- Around line 148-162: Update the beforeEach setup in the first-run tour
controller tests to use vi.resetAllMocks() instead of vi.clearAllMocks(),
ensuring mocks.engine.startTour implementations are restored between tests while
preserving the existing mock state initialization.

In `@src/views/GraphView.vue`:
- Line 33: Update GraphView’s FirstRunTour rendering to mount it only within the
existing first-run/cloud condition, using the available isCloud state. Ensure
useFirstRunTourController is not initialized for sessions where the tour cannot
appear.

---

Outside diff comments:
In `@src/composables/useFeatureFlags.ts`:
- Around line 18-42: Retain ServerFeatureFlag.SUPPORTS_MODEL_TYPE_TAGS and the
flags.supportsModelTypeTags property in useFeatureFlags until all asset-file and
test callers are migrated. If the intended change is a rename, update every
caller in the same change; otherwise preserve the existing alias for
compatibility.
🪄 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: ba36bf54-2d26-400a-9a5a-459d63ab3775

📥 Commits

Reviewing files that changed from the base of the PR and between 644c44b and 7a665bf.

📒 Files selected for processing (49)
  • browser_tests/fixtures/ComfyPage.ts
  • browser_tests/tests/firstRunTourRolePins.spec.ts
  • browser_tests/tests/gettingStartedTour.spec.ts
  • src/components/actionbar/ComfyActionbar.vue
  • src/components/graph/GraphCanvas.vue
  • src/components/tab/TabList.vue
  • src/composables/useFeatureFlags.ts
  • src/locales/en/main.json
  • src/platform/onboarding/TourOverlay.vue
  • src/platform/onboarding/TourSpotlight.interactive.test.ts
  • src/platform/onboarding/TourSpotlight.vue
  • src/platform/onboarding/coachmarkLayout.ts
  • src/platform/onboarding/coachmarkRegistry.ts
  • src/platform/onboarding/coachmarkRegistry.virtualTarget.test.ts
  • src/platform/onboarding/onboardingTourStore.registeredTour.test.ts
  • src/platform/onboarding/onboardingTourStore.ts
  • src/platform/onboarding/onboardingTours.ts
  • src/platform/onboarding/useCoachmarkTarget.ts
  • src/platform/onboarding/useCoachmarkTarget.virtualTarget.test.ts
  • src/platform/remoteConfig/types.ts
  • src/platform/telemetry/types.ts
  • src/platform/workflow/persistence/base/draftTypes.ts
  • src/platform/workflow/persistence/composables/useWorkflowPersistenceV2.test.ts
  • src/platform/workflow/persistence/composables/useWorkflowPersistenceV2.ts
  • src/platform/workflow/sharing/composables/useSharedWorkflowUrlLoader.ts
  • src/platform/workflow/templates/composables/useTemplateUrlLoader.ts
  • src/renderer/extensions/firstRunTour/FirstRunTour.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedCard.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.test.ts
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedScreen.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/GettingStartedTemplateCard.vue
  • src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.test.ts
  • src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts
  • src/renderer/extensions/firstRunTour/gettingStarted/tutorialCards.ts
  • src/renderer/extensions/firstRunTour/roles/resolveTourRoles.test.ts
  • src/renderer/extensions/firstRunTour/roles/resolveTourRoles.ts
  • src/renderer/extensions/firstRunTour/roles/tourRolePins.ts
  • src/renderer/extensions/firstRunTour/roles/tourSequence.test.ts
  • src/renderer/extensions/firstRunTour/roles/tourSequence.ts
  • src/renderer/extensions/firstRunTour/tour/cameraFraming.test.ts
  • src/renderer/extensions/firstRunTour/tour/cameraFraming.ts
  • src/renderer/extensions/firstRunTour/tour/canvasCoachTarget.test.ts
  • src/renderer/extensions/firstRunTour/tour/canvasCoachTarget.ts
  • src/renderer/extensions/firstRunTour/tour/firstRunTourDefinition.test.ts
  • src/renderer/extensions/firstRunTour/tour/firstRunTourDefinition.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts
  • src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts
  • src/views/GraphView.test.ts
  • src/views/GraphView.vue


const baseUrl = process.env.PLAYWRIGHT_TEST_URL || 'http://localhost:8188'

const pinnedTemplates = Object.entries(TOUR_ROLE_PINS)

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.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Assert exact curated-template coverage, not only aggregate counts.

The test derives pinnedTemplates from TOUR_ROLE_PINS, then compares only its served count with CURATED_TEMPLATE_IDS.length. If one curated ID loses its pin while an unrelated extra pin is added, this test still passes and the Getting Started flow can offer a template that produces no tour steps.

As per path instructions, Playwright tests must verify behavioral contracts and cover relevant negative paths directly.

Suggested assertion
   test('every pinned node still exists with its pinned type', async ({
     request
   }) => {
+    const missingPins = CURATED_TEMPLATE_IDS.filter(
+      (templateId) => !(templateId in TOUR_ROLE_PINS)
+    )
+    expect(
+      missingPins,
+      'every Getting Started template must have role pins'
+    ).toEqual([])
+
     const unserved: string[] = []

Also applies to: 68-71

🤖 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 `@browser_tests/tests/firstRunTourRolePins.spec.ts` at line 18, Update the
first-run tour test around pinnedTemplates and the assertions near the
curated-template count check to verify exact ID coverage: assert that the pinned
template IDs match CURATED_TEMPLATE_IDS in both directions or as an equivalent
set comparison. Preserve the existing count assertion only if useful, and ensure
the test would fail when a curated ID is unpinned and an unrelated extra pin is
added.

Source: Path instructions

Comment on lines +228 to +252
test('leaves the nudge until the upgrade dialog closes', async ({
comfyPage
}) => {
test.slow()
const { page } = comfyPage
const { spotlight } = await tourToRunStep(page)
const nudge = page.getByTestId('first-run-nudge')
const upgradeDialog = page.getByTestId('dialog-overlay')

await page.getByTestId('subscribe-to-run-button').click()

await expect(upgradeDialog).toBeVisible()
await expect(
spotlight,
'a tour parked on a button that will never run has nowhere to go'
).toBeHidden()

await page.keyboard.press('Escape')

await expect(upgradeDialog).toBeHidden()
await expect(
nudge,
'the tour ended, so the user still needs somewhere to go next'
).toBeVisible({ timeout: 10_000 })
})

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.

🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Test doesn't verify the nudge stays hidden while the upgrade dialog is open.

The test title says the nudge is left "until the upgrade dialog closes," but the body only asserts nudge becomes visible after Escape. Add an assertion that nudge is hidden right after upgradeDialog becomes visible, so a regression that surfaces both together is actually caught.

✅ Proposed addition
       await page.getByTestId('subscribe-to-run-button').click()

       await expect(upgradeDialog).toBeVisible()
+      await expect(
+        nudge,
+        'the nudge must not appear while the upgrade dialog is still open'
+      ).toBeHidden()
       await expect(
         spotlight,
         'a tour parked on a button that will never run has nowhere to go'
       ).toBeHidden()

As per path instructions (.agents/checks/test-quality.md), reviews should "watch for ... missing edge cases" in changed tests.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
test('leaves the nudge until the upgrade dialog closes', async ({
comfyPage
}) => {
test.slow()
const { page } = comfyPage
const { spotlight } = await tourToRunStep(page)
const nudge = page.getByTestId('first-run-nudge')
const upgradeDialog = page.getByTestId('dialog-overlay')
await page.getByTestId('subscribe-to-run-button').click()
await expect(upgradeDialog).toBeVisible()
await expect(
spotlight,
'a tour parked on a button that will never run has nowhere to go'
).toBeHidden()
await page.keyboard.press('Escape')
await expect(upgradeDialog).toBeHidden()
await expect(
nudge,
'the tour ended, so the user still needs somewhere to go next'
).toBeVisible({ timeout: 10_000 })
})
test('leaves the nudge until the upgrade dialog closes', async ({
comfyPage
}) => {
test.slow()
const { page } = comfyPage
const { spotlight } = await tourToRunStep(page)
const nudge = page.getByTestId('first-run-nudge')
const upgradeDialog = page.getByTestId('dialog-overlay')
await page.getByTestId('subscribe-to-run-button').click()
await expect(upgradeDialog).toBeVisible()
await expect(
nudge,
'the nudge must not appear while the upgrade dialog is still open'
).toBeHidden()
await expect(
spotlight,
'a tour parked on a button that will never run has nowhere to go'
).toBeHidden()
await page.keyboard.press('Escape')
await expect(upgradeDialog).toBeHidden()
await expect(
nudge,
'the tour ended, so the user still needs somewhere to go next'
).toBeVisible({ timeout: 10_000 })
})
🤖 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 `@browser_tests/tests/gettingStartedTour.spec.ts` around lines 228 - 252, Add
an assertion immediately after the existing upgradeDialog visibility check in
the test “leaves the nudge until the upgrade dialog closes” to verify the
first-run nudge is hidden while the dialog is open, while preserving the
existing post-Escape visibility assertion.

Source: Path instructions

Comment on lines +12 to +14
function virtualTarget(rect: DOMRect): CoachTarget {
return { getBoundingClientRect: () => rect }
}

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.

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

No coverage for isMovingTarget / MovingTarget.

This suite exercises plain virtual targets only. The predicate added alongside them ('onMove' in target && typeof target.onMove === 'function') is what drives the live-repositioning path in useCoachmarkTarget.ts, and its negative cases (an HTMLElement, a virtual target without onMove, an onMove that is not a function) are untested. As per path instructions, .agents/checks/test-quality.md asks to "ensure coverage gaps are addressed where logic changed".

🧪 Suggested additional cases
it('treats a target that announces its own motion as moving', () => {
  const moving = { getBoundingClientRect: () => new DOMRect(), onMove: () => () => {} }
  expect(isMovingTarget(moving)).toBe(true)
})

it('treats a plain element or a static virtual target as still', () => {
  expect(isMovingTarget(document.createElement('div'))).toBe(false)
  expect(isMovingTarget(virtualTarget(new DOMRect()))).toBe(false)
})

Also applies to: 16-43

🤖 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/platform/onboarding/coachmarkRegistry.virtualTarget.test.ts` around lines
12 - 14, Expand the tests around isMovingTarget to cover both positive and
negative cases: a target with a callable onMove should be recognized as moving,
while an HTMLElement and a virtualTarget without onMove should be treated as
static; also cover a target whose onMove property is non-callable to verify the
predicate’s type check.

Source: Path instructions

Comment on lines +49 to +55
let pinia: Pinia | undefined

function mountStore() {
pinia = createPinia()
setActivePinia(pinia)
return useOnboardingTourStore()
}

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.

📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use createTestingPinia with stubActions: false.

As per path instructions, docs/testing/vitest-patterns.md states: "use createTestingPinia (not createPinia) for store tests; set stubActions: false when testing real store behavior."

🤖 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/platform/onboarding/onboardingTourStore.registeredTour.test.ts` around
lines 49 - 55, Update mountStore to use createTestingPinia with stubActions set
to false instead of createPinia, while preserving setActivePinia and
useOnboardingTourStore so the test exercises real store actions.

Source: Path instructions

Comment on lines +66 to +76
it('reports no start for an entry no one registered', async () => {
vi.resetModules()
const { useOnboardingTourStore: freshStore } =
await import('./onboardingTourStore')
pinia = createPinia()
setActivePinia(pinia)
const store = freshStore()

await expect(store.startTour('firstRun')).resolves.toBe(false)
expect(store.activeTour).toBeNull()
})

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.

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Fragile isolation: vi.resetModules() only resets the dynamically imported copy.

registerTour mutates module-level TOURS in ./onboardingTours and nothing unregisters it, so this test depends on running before any other. The vi.resetModules() workaround makes the dynamically imported onboardingTourStore pull a second copy of ./onboardingTours (with an empty registry) while the statically imported registerTour in this file keeps writing to the original — two live module graphs for the same contract. It passes, but for an incidental reason.

Prefer exporting a test-visible reset (or unregister) from onboardingTours.ts and clearing the registry in afterEach, so every test starts from a known registry without duplicating the module.

🤖 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/platform/onboarding/onboardingTourStore.registeredTour.test.ts` around
lines 66 - 76, Replace the vi.resetModules workaround in the onboarding tour
tests with a test-visible registry reset or unregister API exported from
onboardingTours.ts. Invoke that reset in afterEach so module-level TOURS is
cleared between tests, and keep onboardingTourStore imported through the normal
single module graph.

Source: Path instructions

Comment on lines +28 to +35
function isFirstRunCandidate(): boolean {
if (!isCloud) return false
if (!useBreakpoints(breakpointsTailwind).greaterOrEqual('md').value)
return false
if (!useSubscription().isSubscriptionEnabled()) return false
if (useNewUserService().isNewUser() !== true) return false
return useFeatureFlags().flags.onboardingTourEnabled
}

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.

🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

VueUse useMediaQuery tryOnScopeDispose cleanup when called outside effect scope

💡 Result:

When tryOnScopeDispose is called outside an active Vue effect scope, it does nothing and returns false [1][2]. It is designed as a safe wrapper around Vue's onScopeDispose function; whereas onScopeDispose will throw an error if called outside an active scope [3], tryOnScopeDispose simply checks if getCurrentScope() returns a truthy value [2]. If an active scope is present, it registers the cleanup function via onScopeDispose and returns true [2]. Regarding useMediaQuery, it is a VueUse composable that typically relies on Vue's reactivity system (including watchEffect and computed) [4][5]. Because these internal mechanisms are tied to an active effect scope, useMediaQuery is intended to be used within a component's setup() function or an explicit effectScope [6][7]. If you call useMediaQuery outside of an active scope, you will lose the automatic cleanup and reactivity benefits, as the cleanup functions (which utilize tryOnScopeDispose or equivalent mechanisms) will not be registered [2][3]. If you must use such composables outside of a component lifecycle, you should manually wrap them in an effectScope to manage their lifecycle and cleanup [6][7].

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

git ls-files 'src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts' \
  'src/renderer/extensions/firstRunTour/gettingStarted/*.ts' \
  'src/renderer/extensions/firstRunTour/**/*.ts' \
  'src/**/useBreakpoints*.ts' \
  'src/**/createSharedComposable*.ts' \
  'package.json'

printf '\n--- firstRunEntry.ts ---\n'
cat -n src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts

printf '\n--- search for createSharedComposable/useBreakpoints usage ---\n'
rg -n "createSharedComposable|useBreakpoints|handleStartupOutcome|handleUrlWorkflow|isFirstRunCandidate" src/renderer/extensions/firstRunTour -S

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 8083


🏁 Script executed:

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
p = Path('src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts')
print(p.read_text())
PY

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 3129


🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1,220p' src/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry.ts

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 3128


🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n "createSharedComposable|useBreakpoints|handleStartupOutcome|handleUrlWorkflow|isFirstRunCandidate" src/renderer/extensions/firstRunTour -S

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 3315


Hoist useBreakpoints into the shared composable scope.

isFirstRunCandidate() is called from handleStartupOutcome and handleUrlWorkflow, well after setup. Creating the breakpoint composable there allocates a fresh media-query listener on each call, and cleanup only attaches when there’s an active effect scope. Move it to the createSharedComposable body and read .value from the cached ref.

♻️ Proposed refactor
 export const useFirstRunEntry = createSharedComposable(() => {
   const settingStore = useSettingStore()
   const gettingStartedVisible = ref(false)
+  const isDesktopWidth = useBreakpoints(breakpointsTailwind).greaterOrEqual('md')
 
   function isFirstRunCandidate(): boolean {
     if (!isCloud) return false
-    if (!useBreakpoints(breakpointsTailwind).greaterOrEqual('md').value)
-      return false
+    if (!isDesktopWidth.value) return false
     if (!useSubscription().isSubscriptionEnabled()) return false
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
function isFirstRunCandidate(): boolean {
if (!isCloud) return false
if (!useBreakpoints(breakpointsTailwind).greaterOrEqual('md').value)
return false
if (!useSubscription().isSubscriptionEnabled()) return false
if (useNewUserService().isNewUser() !== true) return false
return useFeatureFlags().flags.onboardingTourEnabled
}
export const useFirstRunEntry = createSharedComposable(() => {
const settingStore = useSettingStore()
const gettingStartedVisible = ref(false)
const isDesktopWidth = useBreakpoints(breakpointsTailwind).greaterOrEqual(
'md',
)
function isFirstRunCandidate(): boolean {
if (!isCloud) return false
if (!isDesktopWidth.value) return false
if (!useSubscription().isSubscriptionEnabled()) return false
if (useNewUserService().isNewUser() !== true) return false
return useFeatureFlags().flags.onboardingTourEnabled
}
🤖 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/firstRunEntry.ts` around
lines 28 - 35, Move the useBreakpoints(breakpointsTailwind).greaterOrEqual('md')
composable creation from isFirstRunCandidate into the createSharedComposable
setup scope, cache its returned ref, and have isFirstRunCandidate read the
cached ref’s value. Preserve the existing candidate checks and ordering while
ensuring repeated calls from handleStartupOutcome and handleUrlWorkflow do not
create new listeners.

aria-modal="true"
:aria-label="t('gettingStarted.title')"
tabindex="-1"
@keydown.escape.capture.prevent="dismissGettingStarted()"

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.

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Un-awaited/un-voided async call to dismissGettingStarted().

Both the Escape handler (Line 11) and the blank-canvas button (Line 112) invoke dismissGettingStarted() — awaited elsewhere in this file (Line 226) — without await or an explicit void. Elsewhere in this file (loadCatalog(), nextTick(...) in onMounted) floating promises are deliberately marked with void, so these two look like an oversight rather than an intentional fire-and-forget.

🔧 Proposed fix
-        `@keydown.escape.capture.prevent`="dismissGettingStarted()"
+        `@keydown.escape.capture.prevent`="void dismissGettingStarted()"
           <Button
             variant="muted-textonly"
             data-testid="getting-started-blank"
-            `@click`="dismissGettingStarted()"
+            `@click`="void dismissGettingStarted()"
           >

As per path instructions, src/**/*.{ts,vue} guidelines state to "Disallow floating promises and unused imports."

Also applies to: 109-115

🤖 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`
at line 11, Update the Escape key handler and blank-canvas button invoking
dismissGettingStarted() to explicitly mark the asynchronous call with void,
matching the existing fire-and-forget promise handling in loadCatalog() and
onMounted. Keep the awaited invocation elsewhere unchanged.

Source: Path instructions

Comment on lines +165 to +177
it('registers each spotlit node so the engine can find it', async () => {
loadTemplate(FROM_IMAGE)

await buildSteps(FROM_IMAGE)
expect(targetMounted(FIRST_RUN_COACH_IDS.source)).toBe(true)
expect(targetMounted(FIRST_RUN_COACH_IDS.sink)).toBe(true)

releaseFirstRunTargets()
expect(
targetMounted(FIRST_RUN_COACH_IDS.source),
'a finished tour must not leave its targets behind'
).toBe(false)
})

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.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Test doesn't verify prompt target registration.

FROM_IMAGE produces 4 steps (upload/prompt/run/result); registerCanvasTargets registers every non-run kind, so prompt should also be mounted/unmounted, but only source and sink are asserted here.

✅ Proposed addition
     await buildSteps(FROM_IMAGE)
     expect(targetMounted(FIRST_RUN_COACH_IDS.source)).toBe(true)
+    expect(targetMounted(FIRST_RUN_COACH_IDS.prompt)).toBe(true)
     expect(targetMounted(FIRST_RUN_COACH_IDS.sink)).toBe(true)

     releaseFirstRunTargets()
     expect(
       targetMounted(FIRST_RUN_COACH_IDS.source),
       'a finished tour must not leave its targets behind'
     ).toBe(false)

Based on path instructions for **/*.test.ts requiring .agents/checks/test-quality.md review context, which asks reviewers to ensure "coverage gaps are addressed where logic changed."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
it('registers each spotlit node so the engine can find it', async () => {
loadTemplate(FROM_IMAGE)
await buildSteps(FROM_IMAGE)
expect(targetMounted(FIRST_RUN_COACH_IDS.source)).toBe(true)
expect(targetMounted(FIRST_RUN_COACH_IDS.sink)).toBe(true)
releaseFirstRunTargets()
expect(
targetMounted(FIRST_RUN_COACH_IDS.source),
'a finished tour must not leave its targets behind'
).toBe(false)
})
it('registers each spotlit node so the engine can find it', async () => {
loadTemplate(FROM_IMAGE)
await buildSteps(FROM_IMAGE)
expect(targetMounted(FIRST_RUN_COACH_IDS.source)).toBe(true)
expect(targetMounted(FIRST_RUN_COACH_IDS.prompt)).toBe(true)
expect(targetMounted(FIRST_RUN_COACH_IDS.sink)).toBe(true)
releaseFirstRunTargets()
expect(
targetMounted(FIRST_RUN_COACH_IDS.source),
'a finished tour must not leave its targets behind'
).toBe(false)
})
🤖 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/firstRunTourDefinition.test.ts`
around lines 165 - 177, Extend the test case around buildSteps and
releaseFirstRunTargets to assert that the FIRST_RUN_COACH_IDS.prompt target is
mounted before release and unmounted afterward, alongside the existing source
and sink assertions. Use the same targetMounted checks and preserve the current
finished-tour cleanup behavior.

Source: Path instructions

Comment on lines +148 to +162
beforeEach(() => {
setActivePinia(createTestingPinia({ stubActions: false }))
vi.clearAllMocks()
vi.useFakeTimers()
mocks.canRunWorkflows = ref(true)
mocks.workflowStatus.value = new Map()
mocks.executionErrors.hasNodeError = false
mocks.executionErrors.hasPromptError = false
mocks.activeWorkflow = null
mocks.transformValid = true
mocks.steps = []
mocks.engine.activeTour = null
mocks.engine.step = null
mocks.engine.isLast = false
})

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.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

vi.clearAllMocks() leaves startTour implementations bleeding between tests.

clearAllMocks clears call records but keeps mockImplementation. tourOnRunStep and the test at Line 196 both install implementations on mocks.engine.startTour, so any test that doesn't install its own inherits the previous one — the suite currently passes only because of declaration order. resetAllMocks restores a clean slate, which is also what the Vitest patterns guidance asks for.

💚 Proposed fix
     setActivePinia(createTestingPinia({ stubActions: false }))
-    vi.clearAllMocks()
+    vi.resetAllMocks()
     vi.useFakeTimers()

As per path instructions, docs/testing/vitest-patterns.md states: "Reset mocks with vi.resetAllMocks() in beforeEach".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
beforeEach(() => {
setActivePinia(createTestingPinia({ stubActions: false }))
vi.clearAllMocks()
vi.useFakeTimers()
mocks.canRunWorkflows = ref(true)
mocks.workflowStatus.value = new Map()
mocks.executionErrors.hasNodeError = false
mocks.executionErrors.hasPromptError = false
mocks.activeWorkflow = null
mocks.transformValid = true
mocks.steps = []
mocks.engine.activeTour = null
mocks.engine.step = null
mocks.engine.isLast = false
})
beforeEach(() => {
setActivePinia(createTestingPinia({ stubActions: false }))
vi.resetAllMocks()
vi.useFakeTimers()
mocks.canRunWorkflows = ref(true)
mocks.workflowStatus.value = new Map()
mocks.executionErrors.hasNodeError = false
mocks.executionErrors.hasPromptError = false
mocks.activeWorkflow = null
mocks.transformValid = true
mocks.steps = []
mocks.engine.activeTour = null
mocks.engine.step = null
mocks.engine.isLast = false
})
🤖 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`
around lines 148 - 162, Update the beforeEach setup in the first-run tour
controller tests to use vi.resetAllMocks() instead of vi.clearAllMocks(),
ensuring mocks.engine.startTour implementations are restored between tests while
preserving the existing mock state initialization.

Source: Path instructions

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

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.

🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
fd -t f 'useBillingContext.ts' -x ast-grep outline {} --items all
rg -nP -C4 '\b(fetch|api\.|watchEffect|onMounted|refresh|load)\w*\s*\(' -g '**/useBillingContext.ts'

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 1850


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Map the relevant components/composables first.
ast-grep outline src/views/GraphView.vue --items all
printf '\n---\n'
fd -t f 'FirstRunTour.vue' -o 'useFirstRunTourController.ts' -o 'useBillingContext.ts' src

# Read the small relevant slices with line numbers.
printf '\n=== src/views/GraphView.vue ===\n'
cat -n src/views/GraphView.vue | sed -n '1,140p'

printf '\n=== src/components/tours/FirstRunTour.vue ===\n'
cat -n src/components/tours/FirstRunTour.vue | sed -n '1,220p'

printf '\n=== src/composables/tours/useFirstRunTourController.ts ===\n'
cat -n src/composables/tours/useFirstRunTourController.ts | sed -n '1,260p'

printf '\n=== src/composables/billing/useBillingContext.ts ===\n'
cat -n src/composables/billing/useBillingContext.ts | sed -n '1,260p'

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 361


🏁 Script executed:

#!/bin/bash
set -euo pipefail

ast-grep outline src/views/GraphView.vue --items all
printf '\n---\n'
fd -t f 'FirstRunTour.vue' -o 'useFirstRunTourController.ts' -o 'useBillingContext.ts' src

printf '\n=== src/views/GraphView.vue ===\n'
cat -n src/views/GraphView.vue | sed -n '1,140p'

printf '\n=== src/components/tours/FirstRunTour.vue ===\n'
cat -n src/components/tours/FirstRunTour.vue | sed -n '1,220p'

printf '\n=== src/composables/tours/useFirstRunTourController.ts ===\n'
cat -n src/composables/tours/useFirstRunTourController.ts | sed -n '1,260p'

printf '\n=== src/composables/billing/useBillingContext.ts ===\n'
cat -n src/composables/billing/useBillingContext.ts | sed -n '1,260p'

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 361


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the relevant files.
fd -t f 'GraphView.vue' src
fd -t f 'FirstRunTour.vue' src
fd -t f 'useFirstRunTourController.ts' src
fd -t f 'useBillingContext.ts' src

# Read the relevant sections once located.
printf '\n=== GraphView.vue ===\n'
cat -n src/views/GraphView.vue | sed -n '1,140p'

printf '\n=== FirstRunTour.vue ===\n'
cat -n src/components/tours/FirstRunTour.vue | sed -n '1,220p'

printf '\n=== useFirstRunTourController.ts ===\n'
cat -n src/composables/tours/useFirstRunTourController.ts | sed -n '1,260p'

printf '\n=== useBillingContext.ts ===\n'
cat -n src/composables/billing/useBillingContext.ts | sed -n '1,260p'

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 7581


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n=== src/renderer/extensions/firstRunTour/FirstRunTour.vue ===\n'
cat -n src/renderer/extensions/firstRunTour/FirstRunTour.vue | sed -n '1,220p'

printf '\n=== src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts ===\n'
cat -n src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts | sed -n '1,320p'

printf '\n=== src/composables/billing/useBillingContext.ts ===\n'
cat -n src/composables/billing/useBillingContext.ts | sed -n '1,340p'

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 18990


🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n 'isCloud|useBillingContext|document\.addEventListener|watch\(|onMounted|fetch|api\.|useWorkspaceBilling|useTeamWorkspaceStore|createSharedComposable|subscriptionDialog|billingStatus' \
  src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts \
  src/composables/billing/useBillingContext.ts \
  src/renderer/extensions/firstRunTour/FirstRunTour.vue

printf '\n=== key slices: useFirstRunTourController.ts ===\n'
sed -n '1,220p' src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts

printf '\n=== key slices: useBillingContext.ts ===\n'
sed -n '1,240p' src/composables/billing/useBillingContext.ts

Repository: Comfy-Org/ComfyUI_frontend

Length of output: 15816


Gate FirstRunTour behind the first-run/cloud flow

FirstRunTour is mounted for every session, but its setup immediately calls useFirstRunTourController(), which wires useBillingContext() and its immediate watches. That starts billing/workspace initialization even when the tour can never appear. Gate the component where isCloud is available, or move the controller behind the visible branch.

🤖 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/views/GraphView.vue` at line 33, Update GraphView’s FirstRunTour
rendering to mount it only within the existing first-run/cloud condition, using
the available isCloud state. Ensure useFirstRunTourController is not initialized
for sessions where the tour cannot appear.

The landing carries no step number, so a bail there was only visible as an
absent step_number — indistinguishable from a dropped property, and easy to
misread as broken instrumentation.

That matters because the landing is where almost all abandonment happens.
In the first two days of app-mode rollout, of 63 starters 38 skipped and
every one of them emitted a single unnumbered step_shown; all 23 who got
past the landing went on to finish all four steps. The one number worth
watching had to be inferred from a missing field.

Adds is_landing to the tour metadata, set on the stages that happen on the
landing. step_number and coach_id keep their existing contract — absent for
unnumbered steps — so nothing downstream changes shape.

@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 (6)
src/platform/telemetry/types.ts (2)

441-442: ⚠️ Potential issue | 🟠 Major

Duplicate: keep telemetry contracts aligned with existing consumers.

This diff still tightens SubscriptionSuccessMetadata and removes existing telemetry exports, provider methods, event constants, and payload types. Prior review context identified in-repo consumers for these contracts; without migrating them in the same change, imports and typechecking will break and telemetry may be silently lost. Restore the contracts or update every caller/provider before merging.

Also applies to: 568-583, 614-615, 689-690, 731-732, 801-802, 829-834, 862-863, 873-874

🤖 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/platform/telemetry/types.ts` around lines 441 - 442, Keep the telemetry
API backward-compatible by restoring the removed exports, provider methods,
event constants, and payload types, and preserve the existing shape of
SubscriptionSuccessMetadata. Alternatively, update every in-repo consumer and
provider that references these contracts in the same change, ensuring imports
and telemetry emission remain intact and typechecking passes.

192-196: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Keep ExecutionOutcomeMetadata aligned with current telemetry callers. executionStore.ts, src/scripts/app.ts, and DatadogRumTelemetryProvider.ts still pass/read submissionAcceptedAt, executionStartedAt, endTime, success, and failureReason; narrowing the shape here breaks the shared telemetry contract. Update the producers/providers together or keep the existing fields.

🤖 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/platform/telemetry/types.ts` around lines 192 - 196, Update the
ExecutionOutcomeMetadata interface to preserve the shared telemetry fields used
by executionStore.ts, app.ts, and DatadogRumTelemetryProvider:
submissionAcceptedAt, executionStartedAt, endTime, success, and failureReason.
Align the interface with those existing producers and consumers instead of
replacing the contract with only startTime and outcome.
src/platform/onboarding/onboardingTourStore.ts (4)

143-152: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not emit step_shown after a failed onEnter.

The catch block only logs the error, then the code clears opening and records step_shown. A failed setup can therefore display a broken step while analytics reports success. Abort or route to an actionable error state instead.

As per coding guidelines, implement proper error propagation and user-friendly, actionable error messages.

🤖 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/platform/onboarding/onboardingTourStore.ts` around lines 143 - 152,
Update the onEnter error handling in the onboarding transition flow around
nextStep.onEnter so a non-abort failure is propagated or routed to the existing
actionable error state, rather than continuing to clear opening and call
trackTour('step_shown'). Preserve the abort behavior for signal.aborted and
provide a user-facing actionable error message through the established
error-handling path.

Source: Coding guidelines


143-151: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Gate navigation while onEnter is pending.

stepIdx changes before the async hook completes, while waitingForTarget remains false. A user can press Next during a slow hook; the next transition aborts the current hook and can desynchronize the visible step from telemetry. Keep navigation disabled until the transition finishes.

🤖 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/platform/onboarding/onboardingTourStore.ts` around lines 143 - 151,
Disable navigation for the duration of the async onEnter transition in the
step-advance flow around nextStep.onEnter. Set the existing transition/loading
guard before awaiting the hook and clear it only after completion or abort
handling, so Next cannot trigger another transition while onEnter is pending;
preserve the current error logging and aborted-signal behavior.

211-213: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Handle rejected async tour startup promises.

begin() awaits the tour definition without handling rejection. Both the auto-open watcher and replayTour() discard the promise with void, so a resolver or step-building failure becomes an unhandled rejection with no actionable user-facing error.

As per coding guidelines, implement proper error handling and user-friendly, actionable error messages.

Also applies to: 231-245, 254-255

🤖 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/platform/onboarding/onboardingTourStore.ts` around lines 211 - 213, The
async tour startup flow in begin(), the immediate auto-open watcher, and
replayTour() must handle rejected promises instead of discarding them with void.
Catch failures from resolving or building the tour steps, log or surface a clear
actionable user-facing error through the existing onboarding error mechanism,
and ensure watcher/replay callers consume the handled promise without unhandled
rejections.

Source: Coding guidelines


207-217: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Cancel pending auto-open starts when eligibility is lost.

During await definition(), activeTour is still null, so the holds watcher cannot cancel the pending start. If the trigger disappears during resolution, the tour can still open after the user is no longer eligible. Track the pending start or re-check eligibility before committing the resolved steps.

Also applies to: 231-243

🤖 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/platform/onboarding/onboardingTourStore.ts` around lines 207 - 217,
Update the auto-open flow around useTourTriggers, trigger.autoOpen, and
trigger.holds so a start pending during await definition() is canceled when
eligibility is lost. Track and invalidate the pending start, or re-check the
trigger’s current eligibility immediately before committing resolved steps,
ensuring no tour opens after holds becomes false; apply the same protection to
the corresponding flow at the later referenced block.
🤖 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/platform/onboarding/onboardingTourStore.ts`:
- Around line 143-152: Update the onEnter error handling in the onboarding
transition flow around nextStep.onEnter so a non-abort failure is propagated or
routed to the existing actionable error state, rather than continuing to clear
opening and call trackTour('step_shown'). Preserve the abort behavior for
signal.aborted and provide a user-facing actionable error message through the
established error-handling path.
- Around line 143-151: Disable navigation for the duration of the async onEnter
transition in the step-advance flow around nextStep.onEnter. Set the existing
transition/loading guard before awaiting the hook and clear it only after
completion or abort handling, so Next cannot trigger another transition while
onEnter is pending; preserve the current error logging and aborted-signal
behavior.
- Around line 211-213: The async tour startup flow in begin(), the immediate
auto-open watcher, and replayTour() must handle rejected promises instead of
discarding them with void. Catch failures from resolving or building the tour
steps, log or surface a clear actionable user-facing error through the existing
onboarding error mechanism, and ensure watcher/replay callers consume the
handled promise without unhandled rejections.
- Around line 207-217: Update the auto-open flow around useTourTriggers,
trigger.autoOpen, and trigger.holds so a start pending during await definition()
is canceled when eligibility is lost. Track and invalidate the pending start, or
re-check the trigger’s current eligibility immediately before committing
resolved steps, ensuring no tour opens after holds becomes false; apply the same
protection to the corresponding flow at the later referenced block.

In `@src/platform/telemetry/types.ts`:
- Around line 441-442: Keep the telemetry API backward-compatible by restoring
the removed exports, provider methods, event constants, and payload types, and
preserve the existing shape of SubscriptionSuccessMetadata. Alternatively,
update every in-repo consumer and provider that references these contracts in
the same change, ensuring imports and telemetry emission remain intact and
typechecking passes.
- Around line 192-196: Update the ExecutionOutcomeMetadata interface to preserve
the shared telemetry fields used by executionStore.ts, app.ts, and
DatadogRumTelemetryProvider: submissionAcceptedAt, executionStartedAt, endTime,
success, and failureReason. Align the interface with those existing producers
and consumers instead of replacing the contract with only startTime and outcome.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 84ea58f1-aa32-49c5-924e-349808304d8c

📥 Commits

Reviewing files that changed from the base of the PR and between 7a665bf and 97cc4cb.

📒 Files selected for processing (3)
  • src/platform/onboarding/onboardingTourStore.test.ts
  • src/platform/onboarding/onboardingTourStore.ts
  • src/platform/telemetry/types.ts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant