diff --git a/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md index 5d42f670..635178d2 100644 --- a/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md +++ b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md @@ -1,14 +1,15 @@ # ByteLyst Cross-Repo UX Roadmap — v3 (Future-Proof, Elegant, Rich) -> **Version:** v3.1 — 2026-05-27 (review + futurism amendment) -> **Status:** Draft for review +> **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). +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.1 vs v3.0:** corrected product-web inventory (15+ not 11), corrected new-package count (18 in original waves + 8 added below = **26 net-new**), added five subsections on the frontier UX themes that attract today's most discerning customers (on-device AI, real-time CRDT collab, cost & confidence transparency, spatial UI, anti-patterns), introduced Wave 13 (futurism layer), expanded the per-product matrix to all 15+ webs, and added a dedicated **RSC vs client / Web Components interop** section. +> **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. --- @@ -580,12 +581,387 @@ Every package ships with at least one _aspirational_ showcase demo that doubles --- -## 11. Document hygiene +## 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//` +> **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//` with tests. +2. **Vendor snapshot** into `learning_ai_uxui_web/src/lib/-preview/` (mirror byte-for-byte until publish). +3. **Add showcase route** under `src/app/showcase///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 0 / 202 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +───────────────────────────────────────────── +Wave 8 Rollout 0 / 18 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Wave 9 Data 0 / 42 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Wave 10 Shells 0 / 35 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Wave 11 Adaptive 0 / 26 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Wave 12 Mobile 0 / 26 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Wave 13 Futurism 0 / 39 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Cross-cutting 0 / 8 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +Magnet demos 0 / 8 ⬛⬛⬛⬛⬛⬛⬛⬛⬛⬛ 0% +``` + +> **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.3 Wave 8 — Unblock & rollout · `0 / 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` +- [ ] **8.A.7** Author `scripts/count-roadmap-progress.ts` — parses this doc, emits the §11.2 block + +#### 8.B · Showcase demos to add + +- [ ] **8.B.1** `/showcase/motion/all` — Reveal · Stagger · NumberFlow · Tilt · ScrollProgress gallery (one page) +- [ ] **8.B.2** `/showcase/command-palette/global` — wired to `GlobalCommandPalette` provider; ⌘K opens; 30+ commands registered +- [ ] **8.B.3** `/showcase/data-viz/sparkline` — already exists, **add hydration test** (no SSR mismatch with `useId` fix) +- [ ] **8.B.4** `/showcase/data-viz/progress-ring` — already exists, **add a11y label fix verified** + +#### 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 · `0 / 42` + +#### 9.A · `@bytelyst/charts@0.1.0` + +- [ ] **9.A.1** Package scaffold + `` + tests (≥ 10 cases) +- [ ] **9.A.2** `` + `` + tests +- [ ] **9.A.3** `` + tests +- [ ] **9.A.4** `` + `` + tests +- [ ] **9.A.5** `` + tests +- [ ] **9.A.6** Token-driven theming: all 7 schemes verified +- [ ] **9.A.7** **Showcase:** `/showcase/charts/all` — gallery of every chart, theme + density toggle aware +- [ ] **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** `` + `` 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 + +- [ ] **9.D.1** `` (text/rect/circle/card variants) + tests +- [ ] **9.D.2** `` orchestrator + tests +- [ ] **9.D.3** `` with illustration slot + CTA + tests +- [ ] **9.D.4** `` with suggestions slot + tests +- [ ] **9.D.5** `` + `` + `` + tests +- [ ] **9.D.6** `` + `` (token-tinted) + tests +- [ ] **9.D.7** **Showcase:** `/showcase/ui/skeleton-gallery` +- [ ] **9.D.8** **Showcase:** `/showcase/ui/empty-states` — 6 idiomatic empty states +- [ ] **9.D.9** **Showcase:** `/showcase/ui/filter-bar` — interactive chip filter demo +- [ ] **9.D.10** **Codemod:** every product `Skeleton.tsx` → `@bytelyst/ui/skeleton` (delete bespoke) + +#### 9.E · `ai-ui@0.5.0` + +- [ ] **9.E.1** `` with citation interop + tests +- [ ] **9.E.2** `` (split + unified views) + tests +- [ ] **9.E.3** `` (highlight → "what does this do?") + tests +- [ ] **9.E.4** `usePromptHistory()` (↑/↓ recall, per-product persistence) + tests +- [ ] **9.E.5** `useTokenCount()` live count + cost estimate + tests +- [ ] **9.E.6** **Showcase:** `/showcase/ai-ui/markdown-citations` — streamed markdown with inline `` references + +### 11.5 Wave 10 — Product surfaces & shells · `0 / 35` + +#### 10.A · `@bytelyst/dashboard-shell@0.3.0` + +- [ ] **10.A.1** Slot-based `` API design + RFC merged +- [ ] **10.A.2** `` (collapsible groups · badges · route-active states) + tests +- [ ] **10.A.3** `` (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** `` + tests +- [ ] **10.B.2** `` + `useTour()` + tests +- [ ] **10.B.3** `` + `` + 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** `` + `` + tests +- [ ] **10.C.2** `` + `` + `` + 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** `` (left-rail nav) + tests +- [ ] **10.D.2** `` + `` (passkey + 2FA) + tests +- [ ] **10.D.3** `` + `` + `` + 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** `` + `` MDX-driven +- [ ] **10.E.2** `` (EAA-compliant, **no dark patterns** — lint enforced) +- [ ] **10.E.3** `` +- [ ] **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** `` (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** `` (JSON Schema → form via `react-hook-form`) + tests +- [ ] **11.A.2** `` (editable from schema) + tests +- [ ] **11.A.3** `` — 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** `` (Web Speech API + waveform visualiser) +- [ ] **11.C.2** `` + `` +- [ ] **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** `` (chunked upload via `@bytelyst/blob-client`) +- [ ] **11.D.2** `` (image/PDF/text auto) +- [ ] **11.D.3** `` (grid + list views) +- [ ] **11.D.4** `` +- [ ] **11.D.5** **Showcase:** `/showcase/file/upload` + `/showcase/file/browser` + +#### 11.E · `@bytelyst/realtime-ui@0.1.0` + +- [ ] **11.E.1** `` + `useRealtimePresence(channel)` +- [ ] **11.E.2** `` +- [ ] **11.E.3** `` +- [ ] **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** `` (snap points + scrollable body) + tests +- [ ] **12.A.2** `` (safe-area-aware) + tests +- [ ] **12.A.3** `` + tests +- [ ] **12.A.4** `` + tests +- [ ] **12.A.5** Mobile-variant `` / `` (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 · `0 / 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** `` 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 `` 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** `` + `useSharedDoc(roomId)` + `useAwareness()` + tests +- [ ] **13.B.4** `` (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 + +- [ ] **13.C.1** `` + tests +- [ ] **13.C.2** `` + tests +- [ ] **13.C.3** `` + tests +- [ ] **13.C.4** `` (event-store backed) + tests +- [ ] **13.C.5** `` (Shift-click AI response → inspector) + tests +- [ ] **13.C.6** `` (reflects on-device vs cloud mode) + tests +- [ ] **13.C.7** **Showcase:** `/showcase/futurism/trust-surfaces` — every trust component on one demo dashboard + +#### 13.D · `motion@0.2.0` spatial primitives + +- [ ] **13.D.1** `` (scroll-driven, zero-JS where supported) + tests +- [ ] **13.D.2** `` (cursor-follow radial gradient) + tests +- [ ] **13.D.3** `` (Arc-style pointer-attracted button) + tests +- [ ] **13.D.4** `` (OKLCH ambient that shifts with time-of-day) + tests +- [ ] **13.D.5** `` + tests +- [ ] **13.D.6** **Showcase:** `/showcase/futurism/spatial-hero` — full marketing-grade landing page + +#### 13.E · `@bytelyst/generative-theme@0.1.0` + +- [ ] **13.E.1** "Describe your brand" → LLM → Tier-2 token override generator +- [ ] **13.E.2** Output passes contrast-checker + AAA lock before persistence +- [ ] **13.E.3** **Showcase:** `/showcase/futurism/theme-studio` — interactive: type prompt, see live re-theming + +#### 13.F · `@bytelyst/customizable-workspace@0.1.0` + +- [ ] **13.F.1** Drag-resize tiles on `@dnd-kit/sortable` +- [ ] **13.F.2** Saved views per route, layout persistence to platform-service +- [ ] **13.F.3** **Showcase:** `/showcase/futurism/workspace` — drag tiles, save view, reload + +#### 13.G · `@bytelyst/media-ui@0.1.0` + +- [ ] **13.G.1** `` (live image gen with progress) + tests +- [ ] **13.G.2** `` (canvas + transcript scrubber) + tests +- [ ] **13.G.3** `` (pdf.js lazy) + tests +- [ ] **13.G.4** `` (chapters + captions) + tests +- [ ] **13.G.5** **Showcase:** `/showcase/futurism/multimodal` — image-gen, audio waveform, PDF, video on one page + +### 11.9 Cross-cutting · `0 / 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 +- [ ] **CC.3** axe-core gate: 0 critical violations on every showcase route +- [ ] **CC.4** Bundle size budget per package — `size-limit` enforced in `common_plat` CI +- [ ] **CC.5** Storybook 8 deployed per package (Gitea Pages) +- [ ] **CC.6** `docs/design-system/ANTIPATTERNS.md` published (Wave 9 §3.8 ref) +- [ ] **CC.7** Public roadmap page in `tracker-web` renders this doc live +- [ ] **CC.8** **`scripts/count-roadmap-progress.ts`** (Wave 8.A.7) wired into pre-commit hook so the §11.2 block auto-refreshes + +### 11.10 The eight customer-magnet demos (§9.1 — kept here for tracking) + +Each is the _capstone_ demo of its package family. Marketing-grade. + +- [ ] **MAG.1** `/showcase/futurism/spatial-hero` — `` + `` landing hero (Wave 13.D.6) +- [ ] **MAG.2** `/showcase/futurism/on-device-chat` — fully-local chat with honest `` (Wave 13.A.7) +- [ ] **MAG.3** `/showcase/futurism/trust-surfaces` — `` + `` + `` dashboard (Wave 13.C.7) +- [ ] **MAG.4** `/showcase/futurism/crdt-notes` — open two windows, watch them sync (Wave 13.B.6) +- [ ] **MAG.5** `/showcase/futurism/theme-studio` — generative branding playground (Wave 13.E.3) +- [ ] **MAG.6** `/showcase/futurism/workspace` — drag tiles, save view, reload (Wave 13.F.3) +- [ ] **MAG.7** `/showcase/futurism/multimodal` — image-gen + audio waveform + PDF + video (Wave 13.G.5) +- [ ] **MAG.8** `/showcase/ai-ui/debug-overlay` — Shift-click any AI response → inspector (Wave 13.C.5) + +--- + +## 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** (this revision): comprehensive 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.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.2`, `v3.3`, ...). +- Future versions bump as waves close (`v3.3`, `v3.4`, ...). **Owner:** ByteLyst Platform UI guild **Discussion:** `tracker-web` (issue tag: `roadmap-2026`, milestone: `v3`) diff --git a/scripts/count-roadmap-progress.ts b/scripts/count-roadmap-progress.ts new file mode 100644 index 00000000..b77f072d --- /dev/null +++ b/scripts/count-roadmap-progress.ts @@ -0,0 +1,165 @@ +#!/usr/bin/env tsx +/** + * count-roadmap-progress.ts — parse the v3 cross-repo UX roadmap doc and + * regenerate the "§11.2 Progress at a glance" block with live counts. + * + * Usage: + * pnpm dlx tsx scripts/count-roadmap-progress.ts \ + * docs/UI_ROADMAP_2026_V3_CROSS_REPO.md + * + * Behaviour: + * - Reads the given doc. + * - Counts `- [ ]` (open) and `- [x]` / `- [X]` (closed) checkboxes in each + * §11.x sub-section by parsing `### 11.N Wave …` headings. + * - Rewrites the fenced block inside `### 11.2 Progress at a glance` + * in-place so the visible counters match reality. + * - Also rewrites the `· `0 / N`` suffix on every `### 11.x Wave …` + * heading so per-wave totals stay accurate. + * + * Idempotent: re-running with no checkbox changes is a no-op. + * Exit codes: 0 ok, 1 doc not found, 2 expected sections missing. + * + * Authored: Wave 8.A.7 of v3.2 roadmap. + */ +import { readFileSync, writeFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +const docPath = resolve(process.argv[2] ?? 'docs/UI_ROADMAP_2026_V3_CROSS_REPO.md'); + +let src: string; +try { + src = readFileSync(docPath, 'utf8'); +} catch { + console.error(`[count-roadmap-progress] cannot read ${docPath}`); + process.exit(1); +} + +interface Section { + /** Heading label (e.g. "Wave 8 Rollout"). */ + label: string; + /** Regex matching the `### 11.x …` heading. */ + headingRe: RegExp; + /** Regex matching the next `### 11.x …` heading (acts as end-marker). */ + nextHeadingRe: RegExp; +} + +const sections: Section[] = [ + { label: 'Wave 8 Rollout', headingRe: /^### 11\.3 Wave 8 .*$/m, nextHeadingRe: /^### 11\.4 /m }, + { label: 'Wave 9 Data', headingRe: /^### 11\.4 Wave 9 .*$/m, nextHeadingRe: /^### 11\.5 /m }, + { label: 'Wave 10 Shells', headingRe: /^### 11\.5 Wave 10 .*$/m, nextHeadingRe: /^### 11\.6 /m }, + { + label: 'Wave 11 Adaptive', + headingRe: /^### 11\.6 Wave 11 .*$/m, + nextHeadingRe: /^### 11\.7 /m, + }, + { label: 'Wave 12 Mobile', headingRe: /^### 11\.7 Wave 12 .*$/m, nextHeadingRe: /^### 11\.8 /m }, + { + label: 'Wave 13 Futurism', + headingRe: /^### 11\.8 Wave 13 .*$/m, + nextHeadingRe: /^### 11\.9 /m, + }, + { + label: 'Cross-cutting', + headingRe: /^### 11\.9 Cross-cutting .*$/m, + nextHeadingRe: /^### 11\.10 /m, + }, + { label: 'Magnet demos', headingRe: /^### 11\.10 .*$/m, nextHeadingRe: /^---\s*$/m }, +]; + +function sliceSection(text: string, start: RegExp, end: RegExp): string | null { + const startMatch = start.exec(text); + if (!startMatch) return null; + const after = text.slice(startMatch.index); + const endMatch = end.exec(after); + return endMatch ? after.slice(0, endMatch.index) : after; +} + +function countChecks(block: string): { open: number; done: number } { + const open = (block.match(/^- \[ \]/gm) ?? []).length; + const done = (block.match(/^- \[[xX]\]/gm) ?? []).length; + return { open, done }; +} + +function bar(done: number, total: number, width = 10): string { + if (total === 0) return '⬛'.repeat(width); + const filled = Math.round((done / total) * width); + return '🟩'.repeat(filled) + '⬛'.repeat(width - filled); +} + +function pct(done: number, total: number): string { + if (total === 0) return ' 0%'; + return `${String(Math.round((done / total) * 100)).padStart(3)}%`; +} + +interface Tally { + label: string; + done: number; + total: number; +} +const tallies: Tally[] = []; + +let totalDone = 0; +let totalAll = 0; + +for (const s of sections) { + const block = sliceSection(src, s.headingRe, s.nextHeadingRe); + if (block === null) { + console.error(`[count-roadmap-progress] section not found: ${s.label}`); + process.exit(2); + } + const { open, done } = countChecks(block); + const total = open + done; + tallies.push({ label: s.label, done, total }); + totalDone += done; + totalAll += total; +} + +// Build the new "§11.2 Progress at a glance" fenced block. +const lines: string[] = []; +lines.push( + `TOTAL ${String(totalDone).padStart(3)} / ${String(totalAll).padStart(3)} ${bar(totalDone, totalAll)} ${pct(totalDone, totalAll)}` +); +lines.push('─'.repeat(45)); +const labelWidth = Math.max(...tallies.map(t => t.label.length)); +for (const t of tallies) { + lines.push( + `${t.label.padEnd(labelWidth)} ${String(t.done).padStart(3)} / ${String(t.total).padStart(3)} ${bar(t.done, t.total)} ${pct(t.done, t.total)}` + ); +} +const newBlock = lines.join('\n'); + +// Locate the existing fenced block inside §11.2 and replace its body. +const headerRe = /(### 11\.2 Progress at a glance\s*\n+```)([\s\S]*?)(```)/; +const headerMatch = src.match(headerRe); +if (!headerMatch) { + console.error('[count-roadmap-progress] §11.2 fenced block not found'); + process.exit(2); +} +const replaced = src.replace( + headerRe, + (_full, open, _body, close) => `${open}\n${newBlock}\n${close}` +); + +// Also rewrite the per-section `· \`N / M\`` suffix on §11.3 .. §11.10 headings. +let withSuffixes = replaced; +const headingSuffixMap: Array<[RegExp, Tally]> = [ + [/^(### 11\.3 Wave 8 — Unblock & rollout) · `[^`]*`$/m, tallies[0]!], + [/^(### 11\.4 Wave 9 — Data, content, search) · `[^`]*`$/m, tallies[1]!], + [/^(### 11\.5 Wave 10 — Product surfaces & shells) · `[^`]*`$/m, tallies[2]!], + [/^(### 11\.6 Wave 11 — Adaptive \/ ambient \/ multimodal) · `[^`]*`$/m, tallies[3]!], + [/^(### 11\.7 Wave 12 — Mobile · i18n · sustainability) · `[^`]*`$/m, tallies[4]!], + [/^(### 11\.8 Wave 13 — Futurism layer) · `[^`]*`$/m, tallies[5]!], + [/^(### 11\.9 Cross-cutting) · `[^`]*`$/m, tallies[6]!], +]; +for (const [re, t] of headingSuffixMap) { + withSuffixes = withSuffixes.replace(re, (_match, head) => `${head} · \`${t.done} / ${t.total}\``); +} + +if (withSuffixes === src) { + console.log('[count-roadmap-progress] up to date — no changes'); +} else { + writeFileSync(docPath, withSuffixes, 'utf8'); + console.log( + `[count-roadmap-progress] rewrote §11.2 + per-wave headings (${totalDone} / ${totalAll} done)` + ); +}