@cat-factory/app 0.201.1 → 0.204.0

package/app/components/pipeline/PipelineBuilder.vue

@@ -7,6 +7,7 @@ import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 import AgentPromptEditor from '~/components/pipeline/AgentPromptEditor.vue'
 import EstimateThresholdFields from '~/components/pipeline/EstimateThresholdFields.vue'
 import OutputBudgetInput from '~/components/pipeline/OutputBudgetInput.vue'
+import BinaryOutputStepPicker from '~/components/pipeline/BinaryOutputStepPicker.vue'
 import { ESTIMATE_AXES, ESTIMATE_AXIS_FIELD, type EstimateAxis } from '~/utils/estimateGating'
 import { showOverrideField } from '~/utils/uiMode'
 import {
@@ -202,6 +203,36 @@ const stepsDisallowedByPurpose = computed(() =>
   }),
 )
 
+// The workspace's foundational-services catalog, for the binary-output storage/context picker.
+const foundational = useFoundationalServicesStore()
+
+/**
+ * Whether this step's kind is a BINARY-OUTPUT generator, and therefore needs the storage +
+ * context picker. Read off the kind's projected `binaryOutput` flag rather than a kind-id list,
+ * so a deployment's generator opts in by carrying the trait exactly as the engine's own checks
+ * key on it.
+ *
+ * Deliberately NOT behind `showOverrideField` / `isAdvanced` the way the variant picker is: a
+ * variant OVERRIDES what the kind ships, while this selection is REQUIRED. A basic-mode user
+ * who cannot see it has a step that cannot be saved and no way to find out why.
+ */
+function showBinaryOutputPicker(kind: AgentKind): boolean {
+  return agentKindMeta(kind).binaryOutput === true
+}
+
+// An enabled generator step with no storage selection — mirrors the backend save/start
+// rejection (`assertValidBinaryOutputSteps`), surfaced as an inline hint so the user fixes it
+// before the round trip. Same disposition as `skillStepNeedsPick`, for the same reason: both
+// are a step parametrized by a selection it cannot run without.
+const binaryOutputStepNeedsPick = computed(() =>
+  pipelines.draft.some(
+    (kind, i) =>
+      showBinaryOutputPicker(kind) &&
+      pipelines.draftEnabled[i] !== false &&
+      !pipelines.draftBinaryOutput(i)?.storageServiceId,
+  ),
+)
+
 // A step's picked skill id is no longer in the account catalog (the source dir was renamed or
 // unlinked). The step will fail cleanly at dispatch; flag it so the user re-picks.
 function skillMissing(index: number): boolean {
@@ -226,6 +257,11 @@ watch(open, (isOpen) => {
   // The workspace's per-kind output ceilings, which the per-step field shows as its inherited
   // placeholder and the prompt editor edits. Best-effort on the same terms as the prompt index.
   if (isOpen) agentSettings.load().catch(() => {})
+  // The resolved foundational-services catalog, which the binary-output picker offers from.
+  // Single-flighted per workspace, so this shares the panel's load rather than adding one. A
+  // failure is not swallowed into an empty picker: the store records `available: false`, and
+  // the picker says the catalog is unreachable rather than "no services exist".
+  if (isOpen) void foundational.ensureProbed()
 })
 
 function add(kind: AgentKind) {
@@ -531,6 +567,15 @@ async function clone(p: Pipeline) {
             {{ t('pipeline.builder.skillNeedsPick') }}
           </p>
 
+          <p
+            v-if="binaryOutputStepNeedsPick"
+            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
+            data-testid="binary-output-needs-pick"
+          >
+            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
+            {{ t('pipeline.builder.binaryOutputNeedsPick') }}
+          </p>
+
           <p
             v-if="stepsDisallowedByPurpose.length"
             class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
@@ -792,6 +837,15 @@ async function clone(p: Pipeline) {
                 />
               </div>
 
+              <!-- Binary-output picker: a generator kind's step is parametrized by the
+                 foundational STORAGE service its artifacts go through (`stepOptions.binaryOutput`)
+                 plus any services consulted for the generation's scope. Required, not an
+                 override — so it shows in both interface tiers. -->
+              <BinaryOutputStepPicker
+                v-if="showBinaryOutputPicker(unit.kind)"
+                :index="unit.index"
+              />
+
               <!-- This step's own output-token ceiling. An OVERRIDE of the workspace's per-kind
                  setting (itself an override of the deployment routing default), so it is
                  advanced-only until a value is pinned; empty inherits. -->

package/app/components/settings/OpenRouterCatalogPanel.vue

@@ -32,10 +32,13 @@ const back = useIntegrationBack(open)
 const RECOMMENDED_SLUGS = [
   'anthropic/claude-fable-5',
   'anthropic/claude-opus-5',
-  'openai/gpt-5.5',
-  'google/gemini-3-pro',
-  'deepseek/deepseek-chat',
+  'openai/gpt-5.6-sol',
+  'openai/gpt-5.6-terra',
+  'google/gemini-3.1-pro-preview',
+  'google/gemini-3.6-flash',
+  'deepseek/deepseek-v4-flash',
   'moonshotai/kimi-k2.7-code',
+  'z-ai/glm-5.2',
 ]
 
 // Whether the workspace/user has an OpenRouter key connected at any reachable scope.

package/app/components/tutorial/TutorialCatalogue.logic.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { buildCatalogueRows, summarizeProgress } from './TutorialCatalogue.logic'
+import type { TutorialCatalogueEntry, TutorialTourState } from '~/utils/tutorial'
+
+const entry = (
+  id: string,
+  availability: TutorialCatalogueEntry['availability'],
+  stepCount = 3,
+): TutorialCatalogueEntry => ({
+  tour: {
+    id,
+    order: 10,
+    titleKey: `tutorial.tours.${id}.title`,
+    descriptionKey: `tutorial.tours.${id}.description`,
+    steps: Array.from({ length: stepCount }, (_, i) => ({
+      id: `s${i}`,
+      titleKey: 't',
+      bodyKey: 'b',
+    })),
+  },
+  availability,
+  unmet:
+    availability === 'blocked'
+      ? [{ id: 'service', labelKey: 'tutorial.requirements.service', met: () => false }]
+      : [],
+})
+
+const states = (map: Record<string, TutorialTourState>) => (id: string) => map[id] ?? 'notStarted'
+
+describe('buildCatalogueRows', () => {
+  it('carries every tour through, ready or not', () => {
+    const rows = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'blocked'), entry('c', 'not-applicable')],
+      states({}),
+    )
+    expect(rows.map((r) => r.tour.id)).toEqual(['a', 'b', 'c'])
+    expect(rows.map((r) => r.startable)).toEqual([true, false, false])
+  })
+
+  it('counts the steps of a runnable tour and withholds a count for the rest', () => {
+    // A blocked tour's resolved script is not what the user gets once they unblock it, and a
+    // number that quietly changes under them is worse than no number.
+    const rows = buildCatalogueRows([entry('a', 'ready', 4), entry('b', 'blocked', 4)], states({}))
+    expect(rows[0]?.stepCount).toBe(4)
+    expect(rows[1]?.stepCount).toBeNull()
+  })
+
+  it('labels each row from the user`s own progress', () => {
+    const rows = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'ready'), entry('c', 'ready')],
+      states({ a: 'completed', b: 'paused', c: 'inProgress' }),
+    )
+    expect(rows.map((r) => r.action)).toEqual(['restart', 'resume', 'continue'])
+  })
+
+  it('keeps a blocked tour`s unmet requirements for the reason list', () => {
+    const [row] = buildCatalogueRows([entry('a', 'blocked')], states({}))
+    expect(row?.unmet.map((r) => r.id)).toEqual(['service'])
+  })
+})
+
+describe('summarizeProgress', () => {
+  /** The launch offer is still unanswered, so only the rows can make anything resettable. */
+  const unanswered = { launchOfferAnswered: false }
+  const rows = (map: Record<string, TutorialTourState>, ids: string[]) =>
+    buildCatalogueRows(
+      ids.map((id) => entry(id, 'ready')),
+      states(map),
+    )
+
+  it('counts completions against the WHOLE catalog, not the runnable part', () => {
+    // Counting only what this board can offer today would move the denominator every time a
+    // repo was linked or a run finished — and "2 of 2" on a board with four walkthroughs
+    // still waiting reads as a finished tutorial, which is what this surface disproves.
+    const all = buildCatalogueRows(
+      [entry('a', 'ready'), entry('b', 'blocked'), entry('c', 'not-applicable')],
+      states({ a: 'completed' }),
+    )
+    expect(summarizeProgress(all, unanswered)).toMatchObject({ completed: 1, total: 3 })
+  })
+
+  it('offers a reset for a paused tour, not only for completed ones', () => {
+    expect(summarizeProgress(rows({}, ['a', 'b']), unanswered).resettable).toBe(false)
+    expect(summarizeProgress(rows({ a: 'paused' }, ['a', 'b']), unanswered).resettable).toBe(true)
+    expect(summarizeProgress(rows({ a: 'completed' }, ['a', 'b']), unanswered).resettable).toBe(
+      true,
+    )
+  })
+
+  it('offers a reset to a user who only ever answered the launch offer', () => {
+    // The case keying Reset off the rows alone got wrong, and the one that matters most: someone
+    // who clicked "No thanks" and took no tour has nothing completed and nothing paused, yet the
+    // saved answer is exactly what stops the prompt returning. Hiding the control left them no
+    // route back to the first-launch experience Reset promises.
+    expect(summarizeProgress(rows({}, ['a', 'b']), { launchOfferAnswered: true }).resettable).toBe(
+      true,
+    )
+  })
+
+  it('offers no reset on a genuinely untouched install', () => {
+    expect(summarizeProgress([], unanswered).resettable).toBe(false)
+  })
+})

