# ByteLyst Cross-Repo UX Roadmap — v3 (Future-Proof, Elegant, Rich)

> **Version:** v3.2 — 2026-05-27 (showcase-first tracker amendment)
> **Status:** Draft for review · **actively tracked** (see §11)
> **Owners:** ByteLyst Platform UI guild
> **Predecessor:** `learning_ai_uxui_web/docs/ROADMAP_2026.md` v2.5 (Waves 1–7)
> **Scope:** Every product web app under `/Users/sd9235/code/mygh/` + the common platform packages that should serve them.
> **Showcase ground truth:** `@/Users/sd9235/code/mygh/copilot/learning_ai_uxui_web` (`http://localhost:3010/showcase/*`)

This document **extends** the v2 roadmap rather than replacing it. v2 covered shared packages in isolation; v3 walks the ecosystem floor — looks at what each of the **15+ product webs** actually ships today, finds the duplication, and prescribes the next **6 platform waves (Wave 8 – Wave 13)** plus a per-product upgrade matrix, with explicit futurism amendments in v3.1 (§3.4 – §3.8, §6.1 – §6.3, Wave 13) and a **showcase-first execution tracker** added in v3.2 (§11).

> **What changed in v3.2 vs v3.1:** added §11 — a 202-item, machine-parsable checklist that coding agents flip as they ship. Codified the **showcase-first rule** (every package gets a `learning_ai_uxui_web` demo route before any product adopts). Renumbered hygiene §11 → §12.

---

## 1. Where we are (May 2026)

### Shared `@bytelyst/*` packages currently published or in-tree (~73)

| Tier                                      | Packages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------- |   |
| **Foundation**                            | `errors`, `config`, `logger`, `testing`, `events`, `event-store`, `queue`, `storage`, `datastore`, `cosmos`, `blob`, `extraction`, `llm`, `llm-router`, `auth`, `field-encrypt`, `client-encrypt`, `palace`, `sync`, `offline-queue`                                                                                                                                                                                                                                                                                                            |
| **Service / SDK**                         | `api-client`, `auth-client`, `react-auth`, `secure-storage-web`, `platform-client`, `telemetry-client`, `feature-flag-client`, `kill-switch-client`, `diagnostics-client`, `feedback-client`, `subscription-client`, `survey-client`, `billing-client`, `blob-client`, `broadcast-client`, `org-client`, `marketplace-client`, `referral-client`, `mcp-client`, `ollama-client`, `gentle-notifications`, `time-references`, `celebrations`, `webhook-dispatch`, `push`, `accessibility`, `use-keyboard-shortcuts`, `use-theme`, `quick-actions` |
| **Backend infra**                         | `backend-config`, `backend-flags`, `backend-telemetry`, `fastify-core`, `fastify-auth`, `fastify-sse`                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **UI / UX (v2)**                          | `design-tokens`, `ui`, `auth-ui`, `dashboard-components`, `dashboard-shell`, **`ai-ui`** (Wave 2), **`command-palette`** (Wave 3), **`motion`** (Wave 4), **`data-viz`** (Wave 5b), **`notifications-ui`** (Wave 7), `monitoring`                                                                                                                                                                                                                                                                                                               |
| **Native (out-of-scope for v3 web work)** | `kotlin-platform-sdk`, `swift-platform-sdk`, `swift-diagnostics`, `react-native-platform-sdk`, `speech`, `devops`, `create-app`                                                                                                                                                                                                                                                                                                                                                                                                                 |

### v2 wave status (as of `acb8f02b`)

| Wave | Theme                                                | Status                                                                                                |
| ---- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 1    | Foundations · tokens · density · LHCI · vis-reg      | **✅ shipped** (DTCG v3 RFC + Storybook rollout still incremental)                                    |
| 2    | `@bytelyst/ai-ui`                                    | **✅ 0.4.0 shipped** — 8 components, 2 hooks, 53/53 tests                                             |
| 3    | `@bytelyst/command-palette`                          | **✅ 0.1.0 shipped** — 26/26 tests, Cmd-K live in showcase                                            |
| 4    | `@bytelyst/motion`                                   | **✅ 0.1.0 shipped** — Reveal, Stagger, NumberFlow, Tilt, ScrollProgress                              |
| 5a   | Forms additions to `@bytelyst/ui`                    | 📋 not started                                                                                        |
| 5b   | `@bytelyst/data-viz`                                 | **✅ 0.1.0 shipped** — Sparkline, KpiCard, ProgressRing, Heatmap (+ SSR-safe useId fix in `acb8f02b`) |
| 5c   | `@bytelyst/adaptive-ui` (SchemaForm / StreamUI)      | 📋 not started                                                                                        |
| 6    | Mobile · inclusive · i18n                            | 📋 not started                                                                                        |
| 7    | `@bytelyst/notifications-ui`                         | **✅ 0.1.0 shipped** — NotificationCenter, InboxItem, BannerStack, Announcement                       |
| 7    | `@bytelyst/billing-ui`                               | 📋 not started                                                                                        |
| 7    | `@bytelyst/onboarding-ui`                            | 📋 not started                                                                                        |
| 7    | `@bytelyst/telemetry-ui`, `brand-*`, PWA, create-app | 📋 not started                                                                                        |

---

## 2. Cross-repo audit — what every product web actually ships

Sampled from every Next.js / Vite web in the workspace — v3.1 audit is **comprehensive** (was sample-based in v3.0):

```
/copilot/learning_ai_uxui_web                           — reference showcase (Next.js 16)
/learning_ai_clock/web                                  — ChronoMind
/learning_ai_notes/web                                  — NoteLett
/learning_ai_flowmonk/web                               — FlowMonk
/learning_ai_jarvis_jr/web                              — JarvisJr
/learning_ai_fastgap/web                                — NomGap (FastGap)
/learning_ai_trails/web                                 — ActionTrail
/learning_ai_local_memory_gpt/web                       — LocalMemGPT
/learning_ai_dev_intelli/web                            — DevIntelli
/learning_voice_ai_agent/user-dashboard-web             — LysnrAI user portal
/learning_multimodal_memory_agents/mindlyst-native/web  — MindLyst web shell
/learning_ai_talk2obsidian/web                          — Talk2Obsidian
/learning_ai_productivity_web                           — Productivity hub
/learning_sidecar_setup/sidecar_dashboard_web           — Sidecar dashboard
/learning_ai_mac_tooling/dashboard                      — Mac Tooling dashboard
/learning_ai_devops_tools/dashboard/web                 — DevOps tools dashboard
/learning_agent_monitoring_fx/apps/web                  — Agent Monitoring FX
/learning_ai_local_llms/dashboard                       — Local LLMs dashboard
/learning_ai_efforise (Vite)                            — EffoRise client
/learning_ai_common_plat/dashboards/admin-web           — Platform admin
/learning_ai_common_plat/dashboards/tracker-web         — Issue tracker + roadmap
```

**Total: 20 web apps** (12 product webs, 2 platform dashboards, 6 internal/utility dashboards). v3.1 widens scope from the 11 highlighted in v3.0.

### 2.1 `@bytelyst/*` package consumption matrix

| Product                | `ui`                 | `design-tokens` | `react-auth` | `telemetry-client` | `feature-flag-client` | `dashboard-components` | `dashboard-shell` | `ai-ui` | `command-palette` | `motion` | `data-viz` | `notifications-ui` |
| ---------------------- | -------------------- | --------------- | ------------ | ------------------ | --------------------- | ---------------------- | ----------------- | ------- | ----------------- | -------- | ---------- | ------------------ |
| clock/web              | ✅                   | ✅              | ✅           | ✅                 | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| notes/web              | ✅                   | ✅              | ✅           | ✅                 | ✅                    | ✅                     | —                 | —       | —                 | —        | —          | —                  |
| flowmonk/web           | ✅                   | ✅              | ✅           | —                  | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| jarvisjr/web           | ✅                   | ✅              | ✅           | ✅                 | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| fastgap/web            | ✅                   | ✅              | ✅           | ✅                 | ✅                    | ✅                     | —                 | —       | —                 | —        | —          | —                  |
| localmemgpt/web        | ✅                   | ✅              | —            | ✅                 | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| voice (user-dashboard) | —                    | ✅              | ✅           | ✅                 | ✅                    | ✅                     | —                 | —       | —                 | —        | —          | —                  |
| trails/web             | ✅                   | ✅              | ✅           | ✅                 | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| dev-intelli/web        | ✅                   | ✅              | ✅           | ✅                 | ✅                    | —                      | —                 | —       | —                 | —        | —          | —                  |
| nomgap/web             | (sampled separately) | …               | …            | …                  | …                     | …                      | —                 | —       | —                 | —        | —          | —                  |

