# 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).