Cc widgets ai plan

.TODO-future-reference/extra-diagrams/component-flow.puml

@@ -0,0 +1,77 @@
+@startuml
+title Widget Component Flow - Three-Layer Architecture
+
+actor "Application" as App
+participant "Widget Layer" as Widget
+participant "Hook Layer" as Hook
+participant "Component Layer" as Component
+participant "MobX Store" as Store
+participant "SDK" as SDK
+
+App -> Widget: <ComponentCCStationLogin />
+activate Widget
+
+Widget -> Widget: Error boundary wrapper
+Widget -> Hook: useStationLogin()
+activate Hook
+
+Hook -> Store: getInstance()
+activate Store
+
+Store -> SDK: getConfiguration()
+SDK --> Store: config data
+
+Store --> Hook: observable state
+Hook --> Widget: {state, handlers}
+
+deactivate Hook
+
+Widget -> Component: <StationLoginComponent />
+activate Component
+
+Component -> Component: Render UI
+Component -> Component: User interaction
+
+Component -> Hook: onLoginClick()
+activate Hook
+
+Hook -> Store: runInAction(() => ...)
+activate Store
+
+Store -> SDK: login(credentials)
+SDK --> Store: success/error
+
+Store --> Hook: updated state
+deactivate Store
+
+Hook --> Component: new state
+deactivate Hook
+
+Component -> Component: Re-render
+deactivate Component
+
+deactivate Widget
+
+note right of Widget
+  Widget Layer:
+  - Error boundary
+  - Hook consumption
+  - Component composition
+end note
+
+note right of Hook
+  Hook Layer:
+  - Store subscription
+  - Business logic
+  - Event handlers
+end note
+
+note right of Component
+  Component Layer:
+  - Pure presentation
+  - User interactions
+  - Local UI state
+end note
+
+@enduml
+

.TODO-future-reference/extra-diagrams/event-handling.puml

@@ -0,0 +1,73 @@
+@startuml
+title SDK Event Handling Flow
+
+participant "SDK" as SDK
+participant "StoreWrapper" as Wrapper
+participant "Store" as Store
+participant "Observer Component" as Comp
+
+== Initialization ==
+
+Store -> Wrapper: new StoreWrapper(sdk)
+activate Wrapper
+
+Wrapper -> SDK: sdk.on('agent.statechange', handler)
+Wrapper -> SDK: sdk.on('task.incoming', handler)
+Wrapper -> SDK: sdk.on('call.statechange', handler)
+
+Wrapper --> Store: Wrapped SDK with listeners
+deactivate Wrapper
+
+Store -> Comp: getInstance()
+Comp -> Comp: observer() HOC
+
+== Event Occurs ==
+
+SDK -> Wrapper: emit('agent.statechange', data)
+activate Wrapper
+
+Wrapper -> Store: runInAction(() => ...)
+activate Store
+
+Store -> Store: Update observable state
+Store --> Wrapper: State updated
+
+deactivate Store
+
+Wrapper --> Comp: MobX notification
+deactivate Wrapper
+
+Comp -> Comp: Re-render with new state
+
+== Cleanup ==
+
+Comp -> Comp: useEffect cleanup
+Comp -> Store: Remove references
+Store -> Wrapper: Cleanup
+activate Wrapper
+
+Wrapper -> SDK: sdk.off('agent.statechange', handler)
+Wrapper -> SDK: sdk.off('task.incoming', handler)
+Wrapper -> SDK: sdk.off('call.statechange', handler)
+
+Wrapper --> Store: Listeners removed
+deactivate Wrapper
+
+note right of Wrapper
+  StoreWrapper responsibilities:
+  - Event listener management
+  - Automatic cleanup
+  - State synchronization
+  - runInAction wrapping
+end note
+
+note right of Store
+  Store pattern:
+  - Singleton instance
+  - Observable state
+  - Event-driven updates
+  - Centralized state
+end note
+
+@enduml
+

.TODO-future-reference/extra-diagrams/state-management.puml

