From 7fb91de71d369b52726249158380b01a7be90173 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 20 Sep 2026 17:17:48 +1000 Subject: [PATCH] docs(webui): migration checklist for the Vue + shadcn-vue port Records what has to exist again, the contracts that break silently if missed (embed output shape, the Go route registry, capability gating, the single fetch path, SSE teardown), and the behaviour shipped today that lives only in the deleted tree -- the chat launcher, the topbar shrink rules, the clamped activity detail, the corrected contrast tokens, the readyState-derived stream state. Five deleted modules are framework-free and port by rename; each encodes a bug fixed today, so re-deriving them by hand is how those bugs come back. --- docs/prds/vue-migration-checklist.md | 176 +++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/prds/vue-migration-checklist.md diff --git a/docs/prds/vue-migration-checklist.md b/docs/prds/vue-migration-checklist.md new file mode 100644 index 000000000..b26a0f377 --- /dev/null +++ b/docs/prds/vue-migration-checklist.md @@ -0,0 +1,176 @@ +# Preact → Vue 3 + shadcn-vue migration checklist + +**Status:** In progress +**Date:** 2026-09-20 +**Bead:** `archie-core-ocfm` (navigation restructure, folded in below) +**Bootstrap commit:** `e18fb8b2` + +The Preact dashboard was deleted, not ported incrementally. This is the list of +what has to exist again, what must not be lost on the way, and the contracts +that break silently if missed. + +Deleted source is recoverable at `git show e18fb8b2^:ui/src/`. + +## Invariants that outlive the framework + +These are not features; they are things other processes depend on. Breaking one +does not show up as a broken page. + +- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build + must keep `base: "./"` and unhashed `assets/index.{js,css}`. Already set + in `vite.config.ts`; do not let a later Vite change reintroduce hashing. +- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the + route table and `TestDashboardPagesRegistryCoversEveryRoute` parses + `ui/src/router/index.ts` to hold them in step. Adding a route without a + registry entry fails the gate; that guard caught a stale `/chat` entry + earlier today. Keep the `const routes = [` / one-per-line / `nav: false` + shape the parser expects. +- [ ] **Hash routing.** Every existing bookmark, dashboard link and + agent-issued navigation is `#/tasks`. `createWebHashHistory`, already set. +- [ ] **Capability gating.** `GET /api/capabilities` returns which `section`s + the serving process can back; a route whose section is absent must be + hidden, not rendered empty. Was `capabilities.jsx` + + `hiddenRoutes(caps, routes)`. Fail open: unknown or failed response hides + nothing. +- [ ] **Single fetch path.** Every call went through one `send()` in + `base/api.jsx` so the CSRF header, content type, timeout and `ApiError` + shape lived in one place. A test used to fail if a second `fetch()` + appeared there. Port the constraint, not just the functions. +- [ ] **SSE lifecycle.** `subscribeLogs` and the dashboard event stream must be + torn down on unmount or the app leaks a connection per navigation. Preact + did this with an `archie:teardown` event; Vue should use `onUnmounted`. + +## Phase 1 — Foundation + +- [ ] **Theme.** `css/tokens.css` was a complete two-theme semantic token set + (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Map it + onto Tailwind v4's `@theme` so shadcn components inherit it. Do not keep + both systems. +- [ ] **`color-scheme`.** `[data-theme="dark"] { color-scheme: dark }` and the + light equivalent. Without it the UA paints light scrollbars and light + native controls inside the dark app. Fixed today; trivially lost. +- [ ] **Contrast values.** Carry the corrected tokens, not the originals: + `--fg-subtle` `#7d8b9e` dark / `#636f82` light, and `--accent-fg` + `#0d1014` on the dark accent. The originals failed WCAG AA at 3.37:1, + 2.72:1 and 3.2:1. The accent itself is unchanged and is also the link + colour. +- [ ] **API client** (`base/api.jsx` → `src/lib/api.ts`). ~45 methods; list + recoverable from the deleted file. Keep `ApiError` carrying `status`, and + the 401/4xx/5xx classification callers branch on. +- [ ] **App shell.** Topbar, `.shell` frame, main outlet. Note `.shell` has + `backdrop-filter`, which makes it a containing block for `position: + fixed` — the chat launcher must render outside it or it anchors to the + scrolling shell. +- [ ] **Theme toggle** and its persistence. + +## Phase 2 — Shared primitives + +Old hand-built components and their shadcn-vue replacements. Take the +replacement unless the behaviour is genuinely bespoke. + +| Was | Becomes | +|---|---| +| `base/pill.jsx` | `Badge`, with the status-token variants | +| `base/statTile.jsx` | `Card` composition | +| `base/icons.jsx` | `lucide-vue-next` (the set already matched a 24-grid stroke system) | +| `base/gauge.jsx` | bespoke SVG — port as-is | +| `base/log-row.jsx` | bespoke — port as-is | +| `base/format.jsx`, `base/task-meta.jsx` | plain modules, port as-is | +| `css/table.css` | `Table` | +| `css/empty.css` | `Empty` | +| `css/button.css` | `Button` | + +- [ ] **Copy verbatim.** These five are framework-free and need only a rename: + `dashboard/activity-detail.js`, `chat/command-scroll.js`, + `workflows/workflow-rows.js`, `base/stream-state.js`, + `logs/logs-empty.js`. Each encodes a bug fixed today; re-deriving them by + hand is how the bugs come back. +- [ ] `base/uuid.jsx` → `src/lib/uuid.ts`. +- [ ] `routing.jsx` is superseded by vue-router. Do not port it. + +## Phase 3 — Pages + +In dependency order. Each is `git show e18fb8b2^:ui/src//`. + +- [ ] **Dashboard** (5 files). Health row, Throughput tiles, Token outlook, + Live activity table. +- [ ] **Tasks** (13 files — the largest). List, filters, row actions, detail + page with tab bar, stage rail, changed files, attempt config, task logs, + timeline, debug view. +- [ ] **Chat** (8 files). See Phase 5; this one carries the most recent work. +- [ ] **Configuration** (5 files). Currently one ~4000px page; the approved + design splits it into `/system/*` routes — see + `docs/prds/dashboard-navigation-groups.md`. Port into that shape directly + rather than porting the monolith and splitting later. +- [ ] **Logs** (3 files). Filters, live tail, pause, the three empty states. +- [ ] **Event inspector / captures** (3 files). +- [ ] **Field mappings** (3 files), including the mapping editor. +- [ ] **Playbook bindings** (3 files), including the binding editor. +- [ ] **Workflows** (3 files). +- [ ] **Skills**, **Curators**, **Channels** (2 files each). Capability-gated + and hidden on the reference deployment, so they are easy to forget and + easy to ship broken. + +## Phase 4 — Navigation restructure + +Approved in `docs/prds/dashboard-navigation-groups.md`; build it during the +port rather than porting the flat bar first. + +- [ ] Five top-level items: Dashboard, Work, Agent, Events, System. +- [ ] Rename under their group: Inspector, Mappings, Bindings. +- [ ] Per-item descriptions in the dropdown, not hover tooltips. +- [ ] Configuration splits into `/system/{status,appearance,tasks,models,repos,advanced}`. +- [ ] `/settings` redirects to `/system/status` — it is in bookmarks and in the + Go route registry. +- [ ] Add Logs to the nav. It was never in it. +- [ ] Update `dashboard_tools.go` for every new route in the same change. + +## Phase 5 — Behaviour shipped today that a naive port loses + +All of this landed in the last few hours and exists only in the deleted tree. + +- [ ] **Chat is a FAB, not a route.** No `/chat`, no nav entry, no topbar icon. +- [ ] **The panel grows out of the launcher**: collapsed to a pill over the + button, expanding with scale, border-radius and position interpolating + together; contents fade in after the shape arrives. +- [ ] **No scrim, no scroll lock.** The page stays readable and clickable. +- [ ] **No close button** — the FAB is the only toggle, and stays visible on + mobile where the panel becomes a sheet. +- [ ] Header shows the open conversation's name (`panelTitle`). +- [ ] New chat = `message-circle-plus`, in the header. +- [ ] Slash palette is the only command surface; it floats above the input and + scrolls to keep the arrow-key selection visible. +- [ ] Settings popover closes on outside pointerdown and focus-out. +- [ ] Stop renders only while streaming; composer stays writeable and focused + during a send. +- [ ] Bubbles carry no speaker label. +- [ ] **Topbar cannot clip.** The nav is the only shrinkable region; search + collapses below 1500px; nav wraps below 1270px. Previously 106px of the + utility cluster was unreachable between 1221px and ~1582px. +- [ ] **Live activity detail is clamped** to one line with the full payload on + the title. Unclamped it made the dashboard 7,481px tall. +- [ ] **HEALTH cards take their own height** (`align-items: start`). +- [ ] **Workflow rows merge** definitions with statistics. +- [ ] **Log stream reports `unavailable`** from `readyState`, not a permanent + "reconnecting". +- [ ] **Unconfigured capabilities say so** (501 → "Not configured on this + deployment") rather than rendering nothing. +- [ ] **Operator cards on Configuration**: update install/defer, dangerous + action approvals. Both absent when their endpoint 501s. + +## Known-open, carry forward + +Open beads against the old UI that the port should satisfy rather than +reintroduce: `1q89` (tasks column priority, wrapping row actions), `to2y` +(three empty-state treatments; Field mappings dead-ends), `gl96` (Logs missing +from nav), `86au` (gauge `aria-label` announces an unrounded percentage), +`6m8r` (mobile KPI cards push content below the fold; 89 sub-44px targets), +`ggqo` (config page width — moot once Configuration splits), `3tij` +(`/api/workflows` serves no definitions, so "Start work" never renders), +`oif3` (Reload Telegram, blocked on `ry4k`). + +## Not doing + +- Porting the 43 test files. Tests return when there is behaviour worth pinning + rather than a port to re-assert. `task test:ui` is a `vue-tsc` typecheck + meanwhile.