ADR-020: V3 Structural Rendering Migration — Tracking #667
Description
Overview
Tracking issue for ADR-020: V3 Structural Rendering Migration.
Replaces V2's track-row / track-rail / track-junction rendering model (built by #583) with V3's device-group / mapping-branch / mb-rail model (specified in Signal Flow V3 mockups, Combined tab).
ADR: docs/adrs/ADR-020-v3-structural-rendering-migration.md
Total estimate: 22–30h across 4 phases
Test baseline: 125 Signal Flow tests + 27 Chat bridge tests = 152 tests (must not regress)
Implementation Order
#583 (Signal Flow V2) ✅ MERGED
#568 (Chat bridge) ✅ MERGED
#569 (Token budget) 🟡 OPEN (independent — can run in parallel)
│
ADR-019 Phase 1 Shared filter stores ← PREREQUISITE
│
├── ADR-020 Phase 1 V3 Component Scaffold (8–10h)
│ ├── 1A: DeviceGroup + DeviceHeader
│ ├── 1B: MappingBranch + InlineBadge
│ ├── 1C: FanOutRow + UnmappedRow
│ └── 1D: Wire SignalFlowView with feature flag
│
├── ADR-020 Phase 2 Interactions & Live Data (6–8h)
│ ├── 2A: Fired state + event dot animation
│ ├── 2B: InlineBadge click handlers (Chat bridge + MappingEditor)
│ └── 2C: DeviceHeader ← signalPulseStore
│ ↕ (parallel with ADR-019 Phases 2–4)
│
ADR-019 Phase 5 signalFlowMetrics.js ← PREREQUISITE for compact
│
├── ADR-020 Phase 3 Compact Mode (4–6h)
│ ├── 3A: DeviceSummary component
│ └── 3B: Density toggle wiring
│
└── ADR-020 Phase 4 V2 Removal & Test Migration (4–6h)
├── 4A: Delete V2 components
└── 4B: Migrate 125 tests → V3 APIs (target: 165+ tests)
Phase Checklist
Phase 1: V3 Component Scaffold (8–10h)
- 1A: DeviceGroup + DeviceHeader
- 1B: MappingBranch + InlineBadge
- 1C: FanOutRow + UnmappedRow
- 1D: Wire SignalFlowView with feature flag
Phase 2: Interactions & Live Data (6–8h)
- 2A: Fired state + event dot animation
- 2B: InlineBadge click handlers (Chat bridge compat)
- 2C: DeviceHeader ← signalPulseStore
Phase 3: Compact Mode (4–6h)
- 3A: DeviceSummary component
- 3B: Density toggle wiring
Phase 4: V2 Removal & Test Migration (4–6h)
- 4A: Delete V2 components
- 4B: Migrate 125 tests → V3 APIs
Key V2 → V3 Component Mapping
| V2 Component | V3 Replacement | Decision |
|---|---|---|
TrackRow.svelte |
DeviceGroup.svelte |
D1 |
TrackRail.svelte |
MappingBranch.svelte × N |
D1 |
TrackJunction.svelte |
InlineBadge.svelte |
D2 |
CrossTrackConnector.svelte |
Inline ↗ cross-track badge |
D2 |
LoopDetector.svelte |
Inline ⚠ loop badge |
D2 |
| — (new) | FanOutRow.svelte |
D3 |
| — (single terminus dot) | UnmappedRow.svelte × N |
D4 |
| — (new) | DeviceSummary.svelte |
D7 |
| — (new) | EventDot.svelte |
D8 |
Dependencies
| Dependency | Status | Impact |
|---|---|---|
| #583 (Signal Flow V2) | ✅ MERGED | V2 components to be replaced |
| #568 (Chat bridge) | ✅ MERGED | Click dispatch must be preserved |
| ADR-019 Phase 1 (shared filters) | ⬜ Not started | Blocks Phase 1 — V3 consumes shared filters |
| ADR-019 Phase 5 (metrics store) | ⬜ Not started | Blocks Phase 3 — compact mode needs deviceMetrics |
| ADR-015 (signalPulseStore) | ⬜ Not started | Graceful degradation — channel bars + unmapped counts show "—" |
| ADR-017 (MappingEditor) | ⬜ Not started | Graceful degradation — + Map CTA disabled if absent |
References
- ADR-020:
docs/adrs/ADR-020-v3-structural-rendering-migration.md - Mockups:
signal-flow-v3-mockups.html— Combined tab (RECOMMENDED), S1 Branched Layout, S3 Compact Mode - ADR-019: Unified Workspace Filtering & Aggregate Metrics
- ADR-015: LLM Signal Awareness (signalPulseStore)
- ADR-017: Unified Mapping Experience (MappingEditor)
- ADR-014: Mapping Feedback & Simulate (mappingFireState)