cleanup stale tests, profiling reports

profiling/reports/README.md

@@ -0,0 +1,69 @@
+# Profiling Reports
+
+This directory contains performance profiling reports generated by the FlexLöve profiling system.
+
+## Directory Structure
+
+Reports are organized by profile name:
+```
+reports/
+├── animation_stress/
+│   ├── latest.md          # Most recent report (Markdown)
+│   ├── latest.json        # Most recent report (JSON)
+│   ├── 2025-11-20_10-30-00.md
+│   └── 2025-11-20_10-30-00.json
+├── event_stress/
+│   ├── latest.md
+│   └── latest.json
+└── ...
+```
+
+## Report Format
+
+Each test run generates two files:
+- `<timestamp>.md` - Human-readable Markdown report with formatted tables
+- `<timestamp>.json` - Machine-readable JSON data for programmatic analysis
+- `latest.md` - Always contains the most recent report for quick access
+- `latest.json` - Most recent JSON data
+
+## Report Contents
+
+### FPS Statistics
+- **Average FPS**: Mean frames per second across the entire test
+- **Median FPS**: Middle value of all FPS measurements
+- **1% Worst FPS**: The FPS at which 1% of frames performed at or below this level (useful for identifying stutters)
+- **0.1% Worst FPS**: The FPS at which 0.1% of frames performed at or below this level (worst case performance)
+
+### Frame Time Statistics
+- **Average**: Mean frame time in milliseconds
+- **Median**: Middle value of all frame time measurements
+- **95th/99th/99.9th Percentile**: Frame times that 95%/99%/99.9% of frames completed under
+
+### Memory Usage
+- **Average**: Mean memory usage across the test
+- **Peak**: Maximum memory used during the test
+- **95th/99th/99.9th Percentile**: Memory usage levels that 95%/99%/99.9% of samples were under
+
+## How to Generate Reports
+
+### Automatic (on exit)
+Reports are automatically saved when you:
+- Press ESC to return to the menu
+- Quit the profiling application
+
+### Manual
+While a profile is running, press **S** to manually save a report without stopping the test.
+
+## Interpreting Results
+
+### Good Performance Indicators
+- Average FPS close to target (60 FPS for most applications)
+- Small difference between average and 1% worst FPS
+- Low 99.9th percentile frame times (< 20ms for 60 FPS)
+- Stable memory usage without continuous growth
+
+### Performance Issues to Watch For
+- Large gap between average and 1%/0.1% worst FPS (indicates frame drops/stutters)
+- High 99.9th percentile frame times (indicates occasional severe lag spikes)
+- Continuously growing memory usage (indicates memory leak)
+- High memory peak compared to average (indicates GC pressure)