# SWE Light Adversarial Review Round 3: FreeExile Animation Engine

> [!WARNING] **Skepticism Disclaimer**
> High confidence in deterministic atlas grid math, cycle-safe alias graph resolution, and non-finite NaN/Infinity containment across Node.js and headless browser test runners; moderate confidence in multi-DPI subpixel texture rasterization across low-end mobile WebGL drivers.

## 1. What the prior attempt got wrong

1. **Unrecoverable `NaN` State & Canvas Crash on `Infinity` Velocity or `dt`**
   - **Input:** `updateAnimation(animState, Infinity, 0.016)` or `updateAnimation(animState, 4.2, Infinity)`.
   - **Expected:** Safe finite velocity & dt calculation, preventing `Infinity` from multiplying the frame timer and keeping `frameIndex` a valid finite integer in `[0, frames.length - 1]`.
   - **Actual:** `animState.frameTime` became `Infinity`, causing `animState.frameIndex` to evaluate to `Infinity % 8 = NaN`. On subsequent render calls, `fIdx = NaN`, generating `sx: NaN, sy: NaN`, which causes browser Canvas 2D `ctx.drawImage` to throw an unhandled `TypeError` that halts the entire render loop.
   - **Root cause:** Checking `(typeof dt === 'number' && !isNaN(dt))` which evaluates to `true` for `Infinity` and `-Infinity` (because in JS, `Infinity` is of type number and `isNaN(Infinity)` is false). Must use `Number.isFinite(...)` instead. Additionally, `drawEntityFrame` lacked a finite integer fallback on `animState.frameIndex`.

2. **Circular Atlas Aliases Never Detected Early (Ran to Maximum Depth 10) Due to Inverted Target Comparison**
   - **Input:** Custom manifest with 2-cycle or N-cycle alias: `animations: { loop_a: { atlas_clip: 'loop_b' }, loop_b: { atlas_clip: 'loop_a' } }`.
   - **Expected:** Traversal breaks immediately upon detecting a cycle on the first repeat, without wasting iterations.
   - **Actual:** `if (rawClip.atlas_clip === targetClipName) break;` compared the new alias (`rawClip.atlas_clip`) to the previous clip (`targetClipName`). In alternating cycles, they never matched, so the loop always ran to the maximum `aliasDepth = 10` iterations and resolved to whichever clip was reached on the 9th iteration.
   - **Root cause:** Failure to use a `visited` set for cycle tracking across arbitrary cycle lengths.

3. **`NaN` Coordinates & Division-by-Zero via Malformed Frame Dimensions in Manifest**
   - **Input:** Manifest containing frame with `w: 0` or `{ x: NaN, y: Infinity, w: 0, h: -10 }`.
   - **Expected:** Fallback to valid positive manifest `frame_width` (160), `frame_height` (192), and valid finite `sx`, `sy`.
   - **Actual:** `typeof frameObj.x === 'number'` evaluated to `true` for `NaN`, assigning `sx = NaN, sy = NaN`. Furthermore, `Math.floor(texture_width / 0)` produced `cols = Infinity`, and `globalIndex % Infinity` resulted in `NaN`.
   - **Root cause:** Using `typeof ... === 'number'` instead of `Number.isFinite(frameObj.x)` and `Number.isFinite(frameObj.w) && frameObj.w > 0`.

4. **CTM Matrix NaN-Poisoning on Canvas Translate & Rotation**
   - **Input:** `drawEntityFrame(ctx, animState, NaN, 100, 1, 100, 125)` or `options.rotation = Infinity`.
   - **Expected:** Coordinates sanitized with `Number.isFinite` before translating/rotating canvas.
   - **Actual:** `ctx.translate(NaN, 100)` poisoned the 2D Canvas Current Transformation Matrix (CTM) with `NaN`, permanently corrupting the canvas context until reset.
   - **Root cause:** Unsanitized `screenX`, `screenY`, and `options.rotation`.

5. **Boundary Inconsistency Between Kinematic States at Exactly `actualVel === 0.05`**
   - **Input:** `updateAnimation(animState, 0.05, 0.016)` at the end of an action.
   - **Expected:** Consistent determination of moving vs idle across all transition points.
   - **Actual:** Line 150 treated `>= 0.05` as run, but Line 209 and Line 224 checked `> 0.05`, causing action recovery to set `currentClip = 'idle'` while turn inertia lerped as running.
   - **Root cause:** Inconsistent comparison operator (`>= 0.05` vs `> 0.05`).