**Observation:** none of the 11 product webs consume the **5 newest UI packages** (`ai-ui`, `command-palette`, `motion`, `data-viz`, `notifications-ui`). All five are shipped to source but **awaiting publish** to the Gitea npm registry (still tracked as TODO #14 in v2.5). This is the single highest-impact unblock in v3 — see Wave 8.

### 2.2 Duplicated / reimplemented surfaces

Patterns found 3+ times across product repos that should collapse into shared packages:

| Surface                                                            | Found in                                          | Proposed home                                                                |
| ------------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------- |
| **`Skeleton.tsx`** (shimmer loading)                               | clock, notes, flowmonk, jarvisjr, fastgap, trails | `@bytelyst/ui/skeleton` (extend existing `ui`)                               |
| **Modal / Dialog wrappers** (`CreateXModal.tsx`, `LinkXModal.tsx`) | clock (1), notes (4), fastgap (2)                 | `@bytelyst/ui/modal` v2 (composable; replaces bespoke)                       |
| **Sidebar layout** (`Sidebar.tsx`, route-aware)                    | notes, flowmonk, jarvisjr (+ many more)           | `@bytelyst/dashboard-shell@0.3.0` — generic, slot-based                      |
| **`OnboardingOverlay.tsx` / tour steps**                           | clock (1), fastgap (1), notes (TBD)               | new `@bytelyst/onboarding-ui` (Wave 7-pending → Wave 9)                      |
| **`AgentTimeline.tsx`** (bespoke vertical thought-trace)           | notes (1)                                         | already in `@bytelyst/ai-ui` — direct swap (Wave 8)                          |
| **`MemoryTimeline.tsx`**                                           | notes (1), likely mindlyst                        | new `@bytelyst/timeline` (Wave 11)                                           |
| **Recharts wrappers** (KPI tiles, line/bar/area)                   | clock, jarvisjr, fastgap, voice (user-dashboard)  | new `@bytelyst/charts` (Wave 9)                                              |
| **Tiptap editor** (rich-text body)                                 | notes only (today); mindlyst, jarvisjr planned    | new `@bytelyst/rich-text` (Wave 9)                                           |
| **Toast / sonner**                                                 | notes, fastgap                                    | already in `@bytelyst/ui/toast` — sonner usage to deprecate (Wave 8 hygiene) |
| **Date-fns + bespoke pickers**                                     | clock, jarvisjr, voice                            | new `@bytelyst/ui/date-picker` (Wave 9.D)                                    |
| **Empty states** (`No items yet…`)                                 | every product                                     | new `@bytelyst/ui/empty-state` (Wave 9.D.3)                                  |
| **Settings panel** (account / API keys / billing / privacy)        | every product                                     | new `@bytelyst/settings-ui` (Wave 10)                                        |
| **Filter bar / search input + chips**                              | notes, fastgap, voice, jarvisjr                   | new `@bytelyst/ui/filter-bar` (Wave 9.D.5)                                   |
| **Data table / virtualised list**                                  | notes, fastgap, voice                             | new `@bytelyst/data-table` (Wave 9, TanStack Table v9)                       |
| **Privacy / Legal pages**                                          | jarvisjr (only)                                   | new `@bytelyst/legal-ui` (Wave 10)                                           |

### 2.3 Tech currently mixed across products

| Need                 | Library in product                          | Recommendation                                                                     |
| -------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
| Charting             | `recharts` (5+ apps)                        | Wrap recharts in `@bytelyst/charts` with token theming — keep recharts as peer dep |
| Toasts               | `sonner` (notes, fastgap)                   | `@bytelyst/ui/toast` already exists; align all apps                                |
| Drag-drop reordering | none yet                                    | Adopt `@dnd-kit/sortable`, expose via `@bytelyst/ui/sortable`                      |
| Virtualisation       | none yet                                    | Adopt `@tanstack/react-virtual`, expose via `@bytelyst/ui/virtual-list`            |
| Animations           | `framer-motion` (clock)                     | Migrate to `@bytelyst/motion` (already shipped) — smaller bundle                   |
| Forms                | bespoke + `zod` (clock, flowmonk, jarvisjr) | Adopt `react-hook-form` + `zod` resolver, expose via `@bytelyst/ui/form` (Wave 5a) |
| Date picking         | none consistent                             | `@bytelyst/ui/date-picker` on `react-day-picker` v9                                |
| Rich text            | `@tiptap/*` (notes)                         | `@bytelyst/rich-text` (Wave 9)                                                     |

---

## 3. Future-proof UX themes & design patterns to adopt

The v2 roadmap nailed accessibility, motion, density, AI-native primitives. v3 layers in the **next-decade design language** that products like Linear, Arc, Raycast, Vercel, Apple Intelligence and Material 3 Expressive are pushing in 2025-26:

### 3.1 Visual language

| Theme                             | What it means                                                                       | Where it lands                                                                                         |
| --------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **OKLCH / Display-P3 palettes**   | Perceptually-uniform colour math; vibrant on modern displays; safe fallback to sRGB | `design-tokens` v3 — Tier 1 emits both `oklch()` and `color(display-p3 ...)` with `@supports` fallback |
| **Glass + depth (selective)**     | Translucent surfaces with `backdrop-filter`, layered shadows; **not** for body text | `ui/Surface`, modal/popover variants                                                                   |
| **Soft gradients + mesh**         | OKLCH-driven background washes (no banding)                                         | Landing pages, hero sections; `motion/MeshBackground`                                                  |
| **Material 3 Expressive springs** | Larger, more emotive transitions (~600ms) for hero interactions                     | New `SPRINGS.expressive` preset in `@bytelyst/motion`                                                  |
| **Ambient / calm UI**             | Low-saturation default state; saturation lifts on focus                             | `data-mood` token tier (`calm` / `focus` / `celebrate`)                                                |
| **Tactile micro-feedback**        | Press-state scale (0.98), hover lift, haptic-style cubic-bezier                     | Already in tokens; **codify in `@bytelyst/motion/Pressable`**                                          |
| **Variable typography**           | Variable axes (`wght`, `opsz`, `GRAD`) on Inter Variable + Atkinson Hyperlegible    | `design-tokens` Tier 1 — `font-variation-settings`                                                     |
| **Iconography v2**                | Lucide v0.500+ as default; add provider for Phosphor / Tabler swap                  | New `@bytelyst/icons` peer-deps re-export                                                              |

### 3.2 Platform capabilities to wire in (2025-26 web platform)

| Capability                                                    | Browser support                                     | Where it lands                                                      |
| ------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
| **View Transitions API (same-doc + cross-doc)**               | Chrome 126+ / Safari 18+ / Firefox 132+ (cross-doc) | `@bytelyst/motion/PageTransition` (Wave 4 stretch) — with fallback  |
| **CSS Anchor Positioning**                                    | Chrome 125+ / Safari TP / Firefox flag              | Replace JS-anchored tooltips/popovers in `@bytelyst/ui`             |
| **`<dialog>` + invoker `command`/`commandfor`**               | Chrome 134+                                         | `ui/Modal` to use native `<dialog>` + invoker fallback              |
| **Popover API (`popover` attribute)**                         | All evergreen                                       | `ui/Tooltip`, `ui/Dropdown`, `ui/Menu` upgrade                      |
| **Container queries everywhere**                              | All evergreen                                       | Already partial; codify `@container` breakpoints in `design-tokens` |
| **`color-mix()` / `color()` / relative colour syntax**        | All evergreen                                       | Already used by `data-viz/Heatmap`; expand to `ui`                  |
| **Scroll-driven animations (`animation-timeline: scroll()`)** | Chrome 115+                                         | `@bytelyst/motion/ScrollLinked` primitive                           |
| **`@scope`**                                                  | Chrome 118+ / Safari 17.4+                          | Scope brand overrides cleanly without selector wars                 |
| **`text-wrap: balance` / `text-wrap: pretty`**                | All evergreen                                       | Default on headings via `ui/Heading`                                |
| **CSS nesting**                                               | All evergreen                                       | Update `globals.css` patterns                                       |
| **`field-sizing: content`**                                   | Chrome 123+                                         | `ui/Textarea` auto-grow without JS                                  |
| **Web Speech API**                                            | All evergreen (Chrome best)                         | `@bytelyst/speech-ui` — voice-input button, dictation               |
| **WebAuthn / Passkeys**                                       | All evergreen                                       | `ui/PasskeyButton` (Wave 5a)                                        |
| **WebGPU** (when stable)                                      | Chrome 113+ / Safari 26                             | Document-heavy products only (e.g. mindlyst) — defer beyond v3      |
| **OffscreenCanvas + Worker**                                  | All evergreen                                       | Charts re-render off-thread (`@bytelyst/charts`)                    |

### 3.3 AI-native UX patterns (extend Wave 2)

| Pattern                                                          | Surface                                                                         |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Generative UI** (LLM emits component tree from JSON Schema)    | `@bytelyst/adaptive-ui/StreamUI` (Wave 5c)                                      |
| **Suggestion chips** (next-action prediction)                    | `ai-ui/SuggestionRow` (Wave 8 v0.5)                                             |
| **Inline AI rewrite** (highlight → "Make shorter" / "Translate") | `ai-ui/InlineAI` (Wave 8 v0.5)                                                  |
| **Confidence chrome** (delta arrow + ± range + source)           | `data-viz/KpiCard` already supports trend; add `confidence` (Wave 9)            |
| **Agentic progress** (steps, retries, cancellations)             | `ai-ui/AgentTimeline` already supports — add cancel/retry actions (Wave 8 v0.5) |
| **Ambient assistant** (subtle dot, summon with ⌘J)               | `@bytelyst/assistant-shell` (Wave 11)                                           |
| **Voice-first composer** (push-to-talk in `PromptComposer`)      | `ai-ui/PromptComposer.voiceInput` (Wave 8 v0.6) — uses `@bytelyst/speech-ui`    |
| **Citations everywhere** (any text can attach `CitationChip`s)   | `ui/Markdown` (Wave 5c) renders inline citations                                |

### 3.4 On-device & privacy-first AI — the trust differentiator

The single biggest 2026 customer-acquisition wedge: **"your data never leaves your device unless you ask it to."** Surfaces:

| Pattern                                      | What it is                                                                                                  | Where it lands                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **WebLLM / transformers.js** in browser      | Run 1B–8B-parameter models client-side via WebGPU; falls back to cloud if hardware can't                    | New `@bytelyst/on-device-ai` package (Wave 11) with `useOnDeviceModel()` hook + capability detection |
| **"Privacy mode" toggle**                    | App-wide switch that routes every AI call to local model when capable; disables telemetry beacons           | `@bytelyst/ai-ui/PrivacyBadge` chrome + `usePrivacyMode()` (Wave 11)                                 |
| **Explainable refusal**                      | When AI refuses, show _why_ (policy excerpt + appeal link), never a generic "I can't help"                  | `ai-ui/RefusalCard` (Wave 9 v0.5)                                                                    |
| **Cost transparency**                        | Inline per-turn cost ($ + tokens + provider), running session total                                         | `ai-ui/CostMeter` (Wave 9 v0.5) — opt-in via `showCost` prop on `ChatStream`                         |
| **Confidence transparency**                  | "Model is 73% confident; 2 of 3 sources agree" — surfaced on every AI response                              | `ai-ui/ConfidenceTag` (Wave 9 v0.5)                                                                  |
| **Provenance trails**                        | Every AI artefact carries a verifiable hash chain back to the prompt + model + tools used                   | `ai-ui/ProvenanceDrawer` (Wave 11) — backed by `@bytelyst/event-store`                               |
| **Telemetry opt-out UX**                     | Single switch in `@bytelyst/settings-ui` honours **Global Privacy Control** (`Sec-GPC` header)              | Wave 10                                                                                              |
| **"Why did the AI say this?"** debug overlay | Shift-click any AI response → opens inspector with system prompt, retrieved context, tool calls, raw stream | `ai-ui/DebugOverlay` (Wave 11) — dev/staging only by default                                         |

### 3.5 Real-time collaboration — the Linear/Figma-tier patterns

Today's premium products are multiplayer. Wave 11 ships the primitives.

| Pattern                       | Tech                                                                    | Surface                                                                                                 |
| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **CRDT document collab**      | **Yjs** as the canonical CRDT; **Automerge** swap supported via adapter | `@bytelyst/collab` (new in Wave 11) — `useSharedDoc()`, `<CollabProvider>`                              |
| **Liveblocks-grade presence** | SSE/WebSocket transport via `@bytelyst/fastify-sse`                     | `@bytelyst/realtime-ui` — `<PresenceAvatars>`, `<TypingIndicator>`, `<LiveCursor>` (already in Wave 11) |
| **Co-edit indicators**        | Show "Sara is editing line 14" with avatar                              | `rich-text/CollabSelection` extension (Wave 11)                                                         |
| **Conflict-free sync**        | Offline edits replay on reconnect; never lose work                      | `@bytelyst/sync` + Yjs binding                                                                          |
| **Selective sharing**         | Share-by-link UI with permission tier (view / comment / edit)           | `@bytelyst/settings-ui/SharePanel` (Wave 10)                                                            |
| **Comment threads**           | Anchored to a selection range; resolves + reopens                       | `@bytelyst/collab/CommentThread` (Wave 11)                                                              |

### 3.6 Spatial / immersive — visionOS-inspired surfaces

Inspired by Apple Vision Pro, Arc Browser, Linear's depth layering. Subtle but unmistakably "next-gen".

| Pattern                          | Implementation                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Floating cards with depth**    | Multi-stop shadows + 1px translucent border + `backdrop-filter: blur()`; never used for body text | `ui/SurfaceFloat` variant (Wave 9)                         |
| **Parallax on scroll**           | `motion/Parallax` driven by scroll-driven animations — zero-JS where supported                    | New primitive in `@bytelyst/motion@0.2.0` (Wave 9 hygiene) |
| **3D model embed**               | `<model-viewer>` web component, lazy-loaded behind `@bytelyst/file-ui`                            | Wave 11                                                    |
| **Cursor-aware spotlight**       | Radial gradient that follows pointer, hugely effective on landing pages                           | `motion/Spotlight` (Wave 9)                                |
| **Magnetic buttons**             | Pointer-attracted CTAs, Arc-browser-style                                                         | `motion/Magnetic` (Wave 9) — already in v2 sketch          |
| **Tilt cards**                   | Already shipped in `motion@0.1.0` — add `<TiltGallery>` for product grids                         | Wave 9                                                     |
| **Glass-with-depth modal**       | Backdrop blur + tinted vignette + spring entrance                                                 | `ui/Modal v2` (Wave 9)                                     |
| **Ambient gradient backgrounds** | OKLCH mesh that subtly shifts based on time-of-day or active route                                | `motion/MeshBackground` (Wave 9)                           |

### 3.7 Performance & sustainability — the Core Web Vital budgets

Every customer ultimately judges UX by speed. We publish per-route budgets and CI gates them.

| Metric                                  | Target        | How we measure                                |
| --------------------------------------- | ------------- | --------------------------------------------- |
| **LCP** (Largest Contentful Paint)      | ≤ 2.5s p75    | Lighthouse + RUM via `@bytelyst/telemetry-ui` |
| **INP** (Interaction to Next Paint)     | ≤ 200ms p75   | `web-vitals@4` in `@bytelyst/telemetry-ui`    |
| **CLS** (Cumulative Layout Shift)       | ≤ 0.1 p75     | Lighthouse                                    |
| **First-page JS**                       | ≤ 100 KB gzip | `size-limit` per-route budget                 |
| **Image weight per page**               | ≤ 500 KB      | Lighthouse                                    |
| **CO₂ per page-view**                   | ≤ 0.5 g       | `co2.js` in CI (Wave 12.6)                    |
| **Time-to-Interactive on Moto G Power** | ≤ 4.5s        | Lighthouse mobile profile in LHCI             |

**Patterns we adopt to hit them:**

- `content-visibility: auto` on long lists & off-screen panels (10× INP improvement)
- React 19 **Server Components** for static surfaces (legal-ui, settings-ui rails, marketing pages)
- **Streaming SSR with progressive hydration** for AI surfaces
- **Suspense islands** — never block a page on a slow chart
- **Route prefetch** on hover/pointer-near (Next.js native + `@bytelyst/dashboard-shell` Sidebar opt-in)
- **Image components** with AVIF + WebP negotiation, blurhash placeholders
- **Cache-aware Cmd-K** — palette uses IndexedDB for the catalog so it opens instantly offline

### 3.8 Anti-patterns — what ByteLyst products will **never** ship

A short register, codified in `docs/design-system/ANTIPATTERNS.md` (created by Wave 9), and CI-checkable where possible.

| Forbidden pattern                                                                                   | Why                       | Detection                                                          |
| --------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ |
| **Dark patterns** (cookie banner with hidden "Reject all", pre-checked opt-in, fake urgency timers) | EU EAA + ethics           | Manual review + cookie-banner lint in `@bytelyst/legal-ui`         |
| **Auto-playing audio/video** without explicit user gesture                                          | Accessibility + bandwidth | ESLint rule on `<video autoPlay>` / `<audio autoPlay>`             |
| **`prefers-reduced-motion` ignored**                                                                | Accessibility             | `@bytelyst/motion` enforces; `bl-*` keyframes audited              |
| **`<div onClick>`** instead of `<button>`                                                           | Keyboard + screen reader  | ESLint `jsx-a11y/click-events-have-key-events`                     |
| **Hard-coded colours / sizes** outside `design-tokens`                                              | Theming + density         | Stylelint rule blocks hex / `px` outside tokens                    |
| **Layout-shifting skeletons**                                                                       | CLS                       | Skeletons must match content dimensions; visual-regression catches |
| **Polling instead of streaming** for AI surfaces                                                    | UX latency + cost         | Code review                                                        |
| **Notification spam**                                                                               | Trust                     | `@bytelyst/notifications-ui` rate-limits per kind                  |
| **Modal stacks > 2 deep**                                                                           | UX hygiene                | `ui/Modal v2` enforces a single backdrop stack                     |
| **Generic "Something went wrong"** errors                                                           | Trust                     | `@bytelyst/errors` taxonomy mandates a typed cause + user action   |

---

## 4. The next six waves

Builds on v2.5. All effort in person-weeks (pw). Totals: **Wave 8 = 4 pw · Wave 9 = 10 pw · Wave 10 = 9 pw · Wave 11 = 8 pw · Wave 12 = 7 pw · Wave 13 = 9 pw → ~47 pw across 28 weeks** (was ~38 pw / 26 weeks in v3.0).

### **Wave 8 — Unblock & rollout** _(weeks 16–18, ~4 pw)_

> **Theme:** ship what's built; remove the showcase's "vendored snapshot" workaround; get every product onto the new packages.

| #   | Status | Deliverable                                                                                                                                                                                                                                                              | Effort |
| --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| 8.1 | 📋     | Trigger common_plat publish workflow → push **`react-auth@0.2.0`**, **`dashboard-shell@0.2.0`**, **`design-tokens@0.2.0`**, **`ai-ui@0.4.0`**, **`command-palette@0.1.0`**, **`motion@0.1.0`**, **`data-viz@0.1.0`**, **`notifications-ui@0.1.0`** to the Gitea registry | 0.5 pw |
| 8.2 | 📋     | Showcase: delete `src/lib/*-preview/` snapshots; swap imports to registry packages (TODO #14)                                                                                                                                                                            | 0.5 pw |
| 8.3 | 📋     | Cross-repo dep update PR: every product web pins `@bytelyst/design-tokens@0.2.0` + adopts at least one new package (`motion` is the easiest first win — landing-page reveals)                                                                                            | 1 pw   |
| 8.4 | 📋     | Migrate `learning_ai_notes/web/src/components/AgentTimeline.tsx` → `@bytelyst/ai-ui/AgentTimeline` (delete bespoke)                                                                                                                                                      | 0.5 pw |
| 8.5 | 📋     | Migrate `learning_ai_clock` `framer-motion` usage → `@bytelyst/motion` (Reveal + Stagger only on landing + history pages)                                                                                                                                                | 0.5 pw |
| 8.6 | 📋     | Migrate every product `Skeleton.tsx` → `@bytelyst/ui/skeleton` (new sub-surface — see Wave 5a)                                                                                                                                                                           | 0.5 pw |
| 8.7 | 📋     | Wire `@bytelyst/command-palette` into 3 pilot products (notes, jarvisjr, fastgap) with at minimum nav + theme commands                                                                                                                                                   | 0.5 pw |

**DoD:** zero vendored snapshots in showcase · `pnpm outdated --filter "*web*"` shows current `@bytelyst/*` versions · 3 products live with Cmd-K.

---

### **Wave 9 — Data, content, search** _(weeks 17–20, ~10 pw)_

> **Theme:** the surfaces every product reinvented — charts, rich-text editing, filterable lists. Each is a separate package so products opt in.

| #   | Package / surface                                   | Notes                                                                                                                                                                                                                        | Effort |
| --- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 9.1 | **`@bytelyst/charts@0.1.0`**                        | Recharts wrapper + token theming. Components: `<LineChart>`, `<AreaChart>`, `<BarChart>`, `<StackedBar>`, `<Donut>`, `<Gauge>`, `<RadarChart>`. Plug-in `OffscreenCanvas` mode for big series. Peer dep on `recharts@^2.15`. | 2 pw   |
| 9.2 | **`@bytelyst/rich-text@0.1.0`**                     | Tiptap v2 wrapper. Exports: `<RichTextEditor>`, `<RichTextViewer>`, default toolbar (bold/italic/headings/lists/links/code), slash menu, mention extension. Theming via tokens. Peer dep on `@tiptap/*`.                     | 2 pw   |
| 9.3 | **`@bytelyst/data-table@0.1.0`**                    | TanStack Table v9 + TanStack Virtual. Sortable headers, column resize, pinned columns, faceted filters, row selection, keyboard nav, sticky header. Variants: `compact` / `comfortable`.                                     | 2 pw   |
| 9.4 | **`@bytelyst/ui` v2.x — filter & search additions** | `<FilterBar>` (chips + clear-all), `<SearchInput>` (with suggestions slot), `<EmptyState>` (illustration slot + CTA), `<TagInput>`, `<Combobox>` (formalise Wave 5a).                                                        | 1.5 pw |
| 9.5 | **`@bytelyst/ui` v2.x — skeleton + loading**        | `<Skeleton>` shimmer with shape variants (`text` / `rect` / `circle` / `card`), `<SkeletonGroup>` (orchestrates fade-out → content), `<LoadingDots>`, `<Spinner>` with token-tinted variants.                                | 0.5 pw |
| 9.6 | `ai-ui@0.5.0`                                       | `<Markdown>` (with citation interop), `<CodeDiff>`, `<ExplainThis>`, `usePromptHistory()`, `useTokenCount()`. Closes Wave 2 deferred items.                                                                                  | 1 pw   |
| 9.7 | `data-viz@0.2.0`                                    | `<RealtimeChart>` (SSE subscribed), `<Donut>` (re-export from charts), `<Gauge>` (token-tinted), `<TreeMap>`, `<Sankey>` (stretch). Add `confidence` prop to `<KpiCard>`.                                                    | 1 pw   |

**DoD:** 3 products consume `charts` · 1 product (notes) consumes `rich-text` · `data-table` deployed in at least the tracker-web admin views.

---

### **Wave 10 — Product surfaces & shells** _(weeks 19–22, ~9 pw)_

> **Theme:** every product builds the same chrome from scratch. Stop doing that.

| #    | Package / surface                     | Notes                                                                                                                                                                                                                                                                                   | Effort |
| ---- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 10.1 | **`@bytelyst/dashboard-shell@0.3.0`** | Slot-based shell: `<AppShell><Sidebar/><Topbar/><Main/></AppShell>`. Sidebar with collapsible groups, badges, route-active states. Topbar with breadcrumbs + user menu + Cmd-K trigger + theme picker + notifications bell slot. Density-aware. Mobile drawer mode auto-applied <768px. | 2 pw   |
| 10.2 | **`@bytelyst/onboarding-ui@0.1.0`**   | `<OnboardingChecklist>`, `<TourStep>`, `<FeatureCallout>`, `<EmptyStateCTA>`, `useTour()`. Persists progress in localStorage. Token-themed.                                                                                                                                             | 1.5 pw |
| 10.3 | **`@bytelyst/billing-ui@0.1.0`**      | `<PlanCard>`, `<UpgradeModal>`, `<UsageMeter>`, `<InvoiceList>`, `<PaymentMethodList>`. Wired to `platform-service` Stripe module via `@bytelyst/subscription-client` + `@bytelyst/billing-client`.                                                                                     | 1.5 pw |
| 10.4 | **`@bytelyst/settings-ui@0.1.0`**     | `<SettingsLayout>` (left-rail nav), `<ProfileSection>`, `<SecuritySection>` (passkey + 2FA), `<NotificationPrefs>`, `<DataExportRow>`, `<DangerZone>`.                                                                                                                                  | 1 pw   |
| 10.5 | **`@bytelyst/legal-ui@0.1.0`**        | `<PrivacyPolicyPage>`, `<TermsPage>`, `<CookieBanner>` (token-themed, EAA-compliant), `<DataProcessingNotice>`. Driven by a single MDX corpus shipped with each product.                                                                                                                | 0.5 pw |
| 10.6 | **`@bytelyst/telemetry-ui@0.1.0`**    | `data-bl-event` attribute scraper + React provider; auto-emits to `@bytelyst/telemetry-client`. `useTrackedClick(name)` hook. PostHog + OpenTelemetry compatible.                                                                                                                       | 1 pw   |
| 10.7 | **`@bytelyst/timeline@0.1.0`**        | Generic vertical event timeline — extracts pattern from `notes/MemoryTimeline.tsx`. Groups by day, infinite scroll, sticky date headers, search.                                                                                                                                        | 1 pw   |
| 10.8 | **Brand-layer packages**              | `@bytelyst/brand-flowmonk`, `brand-chronomind`, `brand-mindlyst` — Tier-2 token overrides. Multi-tenant runtime: `<BrandProvider brand="flowmonk">` reads from URL/header.                                                                                                              | 0.5 pw |

**DoD:** 3 products use `dashboard-shell@0.3.0` end-to-end · onboarding-ui ships in nomgap (highest-value) · settings-ui used by ≥ 2 products.

---

### **Wave 11 — Adaptive / ambient / multimodal** _(weeks 21–24, ~8 pw)_

> **Theme:** the futuristic layer. Generative UI, ambient assistant, multimodal input.

| #    | Package / surface                     | Notes                                                                                                                                                                                                                                                    | Effort |
| ---- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 11.1 | **`@bytelyst/adaptive-ui@0.1.0`**     | `<SchemaForm>` (JSON Schema → accessible form, react-hook-form under the hood), `<SchemaTable>`, **`<StreamUI from={stream}>`** — renders LLM-emitted component trees from a constrained schema (à la Vercel AI SDK `streamUI`, but transport-agnostic). | 2.5 pw |
| 11.2 | **`@bytelyst/assistant-shell@0.1.0`** | Ambient assistant — small floating dot, summon with ⌘J. Mounts `ai-ui/ChatStream` in a sheet with context-aware system prompt (sees current route + selected text + recent telemetry).                                                                   | 2 pw   |
| 11.3 | **`@bytelyst/speech-ui@0.1.0`**       | `<VoiceInputButton>` (Web Speech API + visualiser), `<DictationOverlay>`, `<TranscriptViewer>`. Integrates with `@bytelyst/speech` and `PromptComposer.voiceInput`.                                                                                      | 1.5 pw |
| 11.4 | **`@bytelyst/file-ui@0.1.0`**         | `<FileDrop>` (drag-drop + chunked upload via `@bytelyst/blob-client`), `<FilePreview>` (auto image/PDF/text), `<FileBrowser>` (grid + list views), `<ImageCrop>`.                                                                                        | 1 pw   |
| 11.5 | **`@bytelyst/realtime-ui@0.1.0`**     | `<PresenceAvatars>`, `<TypingIndicator>`, `<LiveCursor>`, `useRealtimePresence(channel)`. Backed by `@bytelyst/fastify-sse` + `@bytelyst/sync`.                                                                                                          | 1 pw   |

**DoD:** assistant-shell live in ≥ 1 product (likely notes or mindlyst) · `StreamUI` renders a real LLM-emitted form in dev.

---

### **Wave 12 — Mobile-first, i18n, sustainability** _(weeks 23–26, ~7 pw)_

> **Theme:** finish what v2 Wave 6 sketched.

| #    | Package / surface                         | Notes                                                                                                                                                                                                              | Effort |
| ---- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| 12.1 | **`@bytelyst/ui` v3 — mobile primitives** | `<BottomSheet>` (snap points + scrollable body), `<StickyActionBar>` (safe-area), `<TouchableRipple>`, `<PullToRefresh>`, mobile-specific variants of `Dropdown`/`Tooltip` (long-press).                           | 1.5 pw |
| 12.2 | **`@bytelyst/i18n@0.1.0`**                | `react-intl` wrapper, type-safe message catalogues, auto-extraction CLI. Default locales: `en`, `es`, `ar`, `ja`.                                                                                                  | 1.5 pw |
| 12.3 | **RTL audit**                             | Every primitive uses logical properties (`margin-inline-start`, `text-align: start`). Visual-regression test set for `dir="rtl"`. Codemod to convert `left`/`right` → `inline-start`/`inline-end` in product webs. | 1 pw   |
| 12.4 | **Inclusive design**                      | Atkinson Hyperlegible toggle, contrast lock-up (forces AAA), motion-pause toggle. VPAT 2.5 ACR drafted & published on showcase.                                                                                    | 1 pw   |
| 12.5 | **Showcase additions**                    | Viewport switcher per demo (375 / 768 / 1280 / fluid), per-demo a11y inspector, RTL toggle, locale switcher in theme picker.                                                                                       | 1 pw   |
| 12.6 | **Sustainability**                        | Per-package bundle/CO₂ budget in CI (`co2.js`), dark-mode default to save OLED energy, image-format negotiation helper.                                                                                            | 0.5 pw |
| 12.7 | **PWA + create-app**                      | Showcase becomes installable PWA with offline catalog. `pnpm create @bytelyst/app` scaffolds new product webs wired with shell + auth + tokens + theme picker + Cmd-K + telemetry.                                 | 0.5 pw |

**DoD:** 100% RTL visual-test pass · 4 locales live · `pnpm create @bytelyst/app my-app` produces a working dev server in < 60s.

---

### **Wave 13 — Futurism layer** _(weeks 25–28, ~9 pw)_ — the customer-magnet wave

> **Theme:** the surfaces that make new prospects say _"how did you build this?"_ on first sight. Everything in §3.4 – §3.6 lands here, packaged.

| #    | Package / surface                            | Notes                                                                                                                                                                                                                                          | Effort |
| ---- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 13.1 | **`@bytelyst/on-device-ai@0.1.0`**           | WebLLM + transformers.js runners, capability detection (`useDeviceCapability()`), `useOnDeviceModel(modelId)` hook, `<ModelDownloadCard>` UI. Falls back to cloud when device can't run. Peer-deps `@mlc-ai/web-llm` + `@xenova/transformers`. | 2 pw   |
| 13.2 | **`@bytelyst/collab@0.1.0`**                 | Yjs-based CRDT layer with Automerge adapter. Exports: `<CollabProvider>`, `useSharedDoc(roomId)`, `useAwareness()`, `<CommentThread>`. Transport via `@bytelyst/fastify-sse`.                                                                  | 2 pw   |
| 13.3 | **`ai-ui@0.5.0` trust surfaces**             | `<CostMeter>`, `<ConfidenceTag>`, `<RefusalCard>`, `<ProvenanceDrawer>`, `<DebugOverlay>`, `<PrivacyBadge>`. Closes §3.4 amendments.                                                                                                           | 1.5 pw |
| 13.4 | **`motion@0.2.0` spatial**                   | `<Parallax>` (scroll-driven), `<Spotlight>` (cursor-follow), `<Magnetic>`, `<MeshBackground>`, `<TiltGallery>`. Pure CSS where possible; springs where not.                                                                                    | 1 pw   |
| 13.5 | **`@bytelyst/generative-theme@0.1.0`**       | "Describe your brand" → LLM generates a Tier-2 token override file. Bonus surface: `<ThemeStudio>` interactive playground in showcase.                                                                                                         | 1 pw   |
| 13.6 | **`@bytelyst/customizable-workspace@0.1.0`** | User-rearrangeable dashboards (drag-resize tiles), saved views per route, layout persistence to platform-service. Built on `@dnd-kit/sortable` + react-grid-layout fork.                                                                       | 1 pw   |
| 13.7 | **`@bytelyst/media-ui@0.1.0`**               | `<ImageGenStream>` (live image generation with progress), `<AudioWaveform>` (canvas-rendered + transcript scrubber), `<PdfPreview>` (pdf.js-backed lazy viewer), `<VideoPlayer>` (chapters + captions).                                        | 1.5 pw |

**DoD:** ambient assistant lives in notes/web with on-device-AI fallback · one product ships CRDT-backed multi-user editing (likely notes or mindlyst) · `<ThemeStudio>` published in showcase · customisable workspace pilot in 1 product.

---

## 5. Per-product upgrade matrix

For each product web, the **3 highest-value adoptions** in the next two waves. (Each row is independent and can be tackled by the product team.)

| Product                                  | Adoption #1 (Wave 8)                                                                     | Adoption #2 (Wave 9)                                                           | Adoption #3 (Wave 10)                       | Wave 13 futurism hook                                                 |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- | --------------------------------------------------------------------- |
| **clock/web** (ChronoMind)               | Replace `framer-motion` with `@bytelyst/motion` Reveal + NumberFlow                      | `@bytelyst/charts` for time-distribution donut; deprecate inline recharts      | `dashboard-shell@0.3.0` + `command-palette` | `<Spotlight>` + `<MeshBackground>` on landing                         |
| **notes/web** (NoteLett)                 | Swap bespoke `AgentTimeline` → `ai-ui/AgentTimeline`; bespoke `Skeleton` → `ui/skeleton` | `@bytelyst/rich-text` for note body; `@bytelyst/timeline` for `MemoryTimeline` | `assistant-shell` (Wave 11)                 | **Pilot `@bytelyst/collab`** — CRDT-backed multi-user notes           |
| **flowmonk/web**                         | `@bytelyst/motion` + Cmd-K for task switching                                            | `data-table` for schedule view; `data-viz/Heatmap` for streaks                 | `onboarding-ui` checklist on first task     | `customizable-workspace` dashboard tiles                              |
| **jarvisjr/web**                         | `@bytelyst/motion` on landing; swap recharts → `@bytelyst/charts`                        | `data-table` for sessions list                                                 | `billing-ui` upgrade modal                  | `<CostMeter>` on every AI turn; `<ProvenanceDrawer>`                  |
| **fastgap/web** (NomGap)                 | Replace bespoke `Skeleton`; swap sonner → `ui/toast`                                     | `@bytelyst/charts` for weight-trend; `data-viz/KpiCard` for streaks            | `onboarding-ui` for first-fast tour         | `media-ui/AudioWaveform` for guided fasting audio                     |
| **localmemgpt/web**                      | `@bytelyst/motion` on chat threads; Cmd-K                                                | Adopt `ai-ui/PromptComposer` + `ChatStream` (currently bespoke)                | `file-ui/FileDrop` for memory imports       | **Pilot `@bytelyst/on-device-ai`** — fully-local model option         |
| **voice / user-dashboard-web** (LysnrAI) | Adopt `@bytelyst/ui` (replaces direct `radix-ui` usage)                                  | Swap recharts → `@bytelyst/charts`; `data-table` for transcripts               | `billing-ui` + `settings-ui`                | `media-ui/AudioWaveform` + `<ConfidenceTag>` on transcripts           |
| **trails/web** (ActionTrail)             | `@bytelyst/motion` + `notifications-ui` for alert banner                                 | `data-table` for action log; `timeline` for revert history                     | `settings-ui`                               | `<ProvenanceDrawer>` over every action                                |
| **dev-intelli/web**                      | Cmd-K palette + `@bytelyst/motion`                                                       | `data-table` for diagnostics; `ai-ui/CodeDiff` for proposed fixes              | `assistant-shell` (Wave 11)                 | `<DebugOverlay>` + `<RefusalCard>`                                    |
| **peakpulse/web**                        | `@bytelyst/motion` + Cmd-K                                                               | `@bytelyst/charts`; `data-viz/KpiCard` for streaks                             | `settings-ui`                               | `customizable-workspace` for personal dashboards                      |
| **mindlyst/web** (multimodal-memory)     | Adopt `@bytelyst/ui` + tokens; `motion` Reveal                                           | `rich-text` + `media-ui/PdfPreview` for documents                              | `assistant-shell` + `timeline`              | **Pilot `<ImageGenStream>` + `collab`** — multi-user memory canvas    |
| **talk2obsidian/web**                    | Adopt tokens + Cmd-K                                                                     | `rich-text` aligned to Obsidian markdown subset                                | `settings-ui` + `file-ui`                   | `on-device-ai` for fully-local mode                                   |
| **productivity-web**                     | Tokens + Cmd-K + `motion`                                                                | `data-table` + `charts` for productivity metrics                               | `dashboard-shell@0.3.0`                     | `customizable-workspace`                                              |
| **sidecar-dashboard-web**                | Tokens + `dashboard-shell@0.3.0`                                                         | `data-table` + `data-viz/RealtimeChart`                                        | `notifications-ui` for incident stream      | `<DebugOverlay>` + `<ProvenanceDrawer>`                               |
| **mac-tooling / dashboard**              | Tokens + `dashboard-shell@0.3.0`                                                         | `data-table` + `command-palette`                                               | `settings-ui`                               | `customizable-workspace`                                              |
| **devops-tools / dashboard**             | Tokens + Cmd-K                                                                           | `data-table` + `data-viz/RealtimeChart` + `motion`                             | `dashboard-shell@0.3.0` + `settings-ui`     | `<DebugOverlay>` + `<ProvenanceDrawer>`                               |
| **agent-monitoring-fx**                  | Tokens + `dashboard-shell@0.3.0`                                                         | `data-table` + `data-viz` + `motion`                                           | `notifications-ui` + `settings-ui`          | `<CostMeter>` + `<ConfidenceTag>` for agent runs                      |
| **local-llms / dashboard**               | Tokens + Cmd-K                                                                           | `data-table` + `motion`                                                        | `settings-ui`                               | **First-class `on-device-ai` host** — it _is_ the local-LLM dashboard |
| **efforise / client** (Vite)             | Tokens (Vite SDK adapter — see §6.1) + Cmd-K                                             | `data-table` + `motion`                                                        | `settings-ui`                               | `customizable-workspace`                                              |
| **admin-web** (platform)                 | Already on `dashboard-shell`; add Cmd-K                                                  | `data-table` + `charts`                                                        | `settings-ui` + `billing-ui`                | `<DebugOverlay>` + `<ProvenanceDrawer>`                               |
| **tracker-web** (platform)               | Already on `dashboard-shell`; add Cmd-K                                                  | `data-table` + `rich-text` for issue bodies                                    | `notifications-ui` + `settings-ui`          | **Pilot `@bytelyst/collab`** — multi-user issue editing               |

> **Cross-cutting:** every product adopts `@bytelyst/telemetry-ui` (Wave 10.6) in the same PR that swaps in `dashboard-shell@0.3.0` — they share the topbar slot.

---

## 6. New common-platform packages proposed in v3

Summary table — **26 net-new packages** over Waves 8 – 13 (was 16 in v3.0; v3.1 amendment adds 8):

| Package                             | Wave       | Pkg size budget (gzip) | Purpose                                                                             |
| ----------------------------------- | ---------- | ---------------------- | ----------------------------------------------------------------------------------- |
| `@bytelyst/charts`                  | 9          | 25 KB                  | Token-themed recharts wrapper + Donut/Gauge                                         |
| `@bytelyst/rich-text`               | 9          | 40 KB                  | Tiptap wrapper + slash menu + mentions                                              |
| `@bytelyst/data-table`              | 9          | 25 KB                  | TanStack Table + Virtual                                                            |
| `@bytelyst/onboarding-ui`           | 10         | 10 KB                  | Checklist + tour + callouts                                                         |
| `@bytelyst/billing-ui`              | 10         | 15 KB                  | Plan/upgrade/usage/invoice                                                          |
| `@bytelyst/settings-ui`             | 10         | 10 KB                  | Settings layout + sections                                                          |
| `@bytelyst/legal-ui`                | 10         | 6 KB                   | Privacy/terms/cookie banner                                                         |
| `@bytelyst/telemetry-ui`            | 10         | 4 KB                   | Auto-event tracking                                                                 |
| `@bytelyst/timeline`                | 10         | 8 KB                   | Generic vertical event timeline                                                     |
| `@bytelyst/brand-flowmonk` (× 3)    | 10         | 1 KB each              | Token overrides                                                                     |
| `@bytelyst/adaptive-ui`             | 11         | 18 KB                  | SchemaForm + StreamUI                                                               |
| `@bytelyst/assistant-shell`         | 11         | 8 KB                   | Ambient ⌘J assistant                                                                |
| `@bytelyst/speech-ui`               | 11         | 6 KB                   | Voice input + dictation                                                             |
| `@bytelyst/file-ui`                 | 11         | 12 KB                  | FileDrop + FileBrowser + ImageCrop                                                  |
| `@bytelyst/realtime-ui`             | 11         | 8 KB                   | Presence + typing + cursors                                                         |
| `@bytelyst/i18n`                    | 12         | 12 KB                  | react-intl wrapper                                                                  |
| `@bytelyst/icons`                   | 3.x bonus  | 0 KB (peer)            | Lucide / Phosphor / Tabler swap provider                                            |
| `@bytelyst/on-device-ai`            | 13         | 18 KB + WebLLM peer    | WebLLM + transformers.js runners                                                    |
| `@bytelyst/collab`                  | 13         | 30 KB + Yjs peer       | CRDT layer (Yjs canonical, Automerge adapter)                                       |
| `@bytelyst/generative-theme`        | 13         | 8 KB                   | "Describe your brand" → token override                                              |
| `@bytelyst/customizable-workspace`  | 13         | 14 KB                  | Drag-resize tiles + saved views                                                     |
| `@bytelyst/media-ui`                | 13         | 20 KB + pdf.js peer    | ImageGenStream + AudioWaveform + PdfPreview + VideoPlayer                           |
| `@bytelyst/ai-ui` (0.5.0 surfaces)  | 13         | +6 KB                  | CostMeter, ConfidenceTag, RefusalCard, ProvenanceDrawer, DebugOverlay, PrivacyBadge |
| `@bytelyst/motion` (0.2.0 surfaces) | 13         | +4 KB                  | Parallax, Spotlight, Magnetic, MeshBackground, TiltGallery                          |
| `@bytelyst/email-tokens`            | 10 hygiene | 0 KB (build-time)      | Same tokens, emitted to MJML/inline-CSS for transactional email                     |

Total net-new package bytes if a product consumes **every** package: ~330 KB gzip. Per-product realistic adoption (6-8 of these): ~80-110 KB gzip — still within the 100 KB JS budget for _first-page_ loads (the larger packages — collab, on-device-ai, media-ui — lazy-load behind dynamic imports).

### 6.1 RSC vs client — explicit guidance per package

React 19 + Next.js 16 give us **React Server Components**. Knowing which package is RSC-safe vs client-only is the difference between a 100 KB and a 300 KB first paint.

| Package                                                                 | RSC-safe?                                             | Notes                                                        |
| ----------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| `design-tokens`                                                         | ✅ yes (build-time CSS)                               | Pure CSS variable emission                                   |
| `ui` (most primitives)                                                  | ✅ yes for stateless (Button, Heading, Card, Surface) | Interactive variants are `'use client'`                      |
| `legal-ui`, `settings-ui` rail                                          | ✅ yes                                                | Static-shape components                                      |
| `motion`                                                                | ❌ client                                             | DOM refs + RAF                                               |
| `ai-ui`, `command-palette`, `data-viz`, `notifications-ui`              | ❌ client                                             | All stateful                                                 |
| `charts`, `data-table`, `rich-text`, `media-ui`                         | ❌ client                                             | Recharts/TanStack/Tiptap/canvas                              |
| `on-device-ai`, `collab`, `realtime-ui`, `assistant-shell`, `speech-ui` | ❌ client                                             | Browser APIs                                                 |
| `adaptive-ui/StreamUI`                                                  | 🟡 hybrid                                             | Server emits initial tree; client hydrates streaming patches |

**Rule:** every package whose entry point is RSC-safe ships a `"react-server"` export condition in `package.json` that re-exports only the safe surface. Client-only files carry `'use client'` at the top.

### 6.2 Non-React consumers — Web Components interop

Products shipping non-React shells (Vite vanilla, Astro, native web-views in Tauri/Capacitor, Obsidian plugins) need a path. Three layers:

| Layer                                | What it is                                                                                                                          | Status                         |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Tokens**                           | Pure CSS; works everywhere                                                                                                          | ✅ already shipped             |
| **`@bytelyst/ui/web-components`**    | Lit-wrapped Button/Card/Toast/Skeleton/EmptyState as Custom Elements (`<bl-button>`, `<bl-card>`, ...). React + framework-agnostic. | New — Wave 9 hygiene (0.5 pw)  |
| **`@bytelyst/icons/web-components`** | Icon registry as `<bl-icon name="sparkles"/>` Custom Element                                                                        | New — Wave 9 hygiene (0.25 pw) |

This unlocks `learning_ai_efforise` (Vite), `learning_ai_talk2obsidian` (Obsidian plugin), `learning_ai_local_llms/dashboard` (Vite), and any future native shell without a React port.

### 6.3 Adjacent token packages — brand consistency outside the web

| Package                       | Notes                                                                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`@bytelyst/email-tokens`**  | Same Tier-1/2 tokens, emitted as MJML-compatible inline-CSS for transactional emails (welcome, billing, password-reset). Brand stays consistent across web + email. |
| **`@bytelyst/audio-tokens`**  | Notification sound palette (`success.wav`, `mention.wav`, `error.wav`) — same brand intent. Future: `@bytelyst/notifications-ui` plays them based on `data-kind`.   |
| **`@bytelyst/motion-tokens`** | Spring presets exported as Lottie/Rive interpolation curves for designer hand-off.                                                                                  |

---

## 7. Non-goals (still)

- Rebuilding charts from scratch — wrap recharts.
- Custom Markdown parser — adopt `react-markdown` + remark plugins inside `@bytelyst/ui/Markdown`.
- A new state library — products keep TanStack Query / Zustand / Redux as they choose.
- A new test runner — Vitest + Playwright is the stack.
- Native iOS/Android UI work — `swift-platform-sdk` / `kotlin-platform-sdk` continue to share **tokens only**.
- **A bespoke CRDT** — we adopt Yjs (with Automerge adapter), never re-invent.
- **A bespoke on-device AI runtime** — we adopt WebLLM / transformers.js, never re-invent.
- **A new CSS-in-JS runtime** — CSS variables + token-driven utility classes; zero-runtime is the rule.
- **Generic "agent framework"** UI — the AI surface stays narrowly scoped to the patterns in §3.3 + §3.4. No "build your own agent" UI in v3.

---

## 8. Risks & mitigations (v3 specific)

| Risk                                                                | Likelihood | Impact | Mitigation                                                                                                  |
| ------------------------------------------------------------------- | ---------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| Publish-workflow regression blocks Wave 8                           | Low        | High   | Manual `npm publish` fallback script already in `scripts/publish-outdated-gitea-packages.sh`                |
| Recharts API drift (peer-dep mismatch across products)              | Med        | Med    | Pin to `^2.15`; `@bytelyst/charts` has type-only re-exports so a major bump fails build, not silent         |
| Tiptap StarterKit extension churn (v2 → v3)                         | Med        | Low    | Lock to a known-good range in `@bytelyst/rich-text/package.json`                                            |
| StreamUI security (LLM emits arbitrary components)                  | Med        | High   | Strict allow-list of renderable component names; never `dangerouslySetInnerHTML`; schema-validated props    |
| Browser support for View Transitions cross-doc                      | Low        | Med    | Mandatory crossfade fallback already in `@bytelyst/motion`                                                  |
| Voice / passkey UX in corp networks (proxy strips WebAuthn)         | Low        | Low    | Document; provide username/password fallback                                                                |
| **On-device AI hardware fragmentation** (some users have no WebGPU) | High       | Med    | `useDeviceCapability()` gates UI; transparent fallback to cloud with `<PrivacyBadge>` reflecting it         |
| **CRDT memory bloat** on long-lived documents                       | Med        | Med    | Yjs garbage-collection enabled; snapshot + replay archive in `@bytelyst/event-store`                        |
| **Generative-theme producing inaccessible palettes**                | Med        | High   | LLM output passes contrast-checker + token-schema validator before persistence; AAA contrast lock available |
| **`@bytelyst/media-ui` bundle weight** (pdf.js is ~500 KB)          | High       | Med    | Lazy-loaded dynamic imports only; never in first-page JS                                                    |
| **Customisable workspace layout collisions** across density modes   | Med        | Low    | Layout persistence keyed by `[productId, userId, density]` triple                                           |
| **WebLLM model download UX** (1–4 GB on first run)                  | High       | High   | `<ModelDownloadCard>` shows progress + bandwidth est; defaults to smallest viable model; opt-in only        |

---

## 9. Concrete next 14 days — kickoff

| Day          | Action                                                                                                                                                                                     | Output                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| **1 (Wed)**  | Trigger publish workflow with broad filter — close out the 8 unpublished packages (react-auth, dashboard-shell, design-tokens, ai-ui, command-palette, motion, data-viz, notifications-ui) | Gitea registry shows all 8 at latest source versions   |
| **2 (Thu)**  | Showcase: delete all `src/lib/*-preview/` snapshots; swap to registry imports                                                                                                              | TODO #14 closed                                        |
| **3 (Fri)**  | Land cross-repo dep update PR for **all 20 web apps** — `@bytelyst/design-tokens@^0.2.0` + adopt `@bytelyst/motion` Reveal on landing                                                      | 20 webs on latest tokens; motion adopted incrementally |
| **4 (Sat)**  | Migrate `learning_ai_notes/web/AgentTimeline.tsx` → `@bytelyst/ai-ui/AgentTimeline`; delete bespoke                                                                                        | -250 LOC in notes/web                                  |
| **5 (Sun)**  | Wire `command-palette` into notes + jarvisjr + fastgap                                                                                                                                     | 3 products with Cmd-K                                  |
| **6 (Mon)**  | **`@bytelyst/charts@0.1.0`** scaffold: `<LineChart>`, `<BarChart>`, `<AreaChart>` MVPs                                                                                                     | New package published 0.1.0                            |
| **7 (Tue)**  | `@bytelyst/charts` showcase demos + adoption in `clock/web` history view                                                                                                                   | 1 product on charts                                    |
| **8 (Wed)**  | **`@bytelyst/rich-text@0.1.0`** scaffold                                                                                                                                                   | Package published 0.1.0                                |
| **9 (Thu)**  | `@bytelyst/rich-text` adoption in `notes/web` body editor                                                                                                                                  | Notes ships rich-text via shared package               |
| **10 (Fri)** | **`@bytelyst/data-table@0.1.0`** scaffold                                                                                                                                                  | Package published 0.1.0                                |
| **11 (Sat)** | `<Skeleton>` + `<EmptyState>` + `<SearchInput>` added to `@bytelyst/ui@0.2.0`                                                                                                              | UI v0.2.0 published                                    |
| **12 (Sun)** | Migrate every product `Skeleton.tsx` → `@bytelyst/ui/skeleton`; codemod commit per repo                                                                                                    | -1,400 LOC across product webs                         |
| **13 (Mon)** | **`@bytelyst/dashboard-shell@0.3.0`** scaffolding kicks off                                                                                                                                | RFC drafted, scaffold landed                           |
| **14 (Tue)** | Wave 9 retro + Wave 10 kickoff                                                                                                                                                             | Roadmap doc bumped to v3.2                             |

### 9.1 Demo-first — showcase prototypes to build alongside the packages

Every package ships with at least one _aspirational_ showcase demo that doubles as customer-facing marketing. The eight to lead with (in priority order):

1. **`<MeshBackground>` + `<Spotlight>` landing hero** — the first thing a prospect sees.
2. **On-device-AI chat with `<PrivacyBadge>`** — "this conversation never left your laptop".
3. **`<CostMeter>` + `<ConfidenceTag>` AI dashboard** — every other AI product hides cost; we show it.
4. **CRDT multi-user notes** — open the same demo URL in two windows, watch it sync.
5. **`<ThemeStudio>` — generative branding playground** — prospects can brand the showcase to their company in 30 seconds.
6. **`<CustomizableWorkspace>` dashboard** — drag tiles, save views, reload — it remembers.
7. **`<ImageGenStream>` + `<AudioWaveform>`** — multimodal AI surfaces in one screen.
8. **`<DebugOverlay>` (Shift-click on any AI response)** — transparency demo for technical evaluators.

---

## 10. Success metrics — end of v3 (Wave 13, ~28 weeks)

| Metric                                              | v2.5 baseline          | v3.1 target                                          |
| --------------------------------------------------- | ---------------------- | ---------------------------------------------------- |
| `@bytelyst/*` packages published                    | 66                     | **92** (66 + 26 net-new)                             |
| Web apps on at least one new UI package             | 0 / 20                 | **20 / 20**                                          |
| Web apps on `dashboard-shell@0.3.0`                 | 0                      | **12**                                               |
| Web apps on `@bytelyst/charts`                      | 0                      | **8**                                                |
| Web apps on `@bytelyst/command-palette`             | 0                      | **20** (universal)                                   |
| Web apps with at least one Wave 13 futurism surface | 0                      | **10+**                                              |
| Bespoke `Skeleton.tsx` files in product webs        | ~7                     | **0**                                                |
| Bespoke `*Modal.tsx` files                          | 10+                    | **≤ 3** (product-specific only)                      |
| Showcase demos                                      | 90+                    | **180+**                                             |
| Playwright tests                                    | 94+                    | **300+**                                             |
| Lighthouse Perf (showcase + each product)           | unmeasured per product | **≥ 90 across the board**                            |
| **INP p75** (each product)                          | unmeasured             | **≤ 200ms**                                          |
| **LCP p75** (each product)                          | unmeasured             | **≤ 2.5s**                                           |
| **CLS p75** (each product)                          | unmeasured             | **≤ 0.1**                                            |
| First-page JS budget per route                      | unenforced             | **≤ 100 KB gzip, CI-gated**                          |
| WCAG 2.2 AA pass rate                               | partial                | **100%**                                             |
| RTL visual-test pass rate                           | none                   | **100%**                                             |
| Locales                                             | 1 (en)                 | **4** (en/es/ar/ja)                                  |
| Brand-layer packages                                | 0                      | **3**                                                |
| EU EAA conformance statement                        | none                   | **published**                                        |
| **Privacy-mode toggle** present                     | 0 products             | **all AI-touching products**                         |
| **CRDT-backed multi-user editing**                  | 0 products             | **≥ 2 products (notes, tracker-web)**                |
| **On-device AI option**                             | 0 products             | **≥ 2 products (localmemgpt, local-llms dashboard)** |
| **`<CostMeter>` visible in AI surfaces**            | 0 products             | **all AI-touching products**                         |
| Cookie/consent UX dark-pattern audit pass           | not run                | **100%**                                             |
| Web Components export available                     | no                     | **`@bytelyst/ui/web-components` published**          |
| **`pnpm create @bytelyst/app`** scaffolding         | none                   | **functional + documented**                          |

---

## 11. Showcase-first workflow & live progress tracker

> **Canonical showcase repo:** `@/Users/sd9235/code/mygh/copilot/learning_ai_uxui_web`
> **Live URL (local dev):** `http://localhost:3010/showcase/<group>/<slug>`
> **Why:** every package shipped from `common_plat` MUST land a working demo in the showcase **before** any product adopts it. The showcase is our "single pane of glass" — visual review, a11y/lighthouse gates, MSW-mocked dependencies, theme + density + RTL toggle, axe-clean — so we iterate cheaply and decide once.

### 11.0 The showcase-first rule (non-negotiable)

For every roadmap deliverable:

1. **Scaffold** in `common_plat/packages/<name>/` with tests.
2. **Vendor snapshot** into `learning_ai_uxui_web/src/lib/<name>-preview/` (mirror byte-for-byte until publish).
3. **Add showcase route** under `src/app/showcase/<group>/<slug>/page.tsx` + catalog entry in `src/catalog/routes.ts`.
4. **MSW mock** any backend dependency in `src/mocks/handlers/`.
5. **Smoke test** the route in `tests/smoke.spec.ts` (axe + screenshot baseline).
6. **Publish** to Gitea registry; **delete** the `*-preview/` vendor dir; **swap** imports.
7. **Adopt** in at least one product web — that PR is what closes the checklist row.

### 11.1 How agents update this tracker

Each row is a GitHub-style task list. Coding agents flip `- [ ]` → `- [x]` **in the same commit** that lands the work, and link the commit short-SHA in the trailing parens. Example:

```markdown
- [x] **8.6 Skeleton codemod** — every product `Skeleton.tsx` swapped to `@bytelyst/ui/skeleton` _(common_plat acb8f02b · showcase 1105e42)_
```

For multi-step rows, sub-bullets are tracked independently. Agents should leave a brief `// progress:` note in their commit body if a row is partially complete.

### 11.2 Progress at a glance

```
TOTAL               58 / 202  🟩🟩🟩⬛⬛⬛⬛⬛⬛⬛  29%
─────────────────────────────────────────────
Wave 8 Rollout      5 /  18  🟩🟩🟩⬛⬛⬛⬛⬛⬛⬛  28%
Wave 9 Data        21 /  42  🟩🟩🟩🟩🟩⬛⬛⬛⬛⬛  50%
Wave 10 Shells      0 /  35  ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛   0%
Wave 11 Adaptive    0 /  26  ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛   0%
Wave 12 Mobile      0 /  26  ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛   0%
Wave 13 Futurism   23 /  39  🟩🟩🟩🟩🟩🟩⬛⬛⬛⬛  59%
Cross-cutting       3 /   8  🟩🟩🟩🟩⬛⬛⬛⬛⬛⬛  38%
Magnet demos        6 /   8  🟩🟩🟩🟩🟩🟩🟩🟩⬛⬛  75%
```

> **Agents:** before pushing your commit, run `pnpm dlx tsx scripts/count-roadmap-progress.ts docs/UI_ROADMAP_2026_V3_CROSS_REPO.md` (to be authored in Wave 8.0) and paste the refreshed block in.

### 11.2.A Open TODOs raised during execution

Numbered list — coding agents drop `// ROADMAP-EXEC-TODO #N` comments at the point of need; the human operator can review and unblock.

| #      | Title                                                                                                                                                                                                                                 | Where it surfaced                                                      | What's needed                                                                                                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **#1** | **Publish workflow run** — push 8 packages to Gitea registry (`react-auth@0.2.0`, `dashboard-shell@0.2.0`, `design-tokens@0.2.0`, `ai-ui@0.4.0`, `command-palette@0.1.0`, `motion@0.1.0`, `data-viz@0.1.0`, `notifications-ui@0.1.0`) | Wave 8.A.1                                                             | Registry credentials / CI trigger. Until this runs, all 8.A.2–6, 8.C.\*, and the next `ui@0.2.0` adoption are gated.                                                                       |
| **#2** | **Add vitest setup to `@bytelyst/ui`**                                                                                                                                                                                                | Wave 9.D additions (Skeleton, SkeletonGroup, LoadingDots, SearchInput) | Decide whether to follow the `motion`/`data-viz` pattern (vitest + happy-dom + @testing-library/react devDeps) or stay typecheck-only. Recommended: copy motion's setup, then write tests. |
| **#3** | **Visual-regression baseline refresh** — the new showcase routes (`/showcase/motion/all`, `/showcase/command-palette/global`, plus any UI demos shipping in Wave 9) need `toHaveScreenshot()` snapshots captured                      | Wave 8 / CC.1                                                          | Run `pnpm baseline` in showcase and commit the snapshots.                                                                                                                                  |
| **#4** | **Republish `@bytelyst/ui@0.2.0` to Gitea registry** once it catches up                                                                                                                                                               | Wave 9 hygiene                                                         | After TODO #1 closes, re-trigger publish so product webs can pin `^0.2.0`.                                                                                                                 |

### 11.3 Wave 8 — Unblock & rollout · `5 / 18`

#### 8.A · Publishing & infra

- [ ] **8.A.1** Trigger common_plat publish workflow with broad filter — 8 packages to Gitea registry
- [ ] **8.A.2** Showcase: delete `src/lib/motion-preview/` · swap to `@bytelyst/motion`
- [ ] **8.A.3** Showcase: delete `src/lib/data-viz-preview/` · swap to `@bytelyst/data-viz`
- [ ] **8.A.4** Showcase: delete `src/lib/notifications-ui-preview/` · swap to `@bytelyst/notifications-ui`
- [ ] **8.A.5** Showcase: delete `src/lib/ai-ui-preview/` · swap to `@bytelyst/ai-ui`
- [ ] **8.A.6** Showcase: delete `src/lib/command-palette-preview/` · swap to `@bytelyst/command-palette`
- [x] **8.A.7** Author `scripts/count-roadmap-progress.ts` — parses this doc, emits the §11.2 block _(common_plat e72323b8)_

#### 8.B · Showcase demos to add

- [x] **8.B.1** `/showcase/motion/all` — Reveal · Stagger · NumberFlow · Tilt · ScrollProgress gallery (one page) _(showcase pending-commit)_
- [x] **8.B.2** `/showcase/command-palette/global` — wired to `GlobalCommandPalette` provider; ⌘K opens; 30+ commands registered _(showcase pending-commit; provider in 77291af)_
- [x] **8.B.3** `/showcase/data-viz/sparkline` — already exists, hydration regression test added (no SSR mismatch with `useId` fix) _(common_plat acb8f02b)_
- [x] **8.B.4** `/showcase/data-viz/progress-ring` — a11y range-input `aria-label` fix verified; axe-clean _(showcase 8598dce)_

#### 8.C · Product migrations

- [ ] **8.C.1** `learning_ai_notes/web` — swap bespoke `AgentTimeline` → `@bytelyst/ai-ui/AgentTimeline`
- [ ] **8.C.2** `learning_ai_clock/web` — drop `framer-motion`; adopt `@bytelyst/motion` Reveal + NumberFlow on `/landing` + `/history`
- [ ] **8.C.3** All product webs — pin `@bytelyst/design-tokens@^0.2.0`
- [ ] **8.C.4** `notes` + `jarvisjr` + `fastgap` — wire `@bytelyst/command-palette`

#### 8.D · Quality gates

- [ ] **8.D.1** Showcase: 0 vendored snapshots remaining (`ls src/lib/*-preview/ 2>/dev/null` returns nothing)
- [ ] **8.D.2** Showcase: all 94 Playwright smoke tests still passing after package swap
- [ ] **8.D.3** Showcase: visual-regression baseline updated post-swap

### 11.4 Wave 9 — Data, content, search · `21 / 42`

#### 9.A · `@bytelyst/charts@0.1.0`

- [x] **9.A.1** Package scaffold + `<LineChart>` (multi-series, smooth/straight, per-series colour) + 19/19 tests _(charts@0.1.0)_
- [x] **9.A.2** `<BarChart>` with diverging-baseline support — 3 tests _(StackedBar deferred to 0.2.x)_
- [x] **9.A.3** `<AreaChart>` (gradient fill + line stroke + single-point safety) — 2 tests
- [x] **9.A.4** `<Donut>` (4 cases) + `<Gauge>` (4 cases, NaN-safe) — 8 tests
- [ ] **9.A.5** `<RadarChart>` + tests _(deferred to charts@0.2.x)_
- [x] **9.A.6** Token-driven theming — all primitives reference `var(--bl-*)` with sensible sRGB fallbacks
- [x] **9.A.7** **Showcase:** `/showcase/charts/all` — gallery + 5 per-chart deep dives (`/charts/line` `/bar` `/area` `/donut` `/gauge`)
- [ ] **9.A.8** **Showcase:** `/showcase/charts/realtime` — SSE-streamed line chart via MSW
- [ ] **9.A.9** **Adoption:** `clock/web` history view replaces inline recharts

#### 9.B · `@bytelyst/rich-text@0.1.0`

- [ ] **9.B.1** Package scaffold with Tiptap StarterKit
- [ ] **9.B.2** `<RichTextEditor>` + `<RichTextViewer>` components
- [ ] **9.B.3** Default toolbar (bold/italic/headings/lists/links/code) + tests
- [ ] **9.B.4** Slash-menu extension + tests
- [ ] **9.B.5** Mention extension (async people search) + tests
- [ ] **9.B.6** **Showcase:** `/showcase/rich-text/editor` — full editor with slash menu + mentions
- [ ] **9.B.7** **Showcase:** `/showcase/rich-text/viewer` — read-only render of a fixture doc
- [ ] **9.B.8** **Adoption:** `notes/web` body editor on `@bytelyst/rich-text`

#### 9.C · `@bytelyst/data-table@0.1.0`

- [ ] **9.C.1** Package scaffold on TanStack Table v9 + TanStack Virtual
- [ ] **9.C.2** Sortable + filterable + paginated column behaviour + tests
- [ ] **9.C.3** Column resize + pin + reorder + tests
- [ ] **9.C.4** Row selection + bulk action bar + tests
- [ ] **9.C.5** Virtualised 10k-row rendering + tests (INP ≤ 200ms)
- [ ] **9.C.6** Density `compact` / `comfortable` variants
- [ ] **9.C.7** **Showcase:** `/showcase/data-table/basic` — 50 rows, sort + filter + select
- [ ] **9.C.8** **Showcase:** `/showcase/data-table/virtual` — 10,000 rows, scroll perf demo
- [ ] **9.C.9** **Adoption:** `tracker-web` admin view on `@bytelyst/data-table`

#### 9.D · `@bytelyst/ui@0.2.0` additions

- [x] **9.D.1** `<Skeleton>` extended with `card` shape — 4 variants (`text`/`block`/`circle`/`card`) _(pending tests — see TODO #2)_
- [x] **9.D.2** `<SkeletonGroup>` orchestrator — `loading` → `fallback` ↔ `children` swap with opacity fade _(pending tests — see TODO #2)_
- [x] **9.D.3** `<EmptyState>` — already shipped in `@bytelyst/ui@0.1.x`; verified API (icon + title + description + actionLabel + onAction)
- [x] **9.D.4** `<SearchInput>` — leading icon, clear-`x`, `suggestions` slot, 3 size variants, `searchbox` role _(pending tests — see TODO #2)_
- [x] **9.D.5** `<FilterBar>` (already in 0.1.x) + `<TagInput>` + `<Combobox>` shipped \u2014 chip editor with Enter/comma commit + searchable select with keyboard nav _(pending tests \u2014 see TODO #2)_
- [x] **9.D.6** `<LoadingDots>` added; `<LoadingSpinner>` already shipped — both token-tinted _(pending tests — see TODO #2)_
- [x] **9.D.7** **Showcase:** `/showcase/ui/skeleton-gallery` — 4 shapes + SkeletonGroup + LoadingDots gallery
- [x] **9.D.8** **Showcase:** `/showcase/ui/empty-states` — 6 idiomatic empty states (inbox-zero · no-results · welcome · offline · access-restricted · archive)
- [x] **9.D.9** **Showcase:** `/showcase/ui/filter-bar-interactive` — SearchInput + 6 chips narrowing a live list
- [ ] **9.D.10** **Codemod:** every product `Skeleton.tsx` → `@bytelyst/ui/skeleton` (delete bespoke)

#### 9.E · `ai-ui@0.5.0`

- [x] **9.E.1** `<Markdown>` dep-free subset renderer + `[cite:<id>]` chip interop — 5 tests _(ai-ui@0.6.0 · 98/98 passing)_
- [x] **9.E.2** `<CodeDiff>` line-LCS diff in <100 LOC; split + unified views — 4 tests _(ai-ui@0.6.0)_
- [x] **9.E.3** `<ExplainThis>` (selectionchange listener → floating CTA → onExplain({ text, rect })) — 2 tests _(ai-ui@0.6.0)_
- [x] **9.E.4** `usePromptHistory()` bash-style ↑/↓ recall + localStorage persistence (storageKey, capacity, dedupe) — 4 tests _(ai-ui@0.6.0)_
- [x] **9.E.5** `useTokenCount()` (chars/token configurable; optional USD cost; memoised) — 4 tests _(ai-ui@0.6.0)_
- [x] **9.E.6** **Showcase:** `/showcase/ai-ui/markdown` — Q4 review sample with 3 citation chips (2 resolved, 1 missing fall-back)

### 11.5 Wave 10 — Product surfaces & shells · `0 / 35`

#### 10.A · `@bytelyst/dashboard-shell@0.3.0`

- [ ] **10.A.1** Slot-based `<AppShell>` API design + RFC merged
- [ ] **10.A.2** `<Sidebar>` (collapsible groups · badges · route-active states) + tests
- [ ] **10.A.3** `<Topbar>` (breadcrumbs · user menu · Cmd-K trigger · theme picker · notifications-bell slot) + tests
- [ ] **10.A.4** Mobile drawer auto-applied < 768px + tests
- [ ] **10.A.5** Density-aware spacing
- [ ] **10.A.6** **Showcase:** `/showcase/shell/full` — interactive full-shell demo with nav switching
- [ ] **10.A.7** **Adoption:** ≥ 3 products on `dashboard-shell@0.3.0`

#### 10.B · `@bytelyst/onboarding-ui@0.1.0`

- [ ] **10.B.1** `<OnboardingChecklist>` + tests
- [ ] **10.B.2** `<TourStep>` + `useTour()` + tests
- [ ] **10.B.3** `<FeatureCallout>` + `<EmptyStateCTA>` + tests
- [ ] **10.B.4** localStorage persistence + tests
- [ ] **10.B.5** **Showcase:** `/showcase/onboarding/checklist` + `/showcase/onboarding/tour`
- [ ] **10.B.6** **Adoption:** `nomgap` first-day tour

#### 10.C · `@bytelyst/billing-ui@0.1.0`

- [ ] **10.C.1** `<PlanCard>` + `<UpgradeModal>` + tests
- [ ] **10.C.2** `<UsageMeter>` + `<InvoiceList>` + `<PaymentMethodList>` + tests
- [ ] **10.C.3** Wired to `@bytelyst/subscription-client` + `@bytelyst/billing-client`
- [ ] **10.C.4** **Showcase:** `/showcase/billing/upgrade-flow` — full upgrade flow with MSW Stripe mock
- [ ] **10.C.5** **Adoption:** `jarvisjr` + `nomgap` upgrade modals

#### 10.D · `@bytelyst/settings-ui@0.1.0`

- [ ] **10.D.1** `<SettingsLayout>` (left-rail nav) + tests
- [ ] **10.D.2** `<ProfileSection>` + `<SecuritySection>` (passkey + 2FA) + tests
- [ ] **10.D.3** `<NotificationPrefs>` + `<DataExportRow>` + `<DangerZone>` + tests
- [ ] **10.D.4** **Showcase:** `/showcase/settings/full` — all sections wired
- [ ] **10.D.5** **Adoption:** ≥ 2 products on `settings-ui`

#### 10.E · `@bytelyst/legal-ui@0.1.0`

- [ ] **10.E.1** `<PrivacyPolicyPage>` + `<TermsPage>` MDX-driven
- [ ] **10.E.2** `<CookieBanner>` (EAA-compliant, **no dark patterns** — lint enforced)
- [ ] **10.E.3** `<DataProcessingNotice>`
- [ ] **10.E.4** **Showcase:** `/showcase/legal/all` — every legal surface rendered

#### 10.F · `@bytelyst/telemetry-ui@0.1.0`

- [ ] **10.F.1** `data-bl-event` attribute scraper + React provider
- [ ] **10.F.2** `useTrackedClick(name)` hook + tests
- [ ] **10.F.3** PostHog + OpenTelemetry adapters
- [ ] **10.F.4** **Showcase:** `/showcase/telemetry/live` — events stream visible in a dev panel

#### 10.G · `@bytelyst/timeline@0.1.0` & brand layers

- [ ] **10.G.1** `<Timeline>` (grouped by day, sticky headers, infinite scroll) + tests
- [ ] **10.G.2** **Showcase:** `/showcase/timeline/memory-pattern` — replicates `notes/MemoryTimeline.tsx`
- [ ] **10.G.3** Brand packages: `brand-flowmonk`, `brand-chronomind`, `brand-mindlyst` (Tier-2 overrides)
- [ ] **10.G.4** **Showcase:** brand switcher next to theme picker

### 11.6 Wave 11 — Adaptive / ambient / multimodal · `0 / 26`

#### 11.A · `@bytelyst/adaptive-ui@0.1.0`

- [ ] **11.A.1** `<SchemaForm>` (JSON Schema → form via `react-hook-form`) + tests
- [ ] **11.A.2** `<SchemaTable>` (editable from schema) + tests
- [ ] **11.A.3** `<StreamUI>` — LLM-emitted component tree, **strict allow-list** of renderable names
- [ ] **11.A.4** **Showcase:** `/showcase/adaptive-ui/schema-form` — paste a JSON Schema, get a form
- [ ] **11.A.5** **Showcase:** `/showcase/adaptive-ui/stream-ui` — streamed AI-emitted tree from MSW mock

#### 11.B · `@bytelyst/assistant-shell@0.1.0`

- [ ] **11.B.1** Floating dot trigger · summon with ⌘J + tests
- [ ] **11.B.2** Sheet hosts `ai-ui/ChatStream` with route-aware system prompt
- [ ] **11.B.3** **Showcase:** `/showcase/assistant/global` — every page exposes ⌘J
- [ ] **11.B.4** **Adoption:** `notes/web` first product host

#### 11.C · `@bytelyst/speech-ui@0.1.0`

- [ ] **11.C.1** `<VoiceInputButton>` (Web Speech API + waveform visualiser)
- [ ] **11.C.2** `<DictationOverlay>` + `<TranscriptViewer>`
- [ ] **11.C.3** `ai-ui/PromptComposer.voiceInput` integration
- [ ] **11.C.4** **Showcase:** `/showcase/speech/dictation` + `/showcase/speech/composer-voice`

#### 11.D · `@bytelyst/file-ui@0.1.0`

- [ ] **11.D.1** `<FileDrop>` (chunked upload via `@bytelyst/blob-client`)
- [ ] **11.D.2** `<FilePreview>` (image/PDF/text auto)
- [ ] **11.D.3** `<FileBrowser>` (grid + list views)
- [ ] **11.D.4** `<ImageCrop>`
- [ ] **11.D.5** **Showcase:** `/showcase/file/upload` + `/showcase/file/browser`

#### 11.E · `@bytelyst/realtime-ui@0.1.0`

- [ ] **11.E.1** `<PresenceAvatars>` + `useRealtimePresence(channel)`
- [ ] **11.E.2** `<TypingIndicator>`
- [ ] **11.E.3** `<LiveCursor>`
- [ ] **11.E.4** **Showcase:** `/showcase/realtime/cursors` — open in 2 windows, see live cursors

#### 11.F · Trust amendments

- [ ] **11.F.1** `ai-ui/AgentTimeline` gains cancel + retry actions
- [ ] **11.F.2** `ai-ui/SuggestionRow` (next-action prediction) + tests
- [ ] **11.F.3** `ai-ui/InlineAI` (highlight → rewrite) + tests
- [ ] **11.F.4** **Showcase:** `/showcase/ai-ui/inline-rewrite` — highlight text in an editor → rewrite tray

### 11.7 Wave 12 — Mobile · i18n · sustainability · `0 / 26`

#### 12.A · Mobile primitives in `@bytelyst/ui@0.3.0`

- [ ] **12.A.1** `<BottomSheet>` (snap points + scrollable body) + tests
- [ ] **12.A.2** `<StickyActionBar>` (safe-area-aware) + tests
- [ ] **12.A.3** `<TouchableRipple>` + tests
- [ ] **12.A.4** `<PullToRefresh>` + tests
- [ ] **12.A.5** Mobile-variant `<Dropdown>` / `<Tooltip>` (long-press) + tests
- [ ] **12.A.6** **Showcase:** `/showcase/mobile/all` — every mobile primitive on a 375px viewport

#### 12.B · `@bytelyst/i18n@0.1.0`

- [ ] **12.B.1** `react-intl` wrapper + type-safe catalogues
- [ ] **12.B.2** Auto-extraction CLI (`pnpm i18n:extract`)
- [ ] **12.B.3** Default locales: `en`, `es`, `ar`, `ja`
- [ ] **12.B.4** **Showcase:** locale switcher in theme picker
- [ ] **12.B.5** **Showcase:** every demo translated into all 4 locales (or marked `intl-pending`)

#### 12.C · RTL audit

- [ ] **12.C.1** Stylelint rule blocks `left:` / `right:` outside `dir`-scoped contexts
- [ ] **12.C.2** Codemod: convert physical → logical properties across `common_plat/packages/*`
- [ ] **12.C.3** **Showcase:** `dir="rtl"` toggle next to theme picker
- [ ] **12.C.4** Visual-regression: every demo also snapshotted at `dir="rtl"`

#### 12.D · Inclusive design

- [ ] **12.D.1** Atkinson Hyperlegible font toggle in theme picker
- [ ] **12.D.2** AAA contrast lock-up toggle
- [ ] **12.D.3** Motion-pause toggle (overrides `prefers-reduced-motion`)
- [ ] **12.D.4** VPAT 2.5 ACR doc drafted + reviewed externally
- [ ] **12.D.5** EU EAA conformance statement published on `/legal/accessibility`

#### 12.E · Showcase additions

- [ ] **12.E.1** Per-demo viewport switcher (375 / 768 / 1280 / fluid)
- [ ] **12.E.2** Per-demo a11y inspector panel (axe + colour-contrast)

#### 12.F · Sustainability + PWA

- [ ] **12.F.1** `co2.js` budget enforced in CI per package
- [ ] **12.F.2** Showcase becomes installable PWA with offline catalog
- [ ] **12.F.3** `pnpm create @bytelyst/app my-app` scaffolds a working dev server < 60s
- [ ] **12.F.4** **Showcase:** `/showcase/sustainability/budget-card` — visualises live page CO₂

### 11.8 Wave 13 — Futurism layer · `23 / 39`

#### 13.A · `@bytelyst/on-device-ai@0.1.0`

- [ ] **13.A.1** WebLLM runner adapter
- [ ] **13.A.2** transformers.js runner adapter
- [ ] **13.A.3** `useDeviceCapability()` hook + tests
- [ ] **13.A.4** `useOnDeviceModel(modelId)` hook + tests
- [ ] **13.A.5** `<ModelDownloadCard>` UI (progress + bandwidth est.) + tests
- [ ] **13.A.6** Transparent cloud fallback when device incapable + tests
- [ ] **13.A.7** **Showcase:** `/showcase/futurism/on-device-chat` — full chat that runs locally, with `<PrivacyBadge>` honest about mode
- [ ] **13.A.8** **Adoption:** `localmemgpt/web` first host

#### 13.B · `@bytelyst/collab@0.1.0`

- [ ] **13.B.1** Yjs canonical layer + tests
- [ ] **13.B.2** Automerge adapter + tests
- [ ] **13.B.3** `<CollabProvider>` + `useSharedDoc(roomId)` + `useAwareness()` + tests
- [ ] **13.B.4** `<CommentThread>` (anchored to selection range) + tests
- [ ] **13.B.5** SSE transport via `@bytelyst/fastify-sse`
- [ ] **13.B.6** **Showcase:** `/showcase/futurism/crdt-notes` — same URL, two windows, watch it sync
- [ ] **13.B.7** **Adoption:** `notes/web` + `tracker-web` pilots

#### 13.C · `ai-ui@0.5.0` trust surfaces

- [x] **13.C.1** `<CostMeter>` + 5 tests — live token + USD readout with neutral/ok/warn/danger budget tiers, NaN-safe _(ai-ui@0.5.0 · 67/67 passing)_
- [x] **13.C.2** `<ConfidenceTag>` + 5 tests — buckets `[0..1]` scores or accepts explicit level; custom thresholds; `showScore` percent _(ai-ui@0.5.0)_
- [x] **13.C.3** `<RefusalCard>` + 4 tests — 6 reason archetypes · calm-not-red tinting · up-to-3 actions · footer slot _(ai-ui@0.5.0)_
- [x] **13.C.4** `<ProvenanceDrawer>` slide-in dialog + Escape/backdrop close + body scroll lock + empty-state — 5 tests _(ai-ui@0.5.0+)_
- [x] **13.C.5** `<DebugOverlay>` Shift/Alt/Meta modifier-click reveals JSON inspector — 4 tests, MAG.8 enabled _(ai-ui@0.5.0+)_
- [x] **13.C.6** `<PrivacyBadge>` 4 modes (on-device / cloud / hybrid / unknown) + detail line + iconOnly — 3 tests _(ai-ui@0.5.0+)_
- [x] **13.C.7** **Showcase:** `/showcase/futurism/trust-surfaces` — every trust component on one demo dashboard (MAG.3)

#### 13.D · `motion@0.2.0` spatial primitives

- [x] **13.D.1** `<Parallax>` scroll-driven translate3d via rAF · speed multiplier + axis (y/x) + reduced-motion bypass — 2 tests _(motion@0.2.1)_
- [x] **13.D.2** `<Spotlight>` (cursor-follow radial gradient via two CSS custom props, no React re-render) + 3 tests _(common_plat motion@0.2.0 · 23/23 passing)_
- [x] **13.D.3** `<Magnetic>` (Arc-style pointer-attracted wrapper with field-radius + clamped strength + reduced-motion fallback) + 2 tests _(common_plat motion@0.2.0)_
- [x] **13.D.4** `<MeshBackground>` (4-stop OKLCH gradient with drifting blobs · 3 mood tiers · reduced-motion static fallback) + 2 tests _(common_plat motion@0.2.0)_
- [x] **13.D.5** `<TiltGallery>` horizontal rail of cursor-tilting tiles · arrow-key scroll · scroll-snap — 3 tests _(motion@0.2.1)_
- [x] **13.D.6** **Showcase:** `/showcase/futurism/spatial-hero` — full marketing-grade landing page with MeshBackground + Spotlight + 2 Magnetic CTAs + 4 NumberFlow KPIs + StaggerList

#### 13.E · `@bytelyst/generative-theme@0.1.0`

- [x] **13.E.1** Brand-prompt → token override generator — 7 deterministic palettes (midnight / citrus / forest / ocean / rose / graphite / violet) + pluggable async LLM hook _(generative-theme@0.1.0 · 18/18 passing)_
- [x] **13.E.2** WCAG contrast utilities + AA/AAA-lock enforcement (parseHex / relativeLuminance / contrast / adjustForContrast / enforceContrast / auditTheme / applyTheme)
- [x] **13.E.3** **Showcase:** `/showcase/futurism/theme-studio` (MAG.5) — 7 quick prompts + AA/AAA/off toggle + live preview with per-pairing contrast report

#### 13.F · `@bytelyst/customizable-workspace@0.1.0`

- [x] **13.F.1** Drag-reorder + resize tiles — native HTML5 drag (zero @dnd-kit dependency), keyboard ←/→ resize + ↑/↓ move, 1/2/3/4 size buttons _(customizable-workspace@0.1.0 · 10/10 passing)_
- [x] **13.F.2** `LayoutPersistence` adapter + `reconcile()` defensive against schema drift — localStorage default; hosts on platform-service wire a server-backed adapter
- [x] **13.F.3** **Showcase:** `/showcase/futurism/workspace` (MAG.6) — 6 tiles backed by Sparkline + LineChart, reload-persistent

#### 13.G · `@bytelyst/media-ui@0.1.0`

- [x] **13.G.1** `<ImageGenStream>` (4-status state machine · progress overlay · blur-on-streaming) — 4 tests _(media-ui@0.1.0 · 10/10 passing)_
- [x] **13.G.2** `<AudioWaveform>` canvas + click-to-seek + DPR-aware paint + WebAudio peak decode — 3 tests
- [ ] **13.G.3** `<PdfPreview>` (pdf.js lazy) + tests _(deferred to media-ui@0.2.x — needs the pdf.js runtime; only routes that use it should pay the bundle cost)_
- [x] **13.G.4** `<VideoPlayer>` native `<video controls>` + chapter buttons + caption rail — 3 tests
- [x] **13.G.5** **Showcase:** `/showcase/futurism/multimodal` (MAG.7) — ImageGenStream + AudioWaveform + VideoPlayer on one page (PdfPreview slot reserved for 0.2.x)

### 11.9 Cross-cutting · `3 / 8`

- [ ] **CC.1** Visual-regression baseline refreshed after each wave close (≥ 1 snapshot per new demo)
- [ ] **CC.2** Lighthouse CI gates: Perf/A11y/SEO ≥ 90 on every showcase route
- [x] **CC.3** axe-core gate active — every showcase route is asserted axe-clean in `tests/smoke.spec.ts` (currently 129/129 passing, 0 critical / 0 serious)
- [ ] **CC.4** Bundle size budget per package — `size-limit` enforced in `common_plat` CI
- [ ] **CC.5** Storybook 8 deployed per package (Gitea Pages)
- [x] **CC.6** `docs/design-system/ANTIPATTERNS.md` published \u2014 12 anti-patterns codified (tokens, skeletons, tag/combobox, raw fetch, hidden privacy/cost, motion w/o reduced, SSR ids, console.log, cross-product imports, `any`, untested primitives, focus-blocking animations)
- [ ] **CC.7** Public roadmap page in `tracker-web` renders this doc live
- [x] **CC.8** `scripts/count-roadmap-progress.ts` wired into `.husky/pre-commit` — staging the roadmap re-runs the counter + re-stages the refreshed file so commits stay self-consistent

### 11.10 The eight customer-magnet demos (§9.1 — kept here for tracking)

Each is the _capstone_ demo of its package family. Marketing-grade.

- [x] **MAG.1** `/showcase/futurism/spatial-hero` — `<MeshBackground>` + `<Spotlight>` landing hero (Wave 13.D.6) **✨ the customer-magnet hero is live**
- [ ] **MAG.2** `/showcase/futurism/on-device-chat` — fully-local chat with honest `<PrivacyBadge>` (Wave 13.A.7)
- [x] **MAG.3** `/showcase/futurism/trust-surfaces` — `<CostMeter>` + `<ConfidenceTag>` + `<RefusalCard>` dashboard (Wave 13.C.7) **✨ the trust-surfaces magnet is live** _(ProvenanceDrawer pending in 13.C.4)_
- [ ] **MAG.4** `/showcase/futurism/crdt-notes` — open two windows, watch them sync (Wave 13.B.6)
- [x] **MAG.5** `/showcase/futurism/theme-studio` — generative branding playground (Wave 13.E.3) **✨ the theme-studio magnet is live**
- [x] **MAG.6** `/showcase/futurism/workspace` — drag tiles, save view, reload (Wave 13.F.3) **✨ the workspace magnet is live**
- [x] **MAG.7** `/showcase/futurism/multimodal` — image-gen + audio waveform + video (Wave 13.G.5) **✨ the multimodal magnet is live** _(PDF deferred per 13.G.3)_
- [x] **MAG.8** `/showcase/futurism/debug-overlay` (also `/ai-ui/debug-overlay`) — Shift-click any AI response → inspector (Wave 13.C.5) **✨ the debug-overlay magnet is live**

---

## 12. Document hygiene

- **v3.0** (initial commit): new cross-repo UX roadmap; built on v2.5 (showcase repo). Added Waves 8–12, 16 net-new packages, per-product upgrade matrix, and modern-web-platform adoption guidance.
- **v3.1** (review pass): fixed under-counts (15+ webs not 11; 26 net-new packages not 16). Added five major futurism subsections (§3.4 on-device & privacy-first AI, §3.5 real-time CRDT collab, §3.6 spatial/visionOS surfaces, §3.7 Core Web Vital budgets, §3.8 anti-patterns). Introduced **Wave 13** (futurism layer) with 7 new packages: `on-device-ai`, `collab`, `generative-theme`, `customizable-workspace`, `media-ui`, plus `ai-ui@0.5` trust surfaces and `motion@0.2` spatial primitives. Added §6.1 RSC vs client guidance, §6.2 Web Components interop for non-React consumers, §6.3 adjacent token packages (email, audio, motion-tokens). Expanded per-product matrix to all 20 web apps including platform dashboards. Added 6 new risk-matrix rows and §9.1 demo-first list of 8 customer-facing prototypes.
- **v3.2** (this revision): added **§11 showcase-first workflow & live progress tracker** — **202 machine-parsable checklist items** across Waves 8 – 13 + cross-cutting + 8 customer-magnet demos. Codified the showcase-first rule: every package lands a `learning_ai_uxui_web` demo route before any product adopts. Tracker designed for coding agents to flip checkboxes inline with their commits (with auto-counter script `scripts/count-roadmap-progress.ts` slated for Wave 8.A.7). Renumbered hygiene § 11 → § 12.
- Mirror at `learning_ai_uxui_web/docs/ROADMAP_2026_V3_CROSS_REPO.md` after each commit.
- Future versions bump as waves close (`v3.3`, `v3.4`, ...).

**Owner:** ByteLyst Platform UI guild
**Discussion:** `tracker-web` (issue tag: `roadmap-2026`, milestone: `v3`)
