@cat-factory/app 0.196.0 → 0.197.0

package/app/components/panels/ResultWindowShell.logic.spec.ts

@@ -0,0 +1,174 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  PROSE_MEASURE_CLASS,
+  RESULT_WINDOW_WIDTH_CLASS,
+  type ResultWindowWidth,
+} from './ResultWindowShell.logic'
+
+// The width decision is a per-window LAYOUT judgement that lives on each window's
+// `<ResultWindowShell width="…">`, which means nothing in the type system can ask a window author
+// to justify it — and the `full` bucket carries an obligation (continuous prose takes its own
+// reading measure) the shell explicitly cannot enforce on its slot content. That combination is
+// what this file pins, the way `nav-contributions.spec.ts` pins the advanced-nav set: a table
+// naming every window's bucket AND the reason, asserted against what the components actually pass.
+//
+// It caught its own motivating bug — the tracker, spec and tester windows moved to `full` with no
+// measure anywhere in them, so their agent-written summaries ran the width of the display.
+
+/** The default the shell applies when a window passes no `width` (`withDefaults`). */
+const SHELL_DEFAULT_WIDTH: ResultWindowWidth = '3xl'
+
+/**
+ * Every `ResultWindowShell` consumer, its bucket, and why that bucket. The reason is the point:
+ * `full` is for a body that lays out in COLUMNS, where the width buys visible layout, and a
+ * one-column verdict or reader keeps a bucket. A row that cannot state which of those it is has
+ * not made the decision.
+ */
+const WINDOWS: Record<string, { width: ResultWindowWidth; why: string }> = {
+  'brainstorm/BrainstormWindow.vue': {
+    width: 'full',
+    why: 'options column + the choose/dismiss action rail',
+  },
+  'clarity/ClarityReviewWindow.vue': {
+    width: 'full',
+    why: 'findings column + the answer/dismiss action rail',
+  },
+  'consensus/ConsensusSessionWindow.vue': {
+    width: '5xl',
+    why: 'one stacked column of participant prose — no rail competing with it, so width would only lengthen lines',
+  },
+  'docs/DocInterviewWindow.vue': { width: '3xl', why: 'one column of interview question + answer' },
+  'followUp/FollowUpWindow.vue': { width: '3xl', why: 'a short list of follow-up items' },
+  'forkDecision/ForkDecisionWindow.vue': {
+    width: '3xl',
+    why: 'two proposals and a choice between them',
+  },
+  'gates/GateResultView.vue': { width: '3xl', why: 'a gate verdict — one column, short' },
+  'humanTest/HumanTestWindow.vue': {
+    width: '3xl',
+    why: 'one instruction plus a pass/fail control',
+  },
+  'initiative/InitiativePlanningWindow.vue': {
+    width: '4xl',
+    why: 'a planning-progress readout, one column',
+  },
+  'initiative/InitiativeTrackerWindow.vue': {
+    width: 'full',
+    why: 'tracker column + run-metadata rail, and it hands its whole body to the three-column plan review while a plan is parked',
+  },
+  'judge/JudgeResultView.vue': { width: '3xl', why: 'a rubric verdict — one column, short' },
+  'panels/GenericStructuredResultView.vue': {
+    width: '4xl',
+    why: 'the fallback structured-result reader, one column of sections',
+  },
+  'panels/MergerResultView.vue': {
+    width: '3xl',
+    why: 'the merge verdict and its scores — one column, short (the slice-5 pilot)',
+  },
+  'prReview/PrReviewWindow.vue': {
+    width: 'full',
+    why: 'per-file findings with paths, line numbers and suggested fixes, + a rail',
+  },
+  'ralph/RalphLoopResultView.vue': { width: '3xl', why: 'a loop status readout, one column' },
+  'requirements/RequirementsReviewWindow.vue': {
+    width: 'full',
+    why: 'findings column + the answer/dismiss action rail',
+  },
+  'spec/ServiceSpecWindow.vue': {
+    width: 'full',
+    why: 'module/feature-group nav column + the spec detail column',
+  },
+  'testing/TestReportWindow.vue': {
+    width: 'full',
+    why: 'scenario/outcome/concern tree + run-metadata rail',
+  },
+  'visualConfirm/VisualConfirmationWindow.vue': {
+    width: '5xl',
+    why: 'a screenshot grid whose full-bleed reading is the nested ArtifactLightbox, not this window',
+  },
+}
+
+// Anchored on the vitest root (`frontend/app`) rather than `import.meta.url`: the `happy-dom`
+// environment replaces the global `URL`, and `fileURLToPath` then rejects its own file: URLs.
+const componentsDir = resolve(process.cwd(), 'app/components')
+
+/** Every component that mounts the shell, keyed by its path relative to `app/components`. */
+function findConsumers(): Map<string, string> {
+  const found = new Map<string, string>()
+  for (const entry of readdirSync(componentsDir, { recursive: true, encoding: 'utf8' })) {
+    const rel = entry.replace(/\\/g, '/')
+    // The shell itself names its own tag in its header comment — it is not a consumer.
+    if (!rel.endsWith('.vue') || rel.endsWith('panels/ResultWindowShell.vue')) continue
+    const source = readFileSync(`${componentsDir}/${rel}`, 'utf8')
+    if (source.includes('<ResultWindowShell')) found.set(rel, source)
+  }
+  return found
+}
+
+/** The bucket a component passes, or the shell's default when it passes none. */
+function declaredWidth(source: string): ResultWindowWidth {
+  const match = /<ResultWindowShell[\s\S]*?\swidth="([^"]+)"/.exec(source)
+  return (match?.[1] as ResultWindowWidth | undefined) ?? SHELL_DEFAULT_WIDTH
+}
+
+describe('result-window width buckets', () => {
+  const consumers = findConsumers()
+
+  it('finds the shell consumers at all (the scan is doing real work)', () => {
+    expect(existsSync(componentsDir), `no components dir at ${componentsDir}`).toBe(true)
+    expect(consumers.size).toBeGreaterThan(10)
+  })
+
+  it('covers every consumer, with no stale rows', () => {
+    expect([...consumers.keys()].sort()).toEqual(Object.keys(WINDOWS).sort())
+  })
+
+  it('matches what each window actually passes', () => {
+    const actual = [...consumers.entries()].map(([file, source]) => [file, declaredWidth(source)])
+    const declared = Object.entries(WINDOWS).map(([file, row]) => [file, row.width])
+    expect(Object.fromEntries(actual)).toEqual(Object.fromEntries(declared))
+  })
+
+  it('makes every window state a reason for its bucket', () => {
+    for (const [file, row] of Object.entries(WINDOWS)) {
+      expect(row.why.length, `${file} must say why it takes \`${row.width}\``).toBeGreaterThan(20)
+    }
+  })
+
+  // The obligation the shell cannot enforce on its own slot content: a `full` window's continuous
+  // prose carries the step reader's measure, or the extra width lands as 200-character lines. A
+  // window with none anywhere is the shape this catches — it either has no prose (say so by
+  // pointing at the measure it does not need) or it forgot.
+  it('holds every `full` window to the prose reading measure', () => {
+    for (const [file, row] of Object.entries(WINDOWS)) {
+      if (row.width !== 'full') continue
+      const source = consumers.get(file)
+      expect(
+        source?.includes(PROSE_MEASURE_CLASS),
+        `${file} is \`full\`, so its continuous prose must carry \`${PROSE_MEASURE_CLASS}\``,
+      ).toBe(true)
+    }
+  })
+})
+
+describe('RESULT_WINDOW_WIDTH_CLASS', () => {
+  it('caps every bucket at its own name and leaves `full` uncapped', () => {
+    expect(RESULT_WINDOW_WIDTH_CLASS).toEqual({
+      '3xl': 'max-w-3xl',
+      '4xl': 'max-w-4xl',
+      '5xl': 'max-w-5xl',
+      // Not a bigger number: the panel's `w-full` spans the backdrop and the variant's gutter
+      // (`m-4` / `p-4`) is the only inset. A cap here would reintroduce the indefensible number
+      // `full` exists to avoid.
+      full: 'max-w-none',
+    })
+  })
+
+  it('shares one measure with the step reader', () => {
+    // `AgentStepDetail` reads prose at `mx-auto max-w-3xl`; the windows must not hold a second
+    // opinion about how wide prose should be.
+    expect(PROSE_MEASURE_CLASS).toBe('max-w-3xl')
+  })
+})

