fix: narrow the coachmark i18n exemption to derived step keys

- only onboardingCoachmarks.<tour>.<step>.* is dynamically built;
  top-level keys (stepLabel, next, done, skip) stay checked

browser_tests/fixtures/ComfyPage.ts

@@ -4,6 +4,7 @@ import { config as dotenvConfig } from 'dotenv'
 import MCR from 'monocart-coverage-reports'
 
 import { COVERAGE_OUTPUT_DIR } from '@e2e/coverageConfig'
+import { TOURS } from '@/platform/onboarding/onboardingTours'
 import { NodeBadgeMode } from '@/types/nodeSource'
 import { ComfyActionbar } from '@e2e/fixtures/components/Actionbar'
 import { ComfyTemplates } from '@e2e/fixtures/components/Templates'
@@ -535,6 +536,8 @@ export const comfyPageFixture = base.extend<{
         'Comfy.userId': userId,
         // Set tutorial completed to true to avoid loading the tutorial workflow.
         'Comfy.TutorialCompleted': true,
+        // An auto-opened tour's blocker would break unrelated tests.
+        'Comfy.OnboardingCoachmarks.Seen': Object.keys(TOURS),
         'Comfy.Queue.MaxHistoryItems': 64,
         'Comfy.SnapToGrid.GridSize': testComfySnapToGridGridSize,
         'Comfy.VueNodes.AutoScaleLayout': false,

browser_tests/fixtures/components/Tour.ts

@@ -0,0 +1,74 @@
+import type { Locator, Page } from '@playwright/test'
+
+export type CoachTour = 'appMode'
+
+const SEEN_SETTING = 'Comfy.OnboardingCoachmarks.Seen'
+
+/** Accessible name of each tour's in-app replay (help) button. */
+const TOUR_REPLAY_BUTTONS: Record<CoachTour, string> = {
+  appMode: 'Take a tour of App Mode'
+}
+
+/** Coach-mark overlay (src/platform/onboarding/TourOverlay.vue). */
+export class OnboardingCoachmarks {
+  public readonly landing: Locator
+  public readonly landingStartButton: Locator
+  public readonly landingSkipButton: Locator
+  /** The current spotlight step card (the dialog carrying a "Step N of M" label). */
+  public readonly card: Locator
+  public readonly cardNextButton: Locator
+
+  constructor(public readonly page: Page) {
+    this.landing = page.getByTestId('coach-landing')
+    this.landingStartButton = this.landing.getByRole('button', {
+      name: 'Start tutorial'
+    })
+    this.landingSkipButton = this.landing.getByRole('button', {
+      name: 'Skip for now'
+    })
+    this.card = page.getByRole('dialog').filter({ hasText: /Step \d+ of \d+/ })
+    this.cardNextButton = this.card.getByRole('button', { name: 'Next' })
+  }
+
+  /** The tour's in-app help button, which replays it past the seen-flag. */
+  replayButton(tour: CoachTour): Locator {
+    return this.page.getByRole('button', { name: TOUR_REPLAY_BUTTONS[tour] })
+  }
+
+  /** The spotlight card while it is showing the given step number. */
+  cardForStep(step: number): Locator {
+    return this.card.filter({ hasText: new RegExp(`Step ${step} of `) })
+  }
+
+  /**
+   * Clears the pre-seeded seen-flag (so dismissal assertions observe it being
+   * set again) and clicks the tour's replay button, which must be mounted.
+   */
+  async startTour(tour: CoachTour) {
+    await this.clearSeen()
+    await this.replayButton(tour).click()
+  }
+
+  private async clearSeen() {
+    await this.page.evaluate(
+      async (key) => window.app!.extensionManager.setting.set(key, []),
+      SEEN_SETTING
+    )
+  }
+
+  /** An element a tour points at, by its `data-coach-id` anchor. */
+  coachAnchor(id: string): Locator {
+    return this.page.locator(`[data-coach-id="${id}"]`)
+  }
+
+  async seen(tour: CoachTour): Promise<boolean> {
+    const seen = await this.page.evaluate(
+      async (key) =>
+        (await window.app!.extensionManager.setting.get(key)) as
+          | string[]
+          | undefined,
+      SEEN_SETTING
+    )
+    return !!seen?.includes(tour)
+  }
+}

browser_tests/fixtures/tourFixture.ts

@@ -0,0 +1,11 @@
+import { test as base } from '@playwright/test'
+
+import { OnboardingCoachmarks } from '@e2e/fixtures/components/Tour'
+
+export const onboardingFixture = base.extend<{
+  onboarding: OnboardingCoachmarks
+}>({
+  onboarding: async ({ page }, use) => {
+    await use(new OnboardingCoachmarks(page))
+  }
+})

browser_tests/tests/tour.spec.ts

@@ -0,0 +1,98 @@
+import { expect, mergeTests } from '@playwright/test'
+
+import { comfyPageFixture } from '@e2e/fixtures/ComfyPage'
+import { onboardingFixture } from '@e2e/fixtures/tourFixture'
+
+import { COACH_IDS } from '@/platform/onboarding/onboardingTours'
+
+const test = mergeTests(comfyPageFixture, onboardingFixture)
+
+// Relies on the default workflow the test server loads (locally: pnpm dev:test)
+// — an empty graph would show the welcome screen, not the tour's controls.
+test.describe('Onboarding coachmarks', { tag: '@ui' }, () => {
+  test.describe('app-mode tour', () => {
+    test('opens on the welcome landing, focuses Start, and Skip dismisses it', async ({
+      comfyPage,
+      onboarding
+    }) => {
+      await comfyPage.appMode.enterAppModeWithInputs([])
+      await onboarding.startTour('appMode')
+      const coach = onboarding
+
+      await expect(coach.landing).toBeVisible()
+      await expect(coach.landing.getByRole('heading')).toHaveText(
+        'Welcome to Apps'
+      )
+      await expect(coach.landingStartButton).toBeFocused()
+
+      await coach.landingSkipButton.click()
+      await expect(coach.landing).toBeHidden()
+      expect(await coach.seen('appMode')).toBe(true)
+    })
+
+    test('Escape dismisses the welcome landing and marks it seen', async ({
+      comfyPage,
+      onboarding
+    }) => {
+      await comfyPage.appMode.enterAppModeWithInputs([])
+      await onboarding.startTour('appMode')
+      const coach = onboarding
+      await expect(coach.landing).toBeVisible()
+      await expect(coach.landingStartButton).toBeFocused()
+
+      await comfyPage.page.keyboard.press('Escape')
+      await expect(coach.landing).toBeHidden()
+      expect(await coach.seen('appMode')).toBe(true)
+    })
+  })
+
+  test.describe('coach anchors', () => {
+    test('every registry id resolves to an element (drift guard)', async ({
+      comfyPage,
+      onboarding
+    }) => {
+      const coach = onboarding
+      await comfyPage.appMode.enterAppModeWithInputs([])
+      // The assets panel only mounts once its button is clicked; every other
+      // anchor should already be present in a running app.
+      for (const id of Object.values(COACH_IDS).filter(
+        (id) => id !== COACH_IDS.assetsPanel
+      )) {
+        await expect(coach.coachAnchor(id)).toBeVisible()
+      }
+      await coach.coachAnchor(COACH_IDS.assetsButton).click()
+      await expect(coach.coachAnchor(COACH_IDS.assetsPanel)).toBeVisible()
+    })
+  })
+
+  test.describe('spotlight placement', () => {
+    test('every spotlight card stays fully within the viewport', async ({
+      comfyPage,
+      onboarding
+    }) => {
+      const coach = onboarding
+      // Read settled placements, not a transient mid-animation frame.
+      await comfyPage.page.emulateMedia({ reducedMotion: 'reduce' })
+      await comfyPage.appMode.enterAppModeWithInputs([])
+
+      await coach.startTour('appMode')
+      await expect(coach.landing).toBeVisible()
+      await coach.landingStartButton.click()
+
+      // Step 3 (outputs) is the vertically-centred `leftCenter` placement that
+      // must not slide off the top/bottom edge.
+      for (const step of [1, 2, 3]) {
+        const card = coach.cardForStep(step)
+        await expect(card).toBeVisible()
+        await expect(card).toBeInViewport({ ratio: 1 })
+        await coach.cardNextButton.click()
+      }
+
+      // Step 4 (assets button) advances by clicking its target, not Next.
+      await expect(coach.cardForStep(4)).toBeInViewport({ ratio: 1 })
+      await coach.coachAnchor('assets-button').click()
+
+      await expect(coach.cardForStep(5)).toBeInViewport({ ratio: 1 })
+    })
+  })
+})

package.json

@@ -73,6 +73,7 @@
     "@comfyorg/shared-frontend-utils": "workspace:*",
     "@comfyorg/tailwind-utils": "workspace:*",
     "@customerio/cdp-analytics-browser": "catalog:",
+    "@floating-ui/vue": "catalog:",
     "@formkit/auto-animate": "catalog:",
     "@iconify/json": "catalog:",
     "@primeuix/forms": "catalog:",

pnpm-lock.yaml

@@ -30,6 +30,9 @@ catalogs:
     '@eslint/js':
       specifier: ^10.0.1
       version: 10.0.1
+    '@floating-ui/vue':
+      specifier: ^1.1.11
+      version: 1.1.11
     '@formkit/auto-animate':
       specifier: ^0.9.0
       version: 0.9.0
@@ -465,6 +468,9 @@ importers:
       '@customerio/cdp-analytics-browser':
         specifier: 'catalog:'
         version: 0.5.3
+      '@floating-ui/vue':
+        specifier: 'catalog:'
+        version: 1.1.11(vue@3.5.34(typescript@5.9.3))
       '@formkit/auto-animate':
         specifier: 'catalog:'
         version: 0.9.0

pnpm-workspace.yaml

@@ -18,6 +18,7 @@ catalog:
   '@comfyorg/comfyui-electron-types': 0.6.2
   '@customerio/cdp-analytics-browser': ^0.5.3
   '@eslint/js': ^10.0.1
+  '@floating-ui/vue': ^1.1.11
   '@formkit/auto-animate': ^0.9.0
   '@iconify-json/lucide': ^1.1.178
   '@iconify/json': ^2.2.380

scripts/check-unused-i18n-keys.ts

@@ -15,6 +15,7 @@ const IGNORE_PATTERNS = [
   /^dataTypes\./, // Data types might be referenced dynamically
   /^contextMenu\./, // Context menu items might be dynamic
   /^color\./, // Color names might be used dynamically
+  /^onboardingCoachmarks\.[^.]+\.[^.]+\./, // Step keys derived as onboardingCoachmarks.<tour>.<step>.*
   // Auto-generated categories from collect-i18n-general.ts
   /^menuLabels\./, // Menu labels generated from command labels
   /^settingsCategories\./, // Settings categories generated from setting definitions

src/components/appMode/AppModeToolbar.vue

@@ -7,6 +7,7 @@ import { useErrorHandling } from '@/composables/useErrorHandling'
 import { useFeatureFlags } from '@/composables/useFeatureFlags'
 import Button from '@/components/ui/button/Button.vue'
 import { useAppMode } from '@/composables/useAppMode'
+import { vCoachmark } from '@/platform/onboarding/vCoachmark'
 import { isCloud } from '@/platform/distribution/types'
 import {
   openShareDialog,
@@ -87,6 +88,7 @@ function showApps() {
             value: t('sideToolbar.mediaAssets.title'),
             ...tooltipOptions
           }"
+          v-coachmark="'assets-button'"
           variant="textonly"
           size="unset"
           :aria-label="t('sideToolbar.mediaAssets.title')"

src/components/dialog/vRekaZIndex.ts

@@ -1,6 +1,10 @@
 import { ZIndex } from '@primeuix/utils/zindex'
 import type { Directive } from 'vue'
 
+/** Shared PrimeVue/Reka modal stacking sequence; later registrations cover earlier ones. */
+export const MODAL_Z_KEY = 'modal'
+export const MODAL_Z_BASE = 1700
+
 // Both Reka and PrimeVue dialogs can appear at any depth in dialogStack, in
 // any order. PrimeVue auto-increments a per-key z-index counter so later
 // dialogs always cover earlier ones; Reka uses a static z-1700 class which
@@ -9,7 +13,7 @@ import type { Directive } from 'vue'
 // renderers share one stacking sequence: whichever dialog opens last wins.
 export const vRekaZIndex: Directive<HTMLElement> = {
   mounted(el) {
-    ZIndex.set('modal', el, 1700)
+    ZIndex.set(MODAL_Z_KEY, el, MODAL_Z_BASE)
   },
   beforeUnmount(el) {
     ZIndex.clear(el)

src/locales/en/main.json

@@ -3713,6 +3713,7 @@
     "welcome": {
       "title": "App Mode",
       "message": "A simplified view that hides the node graph so you can focus on creating.",
+      "startTour": "Take a tour of App Mode",
       "controls": "Your outputs appear at the bottom, your controls are on the right. Everything else stays out of the way.",
       "sharing": "Share your workflow as a simple tool anyone can use. Export it from the tab menu and when others open it, they'll see App Mode. No node graph knowledge needed.",
       "getStarted": "Click {runButton} to get started.",
@@ -4489,5 +4490,39 @@
     "training": "Training…",
     "processingVideo": "Processing video…",
     "running": "Running…"
+  },
+  "onboardingCoachmarks": {
+    "stepLabel": "Step {current} of {total}",
+    "skip": "Skip",
+    "next": "Next",
+    "done": "Done",
+    "appMode": {
+      "landing": {
+        "title": "Welcome to Apps",
+        "body": "A quick tour of the essentials, in about a minute. You'll fill inputs and see your first generation.",
+        "primary": "Start tutorial",
+        "skip": "Skip for now"
+      },
+      "inputs": {
+        "title": "Add your inputs",
+        "body": "Add what you want to work with. Your inputs are what the app turns into results."
+      },
+      "run": {
+        "title": "Run your app",
+        "body": "Happy with your inputs? Hit Run and your result appears in the center the moment it's ready."
+      },
+      "outputs": {
+        "title": "Get your results",
+        "body": "Your finished results show up here in the center. Download them, or tweak an input and run again."
+      },
+      "assetsButton": {
+        "title": "Open your assets",
+        "body": "Click the Assets button in the left toolbar to open your media library."
+      },
+      "assets": {
+        "title": "Find all your assets",
+        "body": "Every generation and import lives in Media Assets. Open it anytime to browse, download, or reuse past work."
+      }
+    }
   }
 }

src/platform/onboarding/CoachmarkCard.test.ts

@@ -0,0 +1,67 @@
+import { cleanup, render, screen } from '@testing-library/vue'
+import { afterEach, describe, expect, it } from 'vitest'
+import { h } from 'vue'
+
+import CoachmarkCard from './CoachmarkCard.vue'
+
+afterEach(cleanup)
+
+describe('CoachmarkCard', () => {
+  it('renders the title, message and subtitle', () => {
+    render(CoachmarkCard, {
+      props: {
+        title: 'This is your canvas',
+        message: 'Scroll to zoom.',
+        subtitle: 'Step 1 of 3'
+      }
+    })
+    expect(screen.getByRole('heading')).toHaveTextContent('This is your canvas')
+    expect(screen.getByText('Scroll to zoom.')).toBeTruthy()
+    expect(screen.getByText('Step 1 of 3')).toBeTruthy()
+  })
+
+  it('applies titleId to the heading for aria-labelledby wiring', () => {
+    render(CoachmarkCard, {
+      props: { title: 'Heading', message: 'M', titleId: 'title-1' }
+    })
+    expect(screen.getByRole('heading').id).toBe('title-1')
+  })
+
+  it('applies messageId to the message for aria-describedby wiring', () => {
+    render(CoachmarkCard, {
+      props: { title: 'T', message: 'Body copy', messageId: 'desc-1' }
+    })
+    expect(screen.getByText('Body copy').id).toBe('desc-1')
+  })
+
+  it('omits the subtitle when not provided', () => {
+    render(CoachmarkCard, { props: { title: 'T', message: 'M' } })
+    expect(screen.queryByText('Step 1 of 3')).toBeNull()
+  })
+
+  it('renders the image when an image src is given', () => {
+    render(CoachmarkCard, {
+      props: { title: 'T', message: 'M', image: '/foo.png' }
+    })
+    expect(screen.getByAltText('')).toHaveAttribute('src', '/foo.png')
+  })
+
+  it('renders an image slot in place of the default image', () => {
+    render(CoachmarkCard, {
+      props: { title: 'T', message: 'M' },
+      slots: { image: () => h('img', { src: '/slot.png', alt: 'preview' }) }
+    })
+    expect(screen.getByRole('img', { name: 'preview' })).toHaveAttribute(
+      'src',
+      '/slot.png'
+    )
+  })
+
+  it('renders the actions slot', () => {
+    render(CoachmarkCard, {
+      props: { title: 'T', message: 'M' },
+      slots: { actions: () => h('button', 'Next') }
+    })
+    expect(screen.getByRole('button', { name: 'Next' })).toBeTruthy()
+  })
+})

src/platform/onboarding/CoachmarkCard.vue

@@ -0,0 +1,50 @@
+<template>
+  <div
+    class="flex w-full flex-col items-start justify-center gap-3 rounded-2xl bg-secondary-background p-4 drop-shadow-[1px_1px_8px_rgba(0,0,0,0.4)]"
+  >
+    <div
+      v-if="image || $slots.image"
+      class="flex h-[146px] flex-col items-start justify-center gap-4 self-stretch overflow-hidden rounded-xl bg-base-background"
+    >
+      <slot name="image">
+        <img v-if="image" :src="image" alt="" class="size-full object-cover" />
+      </slot>
+    </div>
+    <div class="flex flex-col items-end justify-end gap-6 self-stretch">
+      <div class="flex flex-col items-start gap-2 self-stretch">
+        <p
+          v-if="subtitle"
+          :id="subtitleId"
+          class="m-0 text-xs/normal text-base-foreground"
+        >
+          {{ subtitle }}
+        </p>
+        <h3
+          :id="titleId"
+          class="m-0 text-base/normal font-semibold text-base-foreground"
+        >
+          {{ title }}
+        </h3>
+        <p :id="messageId" class="m-0 text-sm/normal text-muted-foreground">
+          {{ message }}
+        </p>
+      </div>
+      <div v-if="$slots.actions" class="flex items-center gap-3">
+        <slot name="actions" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const { title, titleId, message, subtitle, subtitleId, image, messageId } =
+  defineProps<{
+    title: string
+    titleId?: string
+    message: string
+    subtitle?: string
+    subtitleId?: string
+    image?: string
+    messageId?: string
+  }>()
+</script>

src/platform/onboarding/CoachmarkLanding.test.ts

@@ -0,0 +1,61 @@
+import { cleanup, render, screen } from '@testing-library/vue'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createI18n } from 'vue-i18n'
+
+import CoachmarkLanding from './CoachmarkLanding.vue'
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: { en: { g: { close: 'Close' } } }
+})
+
+function renderLanding() {
+  return render(CoachmarkLanding, {
+    props: {
+      title: 'Welcome to Apps',
+      message: 'A quick tour of the essentials.',
+      primaryLabel: 'Start tutorial',
+      skipLabel: 'Skip for now'
+    },
+    global: { plugins: [i18n] }
+  })
+}
+
+describe('CoachmarkLanding', () => {
+  afterEach(cleanup)
+
+  it('renders the title and message', async () => {
+    renderLanding()
+    expect(await screen.findByText('Welcome to Apps')).toBeTruthy()
+    expect(screen.getByText('A quick tour of the essentials.')).toBeTruthy()
+  })
+
+  it('emits start when the primary action is clicked', async () => {
+    const user = userEvent.setup()
+    const { emitted } = renderLanding()
+    await user.click(
+      await screen.findByRole('button', { name: 'Start tutorial' })
+    )
+    expect(emitted().start).toHaveLength(1)
+  })
+
+  it('emits skip when Skip is clicked', async () => {
+    const user = userEvent.setup()
+    const { emitted } = renderLanding()
+    await user.click(
+      await screen.findByRole('button', { name: 'Skip for now' })
+    )
+    expect(emitted().skip).toHaveLength(1)
+  })
+
+  it('emits skip when Escape is pressed', async () => {
+    const user = userEvent.setup()
+    const { emitted } = renderLanding()
+    await screen.findByText('Welcome to Apps')
+    await user.keyboard('{Escape}')
+    // The explicit listener and Reka's own dismiss may both fire here.
+    expect(emitted().skip?.length).toBeGreaterThanOrEqual(1)
+  })
+})

src/platform/onboarding/CoachmarkLanding.vue

@@ -0,0 +1,110 @@
+<template>
+  <Dialog :open="true" @update:open="(value) => !value && emit('skip')">
+    <DialogPortal>
+      <DialogOverlay v-reka-z-index class="bg-black/60" />
+      <DialogContent
+        v-reka-z-index
+        data-testid="coach-landing"
+        class="w-[800px] max-w-[calc(100vw-2.5rem)] overflow-hidden rounded-2xl border-border-default bg-secondary-background p-0 shadow-[0_24px_80px_rgba(0,0,0,0.85)] md:min-h-98 md:max-w-[800px] md:flex-row"
+        @pointer-down-outside.prevent
+        @open-auto-focus="onOpenAutoFocus"
+      >
+        <DialogClose as-child>
+          <Button
+            variant="muted-textonly"
+            size="icon"
+            :aria-label="t('g.close')"
+            class="absolute top-3 right-3 z-20"
+          >
+            <i class="icon-[lucide--x]" />
+          </Button>
+        </DialogClose>
+        <div
+          class="flex aspect-video items-center justify-center bg-base-background md:aspect-auto md:w-1/2"
+        >
+          <img
+            v-if="image"
+            :src="image"
+            alt=""
+            class="size-full object-cover"
+          />
+        </div>
+        <div
+          class="flex flex-col items-start justify-between self-stretch px-15 pt-15 pb-10 md:w-1/2"
+        >
+          <div class="flex flex-col gap-3">
+            <DialogTitle
+              class="m-0 text-[28px] leading-normal font-medium text-base-foreground"
+            >
+              {{ title }}
+            </DialogTitle>
+            <DialogDescription
+              class="flex flex-col items-start gap-2 self-stretch py-2 text-base/5 text-muted-foreground"
+            >
+              {{ message }}
+            </DialogDescription>
+          </div>
+          <div class="flex w-full items-center justify-end gap-2">
+            <Button variant="secondary" size="lg" @click="emit('skip')">
+              {{ skipLabel }}
+            </Button>
+            <Button
+              ref="startButtonRef"
+              variant="inverted"
+              size="lg"
+              @click="emit('start')"
+            >
+              {{ primaryLabel }}
+            </Button>
+          </div>
+        </div>
+      </DialogContent>
+    </DialogPortal>
+  </Dialog>
+</template>
+
+<script setup lang="ts">
+import { useEventListener } from '@vueuse/core'
+import { useTemplateRef } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import Dialog from '@/components/ui/dialog/Dialog.vue'
+import DialogClose from '@/components/ui/dialog/DialogClose.vue'
+import DialogContent from '@/components/ui/dialog/DialogContent.vue'
+import DialogDescription from '@/components/ui/dialog/DialogDescription.vue'
+import DialogOverlay from '@/components/ui/dialog/DialogOverlay.vue'
+import DialogPortal from '@/components/ui/dialog/DialogPortal.vue'
+import DialogTitle from '@/components/ui/dialog/DialogTitle.vue'
+import Button from '@/components/ui/button/Button.vue'
+import { vRekaZIndex } from '@/components/dialog/vRekaZIndex'
+
+const { title, message, image, primaryLabel, skipLabel } = defineProps<{
+  title: string
+  message: string
+  image?: string
+  primaryLabel: string
+  skipLabel: string
+}>()
+
+const emit = defineEmits<{
+  start: []
+  skip: []
+}>()
+
+const { t } = useI18n()
+
+// The global keybinding handler preventDefaults Escape before Reka's
+// DismissableLayer sees it, so Reka skips its own dismiss; do it explicitly.
+useEventListener(document, 'keydown', (e) => {
+  if (e.key === 'Escape') emit('skip')
+})
+
+const startButtonRef = useTemplateRef('startButtonRef')
+
+// Land focus on the primary action, not the close button Reka would pick.
+function onOpenAutoFocus(event: Event) {
+  event.preventDefault()
+  const el = startButtonRef.value?.$el as HTMLButtonElement | undefined
+  el?.focus()
+}
+</script>

src/platform/onboarding/TourOverlay.test.ts

@@ -0,0 +1,121 @@
+import { fromPartial } from '@total-typescript/shoehorn'
+import { cleanup, render, screen } from '@testing-library/vue'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, ref } from 'vue'
+import { createI18n } from 'vue-i18n'
+
+import TourOverlay from './TourOverlay.vue'
+import type { CoachStep } from './onboardingTours'
+import { useCoachmarkTour } from './useCoachmarkTour'
+
+vi.mock('./useCoachmarkTour', () => ({ useCoachmarkTour: vi.fn() }))
+
+function makeTourState() {
+  return {
+    step: ref<CoachStep | null>(null),
+    title: ref('Canvas title'),
+    body: ref('Canvas body'),
+    isLast: ref(false),
+    primaryLabel: ref('Next'),
+    skipLabel: ref('Skip'),
+    countedStepIdx: ref(0),
+    countedSteps: ref<CoachStep[]>([]),
+    suspendFocusGuard: ref(false),
+    next: vi.fn(),
+    end: vi.fn()
+  }
+}
+
+// Stubbed so the suite covers only TourOverlay's branching and intent wiring.
+vi.mock('./TourSpotlight.vue', () => ({
+  default: defineComponent({
+    emits: ['advance', 'skip'],
+    setup(_, { emit }) {
+      return () =>
+        h('div', { 'data-testid': 'spotlight' }, [
+          h('button', { onClick: () => emit('advance') }, 'advance'),
+          h('button', { onClick: () => emit('skip') }, 'skip')
+        ])
+    }
+  })
+}))
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      g: { close: 'Close' }
+    }
+  }
+})
+
+let s: ReturnType<typeof makeTourState>
+
+const spotlightStep: CoachStep = {
+  name: 'run',
+  placement: 'right'
+}
+
+function landingStep(): CoachStep {
+  return { name: 'landing', placement: 'center', landing: true }
+}
+
+function renderOverlay() {
+  return render(TourOverlay, { global: { plugins: [i18n] } })
+}
+
+describe('TourOverlay', () => {
+  beforeEach(() => {
+    s = makeTourState()
+    vi.mocked(useCoachmarkTour).mockReturnValue(fromPartial(s))
+  })
+
+  afterEach(cleanup)
+
+  it('renders nothing when no tour step is active', () => {
+    renderOverlay()
+    expect(screen.queryByTestId('spotlight')).toBeNull()
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('renders the spotlight for a non-landing step and wires its intents', async () => {
+    const user = userEvent.setup()
+    s.step.value = spotlightStep
+    renderOverlay()
+
+    expect(screen.getByTestId('spotlight')).toBeTruthy()
+
+    await user.click(screen.getByRole('button', { name: 'advance' }))
+    expect(s.next).toHaveBeenCalledOnce()
+
+    await user.click(screen.getByRole('button', { name: 'skip' }))
+    expect(s.end).toHaveBeenCalledWith('skipped')
+  })
+
+  it('renders the landing step and starts the tour on its primary action', async () => {
+    const user = userEvent.setup()
+    s.step.value = landingStep()
+    s.primaryLabel.value = 'Start tutorial'
+    s.skipLabel.value = 'Skip for now'
+    renderOverlay()
+
+    await user.click(
+      await screen.findByRole('button', { name: 'Start tutorial' })
+    )
+    expect(s.next).toHaveBeenCalledOnce()
+  })
+
+  it('ends the tour when the landing is dismissed', async () => {
+    const user = userEvent.setup()
+    s.step.value = landingStep()
+    s.skipLabel.value = 'Skip for now'
+    renderOverlay()
+
+    await user.click(
+      await screen.findByRole('button', { name: 'Skip for now' })
+    )
+    expect(s.end).toHaveBeenCalledWith('skipped')
+  })
+})

src/platform/onboarding/TourOverlay.vue

@@ -0,0 +1,46 @@
+<template>
+  <CoachmarkLanding
+    v-if="step?.landing"
+    :title
+    :message="body"
+    :image="step.image"
+    :primary-label="primaryLabel"
+    :skip-label="skipLabel"
+    @start="next"
+    @skip="end('skipped')"
+  />
+  <TourSpotlight
+    v-else-if="step"
+    :step="step"
+    :title
+    :body
+    :is-last="isLast"
+    :primary-label="primaryLabel"
+    :skip-label="skipLabel"
+    :counted-step-idx="countedStepIdx"
+    :counted-steps-total="countedSteps.length"
+    :suspend-focus-guard="suspendFocusGuard"
+    @advance="next"
+    @skip="end('skipped')"
+  />
+</template>
+
+<script setup lang="ts">
+import CoachmarkLanding from './CoachmarkLanding.vue'
+import TourSpotlight from './TourSpotlight.vue'
+import { useCoachmarkTour } from './useCoachmarkTour'
+
+const {
+  step,
+  isLast,
+  title,
+  body,
+  primaryLabel,
+  skipLabel,
+  countedStepIdx,
+  countedSteps,
+  suspendFocusGuard,
+  next,
+  end
+} = useCoachmarkTour()
+</script>

src/platform/onboarding/TourSpotlight.test.ts

@@ -0,0 +1,195 @@
+import { cleanup, render, screen } from '@testing-library/vue'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+import { createI18n } from 'vue-i18n'
+import type { ComponentProps } from 'vue-component-type-helpers'
+
+import { clearCoachmarks, registerCoachmark } from './coachmarkRegistry'
+import TourSpotlight from './TourSpotlight.vue'
+import type { CoachId, CoachStep } from './onboardingTours'
+
+vi.mock('@primeuix/utils/zindex', () => ({
+  ZIndex: { set: vi.fn(), clear: vi.fn() }
+}))
+
+import { ZIndex } from '@primeuix/utils/zindex'
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      g: { close: 'Close' },
+      onboardingCoachmarks: { stepLabel: 'Step {current} of {total}' }
+    }
+  }
+})
+
+function spotlightStep(overrides: Partial<CoachStep> = {}): CoachStep {
+  return { name: 'run', placement: 'right', ...overrides }
+}
+
+const baseProps = {
+  title: 'Run your app',
+  body: 'Press to run',
+  isLast: false,
+  primaryLabel: 'Next',
+  skipLabel: 'Skip',
+  countedStepIdx: 0,
+  countedStepsTotal: 1,
+  suspendFocusGuard: false
+}
+
+function renderSpotlight(
+  props: Partial<ComponentProps<typeof TourSpotlight>> = {}
+) {
+  return render(TourSpotlight, {
+    props: { step: spotlightStep(), ...baseProps, ...props },
+    global: { plugins: [i18n] }
+  })
+}
+
+/** Register a laid-out target for an id so the spotlight resolves its rect. */
+function mountTarget(id: CoachId): HTMLElement {
+  const el = document.createElement('button')
+  el.getBoundingClientRect = () => new DOMRect(10, 10, 80, 30)
+  document.body.appendChild(el)
+  registerCoachmark(id, el)
+  return el
+}
+
+describe('TourSpotlight', () => {
+  afterEach(() => {
+    cleanup()
+    clearCoachmarks()
+    document.body.replaceChildren()
+    vi.useRealTimers()
+  })
+
+  it('renders the spotlight and card for a step', () => {
+    renderSpotlight()
+    expect(screen.getByTestId('coach-spotlight')).toBeTruthy()
+    // aria-labelledby points at the rendered heading, so the dialog's
+    // accessible name stays in sync with the visible title.
+    expect(screen.getByRole('dialog', { name: 'Run your app' })).toBeTruthy()
+    expect(screen.getByText('Press to run')).toBeTruthy()
+    expect(screen.getByText('Step 1 of 1')).toBeTruthy()
+  })
+
+  it('hides the Skip button on the last step', () => {
+    renderSpotlight({ isLast: true })
+    expect(screen.queryByRole('button', { name: 'Skip' })).toBeNull()
+    expect(screen.getByRole('button', { name: 'Next' })).toBeTruthy()
+  })
+
+  it('keeps Skip on the last step when it advances by target interaction', () => {
+    renderSpotlight({
+      isLast: true,
+      step: spotlightStep({
+        advanceOnTargetClick: true,
+        coachId: 'assets-button'
+      })
+    })
+    expect(screen.getByRole('button', { name: 'Skip' })).toBeTruthy()
+  })
+
+  it('claims the modal stack on mount and releases it on unmount', async () => {
+    vi.mocked(ZIndex.set).mockClear()
+    vi.mocked(ZIndex.clear).mockClear()
+
+    const { unmount } = renderSpotlight()
+    await nextTick()
+    await nextTick()
+    expect(ZIndex.set).toHaveBeenCalled()
+
+    unmount()
+    expect(ZIndex.clear).toHaveBeenCalled()
+  })
+
+  it('re-claims the modal stack per step without leaking entries', async () => {
+    vi.mocked(ZIndex.set).mockClear()
+    vi.mocked(ZIndex.clear).mockClear()
+
+    const { rerender, unmount } = renderSpotlight()
+    await nextTick()
+    await nextTick()
+
+    await rerender({ step: spotlightStep({ placement: 'left' }) })
+    await nextTick()
+    await nextTick()
+
+    unmount()
+    // Every set must pair with a clear (plus the unmount clear), or entries
+    // leak into the shared modal sequence.
+    expect(vi.mocked(ZIndex.clear).mock.calls.length).toBe(
+      vi.mocked(ZIndex.set).mock.calls.length + 1
+    )
+  })
+
+  it('emits advance on the primary button and skip on the secondary', async () => {
+    const user = userEvent.setup()
+    const { emitted } = renderSpotlight()
+
+    await user.click(screen.getByRole('button', { name: 'Next' }))
+    expect(emitted().advance).toHaveLength(1)
+
+    await user.click(screen.getByRole('button', { name: 'Skip' }))
+    expect(emitted().skip).toHaveLength(1)
+  })
+
+  it('emits skip when Escape is pressed', async () => {
+    const user = userEvent.setup()
+    const { emitted } = renderSpotlight()
+
+    await user.keyboard('{Escape}')
+    expect(emitted().skip).toHaveLength(1)
+  })
+
+  it('hides the primary button on a click-to-advance step', () => {
+    renderSpotlight({
+      step: spotlightStep({
+        advanceOnTargetClick: true,
+        coachId: 'assets-button'
+      })
+    })
+    expect(screen.queryByRole('button', { name: 'Next' })).toBeNull()
+  })
+
+  it('emits advance when the spotlighted target is clicked', async () => {
+    const user = userEvent.setup()
+    const target = mountTarget('assets-button')
+    const { emitted } = renderSpotlight({
+      step: spotlightStep({
+        advanceOnTargetClick: true,
+        coachId: 'assets-button'
+      })
+    })
+
+    await user.click(target)
+    expect(emitted().advance).toHaveLength(1)
+  })
+
+  it('pulses the outline after the user stalls on a click-to-advance step', async () => {
+    vi.useFakeTimers()
+    renderSpotlight({
+      step: spotlightStep({
+        advanceOnTargetClick: true,
+        coachId: 'assets-button'
+      })
+    })
+
+    expect(
+      screen.getByTestId('coach-spotlight').getAttribute('class')
+    ).not.toMatch(/coach-pulse/)
+    await vi.advanceTimersByTimeAsync(4000)
+    expect(screen.getByTestId('coach-spotlight').getAttribute('class')).toMatch(
+      /coach-pulse/
+    )
+  })
+
+  it('hides the spotlight and dims via the blocker for a step with no target', () => {
+    renderSpotlight({ step: spotlightStep({ placement: 'center' }) })
+    expect(screen.getByTestId('coach-spotlight').style.opacity).toBe('0')
+  })
+})