6. **Canvas 1px Stroke Antialiasing Blur on High-DPI Displays (Open Ledger Issue #4)**
   - **Input:** Debug overlay rendering with `ctx.strokeRect(dx, dy, dw, dh)`.
   - **Expected:** Crisp 1-pixel border aligned to physical pixel grid.
   - **Actual:** Center-aligned 1px stroke centered on integer/fractional boundaries caused line to span 2 pixels half-alpha on high-DPI viewports.
   - **Root cause:** Lack of half-pixel grid alignment (`Math.round(dx) + 0.5`).

7. **Untested Negative Frame Pivots (Resolved Open Ledger Issue #2)**
   - **Input:** Monster or custom manifest with `pivot: [-0.25, -0.5]`.
   - **Expected:** Offsets correctly calculated (`dx = 25.0`, `dy = 100.0`) without crashing or NaN.
   - **Actual:** Prior attempt left negative pivots as an unverified aspect in the ledger.
   - **Root cause:** Added deterministic test `test_negative_frame_pivot_handling` in test suite.

8. **Degraded Heading on Non-Finite Angles**
   - **Input:** `get8DirectionHeading(NaN)` or `get8DirectionHeading(Infinity)`.
   - **Expected:** Safe fallback to standard `'S'` facing direction.
   - **Actual:** `NaN % 360` yielded `NaN`, falling through all branch checks and returning `'NE'`.
   - **Root cause:** Missing `if (!Number.isFinite(deg)) return 'S';` check.

---

## 2. What I changed

- `client/webapp/js/engine/animation_engine.js`:
  - **Finite Arithmetic Hardening:** Replaced all `typeof ... === 'number'` and `!isNaN(...)` checks with `Number.isFinite(...)` across `actualDt`, `actualVel`, `hitStopTimer`, `actionSpeed`, `frameTime`, `frameIndex`, `screenX`, `screenY`, `rotation`, and `hurtFlash`.
  - **Single-Param dt Fallback Guard:** Restricted velocity-as-dt fallback to `dt === undefined && Number.isFinite(velocity) ? Math.max(0, velocity) : 0.016`, ensuring explicit non-finite dt values fall back cleanly to 0.016 rather than consuming movement speed as frame seconds.
  - **Visited Set Cycle Detection:** Replaced flawed single-step comparison with `const visited = new Set([targetClipName]); while (...) { if (visited.has(rawClip.atlas_clip)) return false; ... }` to guarantee immediate O(1) cycle detection.
  - **Frame Dimension Validation:** Enforced `Number.isFinite(frameObj.w) && frameObj.w > 0` to prevent division by zero in atlas column calculations.
  - **Half-Pixel Subpixel Stroke Alignment:** Aligned debug overlay strokes to pixel centers via `Math.round(dx) + 0.5` to eliminate 2px blur on high-DPI viewports.
  - **Boundary Normalization:** Standardized movement threshold to `>= 0.05` across run transitions, action recovery, and kinetic phase calculations.
  - **Code Compaction:** Maintained total file line count at **348 lines** (strictly `<= 350` lines soft cap per `GEMINI.md`).

- `tests/unit/test_animation_frame_mapping_and_inertia.py`:
  - Added adversarial tests:
    - `test_infinite_velocity_and_dt_finite_safety`: verifies `Infinity` velocity and dt do not corrupt state into `NaN`.
    - `test_negative_frame_pivot_handling`: verifies negative frame pivots (`[-0.25, -0.5]`) calculate proper bounding offsets (`dx: 25.0, dy: 100.0`).
    - `test_malformed_frame_dimensions_fallback`: verifies frames with `w: 0` or `NaN` fall back to manifest defaults without division by zero.
    - `test_non_finite_heading_degree_fallback`: verifies `NaN` degrees safely default to `'S'`.
  - Maintained test suite at **346 lines** (strictly `<= 350` lines soft cap).

---

## 3. Verification Record

- **Deep Verification (ran actual tests):**
  - `pytest tests/unit/test_animation_frame_mapping_and_inertia.py -v`: **46/46 PASSED** (100%).
  - `pytest tests/unit/test_animation_pipeline_and_motion_matching.py tests/unit/test_character_animation_and_skills_vfx.py tests/unit/test_m2_animation_and_combat_feel.py tests/e2e/test_poe2_ui_animation_vfx_e2e.py tests/unit/test_challenger_m2_adversarial.py -v`: **167 PASSED, 9 XPASSED** (0 failures).
  - `node tests/unit/harness_m2_empirical.mjs`: **5/5 PASSED**.
  - `node tests/security_fuzzing/harness_adversarial_m2.mjs`: **4/4 PASSED**.
  - `python tools/lint/check_code_and_doc_hygiene.py --strict`: **PASSED** (0 hard cap violations; both `animation_engine.js` [348 lines] and `test_animation_frame_mapping_and_inertia.py` [346 lines] are `<= 350` lines).
  - Standalone Node script verifying all 198 frames across all 6 classes and all 6 animations against manifest JSON files: **198/198 MATCHED 100%**.
- **Shallow Verification (manual only):**
  - None; all edge cases were verified with deterministic automated test suites.
- **Unverified aspects:**
  - Real human visual perception of sub-pixel sprite bleeding on non-integer device pixel ratios (Retina/HiDPI displays).
  - Hardware accelerated GPU texture filtering on non-integer devicePixelRatio viewports on physical mobile devices.

---

## 4. Known Issues

- `Minor Robustness Risk`: Canvas `imageSmoothingEnabled` default behavior in browser 2D contexts may cause slight texture interpolation blurring if the browser canvas is rendered at fractional CSS pixel scales without `image-rendering: pixelated`.

---

## 5. Remaining risk & next step

- Task is complete. All requirements (R1 Atlas Mapping & Pivot, R2 Turn Inertia Snap Freeze & Auto Run-Idle Transition, R3 Hidden Debug Overlay) are fully satisfied, hardened against non-finite arithmetic, verified across 46 unit tests, and fully compliant with all GEMINI.md line budgets.