@cat-factory/app 0.196.1 → 0.198.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)
 
@@ -54,6 +55,27 @@ 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.                                                                                                                                   |
 
+### 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
+caller is not always a component: `plugins/modular.client.ts` builds the nav gates
+(`createNavGates`) during plugin setup, which instantiates a handful of stores before any
+component exists. So nothing a store reaches for at setup time may require an active
+component instance.
+
+The one that bites is **`useI18n()`, which throws `MUST_BE_CALL_SETUP_TOP` outside a
+component** — and because it happens inside a plugin, Nuxt's error boundary replaces the
+whole app with its 500 page rather than surfacing a broken feature. Resolve translations
+through the Nuxt app's global i18n instance instead (`useNuxtApp().$i18n`, typed as
+`ReturnType<typeof useI18n>`), as `stores/board.ts`, `stores/recurringPipelines.ts` and
+`composables/usePipelineErrorToast.ts` do. This costs no typed-message-key coverage: tier 1
+only sees literal keys written in a `<script setup>`, never in a `.ts` store or composable.
+
+The blast radius is why this is a rule rather than a preference — a store reached one call
+earlier than before takes the entire SPA down at boot, and the unit suite cannot see it
+(nothing there installs the plugin). Every e2e spec does, because every one of them boots
+the app.
+
 ### Always import a layer component explicitly
 
 **Import a component under `components/` by path before using it in a template.** Do not lean on Nuxt's auto-registration. This layer sets no `components` config, so the default `pathPrefix: true` applies and a component is registered under its path-prefixed name: `components/panels/StepEffortReport.vue` becomes `PanelsStepEffortReport`, and a bare `<StepEffortReport>` matches nothing.
@@ -159,6 +181,89 @@ 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).
+
+**A step carries its own `when(gates)` when its BRANCH, not its control, is the thing that
+may not apply.** The two are different facts and only one of them is a defect: a skip means
+the control should be here and isn't, while a `when` means this board is not on that branch
+of the flow (a run parked on a decision has no approval gate, and the reverse). Reporting the
+second as an abridged tour would tell a user who saw exactly the right walkthrough that they
+missed half of it, every time. `resolveTours` (in `utils/tutorial.ts`, applied by
+`navSlotFilter`) drops the rejected steps and then drops a tour left with none, so a tour
+whose every step is branch-specific can never open on an empty cursor. With no gates service
+wired at all (a bare install withholds nothing) every branch survives instead, and only one
+of them can anchor — so the abridged notice ignores any skipped step that carries a `when`,
+which has already declared that not applying is legitimate.
+
+**Gates decide what is OFFERED; the running tour's script is resolved once and HELD.** The
+overlay snapshots its tour when it starts rather than re-reading the gated slot on every
+flip. This is not an optimisation: gates over live run state flip as a direct result of
+following the tour — `answer-park` is offered while something waits for a human, so the
+moment the user answers, its `when` goes false. A re-reading overlay tore itself down there,
+one step short of its own finish card and with nothing recorded as completed, at exactly the
+moment the user succeeded. Holding the script also freezes the branch `resolveTours` chose,
+so a step can't be swapped underneath a stationary cursor.
+
+**Gates must mean what the board RENDERS, not what the store holds.** `boardHasOpenDecision`
+/ `boardHasPendingApproval` are not the store's raw pending counts: a park on a frame block
+has no task card, and a reviewer gate mid-cycle is deliberately suppressed by the card
+(`useReviewStage().isBackground`), so either would offer a tour onto a control that isn't
+there. `hasActionablePark` (`modular/nav-gates.logic.ts`) is the shared rule; the run gates
+are task-scoped for the same reason.
+
+**Fixed proper nouns ride `bodyParams`, not the catalogs.** A step naming the sample
+repository slug (`SAMPLE_REPO` in `modular/tutorial-tours.ts`) passes it as a `{repo}`
+interpolation, so it is written once in code rather than translated into ten catalogs that
+each drift on their own — the same split components make for inline placeholders.
+
+The built-ins walk the delivery loop end to end, each gated on the state the previous one
+leaves behind, so the launch prompt only ever offers what this board can demonstrate: board
+basics, add a repository (`add-service`), create a task (`first-task`), run it (`run-task`),
+answer it when it parks (`answer-park`), review and merge the result (`review-merge`). One
+deliberate asymmetry: `run-task` points at Start without click-to-advance, because starting a
+run spends real model budget and nobody should discover they agreed to that by following a
+tutorial.
+
+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, which skips count as abridged) lives in
+`components/tutorial/TutorialOverlay.logic.ts` so it is unit-tested; the SFC keeps only the
+DOM work. Note that target-click matching is by SELECTOR, not by the highlighted element:
+several anchors (`task-card`, `task-resolve`, `run-step`) render once per board item and the
+ring can only sit on one of them, so requiring the click to land on that one left a user who
+clicked the card the copy asked for with no way forward — such a step renders no Next.
+
+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/github/AddServiceFromRepoModal.vue

