ok

conductor/tracks/performance_dashboard_20260306/spec.md

@@ -1,39 +1,108 @@
 # 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
-- **`src/performance_monitor.py`**: `PerformanceMonitor` class
-- **`get_metrics()`**: Returns FPS, frame time, CPU, input lag
-- **Basic display in GUI diagnostics**
-
-### Gaps to Fill
-- No historical graphs
+ 
+### 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
-
-## Functional Requirements
-- Rolling window of metrics (deque with maxlen)
-- Line graphs for CPU/RAM over time
-- Frame time histogram
-- Uses existing `PerformanceMonitor.get_metrics()`
-
-## Key Integration Points
-| File | Purpose |
-|-----|---------|
-| `src/performance_monitor.py` | Add history storage |
-| `src/gui_2.py` | Graph rendering |
-
+ 
 ## Architectural Constraints
-- 60fps during graph rendering
-- Memory bounded (max 100 data points)
-
+ 
+### 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
-- [ ] Input lag metrics tracked
-- [ ] 1-space indentation
+- [ ] History limited to 100 points
+- [ ] Uses existing `PerformanceMonitor.get_metrics()`
+- [ ] 1-space indentation maintained