@cat-factory/app 0.201.1 → 0.204.0

package/app/components/tutorial/TutorialOverlay.vue

@@ -1,33 +1,53 @@
 <script setup lang="ts">
+import { usePreferredReducedMotion } from '@vueuse/core'
 import {
   computeCoachMarkLayout,
   DEFAULT_TARGET_WAIT_MS,
+  needsReveal,
+  TARGET_IDLE_INTERVAL_MS,
   TARGET_TRACK_INTERVAL_MS,
 } from '~/utils/tutorial'
 import type { CoachMarkLayout, TutorialRect, TutorialStep, TutorialTour } from '~/utils/tutorial'
 import {
+  boardNodeIdFor,
   isTargetClickAdvance,
   resolveSkip,
+  shouldFocusCard,
   stepTargetSelectors,
   unexpectedlySkippedSteps,
   waitBudgetMs,
 } from './TutorialOverlay.logic'
-import type { TutorialDirection } from './TutorialOverlay.logic'
+import type { TutorialAdvanceCause, TutorialDirection } from './TutorialOverlay.logic'
 
 // The one shared tour runtime: resolves the running tour from the `tutorialTours` slot,
 // anchors a highlight ring + tooltip to the current step's `data-testid`, and advances
 // on Next or on a real click on the highlighted control. Mounted (from `pages/index.vue`)
 // only while `tutorial.touring`, so all the DOM tracking below exists only mid-tour.
 //
-// Anchor tracking is a poll, not a one-shot query: board controls move (canvas pan/zoom,
-// panels opening) and appear asynchronously (a step can point INTO the modal the previous
-// step's click opens), so every tick re-queries and re-measures. A target that never
-// appears within the step's wait SKIPS the step — controls are RBAC/tier/deployment
-// dependent, and a tour is a set of opportunities, not a fixed script. Everything that
-// DECIDES rather than measures lives in `TutorialOverlay.logic.ts`, which is unit-tested.
+// Anchor tracking is not a one-shot query: board controls move (canvas pan/zoom, panels
+// opening) and appear asynchronously (a step can point INTO the modal the previous step's
+// click opens). So the runtime HUNTS for a not-yet-mounted anchor on a fast poll bounded by
+// the step's wait budget, and then TRACKS the one it found off events (scroll, resize,
+// element resize, board camera) with a slow backstop tick behind them. A target that never
+// appears within the wait SKIPS the step — controls are RBAC/tier/deployment dependent, and
+// a tour is a set of opportunities, not a fixed script.
+//
+// An anchor that is on the page but off SCREEN is revealed before it is pointed at, by
+// whichever mechanism its container understands: the board is a transform-panned canvas
+// (move the camera), everything else is an ordinary scroll container (`scrollIntoView`).
+//
+// Everything that DECIDES rather than measures lives in `TutorialOverlay.logic.ts`, and the
+// geometry in `utils/tutorial.ts`; both are unit-tested, the SFC is not.
 const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