src/platform/onboarding/TourSpotlight.vue

@@ -0,0 +1,250 @@
+<template>
+  <div ref="overlayRef" class="pointer-events-none fixed inset-0">
+    <div
+      :class="
+        cn('pointer-events-auto absolute inset-0', !targetRect && 'bg-black/60')
+      "
+      :style="blockerStyle"
+    />
+    <div
+      aria-hidden="true"
+      data-testid="coach-spotlight"
+      :class="
+        cn(
+          'pointer-events-none absolute rounded-[10px] shadow-[0_0_0_9999px_rgba(0,0,0,0.6)] outline-2 outline-white motion-safe:transition-[left,top,width,height,opacity] motion-safe:duration-300',
+          outlinePulsing &&
+            'motion-safe:animate-[coach-pulse_1.2s_ease-in-out_infinite]'
+        )
+      "
+      :style="spotlightStyle"
+    />
+    <div
+      ref="cardRef"
+      role="dialog"
+      :aria-modal="!expectsTargetInteraction"
+      :aria-labelledby="titleId"
+      :aria-describedby="`${subtitleId} ${bodyId}`"
+      class="pointer-events-auto absolute max-h-[calc(100vh-72px)] overflow-y-auto motion-safe:transition-[left,top] motion-safe:duration-300"
+      :style="cardStyle"
+    >
+      <CoachmarkCard
+        :subtitle="
+          t('onboardingCoachmarks.stepLabel', {
+            current: countedStepIdx + 1,
+            total: countedStepsTotal
+          })
+        "
+        :subtitle-id="subtitleId"
+        :title
+        :title-id="titleId"
+        :message="body"
+        :message-id="bodyId"
+        :image="step.image"
+      >
+        <template #actions>
+          <Button
+            v-if="showSkip"
+            variant="secondary"
+            size="md"
+            @click="emit('skip')"
+          >
+            {{ skipLabel }}
+          </Button>
+          <Button
+            v-if="!expectsTargetInteraction"
+            variant="inverted"
+            size="md"
+            @click="emit('advance')"
+          >
+            {{ primaryLabel }}
+          </Button>
+        </template>
+      </CoachmarkCard>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { cn } from '@comfyorg/tailwind-utils'
+import { useEventListener, useWindowSize } from '@vueuse/core'
+import { ZIndex } from '@primeuix/utils/zindex'
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onScopeDispose,
+  ref,
+  useId,
+  watch
+} from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import { MODAL_Z_BASE, MODAL_Z_KEY } from '@/components/dialog/vRekaZIndex'
+import Button from '@/components/ui/button/Button.vue'
+
+import CoachmarkCard from './CoachmarkCard.vue'
+import {
+  CARD_WIDTH,
+  SPOTLIGHT_PAD,
+  VIEWPORT_MARGIN,
+  blockerClipPath,
+  clampSpotlight,
+  noTargetCardLeft
+} from './coachmarkLayout'
+import type { CoachStep } from './onboardingTours'
+import { useCoachmarkTarget } from './useCoachmarkTarget'
+import { useFocusTrap } from './useFocusTrap'
+
+const PULSE_IDLE_MS = 4000
+
+const {
+  step,
+  title,
+  body,
+  isLast,
+  primaryLabel,
+  skipLabel,
+  countedStepIdx,
+  countedStepsTotal,
+  suspendFocusGuard
+} = defineProps<{
+  step: CoachStep
+  title: string
+  body: string
+  isLast: boolean
+  primaryLabel: string
+  skipLabel: string
+  countedStepIdx: number
+  countedStepsTotal: number
+  suspendFocusGuard: boolean
+}>()
+
+const emit = defineEmits<{
+  advance: []
+  skip: []
+}>()
+
+const { t } = useI18n()
+const bodyId = useId()
+const subtitleId = useId()
+const titleId = useId()
+
+const overlayRef = ref<HTMLElement | null>(null)
+const cardRef = ref<HTMLElement | null>(null)
+const { width: windowWidth, height: windowHeight } = useWindowSize()
+
+const stepRef = computed<CoachStep | null>(() => step)
+const { targetRect, targetEl, floatingStyles, isPositioned } =
+  useCoachmarkTarget(stepRef, cardRef)
+
+const expectsTargetInteraction = computed(() => !!step.advanceOnTargetClick)
+// Last step's "Done" already dismisses, so hide Skip unless the step has no primary button.
+const showSkip = computed(() => !isLast || expectsTargetInteraction.value)
+
+const focusTrap = useFocusTrap({
+  cardRef,
+  getTarget: () => targetEl.value,
+  isSuspended: () => suspendFocusGuard,
+  onEscape: () => emit('skip')
+})
+
+useEventListener(
+  document,
+  'click',
+  (e: MouseEvent) => {
+    if (!expectsTargetInteraction.value) return
+    const target = targetEl.value
+    if (target && e.composedPath().includes(target)) emit('advance')
+  },
+  { capture: true }
+)
+
+const pulsing = ref(false)
+let pulseTimer: ReturnType<typeof setTimeout> | undefined
+const outlinePulsing = computed(
+  () => pulsing.value && expectsTargetInteraction.value
+)
+
+function schedulePulse() {
+  clearTimeout(pulseTimer)
+  pulsing.value = false
+  if (!expectsTargetInteraction.value) return
+  pulseTimer = setTimeout(() => {
+    pulsing.value = true
+  }, PULSE_IDLE_MS)
+}
+onScopeDispose(() => clearTimeout(pulseTimer))
+
+async function raiseOverlay() {
+  await nextTick()
+  const el = overlayRef.value
+  if (!el) return
+  // ZIndex.set pushes a fresh entry into the shared modal sequence on every
+  // call, so clear the previous one or per-step re-raises leak entries.
+  ZIndex.clear(el)
+  ZIndex.set(MODAL_Z_KEY, el, MODAL_Z_BASE)
+}
+
+// A deferred dialog may have registered above the overlay; reclaim the stack
+// top on every step.
+watch(
+  () => step,
+  () => {
+    schedulePulse()
+    void raiseOverlay()
+    void focusTrap.focusCard()
+  },
+  { immediate: true }
+)
+
+onBeforeUnmount(() => {
+  if (overlayRef.value) ZIndex.clear(overlayRef.value)
+})
+
+const viewport = () => ({
+  width: windowWidth.value,
+  height: windowHeight.value
+})
+
+const spotlightStyle = computed(() => {
+  const r = targetRect.value
+  if (!r) return { opacity: '0' }
+  return { ...clampSpotlight(r, SPOTLIGHT_PAD, viewport()), opacity: '1' }
+})
+
+// Interaction steps punch a hole in the blocker so only the target stays clickable.
+const blockerStyle = computed(() => {
+  const r = targetRect.value
+  if (r && expectsTargetInteraction.value)
+    return { clipPath: blockerClipPath(r) }
+  return {}
+})
+
+const cardStyle = computed(() => {
+  const width = `${CARD_WIDTH}px`
+  const maxWidth = `calc(100vw - ${VIEWPORT_MARGIN * 2}px)`
+  if (!targetEl.value) {
+    return {
+      width,
+      maxWidth,
+      left: `${noTargetCardLeft(windowWidth.value)}px`,
+      top: '30%'
+    }
+  }
+  // Hidden until Floating UI positions it, avoiding a first-frame jump.
+  return {
+    ...floatingStyles.value,
+    width,
+    maxWidth,
+    opacity: isPositioned.value ? '1' : '0'
+  }
+})
+</script>
+
+<style>
+@keyframes coach-pulse {
+  50% {
+    outline-color: rgb(255 255 255 / 0.4);
+  }
+}
+</style>

