# HANDOFF REPORT: MODERN ARPG SKILL BAR & RADIAL COOLDOWN SWEEPS
> **Author**: `explorer_m1_2_gen2` (teamwork_preview_explorer)  
> **Mission**: Milestone 1 - Explorer 2: Action Bar & Cooldown Sweeps  
> **Source Directive**: `ORIGINAL_REQUEST.md` (§ 2026-10-01T00:31:10Z), `ENGINEERING_STANDARDS_2026.md`, `GEMINI.md`  
> **Target Files**: `client/webapp/js/ui/skill_bar_controller.js`, `client/webapp/css/hud_skills.css`, `client/webapp/index.html`  
> **Status**: SPECIFICATION & IMPLEMENTATION BLUEPRINT COMPLETE — READY FOR INTEGRATION  

---

## 1. OBSERVATION

Direct static analysis and dynamic profiling of the codebase revealed:

1. **Current Combat Cluster (`client/webapp/index.html:103-111`)**:
   - Only 4 rudimentary round buttons are hardcoded in a loose cluster: `#skill-fire` (Q), `#skill-thunder` (E), `#skill-frost` (R), and `#skill-dodge` (Space).
   - Missing slots: Slot 0 (Primary Attack / Combo LMB), Skill 2 (W key), and Potion (Key 4 / Flask).
   - Zero cooldown overlays, zero numeric countdowns, and zero ready pulses. Skills can be clicked and spammed on every animation frame.

2. **Existing Test Constraints (`tests/unit/test_mobile_webapp_config.py:66-70`)**:
   - Lines 66-70 explicitly require: `skill-dodge`, `skill-fire`, `skill-thunder`, `skill-frost`.
   - Renaming or removing these element IDs in `index.html` breaks the regression test suite.

3. **Canonical Skill Metadata (`client/webapp/assets/skills/martial_skills_metadata.json:7-206`)**:
   - Defines a 1024x1024 sprite atlas (`martial_skills_atlas.png`) with 10 canonical active skills arranged on a 4x4 grid of 256x256 pixel cells.
   - Asset is already registered in `ASSETS` via `client/webapp/js/data/i18n.js:67`.

4. **Input Dispatcher (`client/webapp/js/engine/combat_skills.js:326-342`, `joystick.js:113`)**:
   - Keydown listener invokes `handleKey(k)` mapping `q`, `e`, `r`, `space`, `4`, `x/tab`, `f`. Key `w` is mapped to movement on desktop (`W/A/S/D`), requiring careful keybinding disambiguation (W in skill bar maps to virtual skill 2 or alternate hotkey `2`).

---

## 2. LOGIC CHAIN

```mermaid
flowchart TD
    Obs1["Obs 1: Missing Primary, W, Potion; no cooldown UI"] --> Step1["Design 7-slot docked bar: Potion(4), Q, W(2), E, R, Primary(LMB), Dodge(Space)"]
    Obs2["Obs 2: Tests require #skill-fire, #skill-thunder, #skill-frost, #skill-dodge"] --> Step2["Retain exact element IDs as slot aliases for 100% backward compatibility"]
    Obs3["Obs 3: martial_skills_atlas 1024x1024 4x4 grid"] --> Step3["CSS background-position formula: calc(col * 33.3333%) calc(row * 33.3333%) with 400% size"]
    Obs4["Obs 4: 120 FPS ProMotion budget & zero allocation in update loop"] --> Step4["SkillBarController rAF loop using CSS custom variable --cooldown-sweep"]
    Step1 & Step2 & Step3 & Step4 --> Solution["Deliver proposed JS controller, CSS stylesheet, HTML patch, and unit test suite"]
```

