manual_slop/conductor/tracks/performance_dashboard_20260306/spec.md

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:

  {
   "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

# 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