src/platform/onboarding/coachmarkController.ts

@@ -0,0 +1,9 @@
+import { createEventHook } from '@vueuse/core'
+
+import type { EntryPath } from './onboardingTours'
+
+// An explicit request to (re)play a tour, which starts it past its seen-flag.
+const tourRequested = createEventHook<EntryPath>()
+
+export const requestTour = tourRequested.trigger
+export const onTourRequested = tourRequested.on

src/platform/onboarding/coachmarkLayout.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  blockerClipPath,
+  clampSpotlight,
+  noTargetCardLeft
+} from './coachmarkLayout'
+
+const VIEWPORT = { width: 1000, height: 800 }
+
+describe('clampSpotlight', () => {
+  it('grows the target rect by the pad on every side', () => {
+    const r = new DOMRect(100, 100, 50, 40)
+    expect(clampSpotlight(r, 8, VIEWPORT)).toEqual({
+      left: '92px',
+      top: '92px',
+      width: '66px',
+      height: '56px'
+    })
+  })
+
+  it('clamps the near edges to the viewport inset', () => {
+    const r = new DOMRect(0, 0, 10, 10)
+    expect(clampSpotlight(r, 8, VIEWPORT)).toMatchObject({
+      left: '2px',
+      top: '2px'
+    })
+  })
+
+  it('clamps the far edges to the viewport inset', () => {
+    const r = new DOMRect(990, 100, 50, 40)
+    const { left, width } = clampSpotlight(r, 8, VIEWPORT)
+    expect(left).toBe('982px')
+    expect(width).toBe('16px')
+  })
+
+  it('never produces a negative size for an off-screen target', () => {
+    const r = new DOMRect(2000, 100, 50, 40)
+    expect(clampSpotlight(r, 8, VIEWPORT)).toMatchObject({ width: '0px' })
+  })
+})
+
+describe('blockerClipPath', () => {
+  it('punches a hole at the target rect corners', () => {
+    const clip = blockerClipPath(new DOMRect(10, 20, 30, 40))
+    expect(clip).toContain('evenodd')
+    // Inner loop traces the target rect (left/top → left/bottom → right/...).
+    expect(clip).toContain('10px 20px')
+    expect(clip).toContain('10px 60px')
+    expect(clip).toContain('40px 60px')
+    expect(clip).toContain('40px 20px')
+  })
+})
+
+describe('noTargetCardLeft', () => {
+  it('centers the card on a wide viewport', () => {
+    expect(noTargetCardLeft(1000)).toBe(350)
+  })
+
+  it('clamps to the viewport margin when the viewport is narrower than the card', () => {
+    expect(noTargetCardLeft(200)).toBe(12)
+  })
+})

