spa/.planning/phase-3-dogfood-readiness/README.md

# Phase 3 — Dogfood readiness

**Status:** ⬜ Not started

The set of operational features that turn a working pilot into something safe to put in front of race operators on race day. None of these tasks change correctness; they change the experience when things don't go perfectly.

## Outcome statement

When Phase 3 is done:

- **Error boundaries** wrap each major feature region (map, sidebar, header). A crash in the map widget doesn't blank the whole UI; the operator sees a "Map crashed; reload to retry" panel and can keep using the rest.
- **Connection-state UI** is unmissable but not noisy. WS reconnecting → small banner. WS offline > 30s → larger warning. Per-device "last seen N seconds ago" in the device sidebar.
- **Mobile-responsive baseline.** The SPA doesn't crash on a 375px-wide viewport. Map fills the screen; sidebar collapses to a sheet. Not a separate mobile app — the same app, usable in a marshal's pocket browser.
- **Per-device detail panel.** Click a device on the map → side panel showing recent positions, current vehicle/crew, last-seen, manual notes the marshal has typed. Doesn't add data flows; consumes existing snapshots.
- **Operator-friendly empty / loading states.** No blank screens during the snapshot fetch; "No devices reporting yet" message when the event has subscribed but no positions arrived.
- **Vitest + React Testing Library set up.** Unit tests for the auth store, the rAF coalescer, the position-store reducer. Not a comprehensive suite — enough that future changes don't silently regress critical paths.

## Why this is a separate phase

Phase 2 produces a working live map. Phase 3 makes that map _fielded_ — usable when networks are flaky, browsers are exotic, screens are tiny, and operators are stressed. None of these tasks block the map from working in a controlled demo, but all of them affect whether the dogfood is genuinely useful versus a mostly-working tech demo.

## Tasks (sketched, not detailed)

| #   | Task                                                  | Notes                                                                                         |
| --- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 3.1 | Error boundaries + crash-recovery UI                  | One per major region (map, sidebar, header). Logs to console + optional remote-error endpoint |
| 3.2 | Connection-state UI                                   | Banner / chip in the header; per-device last-seen in the sidebar                              |
| 3.3 | Mobile-responsive baseline                            | Tailwind breakpoints; map full-screen on mobile; sidebar → sheet                              |
| 3.4 | Per-device detail panel                               | Click → side panel; reads from Directus + position store                                      |
| 3.5 | Empty / loading state polish                          | "Connecting…", "Waiting for first positions…", "No devices in this event yet"                 |
| 3.6 | Vitest + React Testing Library setup + targeted tests | Auth store, coalescer, position-store reducer. Not exhaustive                                 |
| 3.7 | Production logging discipline                         | Console-error captures + optional remote-shipper for stage                                    |
| 3.8 | Visual brand pass — adopt TRM design system           | Apply the design handoff bundle. Bundle path + scope + recommended approach below.            |

## Acceptance for the phase as a whole

- [ ] All eight tasks (3.1–3.8) done.
- [ ] Pulling the network mid-session shows a clear "reconnecting" state; reconnecting works; the operator's selection / event-picker state survives the gap.
- [ ] Loading the SPA on an iPhone 12 (or equivalent) viewport doesn't break layout.
- [ ] Clicking a device opens the detail panel; the panel shows the device's current vehicle/crew (joined from Directus) and recent positions (from the store).
- [ ] Vitest runs in CI; existing tests are green; coverage is documented but not gated on a percentage threshold.
- [ ] The dogfood-day operator sign-off: a marshal can use the SPA on race day without us standing over them. (This is the real acceptance gate; the rest is observable proxy.)

## Task 3.8 — TRM design system adoption (deferred from earlier)

A design handoff bundle was generated by Claude Design (claude.ai/design) on 2026-05-02 and lives at `TRM_Design_System-handoff/trm-design-system/` in this repo. It defines a **Bloomberg / F1-pit-wall** aesthetic — high data density, ink-on-paper base with one race-flag red accent (`#E8412B`), mono numerics for any changing value, square-edged everything, sharp printed offset shadows (no blur), Goldplay (real licensed font with three weights in the bundle's `fonts/`) + JetBrains Mono + Inter. Four surfaces designed: web dashboard, live leaderboard, mobile app, marketing site — only the first two are in this SPA's scope.

The bundle's READMEs (top-level + `trm-design-system/README.md` + `project/README.md`) and `chats/chat1.md` are the source of truth. `colors_and_type.css` ships the full token set as CSS custom properties.

**Recommended approach when Phase 3 picks this up — retheme shadcn, don't replace.** Tailwind 4's `@theme` directive maps cleanly to the design's tokens; shadcn's CSS-variable-driven theming lets us keep all the existing primitives (Button / Input / Form / Card / Alert) and only swap the cosmetics. Concrete steps:

1. Translate `colors_and_type.css` into a Tailwind `@theme` block — the paper / ink / night / race-accent / viz palettes all become Tailwind utilities.
2. Override shadcn's `--background`, `--foreground`, `--primary`, `--destructive`, `--ring`, `--radius` to point at the TRM tokens.
3. Add Goldplay as a webfont via the bundle's woff2 / ttf files (drop into `public/fonts/`); register JetBrains Mono via Google Fonts.
4. Set the global radius to `0` (square-edged) and replace shadcn's soft shadows with the printed offset utility (`box-shadow: 2px 2px 0 0 var(--ink)`).
5. Reskin shadcn primitives where defaults conflict — mainly: button radius, card border (full-ink 1 px not hairline), focus ring colour (race-flag red, 2 px outline + offset).
6. Adopt night mode for the Phase 2 live-map page only (the design says night is the default for trackside / kiosk views, not a toggle); paper/ink everywhere else.
7. Replace the home-page placeholder + login page with the design's chrome (56 px top bar, 240/64 px collapsible sidebar — the dashboard layout).

**Out of scope for 3.8:** mobile app and marketing site. Those are separate products in the design system; the SPA only adopts dashboard + leaderboard surfaces.

**Open question for when 3.8 starts:** the design notes the brand may have a custom icon set (cube / pixel-grid / map glyphs from the logo) — Lucide is the documented substitute. Stick with Lucide unless the custom set surfaces by then.

**Why deferred:** the design's foundational tokens are non-blocking for Phase 1 (login + placeholder home) and Phase 2 (live map without chrome). Adopting them now would either delay the dogfood-blocking work or land partial styling that gets reworked in 3.8 anyway. The bundle is committed alongside this plan so it's findable when Phase 3 runs.