# Track Specification: Performance Dashboard (performance_dashboard_20260306)

 
## Overview
Expand performance metrics panel with CPU/RAM graphs, frame time histogram. Uses existing `performance_monitor.py`.
 
## Current State Audit
 
### Already Implemented (DO NOT re-implement)
 
#### PerformanceMonitor (src/performance_monitor.py)
- **`PerformanceMonitor` class**: Tracks FPS, frame time, CPU, input lag
- **`start_frame()`**: Called at frame start
- **`end_frame()`**: Called at frame end
- **`record_input_event()`**: Track input latency
- **`get_metrics()`**: Returns dict with:
  ```python
  {
   "fps": float,
   "frame_time_ms": float
   "cpu_percent": float
   "input_lag_ms": float
  }
  ```
- **No historical storage** - metrics are per-frame only
 
### Gaps to Fill (This Track's Scope)
- No historical graphs of CPU/RAM over time
- No rolling window storage
- No frame time histogram
 
## Architectural Constraints
 
### 60fps During Graphs
- Graph rendering MUST NOT impact frame rate
- Use simple line rendering (imgui.plot_lines)
 
### Memory Bounds
- Rolling window: max 100 data points (deque)
- Memory per point: ~16 bytes (4 floats)
 
## Architecture Reference
 
### Key Integration Points
 
| File | Lines | Purpose |
|------|-------|---------|
| `src/performance_monitor.py` | 10-80 | `PerformanceMonitor` class |
| `src/gui_2.py` | ~2800-2900 | Diagnostics panel - add graphs |
 
### Proposed Enhancement
```python
# In PerformanceMonitor:
from collections import deque
 
class PerformanceMonitor:
 def __init__(self):
  self._history: deque = deque(maxlen=100)
  
 def get_history(self) -> list[dict]:
  return list(self._history)
```
 
## Functional Requirements
 
### FR1: Historical Data Storage
- Add `_history: deque` to PerformanceMonitor (maxlen=100)
- Store metrics each frame
- `get_history()` returns historical data
 
### FR2: CPU Graph
- Line graph showing CPU% over last 100 frames
- X-axis: frame index
- Y-axis: CPU %
- Use imgui.plot_lines()
 
### FR3: RAM Graph
- Line graph showing RAM usage
- X-axis: frame index
- Y-axis: MB
- Use imgui.plot_lines()
 
### FR4: Frame Time Histogram
- Bar chart showing frame time distribution
- Buckets: 0-16ms, 16-33ms, 33+ms
- Use imgui.plot_histogram()
 
## Non-Functional Requirements
| Requirement | Constraint |
|-------------|------------|
| Frame Time Impact | <1ms for graph render |
| Memory | 100 data points max |
 
## Testing Requirements
### Unit Tests
- Test history storage limits
- Test graph rendering doesn't crash
### Integration Tests
- Verify graphs display in GUI
- Verify 60fps maintained with graphs
 
## Acceptance Criteria
- [ ] CPU graph shows rolling history
- [ ] RAM graph shows rolling history
- [ ] Frame time histogram displays
- [ ] History limited to 100 points
- [ ] Uses existing `PerformanceMonitor.get_metrics()`
- [ ] 1-space indentation maintained