@cat-factory/app 0.241.3 → 0.242.1

package/README.md

@@ -58,6 +58,16 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+### The board's top overlay region has ONE owner
+
+**A surface that appears at the top of the board renders as a member of `BoardTopOverlays`, and places nothing itself.** No `absolute`/`fixed`, no `top-*`, no z-index of its own: the band is a flex column, and it owns placement and stacking for everything in it. A member contributes only its card plus `pointer-events-auto` (the column is click-through, so its empty strip never intercepts clicks on the board underneath).
+
+The reason this is a rule is that the alternative failed exactly once per surface. Each of the toolbar, the spend/connection/PAT banners and the four advisory banners used to anchor itself at `top-0` with its own z-index, so which one you could see came down to who picked the higher number: a standing advisory covered the zoom and fit controls outright, and the board-basics tour then ringed a control nobody could see. Tuning an offset onto one of them (`top-16`, sized against the toolbar pill) fixes the pair that was noticed and leaves the rest, and it goes stale the first time the pill wraps or grows a scrollbar. In one column the overlap is not tuned, it is unrepresentable, and a toolbar that grows pushes the banners down by exactly what it grew.
+
+Order within the column is by what the user loses by not reading it now; the toolbar stays first so a tour anchor and the everyday zoom controls do not move as advisories come and go. Full-width page chrome (the translation-warning strip) is a different surface: it sits in NORMAL FLOW at the top of the shell, so it takes its own height rather than covering the row beneath it.
+
+`app/components/layout/BoardTopOverlays.spec.ts` enforces the no-self-placement half, reading the member list from the component's own imports.
+
 ### A store must be instantiable outside a component `setup`
 
 A Pinia setup store runs its body on the FIRST `useStore()` anywhere in the app, and that

package/app/components/layout/BoardToolbar.vue