@@ -380,7 +380,11 @@ function done() {
             :description="t('github.addService.repositoryHint')"
             required
           >
-            <div class="space-y-1.5">
+            <!-- The wrapper, not the UInputMenu itself, carries the anchor: a tutorial tour
+                 stop needs an element that is present the moment the modal mounts, and it
+                 highlights the whole field rather than whichever inner node Nuxt UI happens
+                 to forward the attribute to. -->
+            <div class="space-y-1.5" data-testid="add-service-repo-search">
               <UInputMenu
                 v-model="selectedRepoId"
                 v-model:search-term="repoSearch"
@@ -553,6 +557,7 @@ function done() {
               icon="i-lucide-plus"
               :loading="adding"
               :disabled="!canAdd"
+              data-testid="add-service-submit"
               @click="add"
             >
               {{ t('github.addService.add') }}

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

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isSafeTargetId,
+  isTargetClickAdvance,
+  resolveSkip,
+  stepTargetIds,
+  stepTargetSelectors,
+  unexpectedlySkippedSteps,
+  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', () => {
+  /** A control carrying `id`, with a nested span, mounted so `closest` can walk to it. */
+  const control = (id: string) => {
+    const el = document.createElement('button')
+    el.setAttribute('data-testid', id)
+    el.appendChild(document.createElement('span'))
+    document.body.appendChild(el)
+    return el
+  }
+
+  it('advances on a real click on the control, or inside it', () => {
+    const el = control('add-task-submit')
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, el)).toBe(true)
+    expect(isTargetClickAdvance(s, el.firstChild)).toBe(true)
+  })
+
+  it('advances on ANY instance of a control the board renders per item', () => {
+    // `task-card` / `task-resolve` / `run-step` exist once per board item, and the ring can
+    // only sit on one of them. Requiring the click to land on THAT one left a user who
+    // clicked the card the step's copy asked for with no way forward — a click-to-advance
+    // step renders no Next button.
+    control('task-card')
+    const second = control('task-card')
+    const s = step({ target: 'task-card', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, second)).toBe(true)
+  })
+
+  it('advances on a fallback anchor too, since either is the control the step named', () => {
+    const s = step({ target: 'ui-mode-switcher', altTargets: ['ui-mode-toggle'] })
+    expect(
+      isTargetClickAdvance({ ...s, advanceOn: 'target-click' }, control('ui-mode-toggle')),
+    ).toBe(true)
+  })
+
+  it('ignores clicks elsewhere, on a Next-advanced step, or on a non-element', () => {
+    const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, control('run-start'))).toBe(false)
+    expect(isTargetClickAdvance(s, null)).toBe(false)
+    expect(isTargetClickAdvance(s, document.createTextNode('stray'))).toBe(false)
+    expect(isTargetClickAdvance(step({ target: 'add-task-submit' }), control('x'))).toBe(false)
+    expect(isTargetClickAdvance(null, control('y'))).toBe(false)
+  })
+})
+
+describe('unexpectedlySkippedSteps', () => {
+  const plain = step({ id: 'addTask', target: 'frame-add-task' })
+  const branch = step({ id: 'approve', target: 'step-approve', when: () => true })
+
+  it('counts a skipped step whose control simply was not there', () => {
+    expect(unexpectedlySkippedSteps(new Set(['addTask']), [plain, branch])).toEqual([plain])
+  })
+
+  it('does not count a branch-gated step, whose absence it already declared legitimate', () => {
+    // The gates-absent case (a bare install withholds nothing, so BOTH branches of a tour
+    // are kept and only one can ever anchor). Reporting that as abridged would put a
+    // permanent "you missed some of this" on a tour that showed exactly the right branch.
+    expect(unexpectedlySkippedSteps(new Set(['approve']), [plain, branch])).toEqual([])
+  })
+
+  it('is empty for a tour that skipped nothing', () => {
+    expect(unexpectedlySkippedSteps(new Set(), [plain, branch])).toEqual([])
+  })
+})

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

