Animation System: Integration, Testing & Documentation

[michaelbeale-IL]

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 <Animation> 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 Restarting the Presage engine #4, complete here):

   • Parse all 69 XML panel configs' <Animation> 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 Restarting the Presage engine #4 (Animation Core Engine POC) must be complete

Blocked By

• Issue Restarting the Presage engine #4