package/app/components/panels/ResultWindowShell.logic.ts

@@ -0,0 +1,31 @@
+// The result-window width vocabulary, extracted from `ResultWindowShell.vue` so it can be
+// asserted (see `ResultWindowShell.logic.spec.ts`, which pins every window's bucket against a
+// table naming its reason — the shape `nav-contributions.spec.ts` uses for the advanced-nav set).
+//
+// WHICH bucket a window takes, and the reading-measure obligation `full` carries, are documented
+// on the shell's `width` prop — that is what a window author reads. This module owns only the
+// vocabulary and its class mapping.
+
+/** Card width buckets — see `ResultWindowShell.vue`'s `width` prop for what picks `full`. */
+export type ResultWindowWidth = '3xl' | '4xl' | '5xl' | 'full'
+
+/**
+ * The bucket → cap mapping. `full` is deliberately `max-w-none` rather than a bigger number:
+ * the panel's `w-full` then spans the backdrop, which the variant insets by one gutter (`m-4`
+ * stretched, `p-4` centered), so the window fills the screen and still reads as a window rather
+ * than a repaint of the app. A `Record` over the union, so a new bucket fails to compile until
+ * it is mapped.
+ */
+export const RESULT_WINDOW_WIDTH_CLASS: Record<ResultWindowWidth, string> = {
+  '3xl': 'max-w-3xl',
+  '4xl': 'max-w-4xl',
+  '5xl': 'max-w-5xl',
+  full: 'max-w-none',
+}
+
+/**
+ * The reading measure a `full` window puts on a run of continuous prose — the step reader's own
+ * (`AgentStepDetail`, `mx-auto max-w-3xl` over the same 13px `.reader-prose`), so the surfaces
+ * cannot drift into two opinions about how wide prose should be.
+ */
+export const PROSE_MEASURE_CLASS = 'max-w-3xl'

