Animation System: Core Engine POC

[Copilot]

• Understand the issue requirements and existing POC in Experimental/AnimationPOC/
• Create all 7 interfaces (IScanTimer, IScanModeStrategy/IScanContext, IAnimationSession, IAnimationService, IHighlightRenderer, IAnimationConfigProvider)
• Create all production implementations (SystemScanTimer, AnimationSession, AnimationService, AutoScanStrategy, ManualScanStrategy, StepScanStrategy, WinFormsHighlightRenderer, AnimationConfigProvider, XmlAnimationConfigAdapter)
• Create test implementation (TestScanTimer)
• Create config model (AnimationConfig, AnimationSequenceConfig, AnimationWidgetConfig)
• Create AnimationEngineEvents (AnimationStateChangedEvent, AnimationTransitionEvent, AnimationHighlightEvent)
• Create Rendering/HighlightStyle.cs
• Update ServiceCollectionExtensions.cs with AddAnimationEngine()
• Create AnimationEngineTests.cs with 20 unit tests
• Fix build failure: add all 19 new animation engine files to ACAT.Core.csproj Compile includes (project uses EnableDefaultCompileItems=false)
• AnimationPlayer.cs completely untouched (zero changes)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Animation System: Core Engine POC</issue_title>
<issue_description># Animation System: Core Engine POC

Labels

phase-3, workstream-b, animation, new-architecture

Milestone

Phase 3: Animation System Modernization

Summary

Implement the new animation engine core as a proof-of-concept, following the architecture defined in ANIMATION_SYSTEM_DESIGN.md §8. This creates the new composable, testable animation architecture alongside the existing AnimationPlayer.cs (which remains untouched as a legacy adapter).

The new engine introduces 7 interfaces, their implementations, a JSON configuration model, DI registration, and comprehensive unit tests.

Context

Why This Matters

The animation system is ACAT's heartbeat — it drives the scanning highlight that allows users with motor disabilities to interact with the application. The current system has significant pain points (documented in Issue intel/acat#206 analysis):

• AnimationPlayer.cs is 1,835 lines mixing timer, state machine, highlighting, and configuration
• Untestable: System.Timers.Timer and WinForms controls can't be mocked
• 3 scan modes (auto/manual/step) entangled in one class
• BCI extension (AnimationSharpManagerV2.cs, 2,885 lines) duplicates ~1,400 lines of core logic

Design Decisions (ADR-001)

• AnimationPlayer.cs retained as legacy adapter (not rewritten)
• PCode interpreter retained as-is (replacement deferred)
• Backward compatibility for IAnimationManager, IPanelAnimationManager, IUserControlAnimationManager
• New engine runs alongside legacy system — callers migrate incrementally

Current Animation Files (16 files, 4,925 lines)

Located in src/Libraries/ACATCore/AnimationManagement/:

File	Lines	Role
AnimationPlayer.cs	1,835	Timer loop, widget highlighting, state machine
AnimationManager.cs	976	Actuator event routing, player lifecycle
Animation.cs	485	Single scan sequence: widget list + PCode
UserControlAnimationManager.cs	402	UserControl variant
PanelAnimationManager.cs	395	Per-panel player management
AnimationsCollection.cs	164	Dictionary of Animations
Animations.cs	156	Collection per panel
Variables.cs	155	Key/value animation runtime vars
AnimationWidget.cs	148	Per-widget highlight settings

Implementation Steps

Step 1: Timer Abstraction

Create IScanTimer — an injectable timer that replaces direct System.Timers.Timer usage (pain point P1).

Files to create:

• src/Libraries/ACATCore/AnimationManagement/Interfaces/IScanTimer.cs

  public interface IScanTimer
  {
      bool Enabled { get; set; }
      double Interval { get; set; }
      bool AutoReset { get; set; }
      event EventHandler Elapsed;
      void Start();
      void Stop();
  }

• src/Libraries/ACATCore/AnimationManagement/SystemScanTimer.cs — wraps System.Timers.Timer for production
• src/Libraries/ACATCore/AnimationManagement/TestScanTimer.cs — manually-triggered timer for unit tests

Step 2: JSON Configuration Data Model

Create the AnimationConfig model per design spec §6, enabling JSON-first configuration alongside existing XML.

Files to create:

• src/Libraries/ACATCore/AnimationManagement/Configuration/AnimationConfig.cs

  • AnimationConfig → PanelName, ScanStrategy, List<AnimationSequenceConfig>
  • AnimationSequenceConfig → Name, IsFirst, AutoStart, Iterations (string for @VarName), ScanTime, FirstPauseTime, OnEnter, OnEnd, List<AnimationWidgetConfig>
  • AnimationWidgetConfig → Name (supports wildcards), PlayBeep, OnSelected

• src/Libraries/ACATCore/AnimationManagement/Interfaces/IAnimationConfigProvider.cs

  public interface IAnimationConfigProvider
  {
      AnimationConfig LoadForPanel(string panelName, string configPath);
      bool HasJsonConfig(string panelName);
  }

• src/Libraries/ACATCore/AnimationManagement/Configuration/AnimationConfigProvider.cs — JSON loader implementation

• src/Libraries/ACATCore/AnimationManagement/Configuration/XmlAnimationConfigAdapter.cs — reads existing XML <Animation> elements into AnimationConfig model (enables migration without changing 69 XML files)

Step 3: Scan Mode Strategies

Implement IScanModeStrategy — strategy pattern that cleanly separates auto-scan, manual-scan, and step-scan logic (pain point P6).

Files to create:

• src/Libraries/ACATCore/AnimationManagement/Interfaces/IScanModeStrategy.cs

  public interface IScanModeStrategy
  {
      ScanInputAction SelectNext(IScanContext context);
      ScanInputAction SelectPrevious(IScanContext context);
    ...

• Fixes Animation System: Core Engine POC #266

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[michaelbeale-IL]

@copilot - The build is failing. I think you need to migrate code from the Experiments Animation POC project.

[Copilot]

@copilot - The build is failing. I think you need to migrate code from the Experiments Animation POC project.

Fixed in ad22576. The root cause was that ACAT.Core.csproj has EnableDefaultCompileItems=false and uses explicit <Compile Include> entries — so the 19 new animation engine files were never compiled, causing ServiceCollectionExtensions.cs (which references the new types) to fail, breaking the ACATCore.Tests.Logging build step and all subsequent test steps.

Added all 19 new files to the <Compile> section of ACAT.Core.csproj.