# BRIEFING — 2026-10-01T02:20:00Z

## Mission
Investigate player dodge roll (Huyễn Ảnh Bộ) and evasion synchronization with incoming monster attacks for Milestone 4, ensuring 0.25s i-frame window, strict <=500 lines limit for client JS modules, and complete client-server parity.

## 🔒 My Identity
- Archetype: explorer
- Roles: investigation, synthesis, preview
- Working directory: c:\Projects\FreeExile\.agents\teamwork\explorer_m4_2_gen2
- Original parent: af73d9ec-d3ff-4501-b986-47b632c5d073
- Milestone: Milestone 4 (Visceral Telegraphing, Evasion i-Frame & Leashing)

## 🔒 Key Constraints
- Read-only investigation — do NOT implement
- Strict line count hard caps: `combat_skills.js` <= 500 lines, `monster_system.js` <= 500 lines
- Must adhere strictly to PoE2 visceral combat model, 0.25s (250ms) i-frame dodge roll (Huyễn Ảnh Bộ)
- Write output to handoff.md in own working directory

## Current Parent
- Conversation ID: af73d9ec-d3ff-4501-b986-47b632c5d073
- Updated: 2026-10-01T02:15:21Z

## Investigation State
- **Explored paths**:
  - `client/webapp/js/engine/combat_skills.js` (lines 280-360, 480-496: dodge execution, cooldown double-spending risk, window exports)
  - `client/webapp/js/engine/monster_system.js` (lines 230-245, 284-320: attack execution, i-frame check, floating text, telegraph integration)
  - `client/webapp/js/engine/canvas_renderer.js` (lines 110-192: iFrameTimer decrement, 1.75x velocity boost, ghostTrails push)
  - `client/webapp/js/engine/entity_renderer.js` (lines 25-45: ghostTrails isometric drawing and alpha fade)
  - `client/webapp/js/ui/skill_bar_controller.js` (lines 40-70, 150-220: dodge slot config, 3 charges, 3s cooldown sweep, activateSlot semantics)
  - `server/world/combat_engine.py` (lines 20-30, 55-100: 250ms evasion_iframe_duration_ms, calculate_damage boundary checks)
  - `client/src/combat/CombatController.ts` (lines 20-75: iOS Metal 250ms duration alignment)
  - `tests/e2e/test_poe2_zone_and_encounter_e2e.py` (Area 4: Dodge i-frame 250ms boundary tests)
  - `tests/e2e/test_poe2_ui_animation_vfx_e2e.py` (Area 7: Dodge i-frame, Area 8: VFX)
  - `explorer_m4_3/handoff.md` (Poise, stagger, leash return, 40-line trimming plan for monster_system.js)
  - `explorer_m4_1/proposed_telegraph_renderer.js` (telegraph shapes, 0.6s–1.2s windup, cancelTelegraph)
- **Key findings**:
  1. Complete client-server parity at 250ms (0.25s): Python Server (`evasion_iframe_duration_ms = 250`), WebApp (`iFrameTimer = 0.25`), and iOS (`evasionIframeDurationMs = 250`).
  2. Cooldown & Charge Gating Flaw: `doDodge()` lacks `isSlotOnCooldown` and `isIFrame` checks, allowing infinite dodge spamming via Spacebar. Also, if invoked via `activateSlot`, charges could decrement twice if `doDodge` unconditionally calls `triggerCooldown`. Solution: `doDodge(invoker)` with guard `if (player.isIFrame || (window.skillBarController?.isSlotOnCooldown('dodge'))) return;` and conditional `if (!invoker) triggerCooldown(...)`.
  3. Monster Attack Evasion Check: `executeMonsterAttackOnPlayer` should use `if (player.isIFrame === true || (player.iFrameTimer && player.iFrameTimer > 0))` for robustness, negate damage (damage = 0), spawn cyan `'NÉ ĐÒN! (i-frame)'` text (`#38bdf8`), play dodge whoosh SFX, and spawn phantom particles.
  4. Telegraph Integration: Currently monsters strike instantaneously with 0 windup. Integrating `window.TelegraphRenderer.startMonsterAttack` when available provides the vital 0.75s–1.0s windup delay that enables players to time the 0.25s dodge roll.
  5. Strict Line Cap Compliance: `combat_skills.js` is at 495 lines and `monster_system.js` is at 496 lines (Hard Cap 500 lines!). Consolidating the window exports in `combat_skills.js` saves 11 lines (down to 484). Explorer_m4_3's consolidation plan in `monster_system.js` saves ~40 lines (down to ~468).
- **Unexplored areas**: None within M4.2 scope.

## Key Decisions Made
- Authored proposed unit test suite `proposed_test_dodge_and_evasion_iframe.py` (16 tests, 100% PASS in 0.003s).
- Authored `dodge_iframe_changes.patch` specifying exact unified diffs.
- Formulated complete 5-Component handoff report.

## Artifact Index
- DISPATCH.md — Task dispatch specification
- BRIEFING.md — Persistent context & state
- progress.md — Heartbeat and status
- proposed_test_dodge_and_evasion_iframe.py — 16-test suite verifying client & server contracts
- dodge_iframe_changes.patch — Precise git patch for downstream Worker
- handoff.md — Comprehensive 5-Component technical report