package/app/components/tutorial/TutorialCatalogue.logic.ts

@@ -0,0 +1,102 @@
+import { launchActionFor } from '~/utils/tutorial'
+import type {
+  TutorialAvailability,
+  TutorialCatalogueEntry,
+  TutorialLaunchAction,
+  TutorialRequirement,
+  TutorialTour,
+  TutorialTourState,
+} from '~/utils/tutorial'
+
+/**
+ * What the catalogue renders per tour, and the progress line above the list.
+ *
+ * Extracted from `TutorialCatalogue.vue` for the same reason the overlay's decisions are
+ * (`TutorialOverlay.logic.ts`): the vitest setup has no SFC transform, so anything that
+ * DECIDES has to live outside the component to be tested. Here that is the whole of what the
+ * surface claims — which tours can be started, which are held back and by what, and how much
+ * of the catalog this user has been through.
+ */
+
+/** One rendered row: an entry, plus everything derived from it and the user's progress. */
+export interface TutorialCatalogueRow {
+  tour: TutorialTour
+  availability: TutorialAvailability
+  /** What is standing in the way, when {@link availability} is `blocked`. */
+  unmet: readonly TutorialRequirement[]
+  state: TutorialTourState
+  action: TutorialLaunchAction
+  /**
+   * How many steps a start would walk this board through — the RESOLVED count, not the
+   * declared one, since branch steps that don't apply here are already gone.
+   *
+   * Null for a tour that cannot run: its resolved script is not what the user would get once
+   * the missing requirement is met, and a number that quietly changes when they unblock it is
+   * worse than no number.
+   */
+  stepCount: number | null
+  /** Whether the row's button does anything (a blocked tour's is inert, not hidden). */
+  startable: boolean
+}
+
+/** The list, in catalog order — the entries arrive sorted by `resolveTourCatalogue`. */
+export function buildCatalogueRows(
+  entries: readonly TutorialCatalogueEntry[],
+  stateOf: (tourId: string) => TutorialTourState,
+): TutorialCatalogueRow[] {
+  return entries.map((entry) => {
+    const ready = entry.availability === 'ready'
+    const state = stateOf(entry.tour.id)
+    return {
+      tour: entry.tour,
+      availability: entry.availability,
+      unmet: entry.unmet,
+      state,
+      action: launchActionFor(state),
+      stepCount: ready ? entry.tour.steps.length : null,
+      startable: ready,
+    }
+  })
+}
+
+/** The headline count. */
+export interface TutorialProgressSummary {
+  completed: number
+  /** Every tour this deployment ships, available or not — the honest denominator. */
+  total: number
+  /**
+   * Whether there is anything for Reset to clear — which is everything `resetProgress` writes,
+   * not only what this list shows. See {@link summarizeProgress}.
+   */
+  resettable: boolean
+}
+
+/**
+ * Progress across the WHOLE catalog, not just the runnable part.
+ *
+ * Counting only what this board can offer today would move the denominator under the user
+ * every time they linked a repo or finished a run — "2 of 2 completed" on a board with four
+ * more walkthroughs waiting behind requirements reads as a finished tutorial, which is the
+ * one thing this surface exists to disprove.
+ *
+ * `launchOfferAnswered` is the store's `decision`, and it is here rather than derived from the
+ * rows because `resetProgress` clears it too — Reset restores the FIRST-LAUNCH experience, and
+ * the saved answer to "would you like a tour?" is most of that. Keying the control on the rows
+ * alone hid it from the one user who most needs it: someone who clicked "No thanks" and took no
+ * tour has nothing completed and nothing paused, so the only route back to the offer was the
+ * control that was not being drawn.
+ */
+export function summarizeProgress(
+  rows: readonly TutorialCatalogueRow[],
+  input: { launchOfferAnswered: boolean },
+): TutorialProgressSummary {
+  const completed = rows.filter((row) => row.state === 'completed').length
+  return {
+    completed,
+    total: rows.length,
+    // A paused tour is progress too: clearing it is exactly what someone handing this to a
+    // colleague wants, and offering Reset only for completions would leave it behind.
+    resettable:
+      completed > 0 || rows.some((row) => row.state === 'paused') || input.launchOfferAnswered,
+  }
+}