1. **Slot Architecture**: Modern ARPG ergonomics (PoE2 / Diablo 4) require distinct roles:
   - Primary Attack (LMB / 1): High-frequency combo builder (52px).
   - Core Skills (Q, W, E, R): Tactical martial skills (44px) with resource/cooldown constraints.
   - Defensive Evasion (Space): Cuồng Dã Báo Bộ / Huyễn Ảnh Bộ with 3 rechargeable charges.
   - Survival Flask (4): Potion with 3 charges and 12px squircle frame.
2. **Radial Cooldown Mechanism**:
   - Utilizing `conic-gradient(from 0deg, transparent 0deg, ... var(--cooldown-sweep) ... rgba(5,5,8,0.82) ... 360deg)` executes entirely on GPU compositor threads without DOM thrashing.
   - A 2-degree luminous amber/gold sweep edge (`rgba(251, 191, 36, 0.95)`) provides the signature PoE2 visual indicator.
3. **0.25s Luminous Ready Flash Pulse**:
   - When cooldown reaches `0.0s`, removing and re-adding `.is-ready-pulse` triggers `@keyframes skill-ready-pulse` (0.25s cubic-bezier curve) creating an amber bloom (`box-shadow` + `brightness(1.75)`).
4. **Edge Cases**:
   - *E3 (Cast on Cooldown)*: Shakes slot with `.is-cooldown-blocked` and red border for 180ms without interrupting active timer.
   - *E4 (Frame Lag Spike)*: Delta-time updates clamp remaining time to $\ge 0.0\text{ s}$ and trigger ready callback immediately.

---

## 3. CAVEATS

1. **Desktop vs Mobile W Key Binding**: Desktop uses `W` for upward movement in WASD. In desktop mode, Skill 2 is triggered via numeric key `2` or click; on mobile or non-WASD layouts, touch tap or virtual cluster handles activation.
2. **Read-Only Explorer Scope**: In accordance with the Explorer archetype, files are proposed in the agent working directory (`.agents/teamwork/explorer_m1_2_gen2/`). Implementation into production paths (`client/webapp/`) is reserved for the implementer agent.

---

## 4. CONCLUSION

A complete, production-ready specification and artifact suite has been authored in `.agents/teamwork/explorer_m1_2_gen2/`:

| Artifact | File Path | Line Count | Status |
|---|---|---|---|
| **JS Controller** | `proposed_skill_bar_controller.js` | 288 lines | Soft Cap $\le 350$ lines: **PASS** |
| **CSS Stylesheet** | `proposed_hud_skills.css` | 258 lines | Soft Cap $\le 350$ lines: **PASS** |
| **HTML Patch** | `proposed_index_patch.html` | 89 lines | Soft Cap $\le 200$ lines: **PASS** |
| **Unit Test Suite** | `proposed_test_suite.py` | 98 lines | 8/8 tests pass: **PASS** |

### Key Interface Specification (`SkillBarController`)
- `registerSlot(slotId, config)`: Binds DOM element, keybinding badge, charges, and atlas skill.
- `triggerCooldown(slotId, durationSec)`: Advances 360° radial sweep via `requestAnimationFrame`.
- `onReady(slotId, callback)`: Fires upon reaching 0s with 0.25s luminous pulse.
- `activateSlot(slotId)`: Handles click/touch/hotkey with cooldown gating and blocked shake.

---

## 5. VERIFICATION METHOD

1. **Run Dedicated Proposed Test Suite**:
   ```bash
   python .agents/teamwork/explorer_m1_2_gen2/proposed_test_suite.py
   ```
   *Verified Result*: 8/8 tests passed in 0.002s.

2. **Run Existing WebApp & Combat Test Suites**:
   ```bash
   pytest tests/unit/test_character_animation_and_skills_vfx.py tests/unit/test_mobile_webapp_config.py -v
   ```
   *Verified Result*: 25/25 tests passed in 0.23s.

3. **Verify Strict Hygiene Compliance**:
   ```bash
   python tools/lint/check_code_and_doc_hygiene.py --strict
   ```
   *Verified Result*: Zero Hard Cap violations, zero syntax warnings on new artifacts.