# Project: FreeExile Real-Browser QA & Cross-Department Issue Documentation

## Architecture
- **Target Application**: FreeExile MMO ARPG 2.5D Client WebApp (`client/webapp/`) and Web PC (`client/web_pc/`), served via `tools/serve_webapp.py` on port `8088`.
- **Browser Automation & Telemetry Engine**: Headless Chromium via Python Playwright (`playwright.sync_api`) + Chrome DevTools Protocol. In-page telemetry hooks into `requestAnimationFrame`, `console`, `performance.memory`, `performance.now()`, DOM mutations, and WebGL/Canvas state. Implemented in `tools/qa/run_browser_qa_suite.py` and `tools/qa/qa_harness_utils.py`.
- **Reporting & Archival Subsystem**: `docs/qa/reports/` with departmental sub-categorization (`CLI`, `SRV`, `GDS`, `ART`, `SEC`), standardized 9-part issue schemas (`QA-BUG-[DEPT]-[YYYYMMDD]-[INDEX].md`), and master `QA_EXECUTIVE_SUMMARY.md`.

## Feature Inventory
| # | Feature | Description | Milestone | Source | Status |
|---|---------|-------------|-----------|--------|--------|
| F1 | Real Browser MMO ARPG Deep Inspection | Frame rate & drops 60fps/120fps, p95/p99 frame times, combat input buffering gap analysis, 0.25s i-frame dodge evasion latency, state sync, runtime console/network logs | M1 | ORIGINAL_REQUEST R1 | DONE |
| F2 | Responsive UI/UX, Viewport & Cross-Locale Validation | Desktop widescreen, Mobile portrait/landscape orientation, Notch/Dynamic Island Safe Area, 9-language in-place reactive switching without reload, virtual joystick & action bar controls | M2 | ORIGINAL_REQUEST R2 | DONE |
| F3 | Stress, VFX Overload & Endurance Testing | Continuous 30-biome traversal, dense combat particle/VFX load, Target Dummy high-frequency assault, memory footprint tracking (Heap, DOM nodes, Canvas VRAM) | M3 | ORIGINAL_REQUEST R3 | DONE |
| F4 | Actionable Cross-Department Issue Documentation | Standardized bug reports in `docs/qa/reports/` across Client, Server, Game Design, Art/VFX, Security with Bug ID, Severity, Repro Steps, Telemetry Logs, Root Cause, Fix Proposal, plus `QA_EXECUTIVE_SUMMARY.md` | M4 | ORIGINAL_REQUEST R4 | DONE |
| F5 | Independent Verification, Review & Forensic Integrity Audit | Multi-agent review (2 Reviewers), empirical verification (2 Challengers), and Forensic Integrity Audit (2 Auditors) | M5 | Studio Directives | DONE |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| M1 | Deep Browser ARPG Inspection (R1) | Build and execute automated browser test suite for R1: FPS/jank, input buffering, i-frame latency, network state sync | None | DONE |
| M2 | Responsive UI/UX & 9-Locale Validation (R2) | Build and execute automated browser test suite for R2: viewports, mobile orientation, safe area, in-place 9-locale reactive switching | None | DONE |
| M3 | Stress, VFX Overload & Endurance Suite (R3) | Build and execute automated browser test suite for R3: 30-biome traversal, VFX overload, dummy attacks, heap/DOM tracking | M1, M2 | DONE |
| M4 | Actionable Cross-Department Documentation (R4) | Generate all standardized departmental issue reports in `docs/qa/reports/` (CLI, SRV, GDS, ART, SEC) and master `QA_EXECUTIVE_SUMMARY.md` with empirical telemetry | M1, M2, M3 | DONE |
| M5 | Review, Adversarial Challenge & Forensic Audit | Independent review by Reviewers, Challengers, and Forensic Auditors for full acceptance criteria validation | M4 | DONE |

## Interface Contracts
### Browser QA Runner ↔ WebApp Client
- **Port**: `8088` (`http://localhost:8088/index.html`)
- **Telemetry Object**: `window.__FREEEXILE_QA__` evaluated via Playwright to collect:
  - `fps`: current FPS, avg FPS, min FPS, max FPS, frame times array (ms), p95, p99, jank count (frames > 33.3ms)
  - `combat`: dodge roll timestamp, i-frame active duration, input buffer dropped count, combo sequence
  - `movement`: pointer click dispatch, target destination, distance displaced
  - `modal`: modal open event, pause toggle, escape key dismiss, unpause
  - `locale`: current language code, switch timestamp, duration (ms), untranslated key count
  - `memory`: JS Heap used (MB), total (MB), DOM nodes count, canvas count, chunk cache slots (count/MB)
- **Report Format**: Markdown files following `docs/qa/reports/QA-BUG-[DEPT]-[YYYYMMDD]-[INDEX].md` containing 9 standardized sections.

## Code Layout
- Test Execution Scripts: `tools/qa/` (`run_browser_qa_suite.py`, `qa_harness_utils.py`)
- QA Reports Directory: `docs/qa/reports/`
  - `docs/qa/reports/QA-BUG-CLI-20261002-01.md` (Client)
  - `docs/qa/reports/QA-BUG-CLI-20261002-02.md` (Client)
  - `docs/qa/reports/QA-BUG-CLI-20261002-03.md` (Client)
  - `docs/qa/reports/QA-BUG-SRV-20261002-01.md` (Server/Network)
  - `docs/qa/reports/QA-BUG-GDS-20261002-01.md` (Game Design)
  - `docs/qa/reports/QA-BUG-ART-20261002-01.md` (Art/VFX)
  - `docs/qa/reports/QA-BUG-SEC-20261002-01.md` (Security/Integrity)
  - `docs/qa/reports/QA_EXECUTIVE_SUMMARY.md` (Master Executive Summary)
- Test Logs & Raw Telemetry: `docs/qa/reports/telemetry/` (`qa_browser_telemetry.json`, 10 PNG screenshots)