# Project: Dedicated PC Desktop Full-Screen Web Client (`client/web_pc/`)

## Architecture
The PC Desktop Web Client provides a dedicated, hardware-accelerated 100vw × 100vh full-screen ARPG experience modeled after Path of Exile / Diablo.
- **Layout & Viewport**: Eliminates `.iphone-frame`, `#simulator-bar`, and touch joystick. Runs directly in `#app-viewport` configured at `position: fixed; inset: 0; width: 100vw; height: 100vh; overflow: hidden;`. Naturally drives `iso_math.js` viewport-based coordinate transforms across 16:9, 16:10, and 21:9 Ultrawide monitors.
- **Asset & Module Reuse**: Employs `<base href="../webapp/">` inside `<head>` of `client/web_pc/index.html` to map all relative asset paths (`./assets/...`) directly to `client/webapp/assets/` without file duplication or changes to `client/webapp/`.
- **Audio Architecture**: Leverages pure Web Audio API procedural synthesis via `js/audio/sfx_engine.js` with zero network audio asset dependencies.
- **Input & Controls**: Dedicated `pc_input_controller.js` managing Click-to-Move / Hold-to-Move, RMB primary skill, QWER martial skills (decoupling key `W` from movement), 1-5 survival flasks, Spacebar Huyễn Ảnh Bộ (0.25s i-frame), and UI modal shortcuts (`I`, `C`, `Esc`, `Tab`/`M`).
- **Grimdark Action HUD**: Symmetrical Health & Mana fluid globes flanking a centered PoE2-style Action Bar, top-right telemetry Minimap, bottom-left collapsible Chat Dock, hover tooltips, and side-by-side dual-docking modals.
- **Reactive Localization**: 100% data-attribute compliance with `FreeExileI18n` for in-place 9-language updates on `freeexile:localeChanged` without page reload.
- **Zero Mobile Regression**: Zero file modifications inside `client/webapp/`. All mobile unit tests and simulator behavior remain pristine.

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | Fullscreen 100vw/100vh Canvas | Occupies 100% of viewport with zero scrollbars/overflow on 16:9, 16:10, 21:9 | M1 | R1 |
| 2 | Mobile Artifact Elimination | Completely removes `.iphone-frame`, `#simulator-bar`, and visible touch joystick | M1 | R1 |
| 3 | Shared Engine & Asset Linking | `<base href="../webapp/">` linking all 105+ assets, monsters, and biome textures | M1 | R1, R4 |
| 4 | Dummy Joystick DOM Guard | Hidden dummy `#joystick-stick` elements to prevent `canvas_renderer.js` null dereference | M1 | R1, R4 |
| 5 | Dedicated PC Dev Server | `tools/serve_web_pc.py` running on port 8089 without touching `tools/serve_webapp.py` | M1 | R4 |
| 6 | Click-to-Move Kinematics | Left-click moves character accurately to world coordinates with click ripple | M1 | R2 |
| 7 | Continuous Hold-to-Move | Holding LMB continuously updates target destination on pointermove | M1 | R2 |
| 8 | RMB Primary Martial Skill | Right-click suppresses context menu, faces cursor, and casts primary martial skill | M1 | R2 |
| 9 | QWER Martial Skills | Keys Q, W, E, R trigger martial skills towards cursor; W decoupled from movement | M1 | R2 |
| 10 | 1-5 Survival Flasks | Keys 1-5 activate Health, Mana, Quicksilver, Granite, and Diamond flasks with cd | M1 | R2 |
| 11 | Spacebar Huyễn Ảnh Bộ | Spacebar activates dodge roll with 0.25s i-frame, cancel attack, 3 charges | M1 | R2 |
| 12 | Keyboard UI Shortcuts | Keys I/B (Inventory), C (Character sheet), Tab/M (Map), Esc (Pause/Settings) | M1 | R2 |
| 13 | Input Typing Focus Guard | Ignores gameplay hotkeys when user is typing in chat or modal input fields | M1 | R2 |
| 14 | Symmetrical Vitality & Qi Globes | Health Globe (bottom-left) and Mana Globe (bottom-right) with fluid and text | M1 | R3 |
| 15 | Central PoE2 Action Bar | Centered bar with flask slots (1-5), skill slots (QWER), mouse slots (LMB/RMB), Space | M1 | R3 |
| 16 | Action Bar Cooldown Sweeps | 360° radial cooldown sweeps, countdown numbers, and ready flash pulses | M1 | R3 |
| 17 | Segmented Experience Bar | Segmented EXP bar spanning underneath the central action bar | M1 | R3 |
| 18 | Top-Right Minimap & Telemetry | 180×130 minimap with zone label, coordinates, cardinal compass, and FPS/Ping | M1 | R3 |
| 19 | Bottom-Left Collapsible Chat Dock | 8 channel tabs, input, expand/collapse toggle, and rich item link inspection | M1 | R3 |
| 20 | Dynamic Hover Tooltips | Tooltip with hotkey badges, title, description, and viewport clamping | M1 | R3 |
| 21 | Side-by-Side Dual-Docking Modals | Left-docked Character Sheet and right-docked Inventory allowing concurrent access | M1 | R3 |
| 22 | Reactive 9-Language i18n | Real-time in-place language translation without page reload across all HUD elements | M1 | R3, R4 |
| 23 | Procedural Audio Integration | Full visceral martial sound synthesis via Web Audio API without audio asset files | M1 | R4 |
| 24 | Zero Console Errors | Clean browser runtime without JavaScript uncaught exceptions or resource 404s | M1 | Acceptance Criteria |
| 25 | Zero Mobile WebApp Regression | `client/webapp/` remains 100% untouched; `serve_webapp.py` tests pass 100% | M1 | R4, Acceptance Criteria |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| 1 | M1: PC Desktop Web Client (`client/web_pc/`) | Full module: Features 1-25 (`index.html`, `css/`, `js/`, `tools/serve_web_pc.py`) | none | IN_PROGRESS |
| 2 | E2E Testing Track | Design and publish E2E test suite (Tiers 1-4) & `TEST_READY.md` | none | IN_PROGRESS |
| 3 | Final Milestone: 100% E2E Pass & Coverage Hardening | Phase 1: 100% E2E test pass + Phase 2: Tier 5 Adversarial Coverage Hardening | M1, E2E | PLANNED |

