refactor: Refactor front end in to some type of javascript package

[Rylorx]

Let's work on refactoring our front end to be compatible with the current raw CSS and HTML in some type of package like REACT, VITE, or something else compatible, so that we can work on standardizing components and move forward from here.

[Rylorx]

Issue: Migrate Visualization to Vite + TypeScript

Objective

Modernize the visualization build system by migrating from vanilla JavaScript with no build tooling to Vite + TypeScript, while preserving the existing architecture and D3.js implementation.

Current State

• Location: tempo/visualization/ui/
• Tech Stack: Vanilla JavaScript ES6 modules, D3.js v7, WebSocket communication
• Total Code: ~3,658 lines (JS, CSS, HTML)
• Build System: None - static files served directly by FastAPI
• Key Files:
  • app.js (70 lines) - Entry point
  • state.js (373 lines) - Centralized state management
  • graph.js (729 lines) - D3.js tree visualization
  • panels.js (420 lines) - UI panels
  • events.js (469 lines) - Event handling
  • ws.js (147 lines) - WebSocket management
  • agentTree.js (176 lines) - Agent hierarchy
  • utils.js (141 lines) - Utilities
  • style.css (996 lines) - Custom dark theme
  • index.html (137 lines)

Goals

1. Add modern development tooling (HMR, fast builds, bundling)
2. Introduce TypeScript for type safety without architectural changes
3. Optimize production builds (minification, tree-shaking, code splitting)
4. Improve developer experience while maintaining current performance
5. Keep D3.js implementation as-is (no React wrappers)
6. Maintain compatibility with FastAPI static file serving

Requirements

Must Have

• ✅ Vite as build tool and dev server
• ✅ TypeScript support (gradual migration, start with .ts or JSDoc)
• ✅ Hot Module Replacement (HMR) for development
• ✅ Production build optimization (minification, bundling)
• ✅ Preserve all existing functionality
• ✅ Keep D3.js visualization logic unchanged
• ✅ Maintain WebSocket real-time updates
• ✅ Update FastAPI integration to serve Vite builds

Nice to Have

• 📦 CSS preprocessing (PostCSS or SASS)
• 🔍 Source maps for debugging
• 🌍 Environment-based configuration
• 📊 Bundle size analysis
• 🎨 CSS modules or scoped styles
• ⚡ Lazy loading for non-critical modules

Must NOT Change

• ❌ Do not migrate to React/Vue/other frameworks
• ❌ Do not rewrite D3.js visualization logic
• ❌ Do not change state management architecture
• ❌ Do not break WebSocket event handling
• ❌ Do not alter the visual design or UX

Implementation Plan

Phase 1: Setup Vite Project Structure

1. Initialize Vite with TypeScript template in a new directory (e.g., tempo/visualization/ui-vite/)
2. Configure vite.config.ts with appropriate settings:
   • Base path for FastAPI serving
   • Build output directory
   • Dev server proxy configuration
   • Asset handling
3. Set up tsconfig.json for gradual TypeScript adoption
4. Configure build scripts in package.json

Phase 2: Migrate Source Files

1. Copy existing JS modules to new structure
2. Rename .js → .ts (or start with JSDoc types)
3. Add type definitions for:
   • State object structure
   • WebSocket message types
   • D3.js node/link data types
   • Event payloads
4. Update imports to use TypeScript conventions
5. Move D3.js from CDN to npm dependency
6. Migrate CSS (consider modules or preprocessing)

Phase 3: FastAPI Integration

1. Update server.py to:
   • Serve Vite dev server in development mode (proxy)
   • Serve built assets from dist/ in production
2. Add environment detection (dev vs prod)
3. Update static file mounting logic
4. Test WebSocket connectivity in both modes

Phase 4: Testing & Validation

1. Verify all visualization features work:
   • Agent execution tree rendering
   • Real-time WebSocket updates
   • Cost tracking animations
   • Context window expansion
   • Agent hierarchy display
   • Findings summary
2. Test HMR during development
3. Validate production build performance
4. Check bundle size and optimization

Phase 5: Documentation & Cleanup

1. Update README with new build instructions
2. Document development workflow (npm commands)
3. Add comments explaining Vite configuration
4. Remove old UI directory
5. Update deployment documentation

Technical Specifications

Package Dependencies (minimum):

{
  "devDependencies": {
    "vite": "^5.0.0",
    "typescript": "^5.3.0"
  },
  "dependencies": {
    "d3": "^7.0.0"
  }
}

FastAPI Integration Pattern:

# Development: Proxy to http://localhost:5173
# Production: StaticFiles(directory="tempo/visualization/ui-vite/dist")

Directory Structure:

tempo/visualization/ui-vite/
├── src/
│   ├── main.ts (app.js)
│   ├── state.ts
│   ├── graph.ts
│   ├── panels.ts
│   ├── events.ts
│   ├── ws.ts
│   ├── agentTree.ts
│   ├── utils.ts
│   └── types.ts (new - shared type definitions)
├── public/
│   └── (static assets)
├── index.html
├── style.css
├── vite.config.ts
├── tsconfig.json
└── package.json

Success Criteria

• Development server runs with HMR working
• Production build completes without errors
• All visualization features work identically to current implementation
• WebSocket real-time updates function correctly
• Bundle size is reasonable (<500KB total)
• FastAPI serves UI correctly in both dev and prod modes
• TypeScript provides type checking without breaking existing logic
• Build time is under 5 seconds
• No visual regressions or UX changes

Non-Goals

• This is NOT a React migration
• This is NOT a visual redesign
• This is NOT a state management refactor
• This is NOT a D3.js rewrite

References

• Current UI location: tempo/visualization/ui/
• FastAPI server: tempo/visualization/server.py
• Event collector: tempo/visualization/collector.py
• Vite docs: https://vitejs.dev
• D3.js docs: https://d3js.org

---

Ready to implement? Assign this issue and let's modernize the tooling while keeping what works!