@@ -0,0 +1,66 @@
+@startuml
+title MobX State Management Pattern
+
+participant "Component" as Comp
+participant "observer() HOC" as Observer
+participant "Store Singleton" as Store
+participant "StoreWrapper" as Wrapper
+participant "SDK" as SDK
+
+Comp -> Observer: Use observer(Component)
+activate Observer
+
+Observer -> Store: getInstance()
+activate Store
+
+Store -> Wrapper: Proxy access
+activate Wrapper
+
+Wrapper -> Wrapper: Event listener setup
+Wrapper -> SDK: Subscribe to events
+SDK --> Wrapper: Event stream
+
+note right of Store
+  Store is:
+  - Singleton instance
+  - makeAutoObservable
+  - Reactive state
+end note
+
+Wrapper --> Store: Wrapped SDK
+deactivate Wrapper
+
+Store --> Observer: Observable state
+Observer --> Comp: Reactive data
+
+note right of Observer
+  Observer:
+  - Auto-subscribes to observables
+  - Re-renders on state change
+  - Cleanup on unmount
+end note
+
+== State Mutation ==
+
+Comp -> Comp: User action
+Comp -> Store: runInAction(() => ...)
+activate Store
+
+Store -> Store: Mutate observable
+Store -> SDK: API call
+SDK --> Store: Response
+
+Store --> Observer: Notify observers
+deactivate Store
+
+Observer -> Comp: Re-render
+
+deactivate Observer
+
+note bottom
+  All state mutations MUST use runInAction()
+  to ensure MobX tracks changes correctly
+end note
+
+@enduml
+

.TODO-future-reference/extra-diagrams/test-flow.puml

@@ -0,0 +1,107 @@
+@startuml
+title Testing Flow - Jest & Playwright
+
+== Jest Unit Testing ==
+
+participant "Test File" as Test
+participant "Mock Store" as MockStore
+participant "Component" as Comp
+participant "React Testing Library" as RTL
+
+Test -> MockStore: Create mock with initial state
+activate MockStore
+
+MockStore --> Test: mockStore instance
+
+Test -> Test: Mock Store.getInstance()
+Test -> RTL: render(<Component />)
+activate RTL
+
+RTL -> Comp: Mount component
+activate Comp
+
+Comp -> MockStore: getInstance()
+MockStore --> Comp: mockStore
+
+Comp -> Comp: Render with mock data
+Comp --> RTL: Rendered output
+
+deactivate Comp
+RTL --> Test: screen queries
+
+Test -> RTL: fireEvent.click(button)
+RTL -> Comp: Trigger handler
+activate Comp
+
+Comp -> MockStore: Update state
+MockStore -> Comp: New state
+
+Comp -> Comp: Re-render
+Comp --> RTL: Updated output
+
+deactivate Comp
+RTL --> Test: Updated screen
+
+Test -> Test: expect(screen.getByText(...))
+
+deactivate RTL
+deactivate MockStore
+
+== Playwright E2E Testing ==
+
+participant "Playwright Test" as PW
+participant "Browser" as Browser
+participant "TestManager" as Manager
+participant "Application" as App
+
+PW -> Manager: new TestManager(config)
+activate Manager
+
+Manager -> Browser: Launch browser
+Browser --> Manager: page instance
+
+Manager -> Browser: Navigate to app
+Browser -> App: Load application
+App --> Browser: Rendered
+
+Manager --> PW: TestManager instance
+
+PW -> Manager: login(credentials)
+Manager -> Browser: page.fill('[data-testid="username"]')
+Manager -> Browser: page.click('[data-testid="login-btn"]')
+
+Browser -> App: Submit login
+App --> Browser: Dashboard loaded
+
+Manager --> PW: Login successful
+
+PW -> Manager: acceptTask()
+Manager -> Browser: page.click('[data-testid="accept-task"]')
+
+Browser -> App: Accept task
+App --> Browser: Task accepted
+
+Manager --> PW: Task accepted
+
+PW -> PW: expect(page.locator(...))
+
+deactivate Manager
+
+note right of MockStore
+  Jest Mocking:
+  - Mock Store.getInstance()
+  - Control state
+  - Verify interactions
+  - Isolate components
+end note
+
+note right of Manager
+  TestManager:
+  - Multi-agent scenarios
+  - Complex workflows
+  - Page object pattern
+  - Reusable helpers
+end note
+
+@enduml
+