src/platform/onboarding/coachmarkLayout.ts

@@ -0,0 +1,67 @@
+export interface Viewport {
+  width: number
+  height: number
+}
+
+export interface BoxStyle {
+  left: string
+  top: string
+  width: string
+  height: string
+}
+
+const SPOTLIGHT_EDGE_INSET = 2
+
+export const CARD_WIDTH = 300
+export const VIEWPORT_MARGIN = 12
+export const CARD_GAP = 16
+// Kept tight so the spotlight glow doesn't spill onto an adjacent clickable control.
+export const SPOTLIGHT_PAD = 4
+
+export function clampSpotlight(
+  r: DOMRect,
+  pad: number,
+  viewport: Viewport
+): BoxStyle {
+  const left = Math.max(SPOTLIGHT_EDGE_INSET, r.left - pad)
+  const top = Math.max(SPOTLIGHT_EDGE_INSET, r.top - pad)
+  const right = Math.min(viewport.width - SPOTLIGHT_EDGE_INSET, r.right + pad)
+  const bottom = Math.min(
+    viewport.height - SPOTLIGHT_EDGE_INSET,
+    r.bottom + pad
+  )
+  return {
+    left: `${left}px`,
+    top: `${top}px`,
+    width: `${Math.max(0, right - left)}px`,
+    height: `${Math.max(0, bottom - top)}px`
+  }
+}
+
+/**
+ * A single polygon tracing the viewport then the target rect; the `evenodd`
+ * fill-rule subtracts the inner loop, leaving a hole at the target's bounds.
+ */
+export function blockerClipPath(r: DOMRect): string {
+  const x1 = `${r.left}px`
+  const y1 = `${r.top}px`
+  const x2 = `${r.right}px`
+  const y2 = `${r.bottom}px`
+  return `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${x1} ${y1}, ${x1} ${y2}, ${x2} ${y2}, ${x2} ${y1}, ${x1} ${y1})`
+}
+
+export function noTargetCardLeft(viewportWidth: number): number {
+  return Math.max(VIEWPORT_MARGIN, (viewportWidth - CARD_WIDTH) / 2)
+}
+
+const TOP_BAR_HEIGHT_VAR = '--comfy-topbar-height'
+
+/** The top bar's height, read from the theme token, plus the standard gap. */
+export function topSafeInset(): number {
+  const root = document.documentElement
+  const raw = getComputedStyle(root).getPropertyValue(TOP_BAR_HEIGHT_VAR).trim()
+  const px = raw.endsWith('rem')
+    ? parseFloat(raw) * parseFloat(getComputedStyle(root).fontSize)
+    : parseFloat(raw)
+  return (Number.isFinite(px) ? px : 0) + CARD_GAP
+}

src/platform/onboarding/coachmarkRegistry.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  clearCoachmarks,
+  coachmarkElements,
+  elementsFor,
+  registerCoachmark,
+  targetMounted,
+  unregisterCoachmark,
+  waitForTarget
+} from './coachmarkRegistry'
+
+/** An element with a non-zero measured rect, so it counts as laid out. */
+function laidOut(): HTMLElement {
+  const el = document.createElement('div')
+  el.getBoundingClientRect = () => new DOMRect(0, 0, 80, 30)
+  return el
+}
+
+describe('coachmarkRegistry', () => {
+  const a = document.createElement('div')
+  const b = document.createElement('div')
+
+  afterEach(clearCoachmarks)
+
+  it('resolves every element registered for an id', () => {
+    registerCoachmark('app-run-button', a)
+    registerCoachmark('app-run-button', b)
+    expect(coachmarkElements('app-run-button')).toEqual([a, b])
+  })
+
+  it('keeps the remaining elements when one of several unregisters', () => {
+    registerCoachmark('app-run-button', a)
+    registerCoachmark('app-run-button', b)
+    unregisterCoachmark('app-run-button', a)
+    expect(coachmarkElements('app-run-button')).toEqual([b])
+  })
+
+  it('gathers the elements registered for any of several ids', () => {
+    registerCoachmark('app-run-button', a)
+    registerCoachmark('outputs', b)
+    expect(elementsFor(['app-run-button', 'outputs'])).toEqual([a, b])
+  })
+})
+
+describe('targetMounted', () => {
+  afterEach(clearCoachmarks)
+
+  it('is true once a laid-out element is registered', () => {
+    expect(targetMounted('app-run-button')).toBe(false)
+    registerCoachmark('app-run-button', laidOut())
+    expect(targetMounted('app-run-button')).toBe(true)
+  })
+
+  it('ignores a registered target that is not laid out (e.g. hidden)', () => {
+    // A plain element measures 0×0 until it lays out.
+    registerCoachmark('outputs', document.createElement('div'))
+    expect(targetMounted('outputs')).toBe(false)
+  })
+})
+
+describe('waitForTarget', () => {
+  let frames: Array<() => void>
+
+  beforeEach(() => {
+    frames = []
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      frames.push(() => cb(0))
+      return frames.length
+    })
+    vi.stubGlobal('cancelAnimationFrame', () => {})
+  })
+
+  afterEach(() => {
+    clearCoachmarks()
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  // Drain the poll queue; an unresolved poll reschedules, so cap the drain to
+  // avoid spinning when the target never lays out.
+  function runFrames(max = 50) {
+    let ran = 0
+    while (frames.length && ran < max) {
+      frames.shift()!()
+      ran++
+    }
+  }
+
+  it('resolves true immediately when a laid-out target is already mounted', async () => {
+    registerCoachmark('app-run-button', laidOut())
+    const signal = new AbortController().signal
+    await expect(waitForTarget('app-run-button', signal, 1000)).resolves.toBe(
+      true
+    )
+  })
+
+  it('resolves true once the target lays out before the timeout', async () => {
+    const signal = new AbortController().signal
+    const found = waitForTarget('app-run-button', signal, 1000)
+    registerCoachmark('app-run-button', laidOut())
+    runFrames()
+    await expect(found).resolves.toBe(true)
+  })
+
+  it('keeps waiting for a registered target until it lays out', async () => {
+    const el = document.createElement('div')
+    registerCoachmark('outputs', el)
+    const signal = new AbortController().signal
+    let resolved: boolean | undefined
+    void waitForTarget('outputs', signal, 1000).then((v) => (resolved = v))
+
+    runFrames()
+    await Promise.resolve()
+    // Registered but measures 0×0: still pending.
+    expect(resolved).toBeUndefined()
+
+    el.getBoundingClientRect = () => new DOMRect(0, 0, 80, 30)
+    runFrames()
+    await Promise.resolve()
+    expect(resolved).toBe(true)
+  })
+
+  it('resolves false when the target never mounts (transient failure)', async () => {
+    vi.useFakeTimers()
+    const signal = new AbortController().signal
+    const found = waitForTarget('outputs', signal, 1000)
+    await vi.advanceTimersByTimeAsync(1000)
+    await expect(found).resolves.toBe(false)
+  })
+
+  it('resolves false when aborted before the target mounts', async () => {
+    const controller = new AbortController()
+    const found = waitForTarget('outputs', controller.signal, 10000)
+    controller.abort()
+    await expect(found).resolves.toBe(false)
+  })
+})

src/platform/onboarding/coachmarkRegistry.ts

@@ -0,0 +1,76 @@
+import { shallowReactive } from 'vue'
+
+import type { CoachId } from './onboardingTours'
+
+const EMPTY: readonly HTMLElement[] = []
+
+/** Laid out — a registered target that is currently visible and has a size. */
+export function isLaidOut(el: HTMLElement): boolean {
+  const r = el.getBoundingClientRect()
+  return r.width > 0 && r.height > 0
+}
+
+// An id can map to several elements (e.g. responsive variants); consumers pick
+// the first laid-out one.
+const registry = shallowReactive(new Map<CoachId, readonly HTMLElement[]>())
+
+export function registerCoachmark(id: CoachId, el: HTMLElement) {
+  registry.set(id, [...(registry.get(id) ?? EMPTY), el])
+}
+
+export function unregisterCoachmark(id: CoachId, el: HTMLElement) {
+  const next = (registry.get(id) ?? EMPTY).filter((entry) => entry !== el)
+  if (next.length) registry.set(id, next)
+  else registry.delete(id)
+}
+
+export function coachmarkElements(id: CoachId): readonly HTMLElement[] {
+  return registry.get(id) ?? EMPTY
+}
+
+export function elementsFor(id: CoachId | CoachId[]): readonly HTMLElement[] {
+  if (!Array.isArray(id)) return coachmarkElements(id)
+  return id.flatMap((coachId) => [...coachmarkElements(coachId)])
+}
+
+export function targetMounted(id: CoachId | CoachId[]): boolean {
+  return elementsFor(id).some(isLaidOut)
+}
+
+/** Resolves once a laid-out element for the id exists; false on timeout or abort. */
+export function waitForTarget(
+  id: CoachId | CoachId[],
+  signal: AbortSignal,
+  timeoutMs: number
+): Promise<boolean> {
+  if (targetMounted(id)) return Promise.resolve(true)
+  // An already-aborted signal never fires 'abort', so resolve up front.
+  if (signal.aborted) return Promise.resolve(false)
+  return new Promise((resolve) => {
+    let done = false
+    let frame = 0
+    function finish(found: boolean) {
+      if (done) return
+      done = true
+      cancelAnimationFrame(frame)
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      resolve(found)
+    }
+    function onAbort() {
+      finish(false)
+    }
+    function poll() {
+      if (targetMounted(id)) finish(true)
+      else frame = requestAnimationFrame(poll)
+    }
+    const timer = setTimeout(() => finish(false), timeoutMs)
+    signal.addEventListener('abort', onAbort)
+    frame = requestAnimationFrame(poll)
+  })
+}
+
+/** Resets shared state between tests. */
+export function clearCoachmarks() {
+  registry.clear()
+}

src/platform/onboarding/onboardingTours.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveSteps } from './onboardingTours'
+import type { CoachStep } from './onboardingTours'
+
+function step(overrides: Partial<CoachStep> = {}): CoachStep {
+  return {
+    name: 'step',
+    placement: 'center',
+    ...overrides
+  }
+}
+
+describe('resolveSteps', () => {
+  const isMounted = (mounted: boolean) => () => mounted
+
+  it('keeps a targetless step', () => {
+    const steps = [step()]
+    expect(resolveSteps(steps, isMounted(false))).toEqual(steps)
+  })
+
+  it('drops a step whose target is not mounted', () => {
+    const steps = [step({ coachId: 'app-run-button' })]
+    expect(resolveSteps(steps, isMounted(false))).toEqual([])
+  })
+
+  it('keeps a mounted step', () => {
+    const steps = [step({ coachId: 'app-run-button' })]
+    expect(resolveSteps(steps, isMounted(true))).toEqual(steps)
+  })
+
+  it('keeps a deferred step even before its target mounts', () => {
+    const steps = [step({ coachId: 'app-run-button', deferTarget: true })]
+    expect(resolveSteps(steps, isMounted(false))).toEqual(steps)
+  })
+
+  it('drops a step whose skip target is already mounted', () => {
+    const steps = [
+      step({
+        coachId: 'assets-button',
+        deferTarget: true,
+        skipIfMounted: 'assets-panel'
+      }),
+      step({ coachId: 'assets-panel', deferTarget: true })
+    ]
+    expect(resolveSteps(steps, isMounted(true))).toEqual([steps[1]])
+  })
+
+  it('keeps a skip-conditional step when its skip target is not mounted', () => {
+    const steps = [
+      step({
+        coachId: 'assets-button',
+        deferTarget: true,
+        skipIfMounted: 'assets-panel'
+      })
+    ]
+    expect(resolveSteps(steps, isMounted(false))).toEqual(steps)
+  })
+})

src/platform/onboarding/onboardingTours.ts

