# UI Element Matrix Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use /ship (recommended) or /executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add declarative per-page UI state regression coverage for Overdeck dashboard routes.

**Architecture:** One Playwright spec owns route invariants and high-value element-state manifest. It reuses existing fixture collector; no auth fixture or visual/a11y infrastructure is introduced.

**Tech Stack:** Astro, React, Playwright, TypeScript.

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|---|---|---|---|
| 1 | Task 1 | `apps/web/tests/ui-matrix.spec.ts` | single task |

## Files

- Create `apps/web/tests/ui-matrix.spec.ts` — declarative route sweep and element-state runner.

### Task 1: Declarative dashboard UI matrix

**Wave:** 1
**Blocks:** —
**Blocked by:** —

**Files:**

- Create: `apps/web/tests/ui-matrix.spec.ts` — fixture-backed route invariant sweep and high-value element manifest.

**Contract:**

- Reuse `startFixtureCollector`, `ALL_PANELS`, `ADAPTER_STATUSES`, and `ALL_ITEMS`.
- Define `UiState = 'present' | 'enabled' | 'disabled' | 'editable' | 'absent'` and manifest entries with route, name, locator, state, optional `required`.
- Cover routes `/`, `/inbox`, `/plans`, `/agents`, `/ci`, `/bots`, `/limits`, `/gates`, `/scoreboard`, `/settings`, `/decisions`, `/map` with route-specific accessible heading invariant.
- Cover exact matrix states: Settings project color input editable and save enabled; Inbox `Reap` enabled and non-gateway action disabled; destructive confirmation dialog present with enabled Cancel and submit controls; Decisions queue controls present.

**Behavior:**

- Generic sweep collects page errors, `console.error` messages, and failed `fetch`/`xhr` requests for each route.
- Each route must await its declared heading, then assert all three failure collections are empty.
- Generic manifest runner must assert every entry exactly; never branch on locator visibility.
- Use semantic or existing stable selectors only. Never use DOM ordinal selectors.

**Acceptance:**

- Run: `pnpm exec playwright test apps/web/tests/ui-matrix.spec.ts`
- Expected: PASS — all route sweep and matrix cases pass.

- [ ] Write failing route-invariant and element-state tests.
- [ ] Run target spec; confirm expected red failure before implementation.
- [ ] Implement minimal manifest runner and entries.
- [ ] Run target spec; confirm pass without warnings.
- [ ] Run `pnpm typecheck`; confirm pass without warnings.
- [ ] Commit: `git add apps/web/tests/ui-matrix.spec.ts && git commit -m "test: add ui element matrix"`