package/app/components/panels/ResultWindowShell.vue

@@ -26,6 +26,10 @@ import StepRestartControl from '~/components/panels/StepRestartControl.vue'
 import StepEffortReport from '~/components/panels/StepEffortReport.vue'
 import StepValidationReport from '~/components/panels/StepValidationReport.vue'
 import { effortBand, effortHint } from '~/utils/effort'
+import {
+  RESULT_WINDOW_WIDTH_CLASS,
+  type ResultWindowWidth,
+} from '~/components/panels/ResultWindowShell.logic'
 
 /** A pipeline step reference — passed by step-result windows to surface the shared
  *  "restart from here" control. `StepRestartControl` self-hides for an off-path open
@@ -42,8 +46,38 @@ const props = withDefaults(
     /** Header title (the accessible dialog name) + optional secondary line. */
     title: string
     subtitle?: string
-    /** Card width bucket + backdrop layout (the two pre-slice-5 chrome variants). */
-    width?: '3xl' | '4xl' | '5xl'
+    /**
+     * Card width bucket + backdrop layout (the two pre-slice-5 chrome variants).
+     *
+     * `full` is the REVIEW/READING bucket: the panel takes the whole viewport minus the
+     * shell's own gutter, the shape the full-bleed step reader (`AgentStepDetail`) already
+     * has. It is for a window whose body lays out in COLUMNS — rails plus a fluid main
+     * column — where the width buys visible layout: the outline and the review rail stop
+     * competing with the document, a findings list stops wrapping every card, a diff or a
+     * results table stops scrolling sideways. A window that is one column of prose or a
+     * short verdict keeps a bucket: stretching two paragraphs across an ultrawide reads
+     * worse, not better.
+     *
+     * The obligation that comes with it: CONTINUOUS PROSE inside a `full` window carries its
+     * own reading measure (`PROSE_MEASURE_CLASS`, the step reader's own, over the same 13px
+     * `.reader-prose`), or the width lands as 200-character lines.
+     *
+     * The unit that obligation attaches to is the PARAGRAPH, not the section — which is the
+     * distinction to get right, because "a findings list reads better at the full span" is
+     * true of the LIST and false of the prose inside each row. A list's rows, badge rows,
+     * control rows, tables, Gherkin blocks, log tails and inputs all take the span; a
+     * finding's detail, a recorded answer, an investigator's justification and a summary
+     * paragraph are prose wherever they sit, and take the measure. Sizing by section is how a
+     * card whose answer control is STACKED under its question — every finding card here —
+     * ends up arguing that its question is "beside" something and keeping 200-character lines.
+     *
+     * What `full` costs: click-outside effectively goes, since the backdrop is then only the
+     * shell's own gutter. That is the same trade the full-bleed reader already makes (it has
+     * no backdrop close at all), and Escape plus the header's close button — the two paths a
+     * keyboard and a pointer user actually reach for — are untouched. A window that wants
+     * click-outside to stay hittable is a window that should have kept a bucket.
+     */
+    width?: ResultWindowWidth
     variant?: 'stretch' | 'centered'
     /** Provide on step-result windows to show the shared restart control; omit on gates
      *  and block-keyed windows (no restart mid-gate / pre-run). */