@@ -0,0 +1,101 @@
+export type EntryPath = 'appMode'
+
+export type CoachPlacement =
+  | 'left'
+  | 'right'
+  | 'center'
+  | 'bottom'
+  /** Left of the target, vertically centred on it (clamps to the viewport edge). */
+  | 'leftCenter'
+  /** Sits on whichever horizontal side of the target has more room. */
+  | 'auto'
+
+/** Every element a tour can point at; the e2e drift guard asserts each resolves. */
+export const COACH_IDS = {
+  appRunButton: 'app-run-button',
+  inputsList: 'inputs-list',
+  outputs: 'outputs',
+  assetsButton: 'assets-button',
+  assetsPanel: 'assets-panel'
+} as const
+
+export type CoachId = (typeof COACH_IDS)[keyof typeof COACH_IDS]
+
+export interface CoachStep {
+  /**
+   * Derives the step's translation keys:
+   * `onboardingCoachmarks.<tour>.<name>.title|body`, plus optional
+   * `primary`/`skip` button-label overrides.
+   */
+  name: string
+  /** Element to spotlight (a list spotlights the first visible candidate). */
+  coachId?: CoachId | CoachId[]
+  placement: CoachPlacement
+  /** The user advances by clicking the spotlighted element, not Next. */
+  advanceOnTargetClick?: boolean
+  /** Drop this step at tour start when this target is already mounted. */
+  skipIfMounted?: CoachId | CoachId[]
+  /** Target mounts later (e.g. a dialog); wait for it instead of dropping the step. */
+  deferTarget?: boolean
+  /** Renders the landing dialog instead of a spotlight. */
+  landing?: boolean
+  image?: string
+}
+
+/**
+ * Fixes the running step set (and so the step count) at tour start: drops
+ * `skipIfMounted` matches and steps whose own target isn't mounted, keeping
+ * targetless and deferred steps.
+ */
+export function resolveSteps(
+  steps: CoachStep[],
+  isMounted: (id: CoachId | CoachId[]) => boolean
+): CoachStep[] {
+  return steps.filter((s) => {
+    if (s.skipIfMounted && isMounted(s.skipIfMounted)) return false
+    return !s.coachId || s.deferTarget || isMounted(s.coachId)
+  })
+}
+
+export const TOURS: Record<EntryPath, CoachStep[]> = {
+  appMode: [
+    {
+      name: 'landing',
+      landing: true,
+      placement: 'center',
+      image: '/assets/images/app-mode-landing.png'
+    },
+    {
+      name: 'inputs',
+      coachId: COACH_IDS.inputsList,
+      placement: 'auto',
+      deferTarget: true
+    },
+    {
+      name: 'run',
+      coachId: COACH_IDS.appRunButton,
+      placement: 'auto',
+      deferTarget: true
+    },
+    {
+      name: 'outputs',
+      coachId: COACH_IDS.outputs,
+      placement: 'leftCenter',
+      deferTarget: true
+    },
+    {
+      name: 'assetsButton',
+      coachId: COACH_IDS.assetsButton,
+      placement: 'right',
+      deferTarget: true,
+      advanceOnTargetClick: true,
+      skipIfMounted: COACH_IDS.assetsPanel
+    },
+    {
+      name: 'assets',
+      coachId: COACH_IDS.assetsPanel,
+      placement: 'auto',
+      deferTarget: true
+    }
+  ]
+}

src/platform/onboarding/useCoachmarkTarget.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { effectScope, ref } from 'vue'
+
+import { clearCoachmarks, registerCoachmark } from './coachmarkRegistry'
+import type { CoachId, CoachStep } from './onboardingTours'
+import { useCoachmarkTarget } from './useCoachmarkTarget'
+
+function step(coachId: CoachId): CoachStep {
+  return { name: 'step', placement: 'right', coachId }
+}
+
+function laidOut(): HTMLElement {
+  const el = document.createElement('div')
+  el.getBoundingClientRect = () => new DOMRect(10, 10, 80, 30)
+  return el
+}
+
+function hidden(): HTMLElement {
+  const el = document.createElement('div')
+  el.getBoundingClientRect = () => new DOMRect(0, 0, 0, 0)
+  return el
+}
+
+describe('useCoachmarkTarget', () => {
+  afterEach(clearCoachmarks)
+
+  function setup(coachId: CoachId) {
+    const scope = effectScope()
+    const stepRef = ref<CoachStep | null>(step(coachId))
+    const cardRef = ref<HTMLElement | null>(null)
+    const api = scope.run(() => useCoachmarkTarget(stepRef, cardRef))!
+    return { scope, api }
+  }
+
+  it('resolves the first laid-out candidate for the step target', () => {
+    const el = laidOut()
+    registerCoachmark('outputs', el)
+    const { scope, api } = setup('outputs')
+    expect(api.targetEl.value).toBe(el)
+    scope.stop()
+  })
+
+  it('skips a registered target that is not laid out', () => {
+    registerCoachmark('outputs', hidden())
+    const laid = laidOut()
+    registerCoachmark('outputs', laid)
+    const { scope, api } = setup('outputs')
+    expect(api.targetEl.value).toBe(laid)
+    scope.stop()
+  })
+
+  it('picks up a target that registers after the step starts', () => {
+    const { scope, api } = setup('outputs')
+    expect(api.targetEl.value).toBeNull()
+
+    const el = laidOut()
+    registerCoachmark('outputs', el)
+    expect(api.targetEl.value).toBe(el)
+    scope.stop()
+  })
+})

src/platform/onboarding/useCoachmarkTarget.ts

@@ -0,0 +1,128 @@
+import { autoUpdate, flip, offset, shift, useFloating } from '@floating-ui/vue'
+import type { Middleware, Placement, Rect } from '@floating-ui/vue'
+import { computed, ref, watch, watchEffect } from 'vue'
+import type { Ref } from 'vue'
+
+import { CARD_GAP, VIEWPORT_MARGIN, topSafeInset } from './coachmarkLayout'
+import { elementsFor, isLaidOut } from './coachmarkRegistry'
+import type { CoachPlacement, CoachStep } from './onboardingTours'
+
+// A target animating in via CSS transform reports through neither scroll nor
+// resize events; poll each frame until its rect holds still this long.
+const MOTION_SETTLE_MS = 250
+
+const PLACEMENT: Record<
+  Exclude<CoachPlacement, 'auto' | 'center'>,
+  Placement
+> = {
+  left: 'left-start',
+  right: 'right-start',
+  leftCenter: 'left',
+  bottom: 'bottom'
+}
+
+function floatingPlacement(step: CoachStep | null): Placement {
+  const placement = step?.placement
+  if (!placement || placement === 'auto' || placement === 'center')
+    return 'right-start'
+  return PLACEMENT[placement]
+}
+
+// Surfaces the measured target rect so the spotlight can trace it.
+const captureReference: Middleware = {
+  name: 'captureReference',
+  fn: (state) => ({ data: { rect: state.rects.reference } })
+}
+
+function middleware(step: CoachStep | null): Middleware[] {
+  const list: Middleware[] = [offset(CARD_GAP)]
+  if (!step?.placement || step.placement === 'auto') list.push(flip())
+  // shift only guards the main axis by default; crossAxis keeps vertically-
+  // centred placements (leftCenter) on-screen too.
+  list.push(
+    shift({
+      crossAxis: true,
+      padding: {
+        top: topSafeInset(),
+        left: VIEWPORT_MARGIN,
+        right: VIEWPORT_MARGIN,
+        bottom: CARD_GAP
+      }
+    }),
+    captureReference
+  )
+  return list
+}
+
+/**
+ * Locates a step's target in the registry and positions the card beside it with
+ * Floating UI, following the target until its rect settles.
+ */
+export function useCoachmarkTarget(
+  step: Ref<CoachStep | null>,
+  cardRef: Ref<HTMLElement | null>
+) {
+  const candidateEls = computed<readonly HTMLElement[]>(() => {
+    const id = step.value?.coachId
+    return id ? elementsFor(id) : []
+  })
+
+  const targetEl = computed<HTMLElement | null>(
+    () => candidateEls.value.find(isLaidOut) ?? null
+  )
+
+  const { floatingStyles, middlewareData, isPositioned, update } = useFloating(
+    targetEl,
+    cardRef,
+    {
+      strategy: 'fixed',
+      transform: false,
+      placement: () => floatingPlacement(step.value),
+      middleware: () => middleware(step.value)
+    }
+  )
+
+  const targetRect = computed<DOMRect | null>(() => {
+    const data = middlewareData.value.captureReference as
+      | { rect: Rect }
+      | undefined
+    const rect = data?.rect
+    if (!rect || rect.width === 0) return null
+    return new DOMRect(rect.x, rect.y, rect.width, rect.height)
+  })
+
+  const trackMotion = ref(false)
+  const rectKey = computed(() => {
+    const r = targetRect.value
+    return r ? `${r.x},${r.y},${r.width},${r.height}` : ''
+  })
+
+  watch(
+    () => step.value,
+    (s) => {
+      trackMotion.value = !!s?.deferTarget
+    },
+    { immediate: true }
+  )
+
+  watch(rectKey, (_key, _prev, onCleanup) => {
+    if (!trackMotion.value) return
+    const timer = setTimeout(() => {
+      trackMotion.value = false
+    }, MOTION_SETTLE_MS)
+    onCleanup(() => clearTimeout(timer))
+  })
+
+  watchEffect((onCleanup) => {
+    const reference = targetEl.value
+    const floating = cardRef.value
+    if (!reference || !floating) return
+    onCleanup(
+      autoUpdate(reference, floating, update, {
+        animationFrame: trackMotion.value
+      })
+    )
+  })
+
+  return { targetEl, targetRect, floatingStyles, isPositioned }
+}

src/platform/onboarding/useCoachmarkTour.test.ts

@@ -0,0 +1,385 @@
+import { createTestingPinia } from '@pinia/testing'
+import { cleanup, render } from '@testing-library/vue'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent } from 'vue'
+import type { Ref } from 'vue'
+import { createI18n } from 'vue-i18n'
+
+import type { AppMode } from '@/utils/appMode'
+
+import { requestTour } from './coachmarkController'
+import { clearCoachmarks, registerCoachmark } from './coachmarkRegistry'
+import type { CoachId } from './onboardingTours'
+import { useCoachmarkTour } from './useCoachmarkTour'
+
+const SEEN_SETTING = 'Comfy.OnboardingCoachmarks.Seen'
+
+// In-memory setting store so seen-state reads/writes don't touch the real
+// settings API; seeded empty and reset per test.
+const settings = vi.hoisted(() => ({ seen: [] as string[] }))
+vi.mock('@/platform/settings/settingStore', () => ({
+  useSettingStore: () => ({
+    get: (key: string) => (key === SEEN_SETTING ? settings.seen : undefined),
+    set: (key: string, value: unknown) => {
+      if (key === SEEN_SETTING) settings.seen = value as string[]
+      return Promise.resolve()
+    }
+  })
+}))
+
+const telemetry = vi.hoisted(() => ({ track: vi.fn() }))
+vi.mock('@/platform/telemetry', () => ({
+  useTelemetry: () => ({ trackOnboardingTour: telemetry.track })
+}))
+
+// `mode` + `hasOutputs` drive the auto-open watcher; hoisted so tests can flip
+// them to simulate entering a populated vs empty app.
+const appModeMock = vi.hoisted(
+  () =>
+    ({ mode: null, hasOutputs: null }) as {
+      mode: Ref<AppMode> | null
+      hasOutputs: Ref<boolean> | null
+    }
+)
+vi.mock('@/composables/useAppMode', async () => {
+  const { ref: r } = await import('vue')
+  appModeMock.mode = r<AppMode>('graph')
+  return { useAppMode: () => ({ mode: appModeMock.mode }) }
+})
+vi.mock('@/stores/appModeStore', async () => {
+  const { ref: r } = await import('vue')
+  appModeMock.hasOutputs = r(false)
+  const hasOutputs = appModeMock.hasOutputs
+  return {
+    useAppModeStore: () => ({
+      get hasOutputs() {
+        return hasOutputs.value
+      }
+    })
+  }
+})
+const APP_MODE_TARGETS: CoachId[] = [
+  'inputs-list',
+  'app-run-button',
+  'outputs',
+  'assets-button',
+  'assets-panel'
+]
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  missingWarn: false,
+  messages: {
+    en: {
+      onboardingCoachmarks: {
+        next: 'Next',
+        done: 'Done',
+        skip: 'Skip',
+        appMode: {
+          landing: { primary: 'Start tutorial', skip: 'Skip for now' }
+        }
+      }
+    }
+  }
+})
+
+const flush = () => new Promise((resolve) => setTimeout(resolve))
+
+function mountTour() {
+  let api!: ReturnType<typeof useCoachmarkTour>
+  render(
+    defineComponent({
+      setup() {
+        api = useCoachmarkTour()
+        return () => null
+      }
+    }),
+    { global: { plugins: [i18n, createTestingPinia({ stubActions: false })] } }
+  )
+  return { api }
+}
+
+function startedCount() {
+  return telemetry.track.mock.calls.filter(([stage]) => stage === 'started')
+    .length
+}
+
+describe('useCoachmarkTour', () => {
+  // Tracks every element mountTarget appends, so teardown removes them even when
+  // a test throws before its own cleanup would run.
+  const appendedTargets: HTMLElement[] = []
+
+  afterEach(() => {
+    cleanup()
+    clearCoachmarks()
+    appendedTargets.forEach((el) => el.remove())
+    appendedTargets.length = 0
+    settings.seen = []
+    if (appModeMock.mode) appModeMock.mode.value = 'graph'
+    if (appModeMock.hasOutputs) appModeMock.hasOutputs.value = false
+    telemetry.track.mockClear()
+    vi.useRealTimers()
+  })
+
+  /** Register one laid-out element for a coach id, so its step resolves at once. */
+  function mountTarget(id: CoachId): HTMLElement {
+    const el = document.createElement('div')
+    el.getBoundingClientRect = () => new DOMRect(0, 0, 100, 100)
+    document.body.appendChild(el)
+    appendedTargets.push(el)
+    registerCoachmark(id, el)
+    return el
+  }
+
+  function registerAppModeTargets(
+    ids: CoachId[] = APP_MODE_TARGETS
+  ): Map<CoachId, HTMLElement> {
+    return new Map(ids.map((id) => [id, mountTarget(id)]))
+  }
+
+  function enterApp(mode: AppMode, hasOutputs: boolean) {
+    const modeRef = appModeMock.mode
+    const outputsRef = appModeMock.hasOutputs
+    if (!modeRef || !outputsRef)
+      throw new Error('app mode mock not initialised')
+    modeRef.value = mode
+    outputsRef.value = hasOutputs
+  }
+
+  it('auto-opens when entering a populated app it has not seen', async () => {
+    mountTour()
+    enterApp('app', true)
+    await flush()
+    expect(startedCount()).toBe(1)
+  })
+
+  it('auto-opens when mounted into an already-populated app', async () => {
+    enterApp('app', true)
+    mountTour()
+    await flush()
+    expect(startedCount()).toBe(1)
+  })
+
+  it('does not auto-open in an empty app with no linear controls', async () => {
+    mountTour()
+    enterApp('app', false)
+    await flush()
+    expect(startedCount()).toBe(0)
+  })
+
+  it('does not auto-open in arrange (builder) mode', async () => {
+    mountTour()
+    enterApp('builder:arrange', true)
+    await flush()
+    expect(startedCount()).toBe(0)
+  })
+
+  it('does not auto-open a populated app once the tour has been dismissed', async () => {
+    settings.seen = ['appMode']
+    mountTour()
+    enterApp('app', true)
+    await flush()
+    expect(startedCount()).toBe(0)
+  })
+
+  it('replays a seen tour when explicitly requested', async () => {
+    settings.seen = ['appMode']
+    mountTour()
+    void requestTour('appMode')
+    await flush()
+    expect(startedCount()).toBe(1)
+  })
+
+  it('marks the tour seen when it ends normally', async () => {
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+    api.end('skipped')
+    expect(settings.seen).toContain('appMode')
+  })
+
+  it('does not mark the tour seen when a deferred target never appears', async () => {
+    vi.useFakeTimers()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    // Flush startTour + the opening landing step.
+    await vi.advanceTimersByTimeAsync(0)
+    // Advance past the landing into the first deferred-target step.
+    api.next()
+    // The deferred target (inputs list) is never registered; exhaust the wait.
+    await vi.advanceTimersByTimeAsync(8000)
+    expect(settings.seen).not.toContain('appMode')
+
+    // The skipped event reports the timed-out step, not the prior landing.
+    const skipped = telemetry.track.mock.calls.find(
+      ([stage]) => stage === 'skipped'
+    )
+    expect(skipped?.[1]).toMatchObject({
+      step_number: 1,
+      coach_id: 'inputs-list'
+    })
+  })
+
+  it('ignores a second concurrent request while the first tour is resolving', async () => {
+    mountTour()
+    // Both fire synchronously; the first resolves steps before the second runs,
+    // so the steps guard drops the second.
+    void requestTour('appMode')
+    void requestTour('appMode')
+    await flush()
+    expect(startedCount()).toBe(1)
+  })
+
+  it('advances through every step to completion and marks the tour seen', async () => {
+    // Register every app-mode target so each step resolves immediately as the
+    // user advances (spotlight steps defer their targets). The assets panel is
+    // mounted, so the assets-button step is skipped — the tour still completes.
+    registerAppModeTargets()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+
+    // Advance until the tour completes (count-agnostic; extra presses after the
+    // final step are no-ops), capped so a stuck tour fails instead of hangs.
+    for (let i = 0; i < 12 && !settings.seen.includes('appMode'); i++) {
+      api.next()
+      await flush()
+    }
+
+    expect(settings.seen).toContain('appMode')
+    const completed = telemetry.track.mock.calls.some(
+      ([stage]) => stage === 'completed'
+    )
+    expect(completed).toBe(true)
+  })
+
+  it('resolves the deferred assets panel after the click-to-advance step', async () => {
+    // Every target except the assets panel — it's still closed, so the
+    // assets-button click step is shown (all five spotlight steps run).
+    registerAppModeTargets(
+      APP_MODE_TARGETS.filter((id) => id !== 'assets-panel')
+    )
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+
+    expect(api.countedSteps.value.length).toBe(5)
+    for (let i = 0; i < 4; i++) {
+      api.next()
+      await flush()
+    }
+    // The assets-button step advances only on a target click (Next is hidden);
+    // TourSpotlight emits `advance`, which next() handles — drive it directly.
+    expect(api.step.value?.advanceOnTargetClick).toBe(true)
+
+    // The panel mounts when the button is clicked; advancing then spotlights it.
+    mountTarget('assets-panel')
+    api.next()
+    await flush()
+
+    expect(api.step.value?.coachId).toBe('assets-panel')
+  })
+
+  it('drops the assets-button step (count 4) when the panel is already open', async () => {
+    // The panel is registered up front, so the step that only exists to open it
+    // is dropped at tour start — the indicator counts four steps, not five.
+    registerAppModeTargets()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+
+    expect(api.countedSteps.value.length).toBe(4)
+
+    // landing → inputs → run → outputs → assets-panel (no assets-button step)
+    for (let i = 0; i < 4; i++) {
+      api.next()
+      await flush()
+    }
+    expect(api.step.value?.coachId).toBe('assets-panel')
+  })
+
+  it('reports step index 0 while no tour is active', () => {
+    const { api } = mountTour()
+    expect(api.countedStepIdx.value).toBe(0)
+  })
+
+  it('labels the buttons from the step, falling back to Next then Done', async () => {
+    registerAppModeTargets()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+
+    // The landing's `primary`/`skip` translation entries override both labels.
+    expect(api.step.value?.landing).toBe(true)
+    expect(api.primaryLabel.value).toBe('Start tutorial')
+    expect(api.skipLabel.value).toBe('Skip for now')
+
+    // Every target is mounted, so the tour is a landing plus four spotlight steps.
+    expect(api.countedSteps.value.length).toBe(4)
+
+    // Landing → first spotlight: labels fall back to the generic Next/Skip.
+    api.next()
+    await flush()
+    expect(api.primaryLabel.value).toBe('Next')
+    expect(api.skipLabel.value).toBe('Skip')
+
+    // Three more advances reach the final step, whose primary action reads Done.
+    for (let i = 0; i < 3; i++) {
+      api.next()
+      await flush()
+    }
+    expect(api.isLast.value).toBe(true)
+    expect(api.primaryLabel.value).toBe('Done')
+  })
+
+  it('reports the user-visible step numbering, omitting it for the landing', async () => {
+    registerAppModeTargets()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+
+    // The count matches the "of M" the card shows: the landing isn't numbered
+    // (and the assets-button step is dropped — its panel is already mounted).
+    const started = telemetry.track.mock.calls.find(
+      ([stage]) => stage === 'started'
+    )
+    expect(started?.[1]).toEqual({ tour: 'appMode', step_count: 4 })
+
+    // The landing's step_shown carries no step number or coach id.
+    const landingShown = telemetry.track.mock.calls.find(
+      ([stage]) => stage === 'step_shown'
+    )
+    expect(landingShown?.[1]).toEqual({ tour: 'appMode', step_count: 4 })
+
+    // Advancing off the landing shows "Step 1 of 4", and the event agrees.
+    api.next()
+    await flush()
+    const shown = telemetry.track.mock.calls
+      .filter(([stage]) => stage === 'step_shown')
+      .at(-1)
+    expect(shown?.[1]).toEqual({
+      tour: 'appMode',
+      step_count: 4,
+      step_number: 1,
+      coach_id: 'inputs-list'
+    })
+  })
+
+  it('advancing off the landing does not mark the tour skipped', async () => {
+    registerAppModeTargets()
+    const { api } = mountTour()
+    void requestTour('appMode')
+    await flush()
+    expect(api.step.value?.landing).toBe(true)
+
+    api.next()
+    await flush()
+
+    expect(api.step.value?.landing).toBeFalsy()
+    const skipped = telemetry.track.mock.calls.some(
+      ([stage]) => stage === 'skipped'
+    )
+    expect(skipped).toBe(false)
+  })
+})

