feat: update tutorial functionality and improve tutorial step management

frontend/src/components/child/ParentView.vue

@@ -445,16 +445,8 @@ function openRoutineMenu(routineId: string, e: MouseEvent) {
       'routine-kebab-menu',
       () => document.querySelector('.kebab-menu') as HTMLElement | null,
     )
-    tutorialMaybeShow(
-      'kebab-edit-points-cost',
-      () => document.querySelector('[data-tutorial~="kebab-edit-points-cost"]') as HTMLElement | null,
-    )
-    tutorialMaybeShow(
-      'routine-schedule',
-      () => document.querySelector('[data-tutorial="routine-schedule"]') as HTMLElement | null,
-    )
   })
-  const items = childRoutineListRef.value?.items ?? []
+  const items: ChildRoutine[] = childRoutineListRef.value?.items ?? []
   const routine = items.find((r) => r.id === routineId)
   if (routine) {
     if (isRoutineExpired(routine)) {
@@ -740,14 +732,6 @@ function openChoreMenu(taskId: string, e: MouseEvent) {
       'chore-kebab-menu',
       () => document.querySelector('.kebab-menu') as HTMLElement | null,
     )
-    tutorialMaybeShow(
-      'kebab-edit-points-cost',
-      () => document.querySelector('[data-tutorial~="kebab-edit-points-cost"]') as HTMLElement | null,
-    )
-    tutorialMaybeShow(
-      'chore-schedule',
-      () => document.querySelector('[data-tutorial="chore-schedule"]') as HTMLElement | null,
-    )
   })
   const items: ChildTask[] = childChoreListRef.value?.items ?? []
   const task = items.find((t) => t.id === taskId)

frontend/src/tutorial/__tests__/controller.spec.ts

@@ -1,17 +1,37 @@
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import {
   shouldShowStep,
   clearChainProgress,
   tutorialEnabled,
   tutorialProgress,
   sessionSkipped,
+  maybeShow,
+  dismissActive,
+  activeStep,
 } from '../controller'
 
+function setKebabAnchorHtml() {
+  document.body.innerHTML = `
+    <div class="kebab-menu"></div>
+    <button data-tutorial="chore-edit-points kebab-edit-points-cost">Edit Points</button>
+    <button data-tutorial="chore-schedule">Schedule</button>
+  `
+}
+
 describe('tutorial controller - shouldShowStep', () => {
   beforeEach(() => {
     tutorialEnabled.value = true
     tutorialProgress.value = {}
     sessionSkipped.value = false
+    activeStep.value = null
+    document.body.innerHTML = ''
+    global.fetch = vi.fn().mockResolvedValue({ ok: true })
+  })
+
+  afterEach(() => {
+    activeStep.value = null
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
   })
 
   it('returns true when tips are enabled, the step is unseen, and the session is not skipped', () => {
@@ -46,3 +66,103 @@ describe('tutorial controller - shouldShowStep', () => {
     expect(shouldShowStep('status-pending', true)).toBe(true)
   })
 })
+
+describe('tutorial controller - maybeShow', () => {
+  beforeEach(() => {
+    tutorialEnabled.value = true
+    tutorialProgress.value = {}
+    sessionSkipped.value = false
+    activeStep.value = null
+    setKebabAnchorHtml()
+    global.fetch = vi.fn().mockResolvedValue({ ok: true })
+  })
+
+  afterEach(() => {
+    activeStep.value = null
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
+  })
+
+  it('promotes a step when the anchor is present', () => {
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value?.def.id).toBe('chore-kebab-menu')
+  })
+
+  it('does not promote a step that has already been seen', () => {
+    tutorialProgress.value = { 'chore-kebab-menu': true }
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value).toBeNull()
+  })
+
+  it('is idempotent for the currently active step', () => {
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value?.def.id).toBe('chore-kebab-menu')
+
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value?.def.id).toBe('chore-kebab-menu')
+  })
+
+  it('drops a step whose anchor is missing', () => {
+    document.body.innerHTML = ''
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value).toBeNull()
+  })
+})
+
+describe('tutorial controller - dismissActive', () => {
+  beforeEach(() => {
+    tutorialEnabled.value = true
+    tutorialProgress.value = {}
+    sessionSkipped.value = false
+    activeStep.value = null
+    setKebabAnchorHtml()
+    global.fetch = vi.fn().mockResolvedValue({ ok: true })
+  })
+
+  afterEach(() => {
+    activeStep.value = null
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
+  })
+
+  it('marks the active step seen and chains the next step', () => {
+    maybeShow('chore-kebab-menu')
+    expect(activeStep.value?.def.id).toBe('chore-kebab-menu')
+
+    dismissActive(true)
+    expect(tutorialProgress.value['chore-kebab-menu']).toBe(true)
+    expect(activeStep.value?.def.id).toBe('chore-edit-points')
+  })
+
+  it('does not duplicate a chained step that is already queued', () => {
+    // Set up: open the chore kebab menu, then queue the next step early.
+    maybeShow('chore-kebab-menu')
+    maybeShow('chore-edit-points')
+    expect(activeStep.value?.def.id).toBe('chore-kebab-menu')
+
+    // Dismissing the menu should chain to chore-edit-points only once.
+    dismissActive(true)
+    expect(activeStep.value?.def.id).toBe('chore-edit-points')
+
+    // If a duplicate had been added, we would still be on chore-edit-points.
+    dismissActive(true)
+    expect(activeStep.value?.def.id).toBe('chore-schedule')
+  })
+
+  it('does not re-chain a step that is currently active', () => {
+    maybeShow('chore-kebab-menu')
+    dismissActive(true)
+    expect(activeStep.value?.def.id).toBe('chore-edit-points')
+
+    // Dismissing chore-edit-points should move to chore-schedule, not loop.
+    dismissActive(true)
+    expect(activeStep.value?.def.id).toBe('chore-schedule')
+  })
+
+  it('does not mark the step seen when markSeen is false', () => {
+    maybeShow('chore-kebab-menu')
+    dismissActive(false)
+    expect(tutorialProgress.value['chore-kebab-menu']).toBeUndefined()
+    expect(activeStep.value).toBeNull()
+  })
+})

frontend/src/tutorial/controller.ts

@@ -147,7 +147,7 @@ export function dismissActive(markSeen = true) {
     }
     if (current.def.next) {
       const nextDef = stepRegistry[current.def.next]
-      if (nextDef && shouldShowStep(nextDef.id)) {
+      if (nextDef && shouldShowStep(nextDef.id) && !queue.some((q) => q.def.id === nextDef.id)) {
         queue.unshift({ def: nextDef, anchor: null })
       }
     }