@cat-factory/app 0.242.0 → 0.242.2

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/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>

package/app/pages/index.vue

@@ -1,15 +1,8 @@
 <script setup lang="ts">
 import BoardCanvas from '~/components/board/BoardCanvas.vue'
 import SideBar from '~/components/layout/SideBar.vue'
-import BoardToolbar from '~/components/layout/BoardToolbar.vue'
-import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
-import ConnectionStatusBanner from '~/components/layout/ConnectionStatusBanner.vue'
+import BoardTopOverlays from '~/components/layout/BoardTopOverlays.vue'
 import TranslationWarningBanner from '~/components/layout/TranslationWarningBanner.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'
 // Always-mounted, fast-path surfaces (opened frequently during a run / board edits, or
 // store-driven so they must react from anywhere — kept eager for snappy open/close).
 import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
@@ -398,170 +391,138 @@ watch(
 </script>
 
 <template>
-  <div class="flex h-screen w-screen overflow-hidden bg-slate-950 text-slate-100">
-    <!-- Non-English locale warning (unofficial translation); slim strip above everything. -->
+  <!-- A COLUMN, so the translation strip below takes its own height instead of covering the
+       row: page chrome that overlays the app is how the board's top controls came to be
+       buried. Everything else lives in the row beneath it. -->
+  <div class="flex h-screen w-screen flex-col overflow-hidden bg-slate-950 text-slate-100">
+    <!-- Non-English locale warning (unofficial translation); slim full-width strip above
+         everything, in flow. -->
     <TranslationWarningBanner />
-    <!-- Local-mode setup prompt (missing GitHub PAT); floats over whatever is shown below. -->
-    <GitHubPatBanner />
-    <!-- Stacked advisory banners: one click-through column so concurrent prompts never draw on
-         top of each other (a fresh, unconfigured deployment can raise all three at once — no AI
-         model + no runner pool + no storage). The wrapper is `pointer-events-none`; each banner
-         re-enables pointer events on its own card, so the empty strip never intercepts clicks on
-         the board chrome underneath.
-         - AI-readiness (no usable model source, or default preset uses unavailable models).
-         - Infrastructure provider (env/runner-pool wired but missing mandatory config).
-         - Infra-setup (this deployment needs an executor / test env / storage the operator hasn't
-           defined yet, so a class of agents can't run).
-         - Default test environment (this BOARD has never chosen the provisioning mechanism its
-           new services should default to). Last in the column: it asks for a convenience default,
-           so it yields to the prompts about things that are outright broken. -->
-    <div
-      v-if="workspace.ready && !needsGitHubInstall && !githubProbePending"
-      class="pointer-events-none absolute inset-x-0 top-0 z-40 flex flex-col items-center gap-2 px-4 pt-4"
-    >
-      <AiProvidersBanner />
-      <ProviderConfigBanner />
-      <InfraSetupBanner />
-      <DefaultTestEnvBanner />
-    </div>
-
-    <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->
-    <div
-      v-if="workspace.ready && githubProbePending"
-      class="m-auto flex flex-col items-center gap-3 text-slate-400"
-    >
-      <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
-      <span class="text-sm">{{ $t('app.loading') }}</span>
-    </div>
+    <div class="relative flex min-h-0 flex-1">
+      <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->
+      <div
+        v-if="workspace.ready && githubProbePending"
+        class="m-auto flex flex-col items-center gap-3 text-slate-400"
+      >
+        <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+        <span class="text-sm">{{ $t('app.loading') }}</span>
+      </div>
 
-    <!-- App enabled but not installed on this workspace: hard onboarding gate. -->
-    <GitHubOnboarding v-else-if="workspace.ready && needsGitHubInstall" />
+      <!-- App enabled but not installed on this workspace: hard onboarding gate. -->
+      <GitHubOnboarding v-else-if="workspace.ready && needsGitHubInstall" />
 
-    <template v-else-if="workspace.ready">
-      <!-- Headless readiness marker for the e2e suite: reflects whether the real-time
-           WebSocket is actually connected (and thus subscribed + resynced). A live spec must
-           wait for this before driving a run, otherwise the run's first status events are
-           broadcast to a not-yet-subscribed browser and missed, leaving the card stuck on a
-           stale status until its assertion times out (the source of the e2e flakiness). Hidden
-           and inert; no visual or behavioural effect. -->
-      <span
-        data-testid="workspace-stream"
-        :data-connected="streamConnected ? 'true' : 'false'"
-        hidden
-      />
-      <SideBar />
-      <main class="relative min-w-0 flex-1">
-        <BoardCanvas />
-        <!-- Compact-viewport navbar trigger: the SideBar is an off-canvas drawer below
-             lg, so surface a hamburger to open it. Hidden on lg+ (static sidebar). -->
-        <!-- z-30 keeps the trigger above the centered BoardToolbar (z-20), whose
-             max-width can otherwise reach this corner on the narrowest viewports. -->
-        <UButton
-          class="absolute start-3 top-3 z-30 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()"
+      <template v-else-if="workspace.ready">
+        <!-- Headless readiness marker for the e2e suite: reflects whether the real-time
+             WebSocket is actually connected (and thus subscribed + resynced). A live spec must
+             wait for this before driving a run, otherwise the run's first status events are
+             broadcast to a not-yet-subscribed browser and missed, leaving the card stuck on a
+             stale status until its assertion times out (the source of the e2e flakiness). Hidden
+             and inert; no visual or behavioural effect. -->
+        <span
+          data-testid="workspace-stream"
+          :data-connected="streamConnected ? 'true' : 'false'"
+          hidden
         />
-        <BoardToolbar />
-        <SpendWarningBanner />
-        <ConnectionStatusBanner
-          :connected="streamConnected"
-          :ever-connected="streamEverConnected"
-          :connection-failed="streamConnectionFailed"
-        />
-        <InspectorPanel />
-        <!-- Code-split focus view. The fade lives here (not inside the component) so the
-             leave animation still plays when `focusBlockId` clears and the v-if unmounts
-             the chunk — an inner Transition would be torn down before it could run. -->
-        <Transition name="focus-fade">
-          <BlockFocusView v-if="ui.focusBlockId" />
-        </Transition>
-      </main>
+        <SideBar />
+        <main class="relative min-w-0 flex-1">
+          <BoardCanvas />
+          <!-- Toolbar, nav trigger and every advisory banner, in ONE stacked region that owns
+               their placement, so no two of them can cover each other. -->
+          <BoardTopOverlays
+            :connected="streamConnected"
+            :ever-connected="streamEverConnected"
+            :connection-failed="streamConnectionFailed"
+          />
+          <InspectorPanel />
+          <!-- Code-split focus view. The fade lives here (not inside the component) so the
+               leave animation still plays when `focusBlockId` clears and the v-if unmounts
+               the chunk — an inner Transition would be torn down before it could run. -->
+          <Transition name="focus-fade">
+            <BlockFocusView v-if="ui.focusBlockId" />
+          </Transition>
+        </main>
 
-      <!-- Always-mounted, fast-path surfaces. -->
-      <PipelineBuilder />
-      <DecisionModal />
-      <AgentStepDetail />
-      <StepResultViewHost />
-      <!-- Consumer-contributed top-level overlays (extension slice D). Renders nothing until a
-           consumer opens one via `ui.openOverlay` / `useAppOverlays().open(...)`. -->
-      <AppOverlayHost />
-      <AddTaskModal />
-      <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
-      <CreateInitiativeModal />
-      <CommandBar />
-      <PersonalCredentialModal />
-      <ConfirmDialog />
-      <KeyboardShortcutsHelp />
+        <!-- Always-mounted, fast-path surfaces. -->
+        <PipelineBuilder />
+        <DecisionModal />
+        <AgentStepDetail />
+        <StepResultViewHost />
+        <!-- Consumer-contributed top-level overlays (extension slice D). Renders nothing until a
+             consumer opens one via `ui.openOverlay` / `useAppOverlays().open(...)`. -->
+        <AppOverlayHost />
+        <AddTaskModal />
+        <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
+        <CreateInitiativeModal />
+        <CommandBar />
+        <PersonalCredentialModal />
+        <ConfirmDialog />
+        <KeyboardShortcutsHelp />
 
-      <!-- Lazy panels: mounted only while their ui open-flag is set, so each loads on
-           first open (its own chunk) rather than bloating the initial bundle. -->
-      <TaskSourceConnectModal v-if="ui.taskConnect" />
-      <TaskImportModal v-if="ui.taskImport" />
-      <BugHuntModal v-if="ui.bugHunt" />
-      <RecurringPipelineModal v-if="ui.addRecurringFrameId" />
-      <ObservabilityPanel v-if="ui.observabilityInstanceId" />
-      <OperatorDashboardPanel v-if="ui.operatorDashboardOpen" />
-      <ReportsPanel v-if="ui.reportsOpen" />
-      <KaizenPanel v-if="ui.kaizenScreenOpen" />
-      <DocumentSourceConnectModal v-if="ui.documentConnect" />
-      <DocumentImportModal v-if="ui.documentImport" />
-      <DocumentTemplatesModal v-if="ui.documentTemplates" />
-      <SpawnPreviewModal v-if="ui.spawnPreview" />
-      <BootstrapModal v-if="ui.bootstrapOpen" />
-      <AddServiceFromRepoModal v-if="ui.addServiceOpen" />
-      <GitHubPanel v-if="ui.githubOpen" />
-      <SlackPanel v-if="ui.slackOpen" />
-      <FragmentLibraryPanel v-if="ui.fragmentLibraryOpen" />
-      <FoundationalServicePanel v-if="ui.foundationalServicesOpen" />
-      <PipelineHealthModal v-if="ui.pipelineHealthOpen" />
-      <RiskPolicyHealthModal v-if="ui.riskPolicyHealthOpen" />
-      <ModelPresetHealthModal v-if="ui.modelPresetHealthOpen" />
-      <IntegrationsHub v-if="ui.integrationsOpen" />
-      <ModelProvidersHub v-if="ui.modelProvidersOpen" />
-      <PersonalSetupModal v-if="ui.personalSetupOpen" />
-      <WorkspaceSettingsPanel v-if="ui.workspaceSettingsOpen" />
-      <AccountSettingsPanel v-if="ui.accountSettingsOpen" />
-      <ObservabilityConnectionPanel v-if="ui.observabilityConnectionOpen" />
-      <ApiTokensPanel v-if="ui.apiTokensOpen" />
-      <InfrastructureWindow v-if="ui.infrastructureOpen" />
-      <EnvironmentSetupWizard v-if="ui.environmentWizardOpen" />
-      <ModelConfigurationPanel v-if="ui.modelConfigOpen" />
-      <LocalModelEndpointsPanel v-if="ui.localModelsOpen" />
-      <SandboxPanel v-if="ui.sandboxOpen" />
-      <UserSecretsSection v-if="ui.userSecretsOpen" />
-      <OpenRouterCatalogPanel v-if="ui.openRouterOpen" />
-      <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
-      <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
-      <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
-      <TutorialPrompt v-if="tutorial.promptOpen" />
-      <TutorialCatalogue v-if="tutorial.catalogueOpen" />
-      <TutorialOverlay v-if="tutorial.touring" />
-      <!-- Mounted off the PENDING id rather than off whether it may currently be SHOWN: the
-           component holds a suppressed offer (a tour is running, a tutorial window is open) and
-           renders it once the way is clear, which is the whole reason the offer survives the
-           moment it was raised in. -->
-      <TutorialNudge v-if="tutorial.pendingNudgeId" />
-    </template>
+        <!-- Lazy panels: mounted only while their ui open-flag is set, so each loads on
+             first open (its own chunk) rather than bloating the initial bundle. -->
+        <TaskSourceConnectModal v-if="ui.taskConnect" />
+        <TaskImportModal v-if="ui.taskImport" />
+        <BugHuntModal v-if="ui.bugHunt" />
+        <RecurringPipelineModal v-if="ui.addRecurringFrameId" />
+        <ObservabilityPanel v-if="ui.observabilityInstanceId" />
+        <OperatorDashboardPanel v-if="ui.operatorDashboardOpen" />
+        <ReportsPanel v-if="ui.reportsOpen" />
+        <KaizenPanel v-if="ui.kaizenScreenOpen" />
+        <DocumentSourceConnectModal v-if="ui.documentConnect" />
+        <DocumentImportModal v-if="ui.documentImport" />
+        <DocumentTemplatesModal v-if="ui.documentTemplates" />
+        <SpawnPreviewModal v-if="ui.spawnPreview" />
+        <BootstrapModal v-if="ui.bootstrapOpen" />
+        <AddServiceFromRepoModal v-if="ui.addServiceOpen" />
+        <GitHubPanel v-if="ui.githubOpen" />
+        <SlackPanel v-if="ui.slackOpen" />
+        <FragmentLibraryPanel v-if="ui.fragmentLibraryOpen" />
+        <FoundationalServicePanel v-if="ui.foundationalServicesOpen" />
+        <PipelineHealthModal v-if="ui.pipelineHealthOpen" />
+        <RiskPolicyHealthModal v-if="ui.riskPolicyHealthOpen" />
+        <ModelPresetHealthModal v-if="ui.modelPresetHealthOpen" />
+        <IntegrationsHub v-if="ui.integrationsOpen" />
+        <ModelProvidersHub v-if="ui.modelProvidersOpen" />
+        <PersonalSetupModal v-if="ui.personalSetupOpen" />
+        <WorkspaceSettingsPanel v-if="ui.workspaceSettingsOpen" />
+        <AccountSettingsPanel v-if="ui.accountSettingsOpen" />
+        <ObservabilityConnectionPanel v-if="ui.observabilityConnectionOpen" />
+        <ApiTokensPanel v-if="ui.apiTokensOpen" />
+        <InfrastructureWindow v-if="ui.infrastructureOpen" />
+        <EnvironmentSetupWizard v-if="ui.environmentWizardOpen" />
+        <ModelConfigurationPanel v-if="ui.modelConfigOpen" />
+        <LocalModelEndpointsPanel v-if="ui.localModelsOpen" />
+        <SandboxPanel v-if="ui.sandboxOpen" />
+        <UserSecretsSection v-if="ui.userSecretsOpen" />
+        <OpenRouterCatalogPanel v-if="ui.openRouterOpen" />
+        <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
+        <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
+        <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
+        <TutorialPrompt v-if="tutorial.promptOpen" />
+        <TutorialCatalogue v-if="tutorial.catalogueOpen" />
+        <TutorialOverlay v-if="tutorial.touring" />
+        <!-- Mounted off the PENDING id rather than off whether it may currently be SHOWN: the
+             component holds a suppressed offer (a tour is running, a tutorial window is open) and
+             renders it once the way is clear, which is the whole reason the offer survives the
+             moment it was raised in. -->
+        <TutorialNudge v-if="tutorial.pendingNudgeId" />
+      </template>
 
-    <!-- Backend unreachable / bootstrap failed -->
-    <div v-else-if="workspace.error" class="m-auto max-w-md p-8 text-center">
-      <UIcon name="i-lucide-plug-zap" class="mx-auto mb-3 h-10 w-10 text-amber-400" />
-      <h1 class="mb-1 text-lg font-semibold">{{ $t('app.backendUnreachable') }}</h1>
-      <p class="mb-4 text-sm text-slate-400">{{ workspace.error }}</p>
-      <UButton color="primary" icon="i-lucide-rotate-ccw" @click="workspace.init()">
-        {{ $t('common.retry') }}
-      </UButton>
-    </div>
+      <!-- Backend unreachable / bootstrap failed -->
+      <div v-else-if="workspace.error" class="m-auto max-w-md p-8 text-center">
+        <UIcon name="i-lucide-plug-zap" class="mx-auto mb-3 h-10 w-10 text-amber-400" />
+        <h1 class="mb-1 text-lg font-semibold">{{ $t('app.backendUnreachable') }}</h1>
+        <p class="mb-4 text-sm text-slate-400">{{ workspace.error }}</p>
+        <UButton color="primary" icon="i-lucide-rotate-ccw" @click="workspace.init()">
+          {{ $t('common.retry') }}
+        </UButton>
+      </div>
 
-    <!-- Initial load -->
-    <div v-else class="m-auto flex flex-col items-center gap-3 text-slate-400">
-      <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
-      <span class="text-sm">{{ $t('app.loadingBoard') }}</span>
+      <!-- Initial load -->
+      <div v-else class="m-auto flex flex-col items-center gap-3 text-slate-400">
+        <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+        <span class="text-sm">{{ $t('app.loadingBoard') }}</span>
+      </div>
     </div>
   </div>
 </template>

package/i18n/locales/de.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "Die Befehlspalette",
-            "body": "Der schnellste Weg zu jeder Aktion: öffnen und lostippen. Von dort kannst du dieses Tutorial jederzeit neu starten."
+            "body": "Der schnellste Weg zu jeder Aktion: öffnen und lostippen. Um dieses Tutorial jederzeit neu zu starten, wähle dort „@:{'nav.tutorials'}“."
           },
           "toolbar": {
             "title": "Board-Steuerung",

package/i18n/locales/en.json

@@ -7236,7 +7236,7 @@
           },
           "commandBar": {
             "title": "The command palette",
-            "body": "The fastest way to reach any action: open it and start typing. You can restart this tutorial from there at any time."
+            "body": "The fastest way to reach any action: open it and start typing. To restart this tutorial at any time, pick \"@:{'nav.tutorials'}\" there."
           },
           "toolbar": {
             "title": "Board controls",

package/i18n/locales/es.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "La paleta de comandos",
-            "body": "La forma más rápida de llegar a cualquier acción: ábrela y empieza a escribir. Desde ahí puedes reiniciar este tutorial en cualquier momento."
+            "body": "La forma más rápida de llegar a cualquier acción: ábrela y empieza a escribir. Para reiniciar este tutorial en cualquier momento, elige ahí \"@:{'nav.tutorials'}\"."
           },
           "toolbar": {
             "title": "Controles del tablero",

package/i18n/locales/fr.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "La palette de commandes",
-            "body": "Le moyen le plus rapide d'atteindre n'importe quelle action : ouvrez-la et commencez à taper. Vous pouvez y relancer ce tutoriel à tout moment."
+            "body": "Le moyen le plus rapide d'atteindre n'importe quelle action : ouvrez-la et commencez à taper. Pour relancer ce tutoriel à tout moment, choisissez-y « @:{'nav.tutorials'} »."
           },
           "toolbar": {
             "title": "Contrôles du tableau",

package/i18n/locales/he.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "לוח הפקודות",
-            "body": "הדרך המהירה ביותר להגיע לכל פעולה: פתח והתחל להקליד. משם אפשר להפעיל מחדש את המדריך הזה בכל עת."
+            "body": "הדרך המהירה ביותר להגיע לכל פעולה: פתח והתחל להקליד. כדי להפעיל מחדש את המדריך הזה בכל עת, בחר שם \"@:{'nav.tutorials'}\"."
           },
           "toolbar": {
             "title": "פקדי הלוח",

package/i18n/locales/it.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "La palette dei comandi",
-            "body": "Il modo più rapido per raggiungere qualsiasi azione: aprila e inizia a digitare. Da lì puoi riavviare questo tutorial in qualsiasi momento."
+            "body": "Il modo più rapido per raggiungere qualsiasi azione: aprila e inizia a digitare. Per riavviare questo tutorial in qualsiasi momento, scegli lì \"@:{'nav.tutorials'}\"."
           },
           "toolbar": {
             "title": "Controlli della board",

package/i18n/locales/ja.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "コマンドパレット",
-            "body": "あらゆる操作への最短ルートです。開いて入力を始めるだけ。ここからいつでもこのチュートリアルを再開できます。"
+            "body": "あらゆる操作への最短ルートです。開いて入力を始めるだけ。このチュートリアルをやり直したいときは、ここで「@:{'nav.tutorials'}」を選んでください。"
           },
           "toolbar": {
             "title": "ボードの操作",

package/i18n/locales/pl.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "Paleta poleceń",
-            "body": "Najszybsza droga do każdej akcji: otwórz i zacznij pisać. Możesz stamtąd w każdej chwili ponownie uruchomić ten samouczek."
+            "body": "Najszybsza droga do każdej akcji: otwórz i zacznij pisać. Aby w każdej chwili ponownie uruchomić ten samouczek, wybierz tam „@:{'nav.tutorials'}”."
           },
           "toolbar": {
             "title": "Sterowanie tablicą",

package/i18n/locales/tr.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "Komut paleti",
-            "body": "Herhangi bir eyleme ulaşmanın en hızlı yolu: açın ve yazmaya başlayın. Bu eğitimi oradan istediğiniz zaman yeniden başlatabilirsiniz."
+            "body": "Herhangi bir eyleme ulaşmanın en hızlı yolu: açın ve yazmaya başlayın. Bu eğitimi istediğiniz zaman yeniden başlatmak için oradan \"@:{'nav.tutorials'}\" seçeneğini seçin."
           },
           "toolbar": {
             "title": "Pano denetimleri",

package/i18n/locales/uk.json

@@ -6984,7 +6984,7 @@
           },
           "commandBar": {
             "title": "Палітра команд",
-            "body": "Найшвидший шлях до будь-якої дії: відкрийте й почніть друкувати. Звідти можна будь-коли перезапустити цей навчальний тур."
+            "body": "Найшвидший шлях до будь-якої дії: відкрийте й почніть друкувати. Щоб будь-коли перезапустити цей тур, виберіть там «@:{'nav.tutorials'}»."
           },
           "toolbar": {
             "title": "Керування дошкою",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.242.0",
+  "version": "0.242.2",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.263.0"
+    "@cat-factory/contracts": "0.264.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",