## Interface Contracts
### `pc_input_controller.js` ↔ `canvas_renderer.js` / `player`
- `pc_input_controller` hooks into canvas pointer events (`pointerdown`, `pointermove`, `pointerup`).
- Transforms screen cursor position to world coordinates via `isoToWorld(sx, sy)`.
- Updates `player.destination = { wx, wy, active: true }` on LMB click or continuous drag.
- Sets `window.enableWasdMovement = false` and `window.keys = {}` so that `canvas_renderer.js` receives `keyX = 0, keyY = 0`, freeing key `W` for martial skills.
- Listens to keys `Q`, `W`, `E`, `R`: rotates `player.facingAngle = Math.atan2(targetWy - player.wy, targetWx - player.wx)` and triggers corresponding combat skills (`doFire()`, `doThunder()`, `doFrost()`, `doPrimaryAttack()`).
- Listens to keys `1`-`5`: triggers survival flasks (health, mana, quicksilver, granite, diamond) with cooldown sweeps via `window.skillBarController`.
- Listens to `Space`: triggers `window.doDodge()` for 0.25s i-frame and ghost trails.
- Suppresses native browser context menu via `contextmenu` event prevention.

### `pc_hud_controller.js` ↔ `hud_orbs.js` / `skill_bar_controller.js` / `FreeExileI18n`
- Binds Health & Mana globes to `#life-orb-canvas` and `#mana-orb-canvas` via existing `HudOrbs` sinusoidal wave renderer.
- Binds central Action Bar slots (`#skill-flask-1..5`, `#skill-q`, `#skill-w`, `#skill-e`, `#skill-r`, `#skill-lmb`, `#skill-rmb`, `#skill-dodge`) to `SkillBarController`.
- Subscribes to `freeexile:localeChanged` event: invokes `FreeExileI18n.updateDOM(document.body)` for instant in-place translation across 9 languages.

## Code Layout
```
client/web_pc/
├── index.html                 # Dedicated PC Desktop Full-Screen Entry Point
├── css/
│   ├── pc_main.css            # 100vw/100vh Layout, Typography, Reset & Zero-Chassis Rules
│   ├── pc_hud.css             # Grimdark Bottom HUD, Orbs, Action Bar, Minimap & Chat
│   └── pc_modals.css          # Left-Docked Character & Right-Docked Bag Modals
└── js/
    ├── pc_input_controller.js # Mouse Click-to-Move, Hold-to-Move, Keybindings, Skills, Flasks
    ├── pc_hud_controller.js   # PC HUD Action Bar & Flask State Controller
    └── pc_main.js             # PC Application Orchestration, Hotkeys, Tooltips, i18n
tools/
└── serve_web_pc.py            # Dedicated PC Web Server (port 8089)
tests/
├── unit/
│   ├── test_pc_input_controller.py
│   └── test_pc_web_client_layout.py
└── e2e/
    └── test_pc_desktop_client_e2e.py
```