package/app/components/tutorial/TutorialCatalogue.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+// The tutorial catalogue: every guided walkthrough this deployment ships, startable (or
+// re-startable) at any time from the sidebar's Help section and the command palette.
+//
+// It is deliberately NOT the launch prompt with a second entry point. The prompt asks a
+// question once, offers what this board can run, and goes away; this answers "what else is
+// there, and why can't I take that one yet?" — so it lists the tours that are HELD BACK too,
+// each with the requirement still missing. Omitting them (which is all a slot filter could do)
+// makes a deployment shipping six walkthroughs look like one shipping two.
+//
+// Everything that decides lives in `TutorialCatalogue.logic.ts` (rows, progress) and
+// `utils/tutorial.ts` (availability, state, action), so the SFC only renders.
+import { buildCatalogueRows, summarizeProgress } from './TutorialCatalogue.logic'
+import type { TutorialCatalogueRow } from './TutorialCatalogue.logic'
+import { TUTORIAL_ACTION_KEYS, TUTORIAL_STATUS_KEYS } from '~/utils/tutorial'
+
+const { t } = useI18n()
+const tutorial = useTutorialStore()
+const { catalogue } = useTutorialTours()
+const { stateOf, launch } = useTutorialLaunch()
+
+const open = computed({
+  get: () => tutorial.catalogueOpen,
+  set: (v: boolean) => (v ? tutorial.openCatalogue() : tutorial.closeCatalogue()),
+})
+
+const rows = computed(() => buildCatalogueRows(catalogue.value, stateOf))
+const progress = computed(() =>
+  summarizeProgress(rows.value, { launchOfferAnswered: tutorial.decision !== null }),
+)
+
+/** A badge only where there is something to say: "not started" is the unremarkable default. */
+const showsStatus = (row: TutorialCatalogueRow) => row.state !== 'notStarted'
+
+const statusColor = (row: TutorialCatalogueRow) =>
+  row.state === 'completed' ? 'success' : row.state === 'inProgress' ? 'primary' : 'neutral'
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="t('tutorial.catalogue.title')"
+    :description="t('tutorial.catalogue.intro')"
+    :ui="{ content: 'max-w-2xl' }"
+  >
+    <template #body>
+      <div class="space-y-4" data-testid="tutorial-catalogue">
+        <p v-if="rows.length > 0" class="text-xs text-slate-400" data-testid="tutorial-progress">
+          {{
+            t('tutorial.catalogue.progress', {
+              completed: progress.completed,
+              total: progress.total,
+            })
+          }}
+        </p>
+        <ul class="space-y-2">
+          <li
+            v-for="row in rows"
+            :key="row.tour.id"
+            class="flex items-start gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            :class="row.startable ? '' : 'opacity-75'"
+            :data-testid="`tutorial-catalogue-entry-${row.tour.id}`"
+          >
+            <UIcon
+              :name="row.tour.icon ?? 'i-lucide-compass'"
+              class="mt-0.5 h-5 w-5 shrink-0 text-primary-400"
+            />
+            <div class="min-w-0 flex-1 space-y-1">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="text-sm font-medium text-slate-100">{{ t(row.tour.titleKey) }}</span>
+                <UBadge
+                  v-if="showsStatus(row)"
+                  :color="statusColor(row)"
+                  variant="subtle"
+                  size="sm"
+                  :data-testid="`tutorial-catalogue-status-${row.tour.id}`"
+                >
+                  {{ t(TUTORIAL_STATUS_KEYS[row.state]) }}
+                </UBadge>
+              </div>
+              <p class="text-xs text-slate-400">{{ t(row.tour.descriptionKey) }}</p>
+              <p v-if="row.stepCount !== null" class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.steps', { count: row.stepCount }, row.stepCount) }}
+              </p>
+              <!-- A held-back tour says what would unlock it, rather than vanishing from the
+                   list: these are things the reader can go and do. -->
+              <div
+                v-else-if="row.availability === 'blocked'"
+                class="text-xs text-slate-500"
+                :data-testid="`tutorial-catalogue-requirements-${row.tour.id}`"
+              >
+                <span>{{ t('tutorial.catalogue.blocked') }}</span>
+                <ul class="mt-1 space-y-0.5">
+                  <li v-for="req in row.unmet" :key="req.id" class="flex items-center gap-1.5">
+                    <UIcon name="i-lucide-lock" class="h-3 w-3 shrink-0" />
+                    <span>{{ t(req.labelKey) }}</span>
+                  </li>
+                </ul>
+              </div>
+              <!-- Requirements met, but every step is about a branch this board isn't on:
+                   nothing to go and fix, so it must not read like the case above. -->
+              <p v-else class="text-xs text-slate-500">
+                {{ t('tutorial.catalogue.notApplicable') }}
+              </p>
+            </div>
+            <UButton
+              size="sm"
+              color="primary"
+              :variant="row.state === 'completed' ? 'soft' : 'solid'"
+              :disabled="!row.startable"
+              :data-testid="`tutorial-catalogue-start-${row.tour.id}`"
+              @click="launch(row.tour.id)"
+            >
+              {{ t(TUTORIAL_ACTION_KEYS[row.action]) }}
+            </UButton>
+          </li>
+        </ul>
+        <!-- No tours at all is a real state (a deployment may register none of its own and
+             strip the built-ins), and it is not the same as one whose tours are all blocked. -->
+        <p v-if="rows.length === 0" class="text-sm text-slate-400">
+          {{ t('tutorial.catalogue.empty') }}
+        </p>
+      </div>
+    </template>
+    <template #footer>
+      <div class="flex w-full items-center justify-between gap-2">
+        <UButton
+          v-if="progress.resettable"
+          color="neutral"
+          variant="ghost"
+          icon="i-lucide-rotate-ccw"
+          :title="t('tutorial.catalogue.resetHint')"
+          data-testid="tutorial-catalogue-reset"
+          @click="tutorial.resetProgress()"
+        >
+          {{ t('tutorial.catalogue.reset') }}
+        </UButton>
+        <span v-else />
+        <UButton
+          color="neutral"
+          variant="soft"
+          data-testid="tutorial-catalogue-close"
+          @click="tutorial.closeCatalogue()"
+        >
+          {{ t('common.close') }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/tutorial/TutorialOverlay.logic.spec.ts

@@ -1,8 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import {
+  boardNodeIdFor,
   isSafeTargetId,
   isTargetClickAdvance,
   resolveSkip,
+  shouldFocusCard,
   stepTargetIds,
   stepTargetSelectors,
   unexpectedlySkippedSteps,
@@ -162,3 +164,47 @@ describe('unexpectedlySkippedSteps', () => {
     expect(unexpectedlySkippedSteps(new Set(), [plain, branch])).toEqual([])
   })
 })
