Animation System: Integration, Testing & Documentation

# Animation System: Integration, Testing & Documentation

## Labels
`phase-3`, `workstream-b`, `animation`, `integration`, `testing`

## Milestone
Phase 3: Animation System Modernization

## Summary

Wire the new animation engine (from Issue #4) into the existing ACAT application, creating adapter layers so the new engine handles scanning while maintaining 100% backward compatibility. Includes comprehensive testing (unit, integration, performance), BCI extension validation, and developer documentation.

This is the higher-risk part of the animation work — it touches production scanning behavior that users with motor disabilities depend on.

## Context

After Issue #4, the new engine exists as standalone components. This issue connects them to the real application:
- `PanelAnimationManager` delegates internally to `IAnimationService.CreateSession()`
- `UserControlAnimationManager` similarly adapted
- Legacy `AnimationPlayer` remains functional for any callers not yet migrated
- BCI extension (`AnimationSharpManagerV2.cs`, 2,885 lines) must continue to function

### Performance Requirements (from Design Spec §14)
- Scan interval deviation: ≤5% at 200ms minimum
- Actuator-to-highlight latency: ≤50ms
- IEventBus dispatch time: ≤1ms
- Config load time: ≤20ms (BCI worst case with 25 animations)

### XML Configuration Landscape
- 69 panel XML config files with `` elements
- Located in `src/ACATResources/panelconfigs/` (`common/`, `en/`, `es/`)
- Highest complexity: `NumericUserControlBCI.xml` (25 animations), `KeyboardABCUserControlBCI2.xml` (25 animations)

## Implementation Steps

### Part 1: Adapter Layer (~3 days)

1. **Create `AnimationPlayerAdapter`** — bridges `PanelAnimationManager` to new `IAnimationService`:
- `PanelAnimationManager` calls remain unchanged from callers' perspective
- Internally creates `IAnimationSession` via `IAnimationService.CreateSession()`
- Routes actuator switch events to `IAnimationSession.HandleInput()`
- Falls back to legacy `AnimationPlayer` if new engine session fails

2. **Update `PanelAnimationManager.cs`**:
- Inject `IAnimationService` (property injection to avoid constructor breakage)
- Use adapter when `IAnimationService` is available
- Preserve all existing public method signatures

3. **Update `UserControlAnimationManager.cs`**:
- Same adapter pattern as `PanelAnimationManager`
- Ensure UserControl-specific behavior preserved

4. **Update `AnimationManager.cs`**:
- Route actuator events to new sessions when active
- Maintain existing event routing for legacy sessions

### Part 2: XML-to-JSON Configuration Bridge (~2 days)

5. **Implement `XmlAnimationConfigAdapter`** (started in Issue #4, complete here):
- Parse all 69 XML panel configs' `` elements
- Convert to `AnimationConfig` JSON model at runtime
- Handle the 5 schema migration constraints:
- C1: `Iterations` as `@VarName` runtime reference
- C2: `ScanTime`/`FirstPauseTime` as variable names
- C3: Wildcard widget names (`Box1/*`, `@SelectedWidget`)
- C4: Per-widget `OnSelected` PCode
- C5: Per-animation `OnEnter`/`OnEnd` PCode
- Cache converted configs (parse once per panel load)

6. **Validate against high-complexity configs**:
- `NumericUserControlBCI.xml` (25 animations)
- `KeyboardABCUserControlBCI2.xml` (25 animations)
- `KeyboardEditUserControlBCI.xml` (17 animations)
- Verify all animations load and scan correctly

### Part 3: BCI Extension Validation (~2 days)

7. **Validate BCI extension compatibility**:
- `src/Extensions/BCI/AnimationSharpManagerV2.cs` (2,885 lines) has its own animation loop and SharpDX overlay rendering
- Verify it continues to function unchanged (BCI extension does NOT use the new engine yet — that's a future phase)
- Ensure no interface changes break BCI compilation
- Test BCI-specific scan modes (eye-gaze, neural signal actuator)

8. **Document BCI migration path** for future work:
- Identify which parts of `AnimationSharpManagerV2.cs` could be replaced by the new engine
- Note ~1,400 lines of duplicated core logic that the new engine could eliminate
- Create brief migration roadmap (not implementing now)

### Part 4: Testing (~3 days)

9. **Integration tests** — test real panel lifecycle with new engine:
- Panel creation → animation session start → widget scanning → user selection → panel close
- Multi-panel scenarios (main panel + dialog overlay)
- Actuator pause/resume during scanning
- Panel transition (close one, open another)

10. **Performance benchmarks**:
- Scan interval accuracy at 200ms, 500ms, 1000ms intervals
- Actuator-to-highlight latency measurement
- Config load time for standard (5 animations) and complex (25 animations) panels
- Memory usage comparison: new engine vs. legacy
- CPU usage during active scanning

11. **Regression tests**:
- All existing scan modes still work (auto, manual, step)
- All existing panel configs load without error
- Keyboard scanning behavior unchanged
- Dialog scanning behavior unchanged

### Part 5: Documentation (~1 day)

12. **Developer guide** — `docs/ANIMATION_ENGINE_GUIDE.md`:
- Architecture overview with component diagram
- How to create a new scan mode strategy
- How to create a custom highlight renderer
- How to add JSON animation configuration for a new panel
- Migration guide for extension authors

13. **Update existing docs**:
- Update `ACAT_MODERNIZATION_PLAN.md` Phase 3 section with completion status
- Update `INDEX.md` with new animation documentation

## Acceptance Criteria

- [ ] Adapter layer bridges `PanelAnimationManager` and `UserControlAnimationManager` to new engine
- [ ] All 69 XML animation configs load correctly through `XmlAnimationConfigAdapter`
- [ ] 5 schema migration constraints (C1–C5) handled correctly
- [ ] BCI extension compiles and functions unchanged
- [ ] Integration tests cover panel lifecycle with new engine
- [ ] Performance benchmarks meet targets:
- [ ] Scan interval deviation ≤5% at 200ms
- [ ] Actuator-to-highlight latency ≤50ms
- [ ] Config load time ≤20ms for complex panels
- [ ] All existing scanning behaviors preserved (zero regression)
- [ ] All existing tests pass
- [ ] Developer guide created with architecture overview and extension guide
- [ ] Solution builds successfully

## Key Files

| File | Role |
|------|------|
| `docs/ANIMATION_SYSTEM_DESIGN.md` | Design spec (§8 POC, §14 acceptance) |
| `docs/ANIMATION_SYSTEM_ANALYSIS.md` | Current system analysis |
| `src/Libraries/ACATCore/AnimationManagement/PanelAnimationManager.cs` | Adapter target |
| `src/Libraries/ACATCore/AnimationManagement/UserControlAnimationManager.cs` | Adapter target |
| `src/Libraries/ACATCore/AnimationManagement/AnimationManager.cs` | Event routing update |
| `src/Libraries/ACATCore/AnimationManagement/AnimationPlayer.cs` | Legacy (do not break) |
| `src/Extensions/BCI/AnimationSharpManagerV2.cs` | BCI validation |
| `src/ACATResources/panelconfigs/` | 69 XML configs to validate |
| `src/Libraries/ACATCore/AnimationManagement/Configuration/XmlAnimationConfigAdapter.cs` | XML bridge |

## Dependencies

- Issue #4 (Animation Core Engine POC) must be complete

## Blocked By

- Issue #4