+const { fitView, viewport } = useBoardFlow()
+// Reduced motion is honoured in BOTH directions here: the CSS below drops the ring's transition
+// and the searching spinner behind `motion-safe:`, and this drives the JS half — an instant
+// scroll and an instant camera move, since a reveal is involuntary motion the user did not ask
+// for and is exactly what the preference is about.
+const reducedMotion = usePreferredReducedMotion()
+const motionMs = computed(() => (reducedMotion.value === 'reduce' ? 0 : 250))
 
 /**
  * The running tour's script, resolved ONCE from the slot when the tour starts and then HELD
@@ -58,18 +78,40 @@ const step = computed<TutorialStep | null>(() => tour.value?.steps[tutorial.step
 const total = computed(() => tour.value?.steps.length ?? 0)
 const isLast = computed(() => tour.value !== null && tutorial.stepIndex >= total.value - 1)
 
-// The tour could not be resolved when it started (a stale persisted id, or a tour this board
-// is not offered at all) or the cursor ran past the end: end it instead of rendering a dead
-// overlay. Since the script is held, this can no longer fire because a gate flipped mid-tour.
+// The tour could not be resolved when it started (a stale persisted id, or a tour this board is
+// not offered at all): end it instead of rendering a dead overlay, and do NOT leave a resume
+// point behind — it is a position in a script that could not be loaded, so offering it again
+// would put the user straight back here. Since the script is held, this can no longer fire
+// because a gate flipped mid-tour.
+//
+// A resolvable tour whose CURSOR is out of range is a different fact with a different fix: it
+// means a resume landed past the end of a script the gates have thinned since. Rewind to the
+// start rather than ending, or breaking off a tour would cost the user the tour itself.
 watch(
   () => [tour.value, step.value] as const,
   ([tr, st]) => {
-    if (tutorial.touring && (!tr || !st)) tutorial.stopTour()
+    if (!tutorial.touring) return
+    if (!tr) tutorial.stopTour({ resumable: false })
+    else if (!st) tutorial.setStepIndex(0)
   },
   { immediate: true },
 )
 
 const targetRect = ref<TutorialRect | null>(null)
+/**
+ * The resolved anchor, held between ticks. Event-driven re-measures (scroll, resize, canvas
+ * pan) reuse it rather than re-running the selector, and the slow backstop tick re-resolves —
+ * so a step still re-anchors when its control is replaced underneath it, without paying for a
+ * document query several times a second for the whole length of the tour.
+ */
+const anchorEl = ref<HTMLElement | null>(null)
+/**
+ * The step index whose anchor has already been brought into view. A reveal is attempted at
+ * most ONCE per step: `fitView` and `scrollIntoView` are animations that take longer than a
+ * tracking tick, so re-deciding each tick would re-issue the move against a viewport still
+ * mid-flight and fight the user the moment they panned away deliberately.
+ */
+const revealedForStep = ref<number | null>(null)
 const cardEl = ref<HTMLElement | null>(null)
 const layout = ref<CoachMarkLayout>({ top: -9999, left: -9999, placement: 'center' })
 
@@ -92,23 +134,73 @@ const unexpectedSkips = computed(() =>
 )
 const abridged = computed(() => unexpectedSkips.value.length > 0)
 
-const viewport = () => ({ width: window.innerWidth, height: window.innerHeight })
+/**
+ * The browser viewport. Named apart from Vue Flow's `viewport` (the board CAMERA) above —
+ * and not `screen`, which would shadow the DOM global of that name for the whole component.
+ */
+const screenSize = () => ({ width: window.innerWidth, height: window.innerHeight })
 /** The tooltip's own size, or a sensible guess before it has rendered once. */
 const cardSize = () => ({
   width: cardEl.value?.offsetWidth ?? 320,
   height: cardEl.value?.offsetHeight ?? 180,
 })
 
+/** Is this element still in the document and still rendering a box? */
+function isUsable(el: HTMLElement | null): el is HTMLElement {
+  // `getClientRects().length` distinguishes a mounted-but-hidden control (display:none
+  // drawer item) from a visible one; pointing at an invisible control helps nobody.
+  return el !== null && el.isConnected && el.getClientRects().length > 0
+}
+
 function queryTarget(s: TutorialStep): HTMLElement | null {
   for (const selector of stepTargetSelectors(s)) {
     const el = document.querySelector<HTMLElement>(selector)
-    // `getClientRects().length` distinguishes a mounted-but-hidden control (display:none
-    // drawer item) from a visible one; pointing at an invisible control helps nobody.
-    if (el && el.getClientRects().length > 0) return el
+    if (isUsable(el)) return el
   }
   return null
 }
 