+
+describe('boardNodeIdFor', () => {
+  /** A stand-in for the DOM ancestry lookup: `closest` hits when the selector is the one
+   * Vue Flow wraps its nodes in, and the hit carries whatever `data-id` we hand it. */
+  const el = (nodeId: string | null) => ({
+    closest: (selector: string) =>
+      selector === '.vue-flow__node' && nodeId !== null
+        ? { getAttribute: (name: string) => (name === 'data-id' ? nodeId : null) }
+        : null,
+  })
+
+  it('reports the node id for an anchor on the board canvas', () => {
+    expect(boardNodeIdFor(el('block-42'))).toBe('block-42')
+  })
+
+  it('reports none for an anchor outside the canvas, so the caller scrolls it instead', () => {
+    // A panel row, a modal button, the sidebar: an ordinary scroll container, where a camera
+    // move would do nothing and `scrollIntoView` is the right mechanism.
+    expect(boardNodeIdFor(el(null))).toBeNull()
+    expect(boardNodeIdFor(null)).toBeNull()
+  })
+
+  it('treats an empty data-id as absent', () => {
+    // `fitView` over an unknown id silently does nothing, which would look exactly like a
+    // reveal that ran — and the step would sit pointing off screen with its budget ticking.
+    expect(boardNodeIdFor(el(''))).toBeNull()
+  })
+})
+
+describe('shouldFocusCard', () => {
+  it('takes focus when the tour starts and when the user drives it', () => {
+    // The overlay is teleported to the end of `body`, so without this a keyboard user has to
+    // tab the whole page to reach Next.
+    expect(shouldFocusCard('tour-start')).toBe(true)
+    expect(shouldFocusCard('nav-control')).toBe(true)
+  })
+
+  it('leaves focus alone when the step advanced because the user clicked the real control', () => {
+    // Such a click routinely opens a modal that autofocuses its own first field, and the next
+    // step is typically the one telling the user to type in it. Pulling focus back onto the
+    // coach mark puts their caret on a tooltip instead of the form the tour just pointed at.
+    expect(shouldFocusCard('target-click')).toBe(false)
+  })
+})

