@cat-factory/app 0.196.0 → 0.197.0

package/README.md

@@ -17,6 +17,7 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [Layout](#layout)
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
+- [In-app tutorial tours](#in-app-tutorial-tours)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -77,11 +78,18 @@ a fixed order, first match wins:
    set the in-app switcher is a read-only indicator, since a preference the resolver ignores
    would be a lie. An unrecognised value is ignored rather than failing the boot.
 2. **The user's own choice**, persisted client-side (the `uiMode` store) and changed from the
-   switcher at the bottom of the sidebar — or from the **command palette** entry, which is
-   deliberately _not_ an advanced item: basic is the default, so the route back to the
-   advanced half has to exist inside basic mode.
+   switcher at the top of the sidebar, under the board switcher — or from the **command
+   palette** entry, which is deliberately _not_ an advanced item: basic is the default, so the
+   route back to the advanced half has to exist inside basic mode.
 3. **`basic`.**
 
+That switcher is a **segmented control showing both tiers**, above the fold rather than in the
+footer, because basic is the shipped default and it is most users' only sight of the tier: a
+dropdown states the current mode but not that another one exists, so the half of the product it
+gates stays invisible to anyone who does not open menus to see what is in them. In the collapsed
+rail it degrades to one button that flips the tier (with only two modes a toggle is
+unambiguous), keeping the current tier's name under the glyph.
+
 The sidebar can independently be **collapsed to an icon rail** (the toggle at its top, lg+
 only — below `lg` the navbar is already an off-canvas drawer). The rail preference is
 **per-tier**: basic _defaults_ to railed and advanced to expanded, and each tier remembers its
@@ -152,6 +160,44 @@ picking what each of them runs on are halves of the same job.
   whatever the tier — the same rule `showOverrideField` states for a single field: a row the
   user can neither read nor clear is worse than a longer list.
 
+## In-app tutorial tours
+
+On first launch (once the board is up and no other startup advisory is open) the app asks
+whether the user wants a guided tour. The answer is SAVED per browser (`stores/tutorial.ts`,
+persisted like the interface tier): "no thanks" stops the prompt for good, closing without
+answering defers it to the next launch, and the command palette's "Take a tour" entry is the
+way back either way.
+
+A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
+control by its `data-testid` (the e2e anchor vocabulary — cover a control that has none by
+adding the test id first) and carrying i18n keys for its copy. One shared runtime
+(`components/tutorial/TutorialOverlay.vue`) renders every tour: it highlights the current
+step's control, places the tooltip (`utils/tutorial.ts` owns the pure geometry + types),
+advances on Next or — for `advanceOn: 'target-click'` steps — on the user really clicking
+the control, so the app's real response (the actual modal, the actual task) is what the next
+step anchors to. `target-click` is for BUTTONS, where the click is the completed action; a
+text field keeps Next, or the tooltip would leave the instruction the moment the user clicked
+in to type. A step whose anchor never appears within its wait is SKIPPED, because controls
+come and go with RBAC, tier, and deployment wiring: a tour is a set of opportunities, not a
+fixed script. Reaching the end having skipped steps is reported on the final card rather than
+congratulating the user on a walkthrough they did not see — and a tour that could only ever
+be abridged should not be offered at all, which is what each tour's `when(gates)` is for (the
+task-creation tour requires board write AND a service frame to add a task to).
+
+Two runtime constraints worth knowing before changing the overlay: it must keep
+`pointer-events-auto` and swallow `pointerdown`, because Nuxt UI modals are reka-ui
+dismissable layers that set `body { pointer-events: none }` and dismiss on an outside
+pointerdown — without both, the tooltip's own buttons go inert and pressing one closes the
+user's half-filled form. And everything that DECIDES (skip direction, wait budget,
+target-click matching) lives in `components/tutorial/TutorialOverlay.logic.ts` so it is
+unit-tested; the SFC keeps only the DOM work.
+
+The catalog is the `tutorialTours` slot: first-party tours live in
+`modular/tutorial-tours.ts`, and a consumer deployment contributes its own through
+`registerAppModule` — they appear in the launch prompt beside the built-ins, gated per tour
+by its `when(gates)` predicate (the same reactive gates service the nav uses, filtered in
+`navSlotFilter`). Completion is persisted per tour id, so renaming an id resets its state.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components — result windows, nav entries, inspector