+/**
+ * The anchor for this step. Reuses the held element unless `requery` is set or it has gone
+ * stale (unmounted, or hidden) — the two cases where it no longer describes anything on screen.
+ */
+function resolveAnchor(s: TutorialStep, requery: boolean): HTMLElement | null {
+  if (!requery && isUsable(anchorEl.value)) return anchorEl.value
+  anchorEl.value = queryTarget(s)
+  return anchorEl.value
+}
+
+/**
+ * Bring an off-screen anchor into view, by whichever mechanism its container understands.
+ *
+ * The board is a transform-panned Vue Flow canvas, so a card that is off screen is not
+ * SCROLLED away and `scrollIntoView` on it does nothing at all; the camera has to move
+ * instead. Everything else — a panel's scroll container, a long modal body, the sidebar —
+ * is an ordinary scroll and `scrollIntoView` is exactly right.
+ *
+ * The camera move is clamped to the CURRENT zoom (`fitView` would otherwise zoom to fit a
+ * single small node, throwing away the user's own view of their board to point at a button).
+ */
+function revealAnchor(el: HTMLElement) {
+  const nodeId = boardNodeIdFor(el)
+  if (nodeId !== null) {
+    const zoom = viewport.value.zoom
+    fitView({
+      nodes: [nodeId],
+      padding: 0.3,
+      minZoom: zoom,
+      maxZoom: zoom,
+      duration: motionMs.value,
+    })
+    return
+  }
+  el.scrollIntoView({
+    behavior: motionMs.value === 0 ? 'auto' : 'smooth',
+    block: 'center',
+    inline: 'center',
+  })
+}
+
 /** Give up on a step whose anchor never appeared, continuing the user's own direction. */
 function skipMissingStep(s: TutorialStep) {
   skippedStepIds.value = new Set(skippedStepIds.value).add(s.id)
@@ -117,28 +209,44 @@ function skipMissingStep(s: TutorialStep) {
   else tutorial.setStepIndex(outcome.index)
 }
 
-function measure() {
+function measure(options?: { requery?: boolean }) {
   const s = step.value
   if (!s) return
   if (!s.target) {
     targetRect.value = null
   } else {
-    const el = queryTarget(s)
+    const el = resolveAnchor(s, options?.requery === true)
     if (!el) {
       targetRect.value = null
       // Centered while searching: the card must not sit at the PREVIOUS step's anchor —
       // nor at its off-screen initial position — pointing at nothing.
-      layout.value = computeCoachMarkLayout(null, cardSize(), viewport())
+      layout.value = computeCoachMarkLayout(null, cardSize(), screenSize())
       if (performance.now() >= searchDeadline.value) skipMissingStep(s)
       return
     }
     const r = el.getBoundingClientRect()
-    targetRect.value = { top: r.top, left: r.left, width: r.width, height: r.height }
+    const rect = { top: r.top, left: r.left, width: r.width, height: r.height }
+    // Reveal BEFORE publishing the rect, so the ring and tooltip are placed from the
+    // post-move position on the next tick rather than flashing at the off-screen one.
+    if (revealedForStep.value !== tutorial.stepIndex && needsReveal(rect, screenSize())) {
+      revealedForStep.value = tutorial.stepIndex
+      revealAnchor(el)
+      // Centre the card for the same reason the searching branch above does, and it is the
+      // same failure: returning without touching `layout` would render THIS step's copy at
+      // the PREVIOUS step's coordinates, pointing at a control the user has already left.
+      // Usually one frame, since the move emits scroll/camera events that re-enter here —
+      // but a reveal that moves nothing (a `fitView` over a node the canvas has dropped)
+      // emits none at all, and then it is the whole backstop tick.
+      layout.value = computeCoachMarkLayout(null, cardSize(), screenSize())
+      return
+    }
+    revealedForStep.value = tutorial.stepIndex
+    targetRect.value = rect
   }
   layout.value = computeCoachMarkLayout(
     s.target ? targetRect.value : null,
     cardSize(),
-    viewport(),
+    screenSize(),
     s.placement,
   )
 }
@@ -149,19 +257,42 @@ function measure() {
 watch(step, async (s) => {
   searchDeadline.value = performance.now() + (s ? waitBudgetMs(s) : DEFAULT_TARGET_WAIT_MS)
   targetRect.value = null
+  anchorEl.value = null
+  revealedForStep.value = null
   await nextTick()
-  measure()
+  measure({ requery: true })
 })
 
-function advance() {
+/**
+ * Put focus on the tooltip so the tour's own controls are one Tab away. WHETHER to do that is
+ * `shouldFocusCard`'s call, in the logic module, so it is pinned by a test — this function is
+ * only the DOM half. `preventScroll` because the card is already placed.
+ */
+async function focusCard(cause: TutorialAdvanceCause) {
+  if (!shouldFocusCard(cause)) return
+  await nextTick()
+  cardEl.value?.focus({ preventScroll: true })
+}
+
+/**
+ * Move the cursor forward. The cause is REQUIRED rather than defaulted: it decides whether
+ * focus moves, and a new call site inheriting a default silently is exactly how a
+ * `target-click` advance came to steal focus from the modal it had just opened.
+ */
+function advance(cause: TutorialAdvanceCause) {
   direction.value = 'forward'
-  if (isLast.value) tutorial.completeTour()
-  else tutorial.setStepIndex(tutorial.stepIndex + 1)
+  if (isLast.value) {
+    tutorial.completeTour()
+    return
+  }
+  tutorial.setStepIndex(tutorial.stepIndex + 1)
+  void focusCard(cause)
 }
 
 function back() {
   direction.value = 'back'
   tutorial.setStepIndex(tutorial.stepIndex - 1)
+  void focusCard('nav-control')
 }
 
 // "Now click this" steps: watch real clicks (capture phase, so a stopPropagation inside a
@@ -169,41 +300,157 @@ function back() {
 // the real handler open its modal/submit its form before the tour moves its anchor.
 function onDocumentClick(event: MouseEvent) {
   if (isTargetClickAdvance(step.value, event.target)) {
-    window.setTimeout(advance, 0)
+    window.setTimeout(() => advance('target-click'), 0)
   }
 }
 
-/** Esc ends the tour, matching every other dismissible surface in the app. */
+/**
+ * Esc ends the tour, matching every other dismissible surface in the app — and, like Skip,
+ * leaves a resume point, because it is by far the easiest key to hit by accident and the
+ * position it discards is the entire walkthrough.
+ */
 function onKeydown(event: KeyboardEvent) {
   if (event.key === 'Escape') tutorial.stopTour()
 }
 
-let trackTimer: ReturnType<typeof setInterval> | undefined
+/**
+ * What a screen reader should be told about the current step.
+ *
+ * A dedicated `role="status"` region rather than `aria-live` on the card itself: the card is a
+ * `dialog` whose entire contents are replaced per step, and assistive tech does not reliably
+ * announce a wholesale subtree replacement inside a dialog. One key with placeholders, not
+ * concatenated fragments, per the i18n rules.
+ *
+ * This is also the SOLE announcement of the step — the card carries no `aria-describedby`,
+ * which would have the body read a second time on every focus move.
+ */
+const announcementText = computed(() =>
+  step.value
+    ? t('tutorial.overlay.announcement', {
+        current: tutorial.stepIndex + 1,
+        total: total.value,
+        title: t(step.value.titleKey),
+        body: t(step.value.bodyKey, step.value.bodyParams ?? {}),
+      })
+    : '',
+)
+
+/**
+ * What the live region actually holds, lagging {@link announcementText} by a tick.
+ *
+ * Assistive tech announces a CHANGE to a live region, and routinely says nothing at all about
+ * one that was INSERTED already populated — the same unreliability that moved this out of the
+ * card in the first place. The overlay mounts with a step already resolved, so a region bound
+ * straight to the text above would arrive full and go unread, silently costing the first step
+ * of every tour. Publishing a tick later guarantees the empty region is in the DOM first, so
+ * the text is always a change to an existing node.
+ */
+const announcement = ref('')
+watch(
+  announcementText,
+  async (text) => {
+    await nextTick()
+    announcement.value = text
+  },
+  { immediate: true },
+)
+
+// Anchor tracking is EVENT-DRIVEN once an anchor is held, with a slow backstop tick behind it;
+// only the hunt for a not-yet-mounted anchor polls fast, and that is bounded by the step's own
+// wait budget. The events below are the ways a control that is already on screen can move:
+// something scrolled (capture phase, so it catches every scroll container, not just the
+// window), the window resized, the control itself resized, or the board camera panned/zoomed.
+/**
+ * Re-measure from the held anchor — the cheap path every motion event takes — coalesced to at
+ * most once per frame.
+ *
+ * `measure()` READS layout (`getBoundingClientRect`, the card's offset size) and then WRITES
+ * it (the ring and tooltip styles), so running it per event thrashes layout. Capture-phase
+ * scroll is the one that makes this bite: it fires for every scroll container on the page and
+ * many times a frame under a momentum scroll, where the poll it replaced ran every 150 ms. A
+ * frame is also the most the user can see, so nothing is lost by waiting for one.
+ */
+let frameHandle = 0
+function remeasure() {
+  if (typeof requestAnimationFrame === 'undefined') {
+    measure()
+    return
+  }
+  if (frameHandle !== 0) return
+  frameHandle = requestAnimationFrame(() => {
+    frameHandle = 0
+    measure()
+  })
+}
+
+let trackTimer: ReturnType<typeof setTimeout> | undefined
+/** Re-resolve the selector on a cadence set by whether we currently HAVE an anchor. */
+function scheduleTrack() {
+  const delay = targetRect.value ? TARGET_IDLE_INTERVAL_MS : TARGET_TRACK_INTERVAL_MS
+  trackTimer = setTimeout(() => {
+    measure({ requery: true })
+    scheduleTrack()
+  }, delay)
+}
+
+/** Follows the held anchor's own size changes (a card growing as its run progresses). */
+const anchorResize =
+  typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(() => remeasure())
+watch(anchorEl, (el) => {
+  anchorResize?.disconnect()
+  if (el) anchorResize?.observe(el)
+})
+
+// The board camera: a pan or zoom moves every canvas anchor without any scroll event at all.
+watch(() => [viewport.value.x, viewport.value.y, viewport.value.zoom], remeasure)
+
 onMounted(() => {
   const s = step.value
   searchDeadline.value = performance.now() + (s ? waitBudgetMs(s) : DEFAULT_TARGET_WAIT_MS)
   document.addEventListener('click', onDocumentClick, true)
   document.addEventListener('keydown', onKeydown)
-  window.addEventListener('resize', measure)
-  trackTimer = setInterval(measure, TARGET_TRACK_INTERVAL_MS)
-  measure()
+  document.addEventListener('scroll', remeasure, { capture: true, passive: true })
+  window.addEventListener('resize', remeasure)
+  scheduleTrack()
+  measure({ requery: true })
+  void focusCard('tour-start')
 })
 onUnmounted(() => {
   document.removeEventListener('click', onDocumentClick, true)
   document.removeEventListener('keydown', onKeydown)
-  window.removeEventListener('resize', measure)
-  if (trackTimer !== undefined) clearInterval(trackTimer)
+  document.removeEventListener('scroll', remeasure, true)
+  window.removeEventListener('resize', remeasure)
+  anchorResize?.disconnect()
+  if (trackTimer !== undefined) clearTimeout(trackTimer)
+  if (frameHandle !== 0) cancelAnimationFrame(frameHandle)
 })
 </script>
 
 <template>
   <!-- Teleported so board/panel stacking contexts can't clip the marks; z-[70] sits above
-       the app's modals (z-50s), since steps legitimately point INTO an open modal. -->
+       the app's modals (z-50s), since steps legitimately point INTO an open modal — with the
+       one exception of the tutorial's OWN windows (`ownWindowOpen`), which no step points into
+       and over which the same z-index would float a ring and a tooltip the user cannot use. -->
   <Teleport to="body">
-    <div v-if="step" data-testid="tutorial-overlay">
+    <!-- The step-change announcement. Visually hidden, and outside BOTH the dialog and the
+         `v-if` below, so the live region is a stable node whose TEXT changes for the whole
+         life of the overlay — never a subtree replaced wholesale, and never one inserted with
+         its content already in place. Assistive tech announces neither of those reliably. The
+         text itself also lands a tick after the node does; see `announcement`. -->
+    <div class="sr-only" role="status" aria-live="polite" data-testid="tutorial-announcement">
+      {{ announcement }}
+    </div>
+    <!-- SUPPRESSED, not unmounted, while a tutorial-owned window is open: this component holds
+         the running tour's resolved script (see `tour` above), and a remount would re-resolve it
+         against gates that may have flipped since the tour started — which is the very failure
+         that holding it fixed. The cursor, the tracking and the script all survive; only the
+         marks go, and they come back the moment the window closes. -->
+    <div v-if="step && !tutorial.ownWindowOpen" data-testid="tutorial-overlay">
+      <!-- `motion-safe:` on the ring's transition: it slides between controls on every step,
+           which is exactly the involuntary movement `prefers-reduced-motion` is about. -->
       <div
         v-if="targetRect"
-        class="ring-primary-400 outline-primary-400/25 pointer-events-none fixed z-[70] rounded-lg outline-4 ring-2 transition-all duration-150"
+        class="ring-primary-400 outline-primary-400/25 pointer-events-none fixed z-[70] rounded-lg outline-4 ring-2 motion-safe:transition-all motion-safe:duration-150"
         :style="{
           top: `${targetRect.top - 4}px`,
           left: `${targetRect.left - 4}px`,
@@ -217,12 +464,19 @@ onUnmounted(() => {
            layer, which sets `body { pointer-events: none }` (leaving this card inert) and
            dismisses on a document-level pointerdown outside its own content (so a press on
            this card would close the user's half-filled form instead of pressing a button). -->
+      <!-- `tabindex="-1"` so `focusCard()` can put focus here when the tour starts and on every
+           Next/Back — without it a keyboard user has to tab the whole page to reach Next, since
+           this is teleported to the end of `body`. No `aria-modal`: a coach mark is NOT modal,
+           and half the catalog asks the user to operate the real control behind it. No
+           `aria-describedby` on the body either: the live region above already reads the body
+           as part of a complete announcement, and pointing at it here would have every focus
+           move read it a second time. -->
       <div
         ref="cardEl"
         role="dialog"
-        aria-live="polite"
+        tabindex="-1"
         :aria-label="t('tutorial.overlay.ariaLabel')"
-        class="pointer-events-auto fixed z-[70] w-80 max-w-[calc(100vw-16px)] rounded-xl border border-slate-700 bg-slate-900 p-4 shadow-2xl"
+        class="pointer-events-auto fixed z-[70] w-80 max-w-[calc(100vw-16px)] rounded-xl border border-slate-700 bg-slate-900 p-4 shadow-2xl outline-none focus-visible:ring-2 focus-visible:ring-primary-400"
         :style="{ top: `${layout.top}px`, left: `${layout.left}px` }"
         data-testid="tutorial-tooltip"
         @pointerdown.stop
@@ -236,13 +490,15 @@ onUnmounted(() => {
         <!-- `bodyParams` carries the fixed proper nouns a step names (a repository slug),
              which live in the catalog's `{named}` placeholders rather than in nine
              translations of the same literal. Absent for most steps. -->
-        <p class="text-sm text-slate-300">{{ t(step.bodyKey, step.bodyParams ?? {}) }}</p>
+        <p class="text-sm text-slate-300">
+          {{ t(step.bodyKey, step.bodyParams ?? {}) }}
+        </p>
         <p
           v-if="searching"
           class="mt-2 flex items-center gap-1.5 text-xs text-slate-400"
           data-testid="tutorial-searching"
         >
-          <UIcon name="i-lucide-loader" class="h-3.5 w-3.5 animate-spin" />
+          <UIcon name="i-lucide-loader" class="h-3.5 w-3.5 motion-safe:animate-spin" />
           {{ t('tutorial.overlay.searching') }}
         </p>
         <p
@@ -295,7 +551,7 @@ onUnmounted(() => {
               size="xs"
               color="primary"
               data-testid="tutorial-next"
-              @click="advance()"
+              @click="advance('nav-control')"
             >
               {{ isLast ? t('tutorial.overlay.done') : t('tutorial.overlay.next') }}
             </UButton>

package/app/components/tutorial/TutorialPrompt.vue

@@ -1,22 +1,32 @@
 <script setup lang="ts">
-// The tutorial launch prompt: asks once on first launch whether the user wants a guided
-// tour, and doubles as the tour picker for later visits (command palette: "Take a tour").
-// Lists whatever the merged `tutorialTours` slot offers this user (first-party + consumer
-// tours, RBAC-gated per tour), so it grows with the catalog rather than hard-coding tours.
+// The tutorial launch prompt: asks once on first launch whether the user wants a guided tour,
+// listing the tours this board can actually run right now (first-party + consumer, resolved
+// against the same gates the nav uses), so it grows with the catalog rather than hard-coding
+// tours.
+//
+// It is the OFFER, not the library: the full list — including the walkthroughs this board
+// can't run yet and what would unlock them — is `TutorialCatalogue.vue`, one button away in
+// the footer and permanently reachable from the sidebar's Help section. That split is why
+// this stays a short, answerable question instead of growing into a browsing surface.
 //
 // The decision semantics live in the store: starting a tour or "No thanks" is SAVED (the
 // prompt never auto-opens again), while closing without answering defers to next launch.
+import { TUTORIAL_ACTION_KEYS } from '~/utils/tutorial'
+
 const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
+// Start / Resume / Repeat is decided in one place for both surfaces — see `useTutorialLaunch`.
+const { actionFor, launch } = useTutorialLaunch()
 
 const open = computed({
   get: () => tutorial.promptOpen,
   set: (v: boolean) => (v ? tutorial.openPrompt() : tutorial.closePrompt()),
 })
 
-// Only an unanswered prompt offers the persistent "No thanks"; once a decision exists this
-// is just a picker, and the only dismissal left is a plain close.
+// Only an unanswered prompt offers the persistent "No thanks": there is a decision to save.
+// Once one exists — this window can still be opened by the store — the only dismissal left is
+// a plain close, since declining something already answered would write nothing new.
 const undecided = computed(() => tutorial.decision === null)
 </script>
 
@@ -49,7 +59,7 @@ const undecided = computed(() => tutorial.decision === null)
                   size="sm"
                   data-testid="tutorial-tour-completed"
                 >
-                  {{ t('tutorial.prompt.completed') }}
+                  {{ t('tutorial.status.completed') }}
                 </UBadge>
               </div>
               <p class="text-xs text-slate-400">{{ t(tour.descriptionKey) }}</p>
@@ -57,15 +67,11 @@ const undecided = computed(() => tutorial.decision === null)
             <UButton
               size="sm"
               color="primary"
-              :variant="tutorial.isCompleted(tour.id) ? 'soft' : 'solid'"
+              :variant="actionFor(tour.id) === 'restart' ? 'soft' : 'solid'"
               :data-testid="`tutorial-start-${tour.id}`"
-              @click="tutorial.startTour(tour.id)"
+              @click="launch(tour.id)"
             >
-              {{
-                tutorial.isCompleted(tour.id)
-                  ? t('tutorial.prompt.restart')
-                  : t('tutorial.prompt.start')
-              }}
+              {{ t(TUTORIAL_ACTION_KEYS[actionFor(tour.id)]) }}
             </UButton>
           </li>
         </ul>
@@ -88,14 +94,27 @@ const undecided = computed(() => tutorial.decision === null)
           {{ t('tutorial.prompt.decline') }}
         </UButton>
         <span v-else />
-        <UButton
-          color="neutral"
-          variant="soft"
-          data-testid="tutorial-close"
-          @click="tutorial.closePrompt()"
-        >
-          {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
-        </UButton>
+        <div class="flex items-center gap-2">
+          <!-- The way to the tours this board can't run yet, and to the ones already taken.
+               Browsing answers nothing, so it neither declines the offer nor accepts it. -->
+          <UButton
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-graduation-cap"
+            data-testid="tutorial-browse"
+            @click="tutorial.openCatalogue()"
+          >
+            {{ t('tutorial.prompt.browse') }}
+          </UButton>
+          <UButton
+            color="neutral"
+            variant="soft"
+            data-testid="tutorial-close"
+            @click="tutorial.closePrompt()"
+          >
+            {{ undecided ? t('tutorial.prompt.later') : t('common.close') }}
+          </UButton>
+        </div>
       </div>
     </template>
   </UModal>

package/app/composables/useNavContributions.ts

@@ -59,7 +59,10 @@ export function useNavContributions() {
     operatorDashboard: () => ui.openOperatorDashboard(),
     reports: () => ui.openReports(),
     shortcuts: () => ui.openShortcutsHelp(),
-    tutorial: () => useTutorialStore().openPrompt(),
+    // The CATALOGUE, not the launch prompt: reaching this from the sidebar or the palette is
+    // "show me the walkthroughs", and the prompt answers a narrower question (would you like
+    // one now?) that a returning user has already answered once.
+    tutorial: () => useTutorialStore().openCatalogue(),
     // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
     // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
     toggleUiMode: () => useUiModeStore().toggleMode(),

package/app/composables/useTutorialLaunch.ts

@@ -0,0 +1,50 @@
+import { launchActionFor, tourState } from '~/utils/tutorial'
+import type { TutorialLaunchAction, TutorialTourState } from '~/utils/tutorial'
+
+/**
+ * Starting a tour, from whichever surface offers it.
+ *
+ * Both the launch prompt and the catalogue answer the same question per tour — start it,
+ * resume where it was broken off, take it again, or step back into the one already running —
+ * and getting that precedence subtly different between the two surfaces would show up as the
+ * same button doing different things on two screens. So the decision is made once here, over
+ * the pure {@link tourState} / {@link launchActionFor} pair, and each surface renders it.
+ */
+export function useTutorialLaunch() {
+  const tutorial = useTutorialStore()
+
+  /** Where this tour stands for this user right now. */
+  function stateOf(tourId: string): TutorialTourState {
+    return tourState({
+      active: tutorial.activeTourId === tourId,
+      resumable: tutorial.interruptedAt(tourId) !== null,
+      completed: tutorial.isCompleted(tourId),
+    })
+  }
+
+  /** What this tour's button will do — also what labels it. */
+  function actionFor(tourId: string): TutorialLaunchAction {
+    return launchActionFor(stateOf(tourId))
+  }
+
+  /**
+   * Act on that. `continue` only steps out of the way: the overlay for that tour is already
+   * on screen, so restarting it from step one — which is what a plain `startTour` would do —
+   * would throw away the position of the walkthrough the user was pointing at.
+   */
+  function launch(tourId: string): void {
+    switch (actionFor(tourId)) {
+      case 'continue':
+        tutorial.closeCatalogue()
+        tutorial.closePrompt()
+        return
+      case 'resume':
+        tutorial.resumeTour(tourId)
+        return
+      default:
+        tutorial.startTour(tourId)
+    }
+  }
+
+  return { stateOf, actionFor, launch }
+}