@@ -134,8 +134,11 @@ const decisionItems = computed(() =>
 </script>
 
 <template>
+  <!-- Positioning and stacking are owned by `BoardTopOverlays`, the one component that lays out
+       the board's top overlay region; this renders only the pill and re-enables pointer events
+       on it. Self-anchoring here is what let a banner cover the toolbar outright. -->
   <div
-    class="absolute left-1/2 top-3 z-20 flex max-w-[calc(100vw-1rem)] -translate-x-1/2 items-center gap-1 overflow-x-auto rounded-full border border-slate-700 bg-slate-900/90 px-2 py-1.5 shadow-xl backdrop-blur"
+    class="pointer-events-auto flex max-w-full items-center gap-1 overflow-x-auto rounded-full border border-slate-700 bg-slate-900/90 px-2 py-1.5 shadow-xl backdrop-blur"
   >
     <!-- zoom controls -->
     <IconButton

package/app/components/layout/BoardTopOverlays.spec.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * `BoardTopOverlays` is the single owner of the board's top overlay region, and that only
+ * holds while its members render as members: a card in a flex column, with no placement of
+ * its own.
+ *
+ * The reason this is a test and not a note in the component is that the failure is SILENT and
+ * only visible on a deployment in the state the banner reports. A member that re-anchors
+ * itself (`absolute top-0`, a z-index of its own) leaves the column and lands back on top of
+ * whatever picked a lower number, which is how a standing advisory came to cover the zoom/fit
+ * controls outright, and the board-basics tour to ring a control nobody could see. Nothing
+ * else catches it: the layout still renders, no type is wrong, and the unit suite mounts no
+ * components.
+ *
+ * The member list is READ FROM THE COMPONENT rather than restated here, so a banner added to
+ * the column is covered by the same commit that adds it, and one removed from the column
+ * stops being checked instead of failing as a phantom.
+ */
+
+const layoutDir = dirname(fileURLToPath(import.meta.url))
+const band = readFileSync(join(layoutDir, 'BoardTopOverlays.vue'), 'utf8')
+
+/** The components the band lays out, from its own imports. */
+function bandMembers(): string[] {
+  return [...band.matchAll(/^import (\w+) from '~\/components\/layout\/(\w+)\.vue'$/gm)].map(
+    (m) => m[2] as string,
+  )
+}
+
+/** Every class token the file applies, from its static `class="…"` attributes. */
+function classTokens(source: string): string[] {
+  return [...source.matchAll(/\bclass="([^"]*)"/g)].flatMap((m) => (m[1] as string).split(/\s+/))
+}
+
+/**
+ * A token that takes a member out of the column's flow. Responsive and state variants count
+ * (`sm:absolute`, `lg:top-0`): the overlap they cause is no less real for being conditional.
+ */
+function selfPlacing(token: string): boolean {
+  const base = token.includes(':') ? (token.split(':').pop() as string) : token
+  return (
+    base === 'fixed' ||
+    base === 'absolute' ||
+    base === 'sticky' ||
+    /^-?(top|bottom|inset)-/.test(base) ||
+    base === 'inset-0' ||
+    base.startsWith('z-')
+  )
+}
+
+describe('BoardTopOverlays members', () => {
+  const members = bandMembers()
+
+  it('lays out every top-region surface, so none of them is left placing itself', () => {
+    // A relation over the source, not a count: the column's job is to be the ONLY placement
+    // authority in this region, and a pinned number would fail on every ordinary addition
+    // while saying nothing about what broke.
+    expect(members.length).toBeGreaterThan(0)
+    expect(new Set(members).size).toBe(members.length)
+  })
+
+  it.each(bandMembers())('%s places nothing itself', (member) => {
+    const offenders = classTokens(readFileSync(join(layoutDir, `${member}.vue`), 'utf8')).filter(
+      selfPlacing,
+    )
+    expect(offenders).toEqual([])
+  })
+})

package/app/components/layout/BoardTopOverlays.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import BoardToolbar from '~/components/layout/BoardToolbar.vue'
+import ConnectionStatusBanner from '~/components/layout/ConnectionStatusBanner.vue'
+import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
+import GitHubPatBanner from '~/components/layout/GitHubPatBanner.vue'
+import AiProvidersBanner from '~/components/layout/AiProvidersBanner.vue'
+import ProviderConfigBanner from '~/components/layout/ProviderConfigBanner.vue'
+import InfraSetupBanner from '~/components/layout/InfraSetupBanner.vue'
+import DefaultTestEnvBanner from '~/components/layout/DefaultTestEnvBanner.vue'
+
+// The single owner of the board's top overlay region: the toolbar pill, the corner nav
+// trigger, and every advisory banner, laid out in ONE flex column.
+//
+// The column is the point. Each of these used to anchor itself (`absolute top-0`, its own
+// z-index), which makes overlap a matter of who picked the higher number: the four advisory
+// banners already deferred to a shared column, but the toolbar, the spend/connection/PAT
+// banners and the nav trigger each positioned themselves. A standing advisory therefore
+// covered the zoom/fit controls outright, for everyone, and the board-basics tour rang a
+// control nobody could see. Stacking them in flow makes that overlap structurally impossible
+// of merely tuned: no offset constant to keep in step with the pill's height, and a toolbar
+// that grows (a wrapped row, a scrollbar on a narrow viewport) pushes the column down by
+// exactly what it grew.
+//
+// The column is `pointer-events-none` so its empty strip never intercepts clicks on the board
+// underneath; each member re-enables pointer events on its own card.
+//
+// The nav trigger sits INSIDE this region rather than beside it. It has to: this column owns
+// the region's z-index, so an outside sibling could only be ordered against the whole column,
+// where what is actually needed is for the trigger to stay above the toolbar pill (whose
+// max-width reaches the corner on the narrowest viewports) and below a banner that has
+// something urgent to say. Both are local orderings, and they only exist here.
+
+// The live-stream state the connection strip renders. Passed down rather than resolved here:
+// the page owns the single stream instance, and creating another would open a second socket.
+defineProps<{
+  connected: boolean
+  everConnected: boolean
+  connectionFailed: boolean
+}>()
+
+const ui = useUiStore()
+</script>
+
+<template>
+  <div
+    class="pointer-events-none absolute inset-x-0 top-0 z-40 flex flex-col items-center gap-2 px-4 pt-3"
+  >
+    <!-- Compact-viewport nav trigger: the SideBar is an off-canvas drawer below lg, so surface
+         a hamburger to open it. Out of the column's flow (it is a corner control, not a
+         centered one) and above the toolbar pill it can overlap there. -->
+    <UButton
+      class="pointer-events-auto absolute start-3 top-3 z-10 lg:hidden"
+      icon="i-lucide-menu"
+      color="neutral"
+      variant="soft"
+      size="sm"
+      :aria-label="ui.mobileNavOpen ? $t('nav.closeMenu') : $t('nav.openMenu')"
+      data-testid="mobile-nav-toggle"
+      @click="ui.toggleMobileNav()"
+    />
+
+    <!-- FIRST, and deliberately so: the toolbar is standing board chrome, and a tour step
+         anchors it. Below the advisories it would move every time one appears or clears. -->
+    <BoardToolbar />
+
+    <!-- Then the advisories, most urgent first. Ordering is by what the user loses by not
+         reading it now, not by how loud the card is.
+         - Connection status: what is on screen right now may already be stale.
+         - Spend exceeded: runs are blocked until the budget moves.
+         - GitHub PAT (local mode): every repo-operating step will fail.
+         - AI readiness: no usable model source, or the default preset names unavailable models.
+         - Infrastructure provider: env/runner-pool wired but missing mandatory config.
+         - Infra setup: an executor / test env / storage this deployment needs is undefined, so
+           a class of agents cannot run.
+         - Default test environment: this BOARD has never chosen the provisioning mechanism its
+           new services should default to. Last, because it asks for a convenience default and
+           so yields to the prompts about things that are outright broken. -->
+    <ConnectionStatusBanner
+      :connected="connected"
+      :ever-connected="everConnected"
+      :connection-failed="connectionFailed"
+    />
+    <SpendWarningBanner />
+    <GitHubPatBanner />
+    <AiProvidersBanner />
+    <ProviderConfigBanner />
+    <InfraSetupBanner />
+    <DefaultTestEnvBanner />
+  </div>
+</template>