@@ -119,18 +153,13 @@ const chipClass = computed(() =>
   effortReport.value ? CHIP_CLASS[effortBand(effortReport.value.difficulty)] : '',
 )
 
-const WIDTH: Record<'3xl' | '4xl' | '5xl', string> = {
-  '3xl': 'max-w-3xl',
-  '4xl': 'max-w-4xl',
-  '5xl': 'max-w-5xl',
-}
 const backdropClass = computed(() => [
   'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-slate-950/70 backdrop-blur-sm',
   props.variant === 'centered' ? 'items-center p-4' : 'items-stretch',
 ])
 const panelClass = computed(() => [
   'flex w-full flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl',
-  WIDTH[props.width],
+  RESULT_WINDOW_WIDTH_CLASS[props.width],
   props.variant === 'centered' ? 'max-h-[90dvh]' : 'm-4',
 ])
 </script>

package/app/components/prReview/PrReviewWindow.vue

@@ -266,7 +266,7 @@ async function onDismiss(id: string): Promise<void> {
     icon-class="bg-indigo-500/15 text-indigo-300"
     :title="block ? t('prReview.titleWithBlock', { title: block.title }) : t('prReview.title')"
     :subtitle="t('prReview.subtitle')"
-    width="3xl"
+    width="full"
     testid="pr-review-window"
     @close="close"
   >
@@ -525,10 +525,11 @@ async function onDismiss(id: string): Promise<void> {
             </p>
           </div>
 
-          <!-- The reviewer's overall assessment. -->
+          <!-- The reviewer's overall assessment. Prose, so it takes the reading measure (see the
+               shell's `width` prop) — this window is `full`-width. -->
           <p
             v-if="state?.summary"
-            class="mb-3 rounded-md bg-slate-800/50 px-3 py-2 text-[12px] text-slate-300"
+            class="mb-3 max-w-3xl rounded-md bg-slate-800/50 px-3 py-2 text-[12px] text-slate-300"
           >
             <span class="text-slate-500">{{ t('prReview.summaryLabel') }}</span>
             {{ state.summary }}
@@ -579,7 +580,7 @@ async function onDismiss(id: string): Promise<void> {
               <h3 class="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
                 {{ g.title }}
               </h3>
-              <p v-if="g.rationale" class="mb-1.5 text-[11px] text-slate-500">
+              <p v-if="g.rationale" class="mb-1.5 max-w-3xl text-[11px] text-slate-500">
                 {{ g.rationale }}
               </p>
               <article
@@ -672,15 +673,22 @@ async function onDismiss(id: string): Promise<void> {
                         · {{ t('prReview.line', { line: f.line }) }}</template
                       >
                     </p>
+                    <!-- The reviewer's prose — what the finding is, what to do about it, and the
+                         investigator's verdict below. Each takes the reading measure even though
+                         the card around it takes the span (see the shell's `width` prop: the unit
+                         is the paragraph, not the section). This window went from the NARROWEST
+                         bucket to `full`, so these are the three paragraphs the width would
+                         otherwise have stretched furthest; the path/line row, the badges and the
+                         per-finding actions are what it is actually for. -->
                     <p
-                      class="mt-1 whitespace-pre-wrap text-[12px] text-slate-300"
+                      class="mt-1 max-w-3xl whitespace-pre-wrap text-[12px] text-slate-300"
                       :class="isRetracted(f) ? 'line-through' : ''"
                     >
                       {{ f.detail }}
                     </p>
                     <p
                       v-if="f.suggestedFix"
-                      class="mt-1 whitespace-pre-wrap rounded-md bg-slate-800/50 px-2 py-1 text-[11px] text-slate-300"
+                      class="mt-1 max-w-3xl whitespace-pre-wrap rounded-md bg-slate-800/50 px-2 py-1 text-[11px] text-slate-300"
                     >
                       <span class="text-slate-500">{{ t('prReview.suggestedFix') }}</span>
                       {{ f.suggestedFix }}
@@ -691,7 +699,7 @@ async function onDismiss(id: string): Promise<void> {
                     <p
                       v-if="f.challenge?.justification"
                       data-testid="pr-review-finding-justification"
-                      class="mt-1.5 whitespace-pre-wrap rounded-md px-2 py-1 text-[11px]"
+                      class="mt-1.5 max-w-3xl whitespace-pre-wrap rounded-md px-2 py-1 text-[11px]"
                       :class="
                         isRetracted(f)
                           ? 'bg-rose-500/10 text-rose-200'

package/app/components/requirements/RequirementsReviewWindow.vue

@@ -653,7 +653,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
     :subtitle="block?.title"
     :step-ref="{ instanceId, stepIndex }"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <template v-if="review" #header-extras>
@@ -796,7 +796,11 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                         {{ 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 mode buttons
+                         and textarea 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>
 
@@ -804,7 +808,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                            ones 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('requirements.answerLabel') }}
@@ -925,7 +929,9 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                             >
                               {{ GROUNDING_LABELS[rec.groundedIn] }}
                             </UBadge>
-                            <p class="mt-1 whitespace-pre-line text-sm text-slate-300">
+                            <!-- The Writer's suggested answer — agent prose, so it takes the
+                                 measure like the finding's own question above it. -->
+                            <p class="mt-1 max-w-3xl whitespace-pre-line text-sm text-slate-300">
                               {{ rec.recommendedText }}
                             </p>
                             <div class="mt-2 flex flex-wrap items-center gap-2">
@@ -1037,7 +1043,11 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                 }}
               </span>
             </button>
-            <div v-show="!docCollapsed">
+            <!-- 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. Left-aligned rather than centred, so
+                 it starts where every finding above it starts. -->
+            <div v-show="!docCollapsed" class="max-w-3xl">
               <div v-for="s in outline.sections" :key="s.id" class="mb-2">
                 <button
                   v-if="s.title"

package/app/components/spec/ServiceSpecWindow.vue

@@ -185,7 +185,7 @@ function kindLabel(item: RequirementItem): string {
     :title="t('spec.title')"
     :subtitle="block ? spec?.service || block.title : undefined"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <!-- view toggle: Gherkin only when the spec (and its feature files) are on main -->
@@ -318,7 +318,10 @@ function kindLabel(item: RequirementItem): string {
         <!-- service overview -->
         <template v-if="selected === null">
           <h2 class="text-lg font-semibold text-white">{{ spec?.service }}</h2>
-          <p v-if="spec?.summary" class="mt-2 whitespace-pre-line text-sm text-slate-300">
+          <!-- The service's own prose, so it takes the reading measure the shell's `full` width
+               obliges (see the `width` prop). The requirement rows and Gherkin blocks below keep
+               the full span — they are structure, not paragraphs. -->
+          <p v-if="spec?.summary" class="mt-2 max-w-3xl whitespace-pre-line text-sm text-slate-300">
             {{ spec.summary }}
           </p>
           <p v-else class="mt-2 text-sm text-slate-500">{{ t('spec.noSummary') }}</p>
@@ -352,7 +355,7 @@ function kindLabel(item: RequirementItem): string {
             {{ selectedModule?.name }}
           </div>
           <h2 class="text-lg font-semibold text-white">{{ selectedGroup.name }}</h2>
-          <p v-if="selectedGroup.summary" class="mt-1 text-sm text-slate-400">
+          <p v-if="selectedGroup.summary" class="mt-1 max-w-3xl text-sm text-slate-400">
             {{ selectedGroup.summary }}
           </p>
 
@@ -500,7 +503,7 @@ function kindLabel(item: RequirementItem): string {
                 <UIcon name="i-lucide-shield-check" class="h-3.5 w-3.5" />
                 {{ t('spec.domainRules') }}
               </div>
-              <ul class="space-y-1.5">
+              <ul class="max-w-3xl space-y-1.5">
                 <li
                   v-for="rule in selectedGroup.rules ?? []"
                   :key="rule.id"

package/app/components/testing/TestReportWindow.vue

@@ -313,7 +313,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
     :title="headerTitle"
     :subtitle="t('testing.subtitle')"
     :step-ref="{ instanceId, stepIndex }"
-    width="5xl"
+    width="full"
     testid="tester-report-window"
     @close="close"
   >
@@ -489,7 +489,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                 :icon="a.outcome === 'completed' ? 'i-lucide-wrench' : 'i-lucide-circle-x'"
                 :icon-class="a.outcome === 'completed' ? 'text-amber-300' : 'text-rose-400'"
               />
-              <p v-if="a.summary" class="mt-1 text-[12px] leading-snug text-slate-400">
+              <p v-if="a.summary" class="mt-1 max-w-3xl text-[12px] leading-snug text-slate-400">
                 {{ a.summary }}
               </p>
               <div v-if="a.concerns && a.concerns.length" class="mt-1.5">
@@ -607,8 +607,13 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
         </div>
 
         <template v-else>
-          <!-- Summary -->
-          <p v-if="report.summary" class="mb-4 text-[13px] leading-relaxed text-slate-300">
+          <!-- Summary — the tester's own prose, so it takes the reading measure the shell's `full`
+               width obliges (see the `width` prop). The scenario rows and log tails below keep the
+               full span. -->
+          <p
+            v-if="report.summary"
+            class="mb-4 max-w-3xl text-[13px] leading-relaxed text-slate-300"
+          >
             {{ report.summary }}
           </p>
 
@@ -675,7 +680,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                   />
                   <div class="min-w-0">
                     <span class="text-[13px] text-slate-200">{{ o.name }}</span>
-                    <p v-if="o.detail" class="text-[12px] leading-snug text-slate-400">
+                    <p v-if="o.detail" class="max-w-3xl text-[12px] leading-snug text-slate-400">
                       {{ o.detail }}
                     </p>
                   </div>
@@ -705,7 +710,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                         {{ SEVERITY_LABELS[c.severity] }}
                       </span>
                     </div>
-                    <p v-if="c.detail" class="text-[12px] leading-snug text-slate-400">
+                    <p v-if="c.detail" class="max-w-3xl text-[12px] leading-snug text-slate-400">
                       {{ c.detail }}
                     </p>
                   </div>

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isSafeTargetId,
+  isTargetClickAdvance,
+  resolveSkip,
+  stepTargetIds,
+  stepTargetSelectors,
+  tourWasAbridged,
+  waitBudgetMs,
+} from '~/components/tutorial/TutorialOverlay.logic'
+import { DEFAULT_TARGET_WAIT_MS } from '~/utils/tutorial'
+import type { TutorialStep } from '~/utils/tutorial'
+
+const step = (over: Partial<TutorialStep> = {}): TutorialStep => ({
+  id: 'a-step',
+  titleKey: 'tutorial.tours.x.steps.a.title',
+  bodyKey: 'tutorial.tours.x.steps.a.body',
+  ...over,
+})
+
+describe('stepTargetIds', () => {
+  it('lists the target then its fallbacks, in order', () => {
+    expect(
+      stepTargetIds(step({ target: 'frame-add-task', altTargets: ['frame-add-task-empty'] })),
+    ).toEqual(['frame-add-task', 'frame-add-task-empty'])
+  })
+
+  it('is empty for an untargeted (centered) step', () => {
+    expect(stepTargetIds(step())).toEqual([])
+  })
+})
+
+describe('isSafeTargetId', () => {
+  it('accepts the kebab-case ids the repo actually uses', () => {
+    for (const id of ['task-card', 'add-task-submit', 'board-fit-view', 'nav-tutorial', 'h2'])
+      expect(isSafeTargetId(id), id).toBe(true)
+  })
+
+  it('rejects anything that could end up inside a selector as syntax', () => {
+    for (const id of ['od"d', "od'd", 'back\\slash', 'a b', 'a]b', 'Upper', ''])
+      expect(isSafeTargetId(id), id).toBe(false)
+  })
+})
+
+describe('stepTargetSelectors', () => {
+  it('builds the data-testid selectors, target first then fallbacks', () => {
+    const s = step({ target: 'frame-add-task', altTargets: ['frame-add-task-empty'] })
+    expect(stepTargetSelectors(s)).toEqual([
+      '[data-testid="frame-add-task"]',
+      '[data-testid="frame-add-task-empty"]',
+    ])
+  })
+
+  it('drops a malformed id rather than building a selector that could throw', () => {
+    // A tour is DATA a consumer deployment authors, so an id arrives from outside this
+    // package. A bad one must degrade to "anchor not found" (a skipped step) — NOT to a
+    // SyntaxError raised out of the 150ms tracking interval, several times a second.
+    const s = step({ target: 'od"d', altTargets: ['task-card'] })
+    expect(stepTargetSelectors(s)).toEqual(['[data-testid="task-card"]'])
+    for (const selector of stepTargetSelectors(s))
+      expect(() => document.querySelector(selector)).not.toThrow()
+  })
+
+  it('is empty for an untargeted step', () => {
+    expect(stepTargetSelectors(step())).toEqual([])
+  })
+})
+
+describe('waitBudgetMs', () => {
+  it('defaults, and honours a step that waits on a just-opened modal', () => {
+    expect(waitBudgetMs(step())).toBe(DEFAULT_TARGET_WAIT_MS)
+    expect(waitBudgetMs(step({ waitForTargetMs: 8000 }))).toBe(8000)
+  })
+})
+
+describe('resolveSkip', () => {
+  it('continues forward past a missing anchor', () => {
+    expect(resolveSkip(1, 'forward', 4)).toEqual({ kind: 'move', index: 2 })
+  })
+
+  it('completes the tour when the last step is the one that went missing', () => {
+    expect(resolveSkip(3, 'forward', 4)).toEqual({ kind: 'complete' })
+  })
+
+  it('keeps travelling BACK when the user is stepping backwards', () => {
+    // Otherwise Back onto a step this deployment does not render bounces the user
+    // straight forward again, making the button unusable exactly where it is needed.
+    expect(resolveSkip(2, 'back', 4)).toEqual({ kind: 'move', index: 1 })
+  })
+
+  it('reverses to forward rather than pinning on the first step', () => {
+    expect(resolveSkip(0, 'back', 4)).toEqual({ kind: 'move', index: 1 })
+  })
+
+  it('completes a single-step tour whose only anchor never appeared', () => {
+    expect(resolveSkip(0, 'back', 1)).toEqual({ kind: 'complete' })
+    expect(resolveSkip(0, 'forward', 1)).toEqual({ kind: 'complete' })
+  })
+})
+
+describe('isTargetClickAdvance', () => {
+  const el = document.createElement('button')
+  const child = document.createElement('span')
+  el.appendChild(child)
+
+  it('advances on a real click on the highlighted control, or inside it', () => {
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, el, el)).toBe(true)
+    expect(isTargetClickAdvance(s, el, child)).toBe(true)
+  })
+
+  it('ignores clicks elsewhere, on a Next-advanced step, or with no anchor', () => {
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, el, document.createElement('div'))).toBe(false)
+    expect(isTargetClickAdvance(s, null, el)).toBe(false)
+    expect(isTargetClickAdvance(step({ target: 'x' }), el, el)).toBe(false)
+    expect(isTargetClickAdvance(null, el, el)).toBe(false)
+  })
+})
+
+describe('tourWasAbridged', () => {
+  it('is true once any step was skipped, so the finish card can say so', () => {
+    expect(tourWasAbridged(new Set())).toBe(false)
+    expect(tourWasAbridged(new Set(['addTask']))).toBe(true)
+  })
+})