@@ -0,0 +1,125 @@
+import { DEFAULT_TARGET_WAIT_MS } from '~/utils/tutorial'
+import type { TutorialStep } from '~/utils/tutorial'
+
+/**
+ * The tour runtime's decision logic, extracted from `TutorialOverlay.vue` so it is
+ * unit-testable (the vitest setup has no SFC transform — same split as
+ * `AppOverlayHost.logic.ts`). The component keeps the DOM work (querying, measuring,
+ * listeners); everything that DECIDES something lives here.
+ */
+
+/**
+ * Which way the step cursor is travelling. It matters only for a step whose anchor
+ * never appears: a skip must continue in the direction the user was already going,
+ * or pressing Back onto a step whose control this deployment doesn't render would
+ * bounce them straight forward again — an unusable Back button.
+ */
+export type TutorialDirection = 'forward' | 'back'
+
+/** What the overlay does with a step whose anchor never appeared. */
+export type SkipOutcome = { kind: 'move'; index: number } | { kind: 'complete' }
+
+/**
+ * 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
+ * nothing real — which is what makes it usable as a GUARD rather than as escaping.
+ *
+ * A tour is DATA and a consumer deployment authors its own, so an id reaches
+ * `querySelector` from outside this package. Escaping it is the obvious move and the wrong
+ * one: `[data-testid="a\"b"]` is valid CSS that real selector engines disagree about (it
+ * throws in happy-dom), so an id with a quote could still take down the tracking interval —
+ * several times a second, for as long as the tour runs. Validating the shape instead means
+ * no selector is ever built from a string that could break one, and an id that fails simply
+ * finds no anchor, which the runtime already handles as a skipped step.
+ */
+export const TARGET_ID_PATTERN = /^[a-z0-9-]+$/
+
+/** Is this a well-formed anchor id, i.e. safe to put in a selector? */
+export function isSafeTargetId(id: string): boolean {
+  return TARGET_ID_PATTERN.test(id)
+}
+
+/** The `data-testid`s a step declares, in priority order (target first, then fallbacks). */
+export function stepTargetIds(step: TutorialStep): string[] {
+  return [step.target, ...(step.altTargets ?? [])].filter((id): id is string => id !== undefined)
+}
+
+/** The selectors to try for a step: its declared ids, minus any that are malformed. */
+export function stepTargetSelectors(step: TutorialStep): string[] {
+  return stepTargetIds(step)
+    .filter(isSafeTargetId)
+    .map((id) => `[data-testid="${id}"]`)
+}
+
+/** How long this step may spend looking for its anchor before it is skipped. */
+export function waitBudgetMs(step: TutorialStep): number {
+  return step.waitForTargetMs ?? DEFAULT_TARGET_WAIT_MS
+}
+
+/**
+ * Where the cursor goes when the current step's anchor never appeared.
+ *
+ * Travelling BACK off the first step has nowhere further back to go, so it reverses to
+ * forward rather than pinning the tour on an anchor that is never coming.
+ */
+export function resolveSkip(
+  index: number,
+  direction: TutorialDirection,
+  total: number,
+): SkipOutcome {
+  if (direction === 'back' && index > 0) return { kind: 'move', index: index - 1 }
+  return index + 1 < total ? { kind: 'move', index: index + 1 } : { kind: 'complete' }
+}
+
+/** The part of a clicked node this check needs: CSS-selector ancestry. */
+interface ClickedNode {
+  closest(selector: string): unknown
+}
+
+/** The clicked node as something we can ask about ancestry, or null (a text node, `document`). */
+function asClickedNode(eventTarget: EventTarget | null): ClickedNode | null {
+  const node = eventTarget as ClickedNode | null
+  return node && typeof node.closest === 'function' ? node : null
+}
+
+/**
+ * Does this real click count as the "now click this" step's advance?
+ *
+ * Matched against the step's SELECTORS rather than against the one element the tracker
+ * happened to highlight, because several of the controls a tour points at are rendered once
+ * PER BOARD ITEM: `task-card`, `task-resolve`, `run-step`. The tracker anchors its ring to
+ * the first match in the DOM, which is not necessarily the card the step's own copy is
+ * asking for ("open a task whose run has finished"). Requiring the click to land inside THAT
+ * element meant a user who clicked the right card got no advance at all — and a
+ * click-to-advance step renders no Next button, so the tour had no way forward but Skip.
+ * Any instance of the control the step names is the action the step asked for.
+ */
+export function isTargetClickAdvance(
+  step: TutorialStep | null,
+  eventTarget: EventTarget | null,
+): boolean {
+  if (!step || step.advanceOn !== 'target-click') return false
+  const node = asClickedNode(eventTarget)
+  if (!node) return false
+  return stepTargetSelectors(step).some((selector) => node.closest(selector) != null)
+}
+
+/**
+ * The skipped steps whose absence is a DEFECT — which is what the final card's "abridged"
+ * notice is about: the controls those steps point at aren't part of this board/role/
+ * deployment, so saying nothing would congratulate the user on a walkthrough they never saw.
+ *
+ * A step carrying a `when` is excluded, because it has already declared that not applying is
+ * a legitimate state rather than a missing control. Normally such a step is DROPPED before
+ * the tour runs (see `resolveTours`), so it never reaches the skip path at all — but with no
+ * gates service wired (a bare install, where nothing is withheld) every branch of a tour is
+ * kept, and exactly one of them can ever anchor. Counting the other as abridged would put a
+ * permanent "you missed some of this" on a tour that showed the user precisely the branch
+ * their board is on.
+ */
+export function unexpectedlySkippedSteps(
+  skippedStepIds: ReadonlySet<string>,
+  steps: readonly TutorialStep[],
+): TutorialStep[] {
+  return steps.filter((s) => skippedStepIds.has(s.id) && s.when === undefined)
+}