package/app/components/layout/ConnectionStatusBanner.vue

@@ -59,10 +59,10 @@ onBeforeUnmount(clearTimer)
 
 <template>
   <Transition name="fade">
-    <div
-      v-if="reconnecting || offline"
-      class="pointer-events-none absolute inset-x-0 top-0 z-50 flex justify-center px-4 pt-2"
-    >
+    <!-- Positioning/stacking is owned by `BoardTopOverlays`; this renders only the pill, which
+         re-enables pointer events on itself (the row around it stays click-through, since it is
+         far wider than the pill it centres). -->
+    <div v-if="reconnecting || offline" class="pointer-events-none flex w-full justify-center">
       <div
         v-if="reconnecting"
         class="pointer-events-auto flex items-center gap-2 rounded-full border border-amber-500/60 bg-amber-950/90 px-3 py-1.5 text-xs text-amber-100 shadow-lg backdrop-blur"

package/app/components/layout/GitHubPatBanner.vue

@@ -16,7 +16,9 @@ const show = computed(() => !!setupUrl.value && !dismissed.value)
 
 <template>
   <Transition name="fade">
-    <div v-if="show" class="absolute inset-x-0 top-0 z-50 flex justify-center px-4 pt-4">
+    <!-- Positioning/stacking is owned by `BoardTopOverlays`; this renders only its card and
+         re-enables pointer events on it. -->
+    <div v-if="show" class="pointer-events-auto w-full max-w-3xl">
       <div
         class="w-full max-w-3xl rounded-2xl border-2 border-amber-500/70 bg-amber-950/95 p-5 shadow-2xl backdrop-blur"
         role="alert"

package/app/components/layout/SpendWarningBanner.vue