package/app/components/brainstorm/BrainstormWindow.vue

@@ -254,7 +254,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
     "
     :subtitle="block?.title"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <template v-if="session" #header-extras>
@@ -361,14 +361,18 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                       {{ t(STATUS_LABELS[item.status]) }}
                     </UBadge>
                   </div>
-                  <p class="mt-1 whitespace-pre-line text-sm text-slate-400">
+                  <!-- The proposal itself is prose, so it takes the measure even though the card
+                       around it takes the span (see the shell's `width` prop: the unit is the
+                       paragraph, not the section). The badge row above and the choose/dismiss
+                       control below are what the full width is actually for. -->
+                  <p class="mt-1 max-w-3xl whitespace-pre-line text-sm text-slate-400">
                     {{ item.detail }}
                   </p>
 
                   <!-- recorded choice -->
                   <div
                     v-if="item.reply"
-                    class="mt-2 rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
+                    class="mt-2 max-w-3xl rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
                   >
                     <span class="text-[10px] uppercase tracking-wide text-slate-500">
                       {{ t('brainstorm.yourChoice') }}
@@ -446,7 +450,10 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                 {{ incorporated ? docNoun : t('brainstorm.docDraft', { doc: docNoun }) }}
               </span>
             </div>
-            <div v-for="s in outline.sections" :key="s.id" class="mb-2">
+            <!-- The same reading measure the options' own prose takes above (see the shell's
+                 `width` prop): the window is `full`-width now, and this is continuous prose that
+                 would otherwise run to 200-character lines. -->
+            <div v-for="s in outline.sections" :key="s.id" class="mb-2 max-w-3xl">
               <button
                 v-if="s.title"
                 class="group flex w-full items-center gap-2 text-start"

package/app/components/clarity/ClarityReviewWindow.vue

@@ -310,7 +310,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
     :title="t('clarity.title')"
     :subtitle="block?.title"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <template v-if="review" #header-extras>
@@ -418,7 +418,11 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                       {{ t(STATUS_LABELS[item.status]) }}
                     </UBadge>
                   </div>
-                  <p class="mt-1 whitespace-pre-line text-sm text-slate-400">
+                  <!-- The reviewer's question is prose, so it takes the measure even though the
+                       card around it takes the span (see the shell's `width` prop: the unit is the
+                       paragraph, not the section). The badge row above and the answer control
+                       below are what the full width is actually for. -->
+                  <p class="mt-1 max-w-3xl whitespace-pre-line text-sm text-slate-400">
                     {{ item.detail }}
                   </p>
 
@@ -426,7 +430,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                            the answer lives in the textarea below, seeded from the reply) -->
                   <div
                     v-if="item.reply && item.status !== 'open' && item.status !== 'answered'"
-                    class="mt-2 rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
+                    class="mt-2 max-w-3xl rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
                   >
                     <span class="text-[10px] uppercase tracking-wide text-slate-500">
                       {{ t('clarity.answerLabel') }}
@@ -490,7 +494,10 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                 {{ incorporated ? t('clarity.docHeading') : t('clarity.docHeadingDraft') }}
               </span>
             </div>
-            <div v-for="s in outline.sections" :key="s.id" class="mb-2">
+            <!-- The same reading measure the findings' own prose takes above (see the shell's
+                 `width` prop): the window is `full`-width now, and this is continuous prose that
+                 would otherwise run to 200-character lines. -->
+            <div v-for="s in outline.sections" :key="s.id" class="mb-2 max-w-3xl">
               <button
                 v-if="s.title"
                 class="group flex w-full items-center gap-2 text-start"

package/app/components/initiative/InitiativePlanReview.vue