src/platform/onboarding/useCoachmarkTour.ts

@@ -0,0 +1,181 @@
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import { useSettingStore } from '@/platform/settings/settingStore'
+import { useTelemetry } from '@/platform/telemetry'
+import type { OnboardingTourStage } from '@/platform/telemetry/types'
+
+import { onTourRequested } from './coachmarkController'
+import { targetMounted, waitForTarget } from './coachmarkRegistry'
+import { TOURS, resolveSteps } from './onboardingTours'
+import type { CoachStep, EntryPath } from './onboardingTours'
+import { useTourTriggers } from './useTourTriggers'
+
+const SEEN_SETTING = 'Comfy.OnboardingCoachmarks.Seen'
+const DEFER_TIMEOUT_MS = 8000
+
+/**
+ * The tour state machine: which tour starts and when, which steps run, and the
+ * advance/skip/complete lifecycle.
+ */
+export function useCoachmarkTour() {
+  const { t, te } = useI18n()
+  const settingStore = useSettingStore()
+  const telemetry = useTelemetry()
+
+  const steps = ref<CoachStep[]>([])
+  const stepIdx = ref(0)
+  const suspendFocusGuard = ref(false)
+  const activeTour = ref<EntryPath | null>(null)
+  let stepController: AbortController | null = null
+
+  const step = computed<CoachStep | null>(
+    () => steps.value[stepIdx.value] ?? null
+  )
+  const isLast = computed(() => stepIdx.value === steps.value.length - 1)
+
+  const countedSteps = computed(() => steps.value.filter((s) => !s.landing))
+  const countedStepIdx = computed(() => {
+    const s = step.value
+    return s ? countedSteps.value.indexOf(s) : 0
+  })
+
+  function trackTour(stage: OnboardingTourStage) {
+    const tour = activeTour.value
+    if (!tour) return
+    const coachId = step.value?.coachId
+    telemetry?.trackOnboardingTour(stage, {
+      tour,
+      step_count: countedSteps.value.length,
+      ...(stage !== 'started' &&
+        countedStepIdx.value >= 0 && {
+          step_number: countedStepIdx.value + 1,
+          coach_id: Array.isArray(coachId) ? coachId.join('+') : coachId
+        })
+    })
+  }
+
+  function stepKey(suffix: string) {
+    return `onboardingCoachmarks.${activeTour.value}.${step.value?.name}.${suffix}`
+  }
+
+  const title = computed(() => (step.value ? t(stepKey('title')) : ''))
+  const body = computed(() => (step.value ? t(stepKey('body')) : ''))
+
+  // A step overrides the generic button labels by declaring `primary`/`skip`
+  // entries under its translation keys.
+  const primaryLabel = computed(() => {
+    if (step.value && te(stepKey('primary'))) return t(stepKey('primary'))
+    return isLast.value
+      ? t('onboardingCoachmarks.done')
+      : t('onboardingCoachmarks.next')
+  })
+
+  const skipLabel = computed(() =>
+    step.value && te(stepKey('skip'))
+      ? t(stepKey('skip'))
+      : t('onboardingCoachmarks.skip')
+  )
+
+  async function showStep(idx: number) {
+    const nextStep = steps.value[idx]
+    if (!nextStep) return
+    stepController?.abort()
+    const controller = new AbortController()
+    stepController = controller
+    const { signal } = controller
+    suspendFocusGuard.value = false
+    if (
+      nextStep.deferTarget &&
+      nextStep.coachId &&
+      !targetMounted(nextStep.coachId)
+    ) {
+      suspendFocusGuard.value = true
+      const found = await waitForTarget(
+        nextStep.coachId,
+        signal,
+        DEFER_TIMEOUT_MS
+      )
+      if (signal.aborted) return
+      suspendFocusGuard.value = false
+      // Point at the timed-out step so telemetry reports it, and skip without
+      // the seen-flag so a missed target isn't permanent.
+      if (!found) {
+        stepIdx.value = idx
+        end('skipped', false)
+        return
+      }
+    }
+    stepIdx.value = idx
+    trackTour('step_shown')
+  }
+
+  function next() {
+    if (isLast.value) {
+      end('completed')
+      return
+    }
+    void showStep(stepIdx.value + 1)
+  }
+
+  function end(outcome: 'completed' | 'skipped', markSeen = true) {
+    trackTour(outcome)
+    stepController?.abort()
+    suspendFocusGuard.value = false
+    steps.value = []
+    stepIdx.value = 0
+    if (markSeen && activeTour.value) markTourSeen(activeTour.value)
+    activeTour.value = null
+  }
+
+  onBeforeUnmount(() => {
+    stepController?.abort()
+  })
+
+  for (const [entryPath, active] of useTourTriggers()) {
+    watch(
+      active,
+      (visible) => {
+        if (visible) startTour(entryPath)
+      },
+      { immediate: true }
+    )
+  }
+
+  function hasSeenTour(entryPath: EntryPath): boolean {
+    return settingStore.get(SEEN_SETTING).includes(entryPath)
+  }
+
+  function markTourSeen(entryPath: EntryPath) {
+    const seen = settingStore.get(SEEN_SETTING)
+    if (seen.includes(entryPath)) return
+    void settingStore.set(SEEN_SETTING, [...seen, entryPath])
+  }
+
+  function startTour(entryPath: EntryPath, force = false) {
+    if (steps.value.length) return
+    if (!force && hasSeenTour(entryPath)) return
+    const resolved = resolveSteps(TOURS[entryPath], targetMounted)
+    if (!resolved.length) return
+    steps.value = resolved
+    activeTour.value = entryPath
+    trackTour('started')
+    void showStep(0)
+  }
+
+  onTourRequested((tour) => startTour(tour, true))
+
+  return {
+    step,
+    isLast,
+    title,
+    body,
+    primaryLabel,
+    skipLabel,
+    countedStepIdx,
+    countedSteps,
+    suspendFocusGuard,
+    next,
+    end
+  }
+}

src/platform/onboarding/useFocusTrap.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { effectScope, nextTick, ref } from 'vue'
+import type { EffectScope } from 'vue'
+
+import { useFocusTrap } from './useFocusTrap'
+
+function button(label: string): HTMLButtonElement {
+  const el = document.createElement('button')
+  el.textContent = label
+  return el
+}
+
+describe('useFocusTrap', () => {
+  let scope: EffectScope
+  let target: HTMLElement
+  let card: HTMLElement
+  let outside: HTMLButtonElement
+  let t1: HTMLButtonElement
+  let t2: HTMLButtonElement
+  let skip: HTMLButtonElement
+  let primary: HTMLButtonElement
+  let suspended: boolean
+  let onEscape: ReturnType<typeof vi.fn<() => void>>
+
+  beforeEach(() => {
+    target = document.createElement('div')
+    t1 = button('t1')
+    t2 = button('t2')
+    target.append(t1, t2)
+    card = document.createElement('div')
+    skip = button('skip')
+    primary = button('primary')
+    card.append(skip, primary)
+    // An element in neither the card nor the spotlighted target.
+    outside = button('outside')
+    document.body.append(target, card, outside)
+    suspended = false
+    onEscape = vi.fn<() => void>()
+    scope = effectScope()
+    scope.run(() =>
+      useFocusTrap({
+        cardRef: ref(card),
+        getTarget: () => target,
+        isSuspended: () => suspended,
+        onEscape
+      })
+    )
+  })
+
+  afterEach(() => {
+    scope.stop()
+    target.remove()
+    card.remove()
+    outside.remove()
+  })
+
+  function press(key: string, shiftKey = false) {
+    document.dispatchEvent(
+      new KeyboardEvent('keydown', { key, shiftKey, bubbles: true })
+    )
+  }
+
+  function focusOutside() {
+    outside.focus()
+    outside.dispatchEvent(new FocusEvent('focusin', { bubbles: true }))
+  }
+
+  it('cycles from the target focusables into the card buttons on Tab', () => {
+    t2.focus()
+    press('Tab')
+    expect(document.activeElement).toBe(skip)
+  })
+
+  it('wraps from the last focusable back to the first on Tab', () => {
+    primary.focus()
+    press('Tab')
+    expect(document.activeElement).toBe(t1)
+  })
+
+  it('wraps from the first focusable to the last on Shift+Tab', () => {
+    t1.focus()
+    press('Tab', true)
+    expect(document.activeElement).toBe(primary)
+  })
+
+  it('enters at the first item on Tab when focus starts outside the trap', () => {
+    outside.focus()
+    press('Tab')
+    expect(document.activeElement).toBe(t1)
+  })
+
+  it('enters at the last item on Shift+Tab when focus starts outside the trap', () => {
+    outside.focus()
+    press('Tab', true)
+    expect(document.activeElement).toBe(primary)
+  })
+
+  it('invokes onEscape when Escape is pressed', () => {
+    press('Escape')
+    expect(onEscape).toHaveBeenCalledOnce()
+  })
+
+  it('pulls stray focus back to the primary action on focusin', async () => {
+    focusOutside()
+    await nextTick()
+    expect(document.activeElement).toBe(primary)
+  })
+
+  it('leaves stray focus alone while suspended', async () => {
+    suspended = true
+    focusOutside()
+    await nextTick()
+    expect(document.activeElement).toBe(outside)
+  })
+})

