spike: Evaluate Svelvet for connection/cable rendering #426
Description
Parent
Part of #362 (Connection Graph Model)
Summary
Evaluate whether Svelvet (or its patterns) can accelerate implementation of cable/connection rendering for Rackula's network connectivity visualization.
Hypothesis: Svelvet's anchor/edge system could provide a battle-tested foundation for port-to-port connections, reducing implementation time for #262 (cable path rendering).
Context
What We Have
PlacedPortschema with stable UUIDs (feat: PlacedPort schema and port instantiation #363 ✅)Connectionmodel with a_port_id/b_port_id (feat: MVP Connection model #365 ✅)- Port indicators rendered on devices (feat: PortIndicators SVG component #249 ✅)
- Cable path rendering algorithm research (spike: cable path rendering algorithm #262 ✅)
- Reference implementation in
docs/research/connection-routing.ts
What We Need
- Visual edge/cable rendering between ports
- Interactive connection creation (drag port → port)
- Connection editing and deletion
- Cross-face routing (front → rear)
- Multi-rack connections (future)
Why Svelvet?
| Svelvet Feature | Rackula Need |
|---|---|
| Anchor components | Port connection points |
| Edge rendering | Cable visualization |
| Direction prop (N/S/E/W) | Front/rear face routing |
| `connecting` state | Cable preview during drag |
| `linked` state | Connected port highlighting |
| Multiple edge types | Different cable styles |
Technical Risks & Edge Cases
1. Coordinate System Mismatch
Risk: HIGH
- Rackula: SVG with viewBox, U-position grid, CSS zoom (panzoom)
- Svelvet: DOM-based with its own coordinate system
Questions to answer:
- Can Svelvet edges render correctly when target positions are in SVG coordinates?
- How do we sync panzoom transforms with Svelvet's internal state?
- Does Svelvet support externally-driven pan/zoom?
2. Cross-Face Routing
Risk: HIGH
- Cables connecting front port → rear port need special visualization
- Single-view mode: "tunnel" indicator (cable goes to other side)
- Dual-view mode: "bridge" curve connecting two separate SVG elements
Questions to answer:
- Can Svelvet edges span multiple containers?
- Do we need custom edge components for cross-face?
3. SVG vs DOM Rendering
Risk: MEDIUM
- Rackula devices are SVG elements
- Svelvet renders edges as DOM/SVG in its own coordinate space
Options:
a) Overlay Svelvet canvas on rack SVG (z-index layering)
b) Port Svelvet patterns to Rackula's SVG rendering
c) Move Rackula rendering to Svelvet entirely
4. Port Position Calculation
Risk: MEDIUM
- Ports are positioned relative to device in SVG user space
- Device position depends on U-position
- Panzoom applies CSS transform to rack container
5. Port Type Constraints
Risk: LOW
- Svelvet: boolean input/output
- Rackula: typed ports (InterfaceType enum)
Solution: Custom validation layer on top of Svelvet
6. State Management
Risk: LOW
- Rackula: Svelte 5 runes ($state, $derived)
- Svelvet: Svelte stores
7. Bundle Size
Risk: LOW
- Need to measure Svelvet's impact on bundle
8. Multi-Rack Connections
Risk: MEDIUM (future)
- Multiple racks = multiple SVG elements
- Edges need to span between racks
Spike Deliverables
Required Outputs
-
Minimal Prototype (`docs/research/svelvet-prototype/`)
- Svelvet canvas overlaid on simplified Rackula rack
- 2-3 devices with ports as Svelvet anchors
- Basic edge connections between ports
-
Coordinate Sync Test
- Test with panzoom zoom/pan
- Verify edge positions update correctly
- Measure any lag or jitter
-
Cross-Face Proof of Concept
- Attempt front→rear connection in single-view mode
- Document what works and what doesn't
-
Performance Benchmark
- Test with 10, 50, 100 connections
- Compare to pure SVG path approach from spike: cable path rendering algorithm #262
-
Findings Document (`docs/research/svelvet-evaluation.md`)
- Go/No-Go recommendation
- If Go: integration architecture proposal
- If No-Go: specific patterns to port manually
NOT in Scope
- Full production implementation
- Mobile optimization
- Accessibility
- Serialization to Connection schema
- Multi-rack support
Evaluation Criteria
Go Criteria (adopt Svelvet)
- Coordinate sync works without visible jitter
- Cross-face connections achievable (even if custom)
- Performance acceptable (60fps with 50+ connections)
- Bundle size increase < 20KB gzipped
- Integration complexity < 2 sprints estimated
No-Go Indicators
- Fundamental coordinate system incompatibility
- Cross-face connections impossible without major fork
- Performance significantly worse than pure SVG
- Would require forking Svelvet to make work
Alternative: Port Patterns Only
If Svelvet integration proves too complex, document which patterns to port:
- Anchor state machine (`linked`, `connecting`, `hovering`)
- Edge path calculation algorithms
- Direction-based curvature
- Connection validation architecture
Acceptance Criteria
- Prototype demonstrates basic port→port edge rendering
- Coordinate synchronization tested with zoom/pan
- Cross-face routing feasibility documented
- Performance benchmarked and compared to pure SVG
- Go/No-Go recommendation with clear rationale
- If Go: proposed integration architecture
- If No-Go: list of patterns worth porting manually
Time Estimate
2-3 days for thorough evaluation
References
- feat: Connection Graph Model - Phase 1: Port-Based Architecture #362 - Connection Graph Model epic
- spike: cable path rendering algorithm #262 - Cable path rendering algorithm spike (completed)
- `docs/research/connection-routing.ts` - Reference implementation
- `docs/research/prototype-connection-paths.html` - Visual prototype
- https://github.com/open-source-labs/Svelvet - Svelvet repo
- https://svelvet.mintlify.app/ - Svelvet docs