@@ -224,45 +224,52 @@ async function copyPlan() {
       class="min-h-0 min-w-0 flex-1 overflow-y-auto px-5 py-4"
       @scroll="onScroll"
     >
-      <!-- No `max-w-*` reading measure here: with the outline and the review rail both taking a
-           fixed column out of the shell's `5xl`, this one is ~490px wide at every size that renders
-           it, so a cap would only ever be dead markup. -->
-      <section
-        v-for="s in outline.sections"
-        :id="s.id"
-        :key="s.id"
-        :ref="(el) => (sectionEls[s.id] = el as HTMLElement | null)"
-        class="scroll-mt-2"
-      >
-        <button
-          v-if="s.depth > 0"
-          class="group flex w-full items-center gap-1.5 rounded py-0.5 text-start transition hover:text-white"
-          :aria-expanded="!collapsed[s.id]"
-          @click="toggle(s.id)"
+      <!-- The reading measure, which the shell's `full` width made load-bearing: this column used
+           to be ~490px at every size that rendered it (a fixed outline and a fixed rail out of a
+           `5xl` shell), so a cap was dead markup and the comment here said so. On a window that now
+           spans the viewport it is the only thing between the plan and 200-character lines, and it
+           is the step reader's own measure (`AgentStepDetail`, `mx-auto max-w-3xl` over the same
+           13px `.reader-prose`) rather than a second opinion about how wide prose should be. The
+           leftover width is the document's margins; the LAYOUT is what the extra space bought —
+           outline and rail no longer competing with the plan for one 5xl card. -->
+      <div class="mx-auto w-full max-w-3xl">
+        <section
+          v-for="s in outline.sections"
+          :id="s.id"
+          :key="s.id"
+          :ref="(el) => (sectionEls[s.id] = el as HTMLElement | null)"
+          class="scroll-mt-2"
         >
-          <UIcon
-            name="i-lucide-chevron-right"
-            class="h-3.5 w-3.5 shrink-0 text-slate-500 transition-transform group-hover:text-slate-300"
-            :class="collapsed[s.id] ? '' : 'rotate-90'"
-          />
-          <span
-            class="font-semibold text-slate-100"
-            :class="s.depth <= 1 ? 'text-base' : s.depth === 2 ? 'text-sm' : 'text-[13px]'"
-            v-html="s.titleHtml"
+          <button
+            v-if="s.depth > 0"
+            class="group flex w-full items-center gap-1.5 rounded py-0.5 text-start transition hover:text-white"
+            :aria-expanded="!collapsed[s.id]"
+            @click="toggle(s.id)"
+          >
+            <UIcon
+              name="i-lucide-chevron-right"
+              class="h-3.5 w-3.5 shrink-0 text-slate-500 transition-transform group-hover:text-slate-300"
+              :class="collapsed[s.id] ? '' : 'rotate-90'"
+            />
+            <span
+              class="font-semibold text-slate-100"
+              :class="s.depth <= 1 ? 'text-base' : s.depth === 2 ? 'text-sm' : 'text-[13px]'"
+              v-html="s.titleHtml"
+            />
+          </button>
+          <!-- `review-mode` carries the click-to-comment affordance, so it tracks the same RBAC
+               gate the composer does — a viewer gets the document, not hover targets that lead
+               nowhere. -->
+          <!-- eslint-disable-next-line vue/no-v-html -->
+          <div
+            v-show="!collapsed[s.id]"
+            class="reader-prose mt-0.5 text-[13px] leading-relaxed text-slate-300"
+            :class="[s.depth > 0 ? 'ps-5' : '', canExecute ? 'review-mode' : '']"
+            @click="onProseClick"
+            v-html="s.bodyHtml"
           />
-        </button>
-        <!-- `review-mode` carries the click-to-comment affordance, so it tracks the same RBAC
-             gate the composer does — a viewer gets the document, not hover targets that lead
-             nowhere. -->
-        <!-- eslint-disable-next-line vue/no-v-html -->
-        <div
-          v-show="!collapsed[s.id]"
-          class="reader-prose mt-0.5 text-[13px] leading-relaxed text-slate-300"
-          :class="[s.depth > 0 ? 'ps-5' : '', canExecute ? 'review-mode' : '']"
-          @click="onProseClick"
-          v-html="s.bodyHtml"
-        />
-      </section>
+        </section>
+      </div>
     </div>
 
     <!-- Review rail: what the human is being asked, the anchored comments so far, and the two

package/app/components/initiative/InitiativeTrackerWindow.vue