src/platform/onboarding/useFocusTrap.ts

@@ -0,0 +1,83 @@
+import { useEventListener } from '@vueuse/core'
+import { nextTick } from 'vue'
+import type { Ref } from 'vue'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+interface FocusTrapOptions {
+  cardRef: Ref<HTMLElement | null>
+  getTarget: () => HTMLElement | null
+  isSuspended: () => boolean
+  onEscape: () => void
+}
+
+/**
+ * Traps focus across two disjoint subtrees — the coach card and the externally
+ * spotlighted target — which a single-subtree trap (Reka FocusScope) can't model.
+ */
+export function useFocusTrap(options: FocusTrapOptions) {
+  const { cardRef, getTarget, isSuspended, onEscape } = options
+
+  /** Focus the primary action (the last button); Skip comes first in the DOM. */
+  async function focusCard() {
+    await nextTick()
+    const buttons = cardRef.value?.querySelectorAll<HTMLElement>('button')
+    buttons?.[buttons.length - 1]?.focus()
+  }
+
+  function focusCycle(): HTMLElement[] {
+    const items: HTMLElement[] = []
+    const target = getTarget()
+    if (target) {
+      if (target.matches(FOCUSABLE)) items.push(target)
+      items.push(...target.querySelectorAll<HTMLElement>(FOCUSABLE))
+    }
+    if (cardRef.value) {
+      items.push(...cardRef.value.querySelectorAll<HTMLElement>(FOCUSABLE))
+    }
+    return items
+  }
+
+  useEventListener(
+    document,
+    'keydown',
+    (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        e.stopPropagation()
+        onEscape()
+        return
+      }
+      if (e.key !== 'Tab') return
+      const items = focusCycle()
+      if (!items.length) return
+      e.preventDefault()
+      const current = items.indexOf(document.activeElement as HTMLElement)
+      const nextIdx =
+        current === -1
+          ? e.shiftKey
+            ? items.length - 1
+            : 0
+          : (current + (e.shiftKey ? -1 : 1) + items.length) % items.length
+      items[nextIdx]?.focus()
+    },
+    { capture: true }
+  )
+
+  useEventListener(
+    document,
+    'focusin',
+    (e: FocusEvent) => {
+      if (isSuspended()) return
+      const node = e.target as Node | null
+      if (!node) return
+      if (cardRef.value?.contains(node)) return
+      if (getTarget()?.contains(node)) return
+      void focusCard()
+    },
+    { capture: true }
+  )
+
+  return { focusCard }
+}

src/platform/onboarding/useTourTriggers.ts

@@ -0,0 +1,16 @@
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+
+import { useAppMode } from '@/composables/useAppMode'
+import { useAppModeStore } from '@/stores/appModeStore'
+
+import type { EntryPath } from './onboardingTours'
+
+/** Each tour's auto-open condition, paired with its entry path. */
+export function useTourTriggers(): [EntryPath, ComputedRef<boolean>][] {
+  const { mode } = useAppMode()
+  const appModeStore = useAppModeStore()
+  return [
+    ['appMode', computed(() => mode.value === 'app' && appModeStore.hasOutputs)]
+  ]
+}

src/platform/onboarding/vCoachmark.test.ts

@@ -0,0 +1,73 @@
+import { cleanup, render } from '@testing-library/vue'
+import { afterEach, describe, expect, it } from 'vitest'
+import { defineComponent, h, nextTick, ref, withDirectives } from 'vue'
+
+import { coachmarkElements } from './coachmarkRegistry'
+import type { CoachId } from './onboardingTours'
+import { vCoachmark } from './vCoachmark'
+
+// Mounts a host element carrying `v-coachmark`, so the directive runs through
+// Vue's real mount/update/unmount lifecycle rather than hand-called hooks.
+function mountHost(initial: CoachId | null) {
+  const coachId = ref<CoachId | null>(initial)
+  const rev = ref(0)
+  const Host = defineComponent({
+    setup: () => () =>
+      withDirectives(
+        h('div', { 'data-testid': 'host', 'data-rev': rev.value }),
+        [[vCoachmark, coachId.value]]
+      )
+  })
+  return {
+    ...render(Host),
+    coachId,
+    // Forces a re-render without touching the bound id, to exercise the
+    // no-op-update guard.
+    rerender: () => {
+      rev.value++
+      return nextTick()
+    }
+  }
+}
+
+describe('vCoachmark', () => {
+  afterEach(cleanup)
+
+  it('registers the element and mirrors the id to data-coach-id on mount', () => {
+    const { getByTestId } = mountHost('app-run-button')
+    const host = getByTestId('host')
+    expect(host.dataset.coachId).toBe('app-run-button')
+    expect(coachmarkElements('app-run-button')).toContain(host)
+  })
+
+  it('does not register an element bound to a falsy id', () => {
+    const { getByTestId } = mountHost(null)
+    expect(getByTestId('host').dataset.coachId).toBeUndefined()
+    expect(coachmarkElements('app-run-button')).toHaveLength(0)
+  })
+
+  it('moves the element to the new id when the binding changes', async () => {
+    const { getByTestId, coachId } = mountHost('app-run-button')
+    const host = getByTestId('host')
+    coachId.value = 'outputs'
+    await nextTick()
+    expect(host.dataset.coachId).toBe('outputs')
+    expect(coachmarkElements('app-run-button')).not.toContain(host)
+    expect(coachmarkElements('outputs')).toContain(host)
+  })
+
+  it('ignores a re-render that leaves the id unchanged', async () => {
+    const { getByTestId, rerender } = mountHost('app-run-button')
+    const host = getByTestId('host')
+    await rerender()
+    expect(coachmarkElements('app-run-button')).toEqual([host])
+  })
+
+  it('unregisters and clears data-coach-id on unmount', () => {
+    const { getByTestId, unmount } = mountHost('app-run-button')
+    const host = getByTestId('host')
+    unmount()
+    expect(host.dataset.coachId).toBeUndefined()
+    expect(coachmarkElements('app-run-button')).not.toContain(host)
+  })
+})

src/platform/onboarding/vCoachmark.ts

@@ -0,0 +1,29 @@
+import type { Directive } from 'vue'
+
+import { registerCoachmark, unregisterCoachmark } from './coachmarkRegistry'
+import type { CoachId } from './onboardingTours'
+
+// The element's `data-coach-id` is the record of what it is registered as.
+function sync(el: HTMLElement, id: CoachId | undefined | null) {
+  const prev = el.dataset.coachId as CoachId | undefined
+  if (prev === id) return
+  if (prev) {
+    unregisterCoachmark(prev, el)
+    delete el.dataset.coachId
+  }
+  if (id) {
+    el.dataset.coachId = id
+    registerCoachmark(id, el)
+  }
+}
+
+/**
+ * Marks an element as a coach-mark target: registers it in the reactive
+ * registry and mirrors the id to `data-coach-id` for e2e locators. A falsy
+ * value is a no-op, so it can be bound to a conditional id.
+ */
+export const vCoachmark: Directive<HTMLElement, CoachId | undefined | null> = {
+  mounted: (el, { value }) => sync(el, value),
+  updated: (el, { value }) => sync(el, value),
+  unmounted: (el) => sync(el, null)
+}

src/platform/settings/constants/coreSettings.ts

@@ -977,6 +977,13 @@ export const CORE_SETTINGS: SettingParams[] = [
     defaultValue: false,
     versionAdded: '1.8.7'
   },
