DatasunriseOU
diff --git a/‎VisualBuilderPlan-v9.md‎
Lines changed: 268 additions & 0 deletions b/‎VisualBuilderPlan-v9.md‎
Lines changed: 268 additions & 0 deletions
@@ -0,0 +1,268 @@
+# VisualBuilderPlan-v9 — UX Polish & Visual System Closure
+
+**Status**: planned 2026-05-24 (epic `cppmega-mlx-v9` — to be created)
+
+**Driver**: post-V8 operator-feedback cycle. V8 closed the
+gallery→train round trip (R01-R12). V9 closes the *visual surface*
+the operator interacts with every minute: canvas chrome, sidebar
+ergonomics, theme consistency, and discoverability.
+
+> "Цвета, фонты, ux — куча компонентов и непонятно зачем. mtp это не
+> компонент? зачем оно тут банером? memory bar длиннюща, как ты это
+> покажешь на h100:8? ckpt path виден когда idle. parallel/insert/
+> transplant — ugly full-width strips. draft 1 + new draft — для
+> чего? TopBar 18 элементов, цвета непоследовательны."
+
+## bd ticket ID mapping
+
+| U#   | scope                                                      | priority | depends on |
+|------|------------------------------------------------------------|----------|------------|
+| U01  | Draft tabs strip (browser-tab style) in TopBar left group  | P2       | -          |
+| U02  | Floating canvas toolbar (vertical 32px icon-strip)         | P2       | -          |
+| U03  | Mass hex-literal migration — 592 → ≤ 150 across `vbgui/src/components` | P3 | UX#8 ratchet |
+| U04  | Theme tokens v2 — layered surfaces + elevation scale       | P3       | U03        |
+| U05  | Sidebar tab strip — collapse 10 tabs into grouped accordion | P2      | -          |
+| U06  | Empty-state contracts for Loss/Optim/Memory/Gotchas tabs   | P3       | -          |
+| U07  | BrickNode unified styling — Palette item == canvas chip    | P3       | U04        |
+| U08  | TopBar responsive collapse — groups stack < 1024px         | P3       | UX#7       |
+| U09  | Help icon catalogue audit — every topic has content or 404 | P2       | -          |
+| U10  | Keyboard shortcuts overlay (? key)                         | P3       | -          |
+
+## 1. Already done (do NOT re-open)
+
+The operator-feedback redesign sprint closed these between
+2026-05-23 and 2026-05-24 (commits `23bb694`, `7908932`, `6fe5518`,
+`7bc0b43`, `5a4e314`, `7e1a031`):
+
+| # | Title | Commit |
+|---|---|---|
+| #0 | HelpModal Portal — escape transformed ancestor (`position:fixed` containing-block trap) | `S3615` |
+| #1 | FeatureInjectionBar dedupe → chip with `×N` count + per-chip remove | `6fe5518` |
+| #2 | DimEnvEditor relocated to right Sidebar `Dimensions` tab | `7bc0b43` |
+| #3 | TrainOptionsPanel + RunHistoryPicker → new `TrainOps` Sidebar tab | `7bc0b43` |
+| #4 | TrainLiveControls conditional `{trainInFlight && ...}` | `7bc0b43` |
+| #5 (interim) | Parallel / Insert / Transplant bars removed from canvas, hosted in TrainOps tab | `7bc0b43` |
+| #6 | MemoryBar compact (100×18 pill) + topology-aware N-rank mini-bars | `23bb694` |
+| #7 | TopBar 3 flex groups (left/center/right) + single Precision dropdown | `5a4e314` |
+| #8 (ratchet) | `HexColorRatchet.test.ts` + per-file baseline + DimensionsTab migration | `7e1a031` |
+
+## 2. Why v9 exists
+
+V8 delivered the *journey*. V9 delivers the *finish*:
+- discoverability (Draft tabs, keyboard shortcuts, help catalogue)
+- visual consistency (theme tokens, BrickNode unity, mass hex
+  migration ratcheted down from 592 to ≤ 150)
+- canvas chrome (floating toolbar instead of buried sidebar splicing
+  section; responsive TopBar)
+- empty-state polish (so first-time operators see prompts instead of
+  white space)
+
+## 3. Goal
+
+Operator opens the GUI cold. Without reading docs they can:
+1. Recognise every clickable region from visual weight alone.
+2. Find every action through ≤ 2 clicks (TopBar + Sidebar grouped).
+3. Use `?` overlay to discover all keyboard shortcuts.
+4. Switch between concurrent specs via Draft tabs.
+5. Splice graphs (parallel/insert/transplant) from a fixed-position
+   floating toolbar instead of scrolling a tab.
+
+## 4. Stages — 10 U-epics × 1-4 sub-tasks ≈ 26 sub-tickets
+
+### U01 — Draft tabs strip in TopBar (P2, 3 subs)
+
+**Why**: operator currently sees `[Draft 1] [+ New Draft]` with no
+visual taxonomy. Should be browser-tab-style strip wedged into
+TopBar left group, right of `project-name`.
+
+**Subs**:
+- U01.1 `vbgui/src/components/DraftTabsStrip.tsx`: render N tabs
+  `[Untitled] [Draft 1] [Draft 2 ×] [+]`. Active tab highlighted.
+  Close button (×) only on inactive tabs.
+- U01.2 `vbgui/src/state/drafts.ts`: `useDrafts()` hook persists
+  drafts to `localStorage` under `vbgui_drafts_v1` (array of full
+  spec snapshots + name + timestamp).
+- U01.3 Vitest: switching draft swaps `nodes` + `edges` + `spec`
+  on canvas; closing draft does NOT lose data of OTHER drafts.
+
+### U02 — Floating canvas toolbar (P2, 4 subs)
+
+**Why**: Parallel / Insert / Transplant currently live in
+`TrainOpsTab` (a hidden tab). They should be a fixed-position
+vertical strip 32px wide, left edge of canvas, between Palette
+and FlowCanvas.
+
+**Subs**:
+- U02.1 `vbgui/src/components/CanvasToolbar.tsx`: vertical icon
+  strip with three icons. Each icon opens a popover (positioned to
+  the right of the icon) that contains the existing
+  `ParallelComposeBar` / `InsertIntoEdgeBar` / `TransplantBar`.
+- U02.2 Remove the splicing section from `TrainOpsTab` (revert
+  linter's interim placement). Update test
+  `tests/TrainOpsTab.test.tsx` to drop the splicing assertions.
+- U02.3 Popovers close on click-outside and on Esc; icons show
+  active-state ring while popover is open.
+- U02.4 Vitest: 3 icons render; opening one closes any other
+  already-open popover; ParallelComposeBar still fires `onCompose`.
+
+### U03 — Mass hex-literal migration (P3, 4 subs)
+
+**Why**: `tests/HexColorRatchet.test.ts` locks in baseline 592. The
+target is ≤ 150 by end of V9 (75% reduction). High-frequency
+literals: `#6b7280` (55), `#374151` (36), `#94a3b8` (30),
+`#e5e7eb` (29).
+
+**Subs**:
+- U03.1 Map every hex literal to the closest semantic token in
+  `src/theme.ts` — produce `vbgui/MIGRATION_TABLE.md` with rows
+  `hex → T.token  category  notes`.
+- U03.2 Migrate `Sidebar.tsx` + every file under `src/components/sidebar/`
+  (target: sidebar drops to ≤ 10 hex total).
+- U03.3 Migrate `BrickContextPanel.tsx` (currently 32 hex —
+  highest single offender after TrainLiveControls).
+- U03.4 Migrate `TrainLiveControls.tsx` (46 hex — relocate its
+  ad-hoc colour table into `T.live*` extension if any unique values
+  remain after migration).
+
+### U04 — Theme tokens v2 — layered surfaces + elevation (P3, 2 subs)
+
+**Why**: existing tokens (`T.surface`, `T.surface2`, `T.surface3`)
+are flat — there's no notion of "card on card" or "modal vs
+popover" depth. Adding `T.surfaceLayered{1,2,3}` and `T.elevation*`
+gives the migration target enough semantic vocabulary.
+
+**Subs**:
+- U04.1 Extend `vbgui/src/theme.css` + `theme.ts` with:
+  `surfaceLayered1/2/3` (each a darker variant of `surface` with a
+  hairline border); `elevationLow/Mid/High` (box-shadow tokens);
+  `liveAccent`, `liveAccentSoft` (semantic for live-train UI).
+- U04.2 Pin the additions in `vbgui/STYLE.md` (see Spec §2).
+
+### U05 — Sidebar tab strip overflow (P2, 3 subs)
+
+**Why**: Sidebar now has 10 tabs (Loss, Optim, Rewriters, Side
+Ch., Sharding, Gotchas, Dimensions, Train Ops, Ablations, Memory).
+At width 320px with `flex: 1 0 33%` they wrap to 4 rows of 3 — eats
+sidebar headroom.
+
+**Subs**:
+- U05.1 Group tabs into 3 sections (Spec / Diagnostics / Train) —
+  visible header per section, tabs underneath as smaller chips.
+- U05.2 OR: dropdown picker for less-used tabs (Ablations,
+  Memory). A/B both, pick one with screenshots.
+- U05.3 Vitest: every existing `sidebar-tab-{name}` testid still
+  resolves (back-compat).
+
+### U06 — Empty-state contracts (P3, 2 subs)
+
+**Why**: opening LossTab / MemoryMatrixTab / GotchasTab cold gives
+blank panels. Operator can't tell whether the tab is broken or
+empty.
+
+**Subs**:
+- U06.1 Each of {LossTab, MemoryMatrixTab, GotchasTab,
+  AblationsTab} renders an empty-state block when its data array
+  is `[]`. Block = icon + headline + 1-sentence prompt + CTA.
+  Example for GotchasTab: "✓ No issues yet — run Smoke to populate".
+- U06.2 Vitest: each tab in empty state has
+  `data-testid="<tab>-empty-state"` and renders the CTA text.
+
+### U07 — BrickNode unified styling (P3, 2 subs)
+
+**Why**: Palette items (left dock) and canvas nodes use different
+chrome — Palette is white-bg + grey border, canvas is dark + accent
+glow. Single brick should *look the same* in both places (different
+backgrounds, identical typography + accent treatment).
+
+**Subs**:
+- U07.1 Extract shared `BrickChip` primitive used by both
+  `Palette` items and `BrickNode` canvas nodes.
+- U07.2 Vitest: Palette item and BrickNode for the same kind have
+  same `data-brick-kind` + same `--vb-node-accent` CSS variable.
+
+### U08 — TopBar responsive collapse (P3, 2 subs)
+
+**Why**: UX#7 split into 3 flex groups. Below 1024px width they
+overflow horizontally — need to stack groups onto 2 rows when
+viewport is narrow.
+
+**Subs**:
+- U08.1 `@container` or `min-width` media query — when
+  `< 1024px` stack the center group below left+right.
+- U08.2 Vitest with jsdom-resize: at 800px width
+  `top-bar-group-center.style.flexDirection === "column"` OR a
+  wrap container.
+
+### U09 — Help icon catalogue audit (P2, 3 subs)
+
+**Why**: `HelpIcon topic="..."` references ~80 topics. Many may
+have drifted (renames, broken slugs) — operator clicks `?` and
+sees "missing" modal. Need a programmatic audit + autofix path.
+
+**Subs**:
+- U09.1 vitest scans every `<HelpIcon topic="X">` use, every
+  `Tooltip name="X">`, and every `ExplainModal name="X">` in
+  `vbgui/src/components/**/*.tsx`. For each, asserts the topic
+  exists in `HELP_TOPICS` map OR a `catalog.explain` RPC response.
+  Failing topics listed.
+- U09.2 Add missing topics to `HelpIcon.tsx` HELP_TOPICS map (one
+  paragraph each) OR remove the reference if the surface is dead.
+- U09.3 Add `topic` autocomplete TS type so future references type-check.
+
+### U10 — Keyboard shortcuts overlay (P3, 3 subs)
+
+**Why**: power users want `?` to bring up a list of all shortcuts.
+Currently only Cmd/Ctrl+Z (undo) + Shift+Cmd/Ctrl+Z (redo) are
+hinted in button titles.
+
+**Subs**:
+- U10.1 `vbgui/src/components/KeyboardShortcutsOverlay.tsx`:
+  modal triggered by `?` (and dismissed by `?` or Esc) listing
+  every registered shortcut grouped by section (Canvas / Sidebar
+  / Train / Help).
+- U10.2 `vbgui/src/state/shortcuts.ts`: central registry — every
+  bound shortcut registers `{key, label, section, handler}` so the
+  overlay is generated, not hand-edited.
+- U10.3 Vitest: pressing `?` opens overlay; overlay lists ≥ 1
+  shortcut per section.
+
+## 5. Workflow per epic (same as v5/v6/v7/v8)
+
+1. Read `VisualBuilderSpec-v9.md` for the relevant U-section.
+2. Create files per spec, with the listed data-testids.
+3. Write vitest tests first (TDD); they should fail.
+4. Wire the component; tests pass.
+5. Run full `npx vitest run` from `vbgui/` to confirm zero regression.
+6. Commit with `UX-U0#: <title>` message; close the bd ticket.
+7. Push to main.
+
+## 6. Acceptance counters (mirrors §4)
+
+- 10 U-epics → 26 sub-tickets created in bd as
+  `cppmega-mlx-v9/U01..U10` (one parent + 10 child epics).
+- Each sub-ticket has acceptance criteria copied from §4.
+- New vitest count: ≥ 25 (across all U-stages).
+- `HexColorRatchet.test.ts` baseline drops from 592 to ≤ 150 by end
+  of U03 (≥ 75% reduction).
+
+## 7. Out of scope (V10+)
+
+- True theming (user-switchable light/dark/contrast).
+- Drag-to-reorder canvas nodes (current ELK auto-align only).
+- Multi-user collaboration (CRDT spec sync).
+- Mobile/tablet viewports (focused on ≥ 1024px desktop).
+- Internationalisation (English-only UI text).
+
+## 8. Done definition
+
+V9 is done when:
+- All 10 U-epics closed in bd (sub-tickets either closed or
+  deferred to V10 with explicit reason).
+- `npx vitest run` from `vbgui/`: 0 failures (counting only
+  V9-relevant test files; pre-existing HelpModal/Palette/Backward
+  failures are tracked separately).
+- `HexColorRatchet` baseline ≤ 150.
+- `VisualBuilderPlan-v9.md` + `VisualBuilderSpec-v9.md` + `vbgui/STYLE.md`
+  shipped on `main`.
+- A 5-min screen-recording captures Draft tabs + Canvas toolbar +
+  empty states + `?` overlay (UAT footage).