package/app/components/tutorial/TutorialOverlay.logic.ts

@@ -19,6 +19,33 @@ export type TutorialDirection = 'forward' | 'back'
 /** What the overlay does with a step whose anchor never appeared. */
 export type SkipOutcome = { kind: 'move'; index: number } | { kind: 'complete' }
 
+/**
+ * Why the step cursor moved. The overlay's only reason for tracking this is the focus
+ * decision below, which is why it is a CAUSE rather than a boolean the call sites pass: the
+ * question "who moved the cursor" has an obvious answer at every call site, where "should
+ * this one steal focus" has to be re-derived — and getting it wrong is silent.
+ */
+export type TutorialAdvanceCause = 'tour-start' | 'nav-control' | 'target-click'
+
+/**
+ * Does the coach mark take focus now that the cursor has moved?
+ *
+ * Yes for the tour's own controls: the overlay is teleported to the end of `body`, so without
+ * this a keyboard user has to tab the whole page to reach Next.
+ *
+ * No for a `target-click` advance, and that is the whole reason this is a function. Such a
+ * step advances because the user operated a REAL control, which routinely opens a modal that
+ * rightly autofocuses its own first field — and the next step is typically the one telling
+ * them to type in it. Pulling focus back onto our card leaves the caret on a tooltip instead
+ * of the form, so the tour breaks the very interaction it just asked for.
+ *
+ * Not a focus trap either way: half the catalog asks the user to operate the control behind
+ * the card, which a trap would put out of reach.
+ */
+export function shouldFocusCard(cause: TutorialAdvanceCause): boolean {
+  return cause !== 'target-click'
+}
+
 /**
  * What a `data-testid` may look like. Every one of the ~470 test ids in this layer is
  * lowercase kebab-case, and the e2e suite's convention keeps it that way, so this rejects
@@ -71,6 +98,32 @@ export function resolveSkip(
   return index + 1 < total ? { kind: 'move', index: index + 1 } : { kind: 'complete' }
 }
 
+/**
+ * Vue Flow's per-node wrapper, which carries the node id in `data-id`. The board is a
+ * TRANSFORM-panned canvas rather than a scroll container, so an anchor inside one of these is
+ * revealed by moving the camera (`fitView({ nodes })`), where every other anchor is revealed
+ * by `scrollIntoView`. Asking the DOM which of the two an element is beats keying off the
+ * step's target id, since the same id (`task-card`) is a canvas node on the board and a plain
+ * list row in a panel.
+ */
+export const BOARD_NODE_SELECTOR = '.vue-flow__node'
+
+/** The part of an element the reveal path needs: ancestry, and that ancestor's node id. */
+interface RevealNode {
+  closest(selector: string): { getAttribute(name: string): string | null } | null
+}
+
+/**
+ * The board-canvas node id owning this element, or null when the element is not on the canvas
+ * (so the caller scrolls it into view instead). An empty `data-id` counts as absent: Vue Flow
+ * would match nothing, and a `fitView` over an unknown id silently does nothing at all — which
+ * would look exactly like a reveal that ran.
+ */
+export function boardNodeIdFor(el: RevealNode | null): string | null {
+  const id = el?.closest(BOARD_NODE_SELECTOR)?.getAttribute('data-id') ?? null
+  return id !== null && id.length > 0 ? id : null
+}
+
 /** The part of a clicked node this check needs: CSS-selector ancestry. */
 interface ClickedNode {
   closest(selector: string): unknown