manual_slop/conductor/archive/ui_performance_20260223/spec.md

Specification: UI Performance Metrics and AI Diagnostics

Overview

This track aims to resolve subpar UI performance (currently perceived below 60 FPS) by implementing a robust performance monitoring system. This system will collect high-resolution telemetry (Frame Time, Input Lag, Thread Usage) and expose it to both the user (via a Diagnostics Panel) and the AI (via API hooks). This ensures that performance degradation is caught early during development and testing.

Functional Requirements

• Metric Collection Engine:
  • Track Frame Time (ms) for every frame rendered by Dear PyGui.
  • Measure Input Lag (estimated delay between input events and UI state updates).
  • Monitor CPU/Thread Usage, specifically identifying blocks in the main UI thread.
• Diagnostics Panel:
  • A new dedicated panel in the GUI to display real-time performance graphs and stats.
  • Historical trend visualization for frame times to identify spikes.
• AI API Hooks:
  • Polling Tool: A tool (e.g., get_ui_performance) that allows the AI to request a snapshot of current telemetry.
  • Event-Driven Alerts: A mechanism to notify the AI (or append to history) when performance metrics cross a "degradation" threshold (e.g., frame time > 33ms).
• Performance Optimization:
  • Identify the "heavy" process currently running in the main UI thread loop.
  • Refactor identified bottlenecks to utilize background workers or optimized logic.

Non-Functional Requirements

• Low Overhead: The monitoring system itself must not significantly impact UI performance (target <1% CPU overhead).
• Accuracy: Frame timings must be accurate to sub-millisecond resolution.

Acceptance Criteria

• UI consistently maintains "Smooth Frame Timing" (minimized spikes) under normal load.
• Main thread load is reduced, evidenced by metrics showing less than 50% busy time during idle/light use.
• AI can successfully retrieve performance data using the get_ui_performance tool.
• AI is alerted when a simulated performance drop occurs.
• The Diagnostics Panel displays live, accurate data.

Out of Scope

• GPU-specific profiling (e.g., VRAM usage, shader timings).
• Remote telemetry/analytics (data stays local).