@@ -32,10 +32,9 @@ async function resume() {
 
 <template>
   <Transition name="fade">
-    <div
-      v-if="exceeded && spend"
-      class="absolute inset-x-0 top-0 z-50 flex justify-center px-4 pt-4"
-    >
+    <!-- Positioning/stacking is owned by `BoardTopOverlays`; this renders only its card and
+         re-enables pointer events on it. -->
+    <div v-if="exceeded && spend" class="pointer-events-auto w-full max-w-3xl">
       <div
         class="w-full max-w-3xl rounded-2xl border-2 border-red-500/70 bg-red-950/95 p-5 shadow-2xl backdrop-blur"
         role="alert"

package/app/components/layout/TranslationWarningBanner.vue

@@ -5,8 +5,10 @@ import { computed } from 'vue'
 // Shown whenever the active locale is NOT English: the non-English catalogs are
 // community/AI-provided and may be inaccurate, so warn the user and point them at the
 // repository to report mistakes or open a fix PR. Rendered as a slim full-width strip at
-// the very top (distinct from the centered config-warning cards below it, so they don't
-// overlap). Dismissal is persisted per-locale in localStorage: once dismissed for a locale
+// the very top of the shell, IN NORMAL FLOW rather than fixed over the page: a strip that
+// takes its own height cannot cover anything, where the fixed one sat over the board's top
+// controls for the whole of every non-English session. Dismissal is persisted per-locale in
+// localStorage: once dismissed for a locale
 // it stays hidden across reloads, but switching to a different (separately-translated)
 // locale shows it again, since that catalog is a fresh, independently-translated context.
 const REPO_URL = 'https://github.com/kibertoad/cat-factory'
@@ -29,7 +31,7 @@ function dismiss() {
       v-if="show"
       data-testid="translation-warning"
       role="alert"
-      class="fixed inset-x-0 top-0 z-50 flex items-center gap-3 border-b border-amber-500/40 bg-amber-950/95 px-4 py-2 text-[13px] text-amber-100 shadow-lg backdrop-blur"
+      class="flex shrink-0 items-center gap-3 border-b border-amber-500/40 bg-amber-950/95 px-4 py-2 text-[13px] text-amber-100 shadow-lg backdrop-blur"
     >
       <UIcon name="i-lucide-languages" class="h-4 w-4 shrink-0 text-amber-400" />
       <p class="min-w-0 flex-1">

package/app/components/outcome/OutcomeSummaryWindow.vue

@@ -12,8 +12,8 @@
 // It composes NOTHING itself: `composeRunOutcome` (`~/utils/runOutcome`) is the pure reduction,
 // so the rules that matter (a regression is an `established` requirement observed to fail; an
 // absent producer never renders as a clean result) are unit-tested without mounting this. What
-// lives here is presentation only, plus the ONE fetch the card owns: the enclosing service's
-// spec, which turns the tester's requirement IDS into the requirement TITLES a reader came for.
+// lives here is presentation only, plus the ONE fetch the card owns: the spec THIS RUN was
+// judged against, which turns the tester's requirement IDS into the TITLES a reader came for.
 import { computed, onUnmounted, ref, watch } from 'vue'
 import type {
   OutcomeCheckKind,
@@ -47,32 +47,43 @@ const { t } = useI18n()
 const blobs = useArtifactBlobs()
 onUnmounted(() => blobs.revokeAll())
 
-// The shared seam contract. The `onOpen` loader fetches the ENCLOSING SERVICE's spec: the
-// requirement verdicts are keyed by the spec's own ids, and without it the coverage section can
-// only show ids (which it then says, rather than letting an id read as a title).
-const { open, blockId, instanceId, close } = useResultView('outcome', {
-  onOpen: (view) => {
-    const block = board.getBlock(view.blockId)
-    const service = block ? board.serviceOf(block) : undefined
-    if (service) void serviceSpec.load(service.id)
-  },
-})
+// The shared seam contract.
+const { open, blockId, instanceId, close } = useResultView('outcome')
 
 const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
-const service = computed(() => (block.value ? board.serviceOf(block.value) : undefined))
-const instance = computed(() => {
+const runId = computed(() => {
   // The run carried by the opener, else the block's own live run: a card opened from a
   // notification names the run, one opened from the board does not.
-  const id = instanceId.value ?? block.value?.executionId ?? null
-  return id ? (execution.getInstance(id) ?? null) : null
+  return instanceId.value ?? block.value?.executionId ?? null
 })
+const instance = computed(() => (runId.value ? (execution.getInstance(runId.value) ?? null) : null))
+
+// The ONE fetch this card owns: the spec THIS RUN was judged against. Requirement verdicts are
+// keyed by the spec's own ids, and without the spec the coverage section can only show ids
+// (which it then says, rather than letting an id read as a title).
+//
+// Keyed by the RUN, not by the enclosing service, and that is a correctness matter rather than a
+// cache detail: the service read comes from the repo's default branch, so for as long as the
+// run's pull request is open it is missing exactly the requirements the run added and the tester
+// just ruled on. Every one of those verdicts joined against nothing and rendered as "not
+// checked", and the card's counts contradicted `GET /api/v1/runs/:runId/outcome` for one run.
+//
+// A watch rather than the `onOpen` hook, because the run id can arrive after the block does (a
+// card open on a task that starts a run) and the join must follow it.
+watch(
+  runId,
+  (id) => {
+    if (id) void serviceSpec.loadForRun(id)
+  },
+  { immediate: true },
+)
 
 const outcome = computed(() =>
   block.value
     ? composeRunOutcome({
         block: block.value,
         instance: instance.value,
-        spec: service.value ? serviceSpec.viewFor(service.value.id) : null,
+        spec: runId.value ? serviceSpec.viewForRun(runId.value) : null,
       })
     : null,
 )
@@ -110,6 +121,7 @@ const REQUIREMENTS_GAP_KEYS: Record<RequirementsGap, string> = {
   no_tester_step: 'outcome.requirements.gap.no_tester_step',
   tester_not_reported: 'outcome.requirements.gap.tester_not_reported',
   no_verdicts: 'outcome.requirements.gap.no_verdicts',
+  no_requirements: 'outcome.requirements.gap.no_requirements',
 }
 const TESTS_GAP_KEYS: Record<TestsGap, string> = {
   run_unavailable: RUN_UNAVAILABLE_KEY,
@@ -128,7 +140,6 @@ const VISUALS_GAP_KEYS: Record<VisualsGap, string> = {
  */
 const SPEC_JOIN_KEYS: Record<Exclude<OutcomeSpecJoin, 'joined'>, string> = {
   not_read: 'outcome.requirements.spec.not_read',
-  unmatched: 'outcome.requirements.spec.unmatched',
 }
 
 const VERDICT_META: Record<RequirementVerdictStatus, { color: string; key: string }> = {
@@ -186,9 +197,11 @@ const headerTitle = computed(() => outcome.value?.title ?? t('outcome.title'))
 const disposition = computed(() => outcome.value?.disposition ?? 'not_run')
 
 /**
- * The note under the requirement counts when the rows carry no spec titles, null when they do.
- * Resolved here so the `joined` exclusion is checked by the compiler once, rather than by a
- * template condition that would silently render nothing if the union grew.
+ * The note under the requirement counts when the section was NOT counted against the service's
+ * `spec/`, null when it was. It is a statement about the DENOMINATOR, not about missing titles:
+ * an unjoined section counts only what the tester chose to rule on and says nothing about what it
+ * skipped. Resolved here so the `joined` exclusion is checked by the compiler once, rather than by
+ * a template condition that would silently render nothing if the union grew.
  */
 const specNote = computed(() => {
   const requirements = outcome.value?.requirements
@@ -198,19 +211,22 @@ const specNote = computed(() => {
   return t(SPEC_JOIN_KEYS[requirements.spec])
 })
 
+/** The requirement rows, in the composer's severity-first order. */
+const requirementRows = computed(() => {
+  const requirements = outcome.value?.requirements
+  return requirements?.status === 'reported' ? requirements.entries : []
+})
+
 /**
- * The requirement rows, each carrying whether its id is standing in for a title it has no way
- * to show. Marked per row ONLY where the section as a whole joined: an id sitting unmarked
- * between two named requirements reads as a requirement someone named after a slug, while a
- * marker on every row of a section the note above already explains is just noise.
+ * How many verdicts the tester returned against ids this service's `spec/` does not carry, or 0.
+ *
+ * Surfaced because the counts above are the SPEC's and this number is the difference between them
+ * and the tester's own tally. Unstated, a reader comparing the two reads the gap as one of the two
+ * being wrong, when it is really a spec that moved on under the tester.
  */
-const requirementRows = computed(() => {
+const unmatchedVerdicts = computed(() => {
   const requirements = outcome.value?.requirements
-  if (!requirements || requirements.status !== 'reported') return []
-  return requirements.entries.map((entry) => ({
-    ...entry,
-    idOnly: requirements.spec === 'joined' && entry.title === null,
-  }))
+  return requirements?.status === 'reported' ? requirements.unmatchedVerdicts : 0
 })
 
 /** The captured views, resolved to blobs as they arrive (the card shows them inline). */
@@ -373,8 +389,8 @@ function openTestReport() {
               }}
             </UBadge>
           </div>
-          <!-- The ids are all there is: say WHICH reason, rather than letting a slug read as
-               the name of a requirement (never read, versus read and naming none of these). -->
+          <!-- The coverage was not counted against the spec, so say what the numbers above do
+               and do not cover rather than letting them read as the whole picture. -->
           <p
             v-if="specNote"
             class="mb-2 text-[11px] leading-relaxed text-amber-300/90"
@@ -382,6 +398,16 @@ function openTestReport() {
           >
             {{ specNote }}
           </p>
+          <!-- The tester ruled on ids the spec does not carry, so its own tally and the counts
+               above legitimately differ. Said out loud, because the alternative is a reader
+               deciding which of the two numbers to distrust. -->
+          <p
+            v-if="unmatchedVerdicts > 0"
+            class="mb-2 text-[11px] leading-relaxed text-amber-300/90"
+            data-testid="outcome-unmatched-verdicts"
+          >
+            {{ t('outcome.requirements.unmatchedVerdicts', { count: unmatchedVerdicts }) }}
+          </p>
           <ul class="space-y-1.5">
             <li
               v-for="req in requirementRows"
@@ -396,18 +422,6 @@ function openTestReport() {
               <div class="min-w-0">
                 <div class="flex flex-wrap items-center gap-1.5">
                   <span class="text-[13px] text-slate-200">{{ req.title ?? req.id }}</span>
-                  <!-- This row's id is standing in for a title the spec does not have for it,
-                       beside rows that DO carry one. -->
-                  <UBadge
-                    v-if="req.idOnly"
-                    color="neutral"
-                    variant="subtle"
-                    size="sm"
-                    :title="t('outcome.requirements.idOnlyHint')"
-                    data-testid="outcome-requirement-id-only"
-                  >
-                    {{ t('outcome.requirements.idOnly') }}
-                  </UBadge>
                   <UBadge
                     v-if="req.regression"
                     color="error"

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import {
   boardNodeIdFor,
+  focusLeftCard,
   isSafeTargetId,
   isTargetClickAdvance,
   resolveSkip,
@@ -208,3 +209,41 @@ describe('shouldFocusCard', () => {
     expect(shouldFocusCard('target-click')).toBe(false)
   })
 })
+
+describe('focusLeftCard', () => {
+  const card = () => {
+    const el = document.createElement('div')
+    const next = document.createElement('button')
+    el.appendChild(next)
+    document.body.appendChild(el)
+    return { el, next }
+  }
+
+  it('keeps the card focusable while focus is still inside it', () => {
+    // Tabbing from the card onto its own Next button must NOT drop `tabindex`: the card would
+    // become click-focusable again while the user is still in it, which is the exact state the
+    // attribute exists to avoid.
+    const { el, next } = card()
+    expect(focusLeftCard(el, next)).toBe(false)
+    expect(focusLeftCard(el, el)).toBe(false)
+  })
+
+  it('treats focus moving to anything outside the card as having left', () => {
+    const { el } = card()
+    const outside = document.createElement('input')
+    document.body.appendChild(outside)
+    expect(focusLeftCard(el, outside)).toBe(true)
+  })
+
+  it('treats focus falling to nothing as having left', () => {
+    // The `relatedTarget: null` case is not an edge: it is what happens when the pressed
+    // control unmounts under the press, which Back at step 1 does every time.
+    const { el } = card()
+    expect(focusLeftCard(el, null)).toBe(true)
+  })
+
+  it('reports left when there is no card', () => {
+    // An unmounted card holds no focus, so the flag must not be left standing.
+    expect(focusLeftCard(null, null)).toBe(true)
+  })
+})

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

@@ -46,6 +46,29 @@ export function shouldFocusCard(cause: TutorialAdvanceCause): boolean {
   return cause !== 'target-click'
 }
 
+/**
+ * Has focus actually LEFT the coach mark, as opposed to moving between its own controls?
+ *
+ * The card's `tabindex` is not a standing attribute (see `focusCard` in the component): it
+ * exists only while the card holds focus, because the same attribute that lets `focusCard`
+ * put focus here also makes the card CLICK-focusable, and a press that moves focus onto the
+ * card is what kills text selection on the steps pointing into an open modal. So the card
+ * drops the attribute the moment focus leaves, and this is the "leaves" test.
+ *
+ * Tabbing from the card onto its own Next button is NOT leaving: dropping the attribute
+ * there would make the card click-focusable again while the user is still inside it, which
+ * is the precise state the attribute is meant to be absent in.
+ *
+ * A `relatedTarget` of `null` (focus fell to `<body>`, as it does when the pressed control
+ * unmounts) counts as leaving. That is the honest reading: nothing inside the card holds
+ * focus any more.
+ */
+export function focusLeftCard(card: Node | null, relatedTarget: EventTarget | null): boolean {
+  if (!card) return true
+  if (!(relatedTarget instanceof Node)) return true
+  return !card.contains(relatedTarget)
+}
+
 /**
  * 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

package/app/components/tutorial/TutorialOverlay.vue

@@ -11,6 +11,7 @@ import {
 import type { CoachMarkLayout, TutorialRect, TutorialStep, TutorialTour } from '~/utils/tutorial'
 import {
   boardNodeIdFor,
+  focusLeftCard,
   isTargetClickAdvance,
   resolveSkip,
   shouldFocusCard,
@@ -317,6 +318,28 @@ watch(step, async (s) => {
   measure({ requery: true })
 })
 
+/**
+ * Whether the card currently carries `tabindex="-1"`.
+ *
+ * The attribute is NOT standing, and that is the whole design. It is what lets `focusCard`
+ * put focus on the card, and it equally makes the card CLICK-focusable, which is the half we
+ * never want: a press on the card's text focuses it, that focus move leaves an open modal's
+ * focus trap, the trap yanks focus back, and Chromium abandons the selection the press was
+ * starting (`selectstart` never fires). The one string a user reliably tries to copy, the
+ * sample repo slug in the add-service tour, could not be selected. `preventDefault` on the
+ * press is not the alternative: cancelling pointerdown or mousedown cancels the selection
+ * itself.
+ *
+ * So the card is focusable only across the window where it actually holds focus: applied by
+ * `focusCard` just before it focuses, dropped again by `onCardFocusOut`. Outside that window
+ * a press moves focus nowhere, on every input type, with no timing window to lose. Lifting
+ * the attribute for the DURATION OF A GESTURE cannot work instead, because the gesture has no
+ * reliable end event to restore on (a touch's compatibility `mousedown` arrives at touch END,
+ * long after any tick-scoped restore) and because `focusCard`'s own `await nextTick()` is a
+ * microtask that beats a macrotask restore, leaving `.focus()` a silent no-op.
+ */
+const cardFocusable = ref(false)
+
 /**
  * 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
@@ -324,8 +347,22 @@ watch(step, async (s) => {
  */
 async function focusCard(cause: TutorialAdvanceCause) {
   if (!shouldFocusCard(cause)) return
+  cardFocusable.value = true
+  // One tick for BOTH the step's own re-render and the attribute above: `.focus()` on a card
+  // that is not yet focusable is a silent no-op, and focus then sits whereever the press left
+  // it (`<body>`, when the pressed control was a Back button that this step unmounts).
   await nextTick()
-  cardEl.value?.focus({ preventScroll: true })
+  const el = cardEl.value
+  el?.focus({ preventScroll: true })
+  // Focus did not land: the card unmounted, or a modal's focus trap pulled it straight back.
+  // Clear the flag here rather than waiting for a `focusout` that will never fire, or the
+  // card is left click-focusable, which is exactly the state this is all avoiding.
+  if (!el || document.activeElement !== el) cardFocusable.value = false
+}
+
+/** Focus has left the card, so it stops being focusable until something focuses it again. */
+function onCardFocusOut(event: FocusEvent) {
+  if (focusLeftCard(cardEl.value, event.relatedTarget)) cardFocusable.value = false
 }
 
 /**
@@ -520,20 +557,23 @@ onUnmounted(() => {
            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. -->
+           this is teleported to the end of `body`. BOUND rather than static, and absent while
+           the card does not hold focus: see `cardFocusable`, without which a press on the card's
+           text focuses it and an open modal's focus trap cancels the selection being started.
+           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"
-        tabindex="-1"
+        :tabindex="cardFocusable ? -1 : undefined"
         :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 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
+        @focusout="onCardFocusOut"
       >
         <div class="mb-1 flex items-start justify-between gap-3">
           <h3 class="text-sm font-semibold text-slate-100">{{ t(step.titleKey) }}</h3>