@@ -245,7 +245,7 @@ async function savePolicy() {
     icon-class="bg-indigo-500/15 text-indigo-300"
     :title="initiative?.title ?? block?.title ?? t('initiative.tracker.title')"
     :subtitle="t('initiative.tracker.subtitle')"
-    width="5xl"
+    width="full"
     testid="initiative-tracker-window"
     @close="close"
   >
@@ -353,12 +353,15 @@ async function savePolicy() {
             </div>
           </section>
 
-          <!-- Goal & constraints -->
+          <!-- Goal & constraints. The planner's own prose, so it takes the reading measure the
+               shell's `full` width obliges (see the `width` prop): the phase/item rows below are
+               structure that reads better at the full span, but these are paragraphs and bullets
+               of agent-written text that would otherwise run the width of the display. -->
           <section v-if="initiative.goal" class="mb-4">
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.goal') }}
             </h3>
-            <p class="whitespace-pre-wrap text-[13px] leading-relaxed text-slate-300">
+            <p class="max-w-3xl whitespace-pre-wrap text-[13px] leading-relaxed text-slate-300">
               {{ initiative.goal }}
             </p>
           </section>
@@ -366,7 +369,7 @@ async function savePolicy() {
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.constraints') }}
             </h3>
-            <ul class="list-inside list-disc text-[13px] text-slate-300">
+            <ul class="max-w-3xl list-inside list-disc text-[13px] text-slate-300">
               <li v-for="(c, i) in initiative.constraints" :key="i">{{ c }}</li>
             </ul>
           </section>
@@ -374,7 +377,7 @@ async function savePolicy() {
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.nonGoals') }}
             </h3>
-            <ul class="list-inside list-disc text-[13px] text-slate-300">
+            <ul class="max-w-3xl list-inside list-disc text-[13px] text-slate-300">
               <li v-for="(g, i) in initiative.nonGoals" :key="i">{{ g }}</li>
             </ul>
           </section>
@@ -382,7 +385,7 @@ async function savePolicy() {
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.analysis') }}
             </h3>
-            <p class="whitespace-pre-wrap text-[13px] leading-relaxed text-slate-300">
+            <p class="max-w-3xl whitespace-pre-wrap text-[13px] leading-relaxed text-slate-300">
               {{ initiative.analysisSummary }}
             </p>
           </section>
@@ -450,7 +453,7 @@ async function savePolicy() {
                           })
                         }}
                       </div>
-                      <div v-if="item.note" class="mt-0.5 text-[10px] text-amber-300/80">
+                      <div v-if="item.note" class="mt-0.5 max-w-3xl text-[10px] text-amber-300/80">
                         {{ item.note }}
                       </div>
                       <div
@@ -592,7 +595,7 @@ async function savePolicy() {
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.deviations') }}
             </h3>
-            <ul class="list-inside list-disc text-[13px] text-slate-300">
+            <ul class="max-w-3xl list-inside list-disc text-[13px] text-slate-300">
               <li v-for="d in initiative.deviations" :key="d.id">
                 <code v-if="d.itemId" class="text-slate-400">{{ d.itemId }}</code>
                 {{ d.description }}
@@ -688,7 +691,7 @@ async function savePolicy() {
             <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
               {{ t('initiative.tracker.caveats') }}
             </h3>
-            <ul class="list-inside list-disc text-[13px] text-slate-300">
+            <ul class="max-w-3xl list-inside list-disc text-[13px] text-slate-300">
               <li v-for="(c, i) in initiative.caveats" :key="i">{{ c }}</li>
             </ul>
           </section>

package/app/components/layout/SideBar.vue

@@ -9,7 +9,8 @@
 // Two orthogonal ways this panel shrinks. WHICH destinations exist is the interface
 // TIER (basic hides the `advanced` contributions, filtered upstream in `navSlotFilter`);
 // how much room they take is the COLLAPSE state (the icon-only rail). Basic mode starts
-// railed, but either can be changed independently from the footer switcher / the toggle.
+// railed, but either can be changed independently from the tier switcher at the top /
+// the rail toggle.
 import { useEventListener, useScrollLock } from '@vueuse/core'
 import BoardSwitcher from '~/components/layout/BoardSwitcher.vue'
 import LanguageSwitcher from '~/components/layout/LanguageSwitcher.vue'
@@ -179,6 +180,17 @@ watch(
 
     <BoardSwitcher :collapsed="railed" />
 
+    <!-- The interface tier sits ABOVE the destinations it gates, not in the footer: basic is the
+         shipped default, so this row is most users' only sight of the tier, and below the fold in
+         a scrolled navbar it is a thin thread to hang the advanced half of the product on. The
+         wrapper is what keeps the control and its hint together — the aside's own `gap-4` would
+         otherwise push them apart. Kept OUT of the `onNavAction` group deliberately: switching
+         tiers opens nothing, and closing the compact drawer would hide the destinations the
+         switch just revealed. -->
+    <div class="space-y-1">
+      <UiModeSwitcher :collapsed="railed" />
+    </div>
+
     <div class="contents" @click="onNavAction">
       <!-- Command bar launcher (⌘K) — the primary way to create blocks / pipelines
          and reach every action below. -->
@@ -236,7 +248,6 @@ watch(
     </div>
 
     <div class="mt-auto space-y-2">
-      <UiModeSwitcher :collapsed="railed" />
       <LanguageSwitcher :collapsed="railed" />
       <UserMenu :collapsed="railed" />
     </div>

package/app/components/layout/UiModeSwitcher.vue

@@ -1,14 +1,23 @@
 <script setup lang="ts">
-import type { DropdownMenuItem } from '@nuxt/ui'
 import { computed } from 'vue'
 import { UI_MODES, type UiMode } from '~/utils/uiMode'
 
-// Interface-tier picker, shown at the sidebar bottom next to the language switcher (the
-// same shape, deliberately: both are per-user shell preferences rather than board state).
-// Basic mode hides the power-user destinations and the less-used run options; advanced
-// shows everything. The user's pick is persisted client-side — unless the deployment pinned
-// the tier via NUXT_PUBLIC_UI_MODE, in which case the row is a read-only indicator, since
-// writing a preference the resolver ignores would be a lie (see `stores/uiMode.ts`).
+// Interface-tier picker, shown at the TOP of the sidebar under the board switcher. Basic mode
+// hides the power-user destinations and the less-used run options; advanced shows everything.
+//
+// It is a SEGMENTED control rather than a dropdown, and it sits above the fold rather than in the
+// footer, because basic is the shipped default and this row is most users' only sight of the tier:
+// a dropdown states the current mode but not that another one exists, so the half of the product
+// it gates is discoverable only to someone who already opens menus to see what is in them. Showing
+// both segments makes the choice — and the fact that there IS a choice — legible at rest.
+//
+// The user's pick is persisted client-side — unless the deployment pinned the tier via
+// NUXT_PUBLIC_UI_MODE, in which case the row is a read-only indicator, since writing a preference
+// the resolver ignores would be a lie (see `stores/uiMode.ts`).
+//
+// `collapsed` is the icon-only rail (basic mode's own default), where two segments do not fit at
+// 3.5rem. It degrades to ONE button that flips the tier directly — with only two modes a toggle is
+// unambiguous — keeping the current tier's NAME under the glyph rather than an icon alone.
 withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
 
 const uiMode = useUiModeStore()
@@ -27,28 +36,20 @@ const MODE_HINTS: Record<UiMode, string> = {
 
 const currentLabel = computed(() => t(MODE_LABELS[uiMode.mode]))
 const icon = computed(() => (uiMode.isAdvanced ? 'i-lucide-toggle-right' : 'i-lucide-toggle-left'))
-/** Tooltip for the collapsed rail (and the pinned row): mode + why it can't be changed. */
-const title = computed(() =>
-  uiMode.envPinned
-    ? `${t('uiMode.switcher')}: ${currentLabel.value} (${t('uiMode.pinned')})`
-    : `${t('uiMode.switcher')}: ${currentLabel.value}`,
+/** The tier the rail button would switch TO, so its tooltip names the act and not the state. */
+const otherMode = computed<UiMode>(() => (uiMode.isAdvanced ? 'basic' : 'advanced'))
+/** Tooltip for the pinned row (both variants): mode + why it can't be changed. */
+const pinnedTitle = computed(
+  () => `${t('uiMode.switcher')}: ${currentLabel.value} (${t('uiMode.pinned')})`,
 )
-
-const items = computed<DropdownMenuItem[][]>(() => [
-  UI_MODES.map((mode) => ({
-    label: t(MODE_LABELS[mode]),
-    icon: mode === uiMode.mode ? 'i-lucide-check' : undefined,
-    onSelect: () => uiMode.setMode(mode),
-  })),
-])
 </script>
 
 <template>
-  <!-- Pinned by the deployment: no dropdown, just the current tier. -->
+  <!-- Pinned by the deployment: no control, just the current tier. -->
   <div
     v-if="uiMode.envPinned"
     data-testid="ui-mode-pinned"
-    :title="title"
+    :title="pinnedTitle"
     class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/40 p-2 text-start"
     :class="collapsed ? 'justify-center' : ''"
   >
@@ -62,25 +63,51 @@ const items = computed<DropdownMenuItem[][]>(() => [
     <UIcon v-if="!collapsed" name="i-lucide-lock" class="h-3.5 w-3.5 shrink-0 text-slate-600" />
   </div>
 
-  <UDropdownMenu v-else :items="items" :content="{ side: 'top', align: 'start' }">
-    <button
-      type="button"
-      data-testid="ui-mode-switcher"
+  <!-- Rail: one button, flips the tier. The label rides under the glyph so the rail still says
+       which tier is on — the audience that needs to find the advanced half is exactly the one
+       sitting in basic mode's collapsed default. -->
+  <button
+    v-else-if="collapsed"
+    type="button"
+    data-testid="ui-mode-toggle"
+    :aria-label="t('uiMode.switchTo', { mode: t(MODE_LABELS[otherMode]) })"
+    :title="t('uiMode.switchTo', { mode: t(MODE_LABELS[otherMode]) })"
+    class="flex w-full flex-col items-center gap-0.5 rounded-lg border border-slate-700 bg-slate-900/60 px-1 py-1.5 transition hover:border-indigo-500/60 hover:bg-slate-800/60"
+    @click="uiMode.toggleMode()"
+  >
+    <UIcon :name="icon" class="h-4 w-4 shrink-0 text-indigo-400" />
+    <span class="w-full truncate text-center text-[9px] font-medium uppercase text-slate-300">
+      {{ currentLabel }}
+    </span>
+  </button>
+
+  <div v-else data-testid="ui-mode-switcher" class="w-full">
+    <div class="mb-1 px-1 text-[10px] uppercase tracking-wide text-slate-500">
+      {{ t('uiMode.switcher') }}
+    </div>
+    <div
+      role="group"
       :aria-label="t('uiMode.switcher')"
-      :title="title"
-      class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
-      :class="collapsed ? 'justify-center' : ''"
+      class="flex w-full gap-1 rounded-lg border border-slate-700 bg-slate-900/60 p-1"
     >
-      <UIcon :name="icon" class="h-4 w-4 shrink-0 text-slate-400" />
-      <div v-if="!collapsed" class="min-w-0 flex-1">
-        <div class="truncate text-[10px] uppercase tracking-wide text-slate-500">
-          {{ t('uiMode.switcher') }}
-        </div>
-        <div class="truncate text-xs font-medium text-white">{{ currentLabel }}</div>
-      </div>
-      <UIcon v-if="!collapsed" name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
-    </button>
-  </UDropdownMenu>
+      <button
+        v-for="mode in UI_MODES"
+        :key="mode"
+        type="button"
+        :data-testid="`ui-mode-option-${mode}`"
+        :aria-pressed="mode === uiMode.mode"
+        class="flex-1 truncate rounded-md px-2 py-1 text-xs font-medium transition"
+        :class="
+          mode === uiMode.mode
+            ? 'bg-indigo-500/20 text-indigo-200 ring-1 ring-indigo-500/50'
+            : 'text-slate-400 hover:bg-slate-800/70 hover:text-slate-200'
+        "
+        @click="uiMode.setMode(mode)"
+      >
+        {{ t(MODE_LABELS[mode]) }}
+      </button>
+    </div>
+  </div>
 
   <!-- The one-line "what this tier gives you", so the choice is self-explanatory. Dropped in
        the collapsed rail, where the tooltip above carries the mode instead. -->