+  {
+    id: 'Comfy.OnboardingCoachmarks.Seen',
+    name: 'Onboarding coachmark tours the user has already seen',
+    type: 'hidden',
+    defaultValue: [],
+    versionAdded: '1.48.0'
+  },
   {
     id: 'Comfy.InstalledVersion',
     name: 'The frontend version that was running when the user first installed ComfyUI',

src/platform/telemetry/TelemetryRegistry.ts

@@ -16,6 +16,8 @@ import type {
   NodeAddedMetadata,
   NodeSearchMetadata,
   NodeSearchResultMetadata,
+  OnboardingTourMetadata,
+  OnboardingTourStage,
   SearchQueryMetadata,
   PageViewMetadata,
   PageVisibilityMetadata,
@@ -150,6 +152,13 @@ export class TelemetryRegistry implements TelemetryDispatcher {
     this.dispatch((provider) => provider.trackSurvey?.(stage, responses))
   }
 
+  trackOnboardingTour(
+    stage: OnboardingTourStage,
+    metadata: OnboardingTourMetadata
+  ): void {
+    this.dispatch((provider) => provider.trackOnboardingTour?.(stage, metadata))
+  }
+
   trackEmailVerification(stage: 'opened' | 'requested' | 'completed'): void {
     this.dispatch((provider) => provider.trackEmailVerification?.(stage))
   }

src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.test.ts

@@ -38,6 +38,8 @@ import type {
   AuthMetadata,
   DefaultViewSetMetadata,
   EnterLinearMetadata,
+  OnboardingTourMetadata,
+  OnboardingTourStage,
   RunButtonProperties,
   ShareFlowMetadata,
   ShellLayoutMetadata,
@@ -460,6 +462,35 @@ describe('MixpanelTelemetryProvider — direct event tracking methods', () => {
     )
   })
 
+  it.for<
+    [
+      OnboardingTourStage,
+      (typeof TelemetryEvents)[keyof typeof TelemetryEvents]
+    ]
+  >([
+    ['started', TelemetryEvents.ONBOARDING_TOUR_STARTED],
+    ['step_shown', TelemetryEvents.ONBOARDING_TOUR_STEP_SHOWN],
+    ['completed', TelemetryEvents.ONBOARDING_TOUR_COMPLETED],
+    ['skipped', TelemetryEvents.ONBOARDING_TOUR_SKIPPED]
+  ])(
+    'trackOnboardingTour(%s) dispatches %s',
+    async ([stage, expectedEvent]) => {
+      const provider = new MixpanelTelemetryProvider()
+      await waitForMixpanelInit()
+      mockMixpanel.track.mockClear()
+
+      const metadata: OnboardingTourMetadata = {
+        tour: 'appMode',
+        step_count: 6,
+        step_number: 2,
+        coach_id: 'app-run-button'
+      }
+      provider.trackOnboardingTour(stage, metadata)
+
+      expect(mockMixpanel.track).toHaveBeenCalledWith(expectedEvent, metadata)
+    }
+  )
+
   it('omits share_id from existing Mixpanel events', async () => {
     const provider = new MixpanelTelemetryProvider()
     await waitForMixpanelInit()

src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.ts

@@ -20,6 +20,8 @@ import type {
   HelpResourceClickedMetadata,
   NodeSearchMetadata,
   NodeSearchResultMetadata,
+  OnboardingTourMetadata,
+  OnboardingTourStage,
   PageVisibilityMetadata,
   RunButtonProperties,
   SettingChangedMetadata,
@@ -44,7 +46,7 @@ import type {
 } from '../../types'
 import { remoteConfig } from '@/platform/remoteConfig/remoteConfig'
 import type { RemoteConfig } from '@/platform/remoteConfig/types'
-import { TelemetryEvents } from '../../types'
+import { OnboardingTourEvents, TelemetryEvents } from '../../types'
 import { normalizeSurveyResponses } from '../../utils/surveyNormalization'
 
 const DEFAULT_DISABLED_EVENTS = [
@@ -280,6 +282,13 @@ export class MixpanelTelemetryProvider implements TelemetryProvider {
     this.trackEvent(TelemetryEvents.RUN_BUTTON_CLICKED, properties)
   }
 
+  trackOnboardingTour(
+    stage: OnboardingTourStage,
+    metadata: OnboardingTourMetadata
+  ): void {
+    this.trackEvent(OnboardingTourEvents[stage], metadata)
+  }
+
   trackSurvey(
     stage: 'opened' | 'submitted',
     responses?: SurveyResponses

src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.test.ts

@@ -4,6 +4,7 @@ import type { Ref } from 'vue'
 import { nextTick, ref } from 'vue'
 
 import { TelemetryEvents } from '../../types'
+import type { OnboardingTourStage } from '../../types'
 
 const hoisted = vi.hoisted(() => {
   const mockCapture = vi.fn()
@@ -613,6 +614,38 @@ describe('PostHogTelemetryProvider', () => {
         shellLayoutMetadata
       )
     })
+
+    it.for<
+      [
+        OnboardingTourStage,
+        (typeof TelemetryEvents)[keyof typeof TelemetryEvents]
+      ]
+    >([
+      ['started', TelemetryEvents.ONBOARDING_TOUR_STARTED],
+      ['step_shown', TelemetryEvents.ONBOARDING_TOUR_STEP_SHOWN],
+      ['completed', TelemetryEvents.ONBOARDING_TOUR_COMPLETED],
+      ['skipped', TelemetryEvents.ONBOARDING_TOUR_SKIPPED]
+    ])(
+      'maps onboarding tour stage %s to %s',
+      async ([stage, expectedEvent]) => {
+        const provider = createProvider()
+        await vi.dynamicImportSettled()
+
+        const metadata = {
+          tour: 'appMode',
+          step_count: 6,
+          step_number: 2,
+          coach_id: 'app-run-button'
+        } as const
+
+        provider.trackOnboardingTour(stage, metadata)
+
+        expect(hoisted.mockCapture).toHaveBeenCalledWith(
+          expectedEvent,
+          metadata
+        )
+      }
+    )
   })
 
   describe('survey tracking', () => {

src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts

@@ -23,6 +23,8 @@ import type {
   NodeAddedMetadata,
   NodeSearchMetadata,
   NodeSearchResultMetadata,
+  OnboardingTourMetadata,
+  OnboardingTourStage,
   SearchQueryMetadata,
   PageViewMetadata,
   PageVisibilityMetadata,
@@ -47,7 +49,7 @@ import type {
   WorkflowSavedMetadata,
   WorkspaceInviteMetadata
 } from '../../types'
-import { TelemetryEvents } from '../../types'
+import { OnboardingTourEvents, TelemetryEvents } from '../../types'
 import { normalizeSurveyResponses } from '../../utils/surveyNormalization'
 
 const DEFAULT_DISABLED_EVENTS = [
@@ -388,6 +390,13 @@ export class PostHogTelemetryProvider implements TelemetryProvider {
     this.trackEvent(TelemetryEvents.RUN_BUTTON_CLICKED, properties)
   }
 
+  trackOnboardingTour(
+    stage: OnboardingTourStage,
+    metadata: OnboardingTourMetadata
+  ): void {
+    this.trackEvent(OnboardingTourEvents[stage], metadata)
+  }
+
   trackSurvey(
     stage: 'opened' | 'submitted',
     responses?: SurveyResponses

src/platform/telemetry/types.ts

@@ -66,6 +66,24 @@ export interface SurveyResponses {
   intent?: string[]
 }
 
+export type OnboardingTourStage =
+  | 'started'
+  | 'step_shown'
+  | 'completed'
+  | 'skipped'
+
+/**
+ * `step_number` is 1-based and matches the "Step N of M" indicator the user
+ * sees, with `step_count` as M. Both `step_number` and `coach_id` are absent
+ * for steps with no numbered spotlight (e.g. the landing).
+ */
+export interface OnboardingTourMetadata {
+  tour: string
+  step_count: number
+  step_number?: number
+  coach_id?: string
+}
+
 export interface SurveyResponsesNormalized extends SurveyResponses {
   industry_normalized?: string
   industry_raw?: string
@@ -528,6 +546,12 @@ export interface TelemetryProvider {
   // Survey flow events
   trackSurvey?(stage: 'opened' | 'submitted', responses?: SurveyResponses): void
 
+  // Onboarding coachmark tour events
+  trackOnboardingTour?(
+    stage: OnboardingTourStage,
+    metadata: OnboardingTourMetadata
+  ): void
+
   // Email verification events
   trackEmailVerification?(stage: 'opened' | 'requested' | 'completed'): void
 
@@ -628,6 +652,12 @@ export const TelemetryEvents = {
   USER_SURVEY_OPENED: 'app:user_survey_opened',
   USER_SURVEY_SUBMITTED: 'app:user_survey_submitted',
 
+  // Onboarding Coachmarks
+  ONBOARDING_TOUR_STARTED: 'app:onboarding_tour_started',
+  ONBOARDING_TOUR_STEP_SHOWN: 'app:onboarding_tour_step_shown',
+  ONBOARDING_TOUR_COMPLETED: 'app:onboarding_tour_completed',
+  ONBOARDING_TOUR_SKIPPED: 'app:onboarding_tour_skipped',
+
   // Email Verification
   USER_EMAIL_VERIFY_OPENED: 'app:user_email_verify_opened',
   USER_EMAIL_VERIFY_REQUESTED: 'app:user_email_verify_requested',
@@ -691,6 +721,16 @@ export const TelemetryEvents = {
 export type TelemetryEventName =
   (typeof TelemetryEvents)[keyof typeof TelemetryEvents]
 
+export const OnboardingTourEvents: Record<
+  OnboardingTourStage,
+  TelemetryEventName
+> = {
+  started: TelemetryEvents.ONBOARDING_TOUR_STARTED,
+  step_shown: TelemetryEvents.ONBOARDING_TOUR_STEP_SHOWN,
+  completed: TelemetryEvents.ONBOARDING_TOUR_COMPLETED,
+  skipped: TelemetryEvents.ONBOARDING_TOUR_SKIPPED
+}
+
 export type ExecutionTriggerSource =
   | 'button'
   | 'keybinding'
@@ -703,6 +743,7 @@ export type ExecutionTriggerSource =
  */
 export type TelemetryEventProperties =
   | AuthMetadata
+  | OnboardingTourMetadata
   | SurveyResponses
   | TemplateMetadata
   | ExecutionContext

src/renderer/extensions/linearMode/LinearControls.vue

@@ -8,6 +8,8 @@ import AppModeWidgetList from '@/components/builder/AppModeWidgetList.vue'
 import { useErrorOverlayState } from '@/components/error/useErrorOverlayState'
 import Loader from '@/components/loader/Loader.vue'
 import ScrubableNumberInput from '@/components/common/ScrubableNumberInput.vue'
+import { requestTour } from '@/platform/onboarding/coachmarkController'
+import { vCoachmark } from '@/platform/onboarding/vCoachmark'
 import Popover from '@/components/ui/Popover.vue'
 import Button from '@/components/ui/button/Button.vue'
 import { useBillingContext } from '@/composables/billing/useBillingContext'
@@ -102,16 +104,24 @@ function handleDragDrop() {
       class="flex h-12 items-center gap-2 border-x border-border-subtle bg-comfy-menu-bg px-4 py-2 contain-size"
     >
       <span
-        class="truncate font-bold"
+        class="min-w-0 flex-1 truncate font-bold"
         v-text="workflowStore.activeWorkflow?.filename"
       />
-      <div class="flex-1" />
-      <Button v-if="false"> {{ t('menuLabels.publish') }} </Button>
+      <Button
+        variant="textonly"
+        size="icon"
+        :aria-label="t('linearMode.welcome.startTour')"
+        class="rounded-lg border border-solid border-border-default text-muted-foreground hover:border-interface-stroke hover:text-base-foreground"
+        @click="requestTour('appMode')"
+      >
+        <i class="icon-[lucide--circle-question-mark] size-4" />
+      </Button>
     </section>
     <div
       class="flex h-full flex-col gap-2 border-x border-(--interface-stroke) bg-comfy-menu-bg px-2 md:border-y"
     >
       <section
+        v-coachmark="'inputs-list'"
         data-testid="linear-widgets"
         class="grow scroll-shadows-comfy-menu-bg overflow-y-auto contain-size"
       >
@@ -152,34 +162,78 @@ function handleDragDrop() {
         class="border-t border-node-component-border p-4 pb-6"
       >
         <LinearRunErrorWarning v-if="showRunErrorWarning" />
-        <SubscribeToRunButton
-          v-if="!isActiveSubscription"
-          class="mt-4 w-full"
-        />
-        <div v-else class="mt-4 flex">
-          <PartnerNodesList mobile />
-          <Popover side="top" @open-auto-focus.prevent>
-            <template #button>
-              <Button size="lg" class="-mr-3 pr-7">
-                <i v-if="batchCount == 1" class="icon-[lucide--chevron-down]" />
-                <div v-else class="tabular-nums" v-text="`${batchCount}x`" />
-              </Button>
-            </template>
-            <div
-              class="m-1 mb-2 text-node-component-slot-text"
-              v-text="t('linearMode.runCount')"
-            />
-            <ScrubableNumberInput
-              v-model="batchCount"
-              :aria-label="t('linearMode.runCount')"
-              :min="1"
-              :max="settingStore.get('Comfy.QueueButton.BatchCountLimit')"
-              class="h-10 min-w-40"
-            />
-          </Popover>
+        <div v-coachmark="'app-run-button'">
+          <SubscribeToRunButton
+            v-if="!isActiveSubscription"
+            class="mt-4 w-full"
+          />
+          <div v-else class="mt-4 flex">
+            <PartnerNodesList mobile />
+            <Popover side="top" @open-auto-focus.prevent>
+              <template #button>
+                <Button size="lg" class="-mr-3 pr-7">
+                  <i
+                    v-if="batchCount == 1"
+                    class="icon-[lucide--chevron-down]"
+                  />
+                  <div v-else class="tabular-nums" v-text="`${batchCount}x`" />
+                </Button>
+              </template>
+              <div
+                class="m-1 mb-2 text-node-component-slot-text"
+                v-text="t('linearMode.runCount')"
+              />
+              <ScrubableNumberInput
+                v-model="batchCount"
+                :aria-label="t('linearMode.runCount')"
+                :min="1"
+                :max="settingStore.get('Comfy.QueueButton.BatchCountLimit')"
+                class="h-10 min-w-40"
+              />
+            </Popover>
+            <Button
+              variant="primary"
+              class="grow"
+              size="lg"
+              :aria-describedby="
+                showRunErrorWarning
+                  ? LINEAR_RUN_ERROR_WARNING_DESCRIPTION_ID
+                  : undefined
+              "
+              @click="runButtonClick"
+            >
+              <i aria-hidden="true" class="icon-[lucide--play]" />
+              {{ t('menu.run') }}
+            </Button>
+          </div>
+        </div>
+      </section>
+      <section
+        v-else
+        :data-testid="linearRunButtonTestId"
+        class="border-t border-node-component-border p-4 pb-6"
+      >
+        <LinearRunErrorWarning v-if="showRunErrorWarning" />
+        <div v-coachmark="'app-run-button'">
+          <div
+            class="m-1 mb-2 text-node-component-slot-text"
+            v-text="t('linearMode.runCount')"
+          />
+          <ScrubableNumberInput
+            v-model="batchCount"
+            :aria-label="t('linearMode.runCount')"
+            :min="1"
+            :max="settingStore.get('Comfy.QueueButton.BatchCountLimit')"
+            class="h-7 min-w-40"
+          />
+          <SubscribeToRunButton
+            v-if="!isActiveSubscription"
+            class="mt-4 w-full"
+          />
           <Button
+            v-else
             variant="primary"
-            class="grow"
+            class="mt-4 w-full text-sm"
             size="lg"
             :aria-describedby="
               showRunErrorWarning
@@ -193,43 +247,6 @@ function handleDragDrop() {
           </Button>
         </div>
       </section>
-      <section
-        v-else
-        :data-testid="linearRunButtonTestId"
-        class="border-t border-node-component-border p-4 pb-6"
-      >
-        <LinearRunErrorWarning v-if="showRunErrorWarning" />
-        <div
-          class="m-1 mb-2 text-node-component-slot-text"
-          v-text="t('linearMode.runCount')"
-        />
-        <ScrubableNumberInput
-          v-model="batchCount"
-          :aria-label="t('linearMode.runCount')"
-          :min="1"
-          :max="settingStore.get('Comfy.QueueButton.BatchCountLimit')"
-          class="h-7 min-w-40"
-        />
-        <SubscribeToRunButton
-          v-if="!isActiveSubscription"
-          class="mt-4 w-full"
-        />
-        <Button
-          v-else
-          variant="primary"
-          class="mt-4 w-full text-sm"
-          size="lg"
-          :aria-describedby="
-            showRunErrorWarning
-              ? LINEAR_RUN_ERROR_WARNING_DESCRIPTION_ID
-              : undefined
-          "
-          @click="runButtonClick"
-        >
-          <i aria-hidden="true" class="icon-[lucide--play]" />
-          {{ t('menu.run') }}
-        </Button>
-      </section>
     </div>
   </div>
   <div

src/renderer/extensions/linearMode/LinearWelcome.vue

@@ -1,12 +1,13 @@
 <script setup lang="ts">
-import { useI18n } from 'vue-i18n'
-import { useAppMode } from '@/composables/useAppMode'
-import { useWorkflowTemplateSelectorDialog } from '@/composables/useWorkflowTemplateSelectorDialog'
-import { useAppModeStore } from '@/stores/appModeStore'
-import Button from '@/components/ui/button/Button.vue'
-import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
 import { storeToRefs } from 'pinia'
 import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import Button from '@/components/ui/button/Button.vue'
+import { useAppMode } from '@/composables/useAppMode'
+import { useWorkflowTemplateSelectorDialog } from '@/composables/useWorkflowTemplateSelectorDialog'
+import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
+import { useAppModeStore } from '@/stores/appModeStore'
 
 const { t } = useI18n()
 const { setMode } = useAppMode()

src/schemas/apiSchema.ts

@@ -414,6 +414,7 @@ const zSettings = z.object({
   'Comfy.Toast.DisableReconnectingToast': z.boolean(),
   'Comfy.Workflow.Persist': z.boolean(),
   'Comfy.TutorialCompleted': z.boolean(),
+  'Comfy.OnboardingCoachmarks.Seen': z.array(z.string()),
   'Comfy.InstalledVersion': z.string().nullable(),
   'Comfy.Node.AllowImageSizeDraw': z.boolean(),
   'Comfy.Minimap.Visible': z.boolean(),

src/views/GraphView.vue

@@ -29,6 +29,7 @@
   <DesktopCloudNotificationController />
   <UnloadWindowConfirmDialog v-if="!isDesktop" />
   <MenuHamburger />
+  <TourOverlay v-if="graphReady" />
 </template>
 
 <script setup lang="ts">
@@ -49,6 +50,7 @@ import { runWhenGlobalIdle } from '@/base/common/async'
 import MenuHamburger from '@/components/MenuHamburger.vue'
 import UnloadWindowConfirmDialog from '@/components/dialog/UnloadWindowConfirmDialog.vue'
 import GraphCanvas from '@/components/graph/GraphCanvas.vue'
+import TourOverlay from '@/platform/onboarding/TourOverlay.vue'
 import GlobalToast from '@/components/toast/GlobalToast.vue'
 import InviteAcceptedToast from '@/platform/workspace/components/toasts/InviteAcceptedToast.vue'
 import RerouteMigrationToast from '@/components/toast/RerouteMigrationToast.vue'
@@ -111,6 +113,7 @@ const queueStore = useQueueStore()
 const assetsStore = useAssetsStore()
 const versionCompatibilityStore = useVersionCompatibilityStore()
 const graphCanvasContainerRef = ref<HTMLDivElement | null>(null)
+const graphReady = ref(false)
 const { isBuilderMode, mode, isAppMode } = useAppMode()
 const { linearMode } = storeToRefs(useCanvasStore())
 
@@ -294,6 +297,7 @@ void nextTick(() => {
 })
 
 const onGraphReady = () => {
+  graphReady.value = true
   runWhenGlobalIdle(() => {
     // Track user login when app is ready in graph view (cloud only)
     if (isCloud && authStore.isAuthenticated && !hasTrackedLogin) {

src/views/LinearView.vue

@@ -12,6 +12,7 @@ import ExtensionSlot from '@/components/common/ExtensionSlot.vue'
 import TopbarBadges from '@/components/topbar/TopbarBadges.vue'
 import TopbarSubscribeButton from '@/components/topbar/TopbarSubscribeButton.vue'
 import WorkflowTabs from '@/components/topbar/WorkflowTabs.vue'
+import { vCoachmark } from '@/platform/onboarding/vCoachmark'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { cn } from '@comfyorg/tailwind-utils'
 import LinearControls from '@/renderer/extensions/linearMode/LinearControls.vue'
@@ -134,6 +135,7 @@ function dragDrop(e: DragEvent) {
         <AppBuilder v-if="showLeftBuilder" />
         <div
           v-else-if="sidebarOnLeft && activeTab"
+          v-coachmark="activeTab?.id === 'assets' ? 'assets-panel' : undefined"
           class="size-full overflow-x-hidden border-r border-border-subtle"
         >
           <ExtensionSlot :extension="activeTab" />
@@ -146,6 +148,7 @@ function dragDrop(e: DragEvent) {
       </SplitterPanel>
       <SplitterPanel
         id="linearCenterPanel"
+        v-coachmark="'outputs'"
         data-testid="linear-center-panel"
         :size="CENTER_PANEL_SIZE"
         class="relative flex min-w-[20vw] flex-col gap-4 text-muted-foreground outline-none"
@@ -188,6 +191,7 @@ function dragDrop(e: DragEvent) {
         />
         <div
           v-else-if="activeTab"
+          v-coachmark="activeTab?.id === 'assets' ? 'assets-panel' : undefined"
           class="h-full overflow-x-hidden border-l border-border-subtle"
         >
           <ExtensionSlot :extension="activeTab" />