# Module System Refactoring TODO

## High Priority (Critical Architectural Issues)

### 1. Asynchronous Flow Control Improvements
- [ ] Remove all `setTimeout` calls used for synchronization in modules
  - [X] Replace timeout in `browser-tts-handler.js` with proper Promise handling for voice loading
  - [X] Eliminate race condition in `tts-player.js` that uses a hard-coded 1000ms timeout
  - [ ] Remove all `setTimeout` calls in `ui-controller.js` for UI updates
- [ ] Implement proper Promise-based flow control in all modules
  - [ ] Update `kokoro-handler.js` to correctly handle loading events
  - [ ] Ensure all `async/await` patterns follow best practices
  - [ ] Fix race conditions in module loading sequences

### 2. Module State Management
- [ ] Fix premature reporting of `FINISHED` state
  - [ ] Ensure `tts-player.js` properly waits for Kokoro loading before reporting FINISHED
  - [ ] Add proper state checks in all modules before reporting FINISHED
- [ ] Implement proper state transition reporting
  - [ ] Update modules to use event system for reporting state transitions
  - [ ] Add better error handling during module initialization

### 3. Module Dependencies & Loading
- [ ] Fix missing dependency declarations
  - [ ] Update `ui-controller.js` to properly declare its TTS dependency
  - [ ] Ensure all modules correctly specify all dependencies
- [ ] Remove dependency availability checks within modules
  - [ ] Remove conditional checks like `if (!this.ttsHandler)` in `ui-controller.js`
  - [ ] Rely on the module loader for dependency management

## Medium Priority (Functionality & Implementation Issues)

### 4. TTS Handler Implementation
- [ ] Implement missing `tts-handler.js` file content
  - [ ] Create proper implementation with consistent interface
  - [ ] Ensure it uses proper event-based communication
- [ ] Fix inconsistent event usage across TTS handlers
  - [ ] Replace direct callbacks with event system
  - [ ] Standardize event names and parameters

### 5. Animation Queue Enhancements
- [ ] Implement proper queue control mechanisms
  - [ ] Add pause/resume functionality
  - [ ] Implement more robust animation timing
  - [ ] Add priority management for animations

### 6. UI Controller Cleanup
- [ ] Fix duplicate methods in UI Controller
  - [ ] Deduplicate code for creating UI elements
  - [ ] Consolidate event handling functions
- [ ] Remove redundant `ModuleEvent` class implementation
  - [ ] Use the shared implementation from `base-module.js`

### 7. Kokoro Loading Implementation
- [ ] Implement proper `requestIdleCallback` for Kokoro loading
  - [ ] Follow the pattern described in the specification
  - [ ] Add progress reporting during Kokoro loading
- [ ] Fix event handling for loading completion

## Lower Priority (Refinements & Optimizations)

### 8. Code Quality & Consistency
- [ ] Standardize module registration pattern
  - [ ] Ensure all modules follow the same pattern
  - [ ] Fix inconsistencies in export approaches
- [ ] Improve module progress reporting
  - [ ] Make progress reporting more granular
  - [ ] Add more descriptive status messages

### 9. Error Handling Improvements
- [ ] Add better error recovery mechanisms
  - [ ] Implement fallbacks for critical failures
  - [ ] Add user-friendly error messages
- [ ] Improve error logging
  - [ ] Add structured error reporting
  - [ ] Implement debugging tools

### 10. Performance Optimizations
- [ ] Optimize module loading sequence
  - [ ] Prioritize critical modules
  - [ ] Defer non-essential loading
- [ ] Improve resource utilization
  - [ ] Minimize memory footprint
  - [ ] Reduce CPU usage during animations

## Documentation & Testing

### 11. Documentation
- [ ] Add JSDoc comments to all public methods
- [ ] Create architectural documentation
  - [ ] Document module dependencies
  - [ ] Explain event system
- [ ] Add example usage for modules

### 12. Testing
- [ ] Create unit tests for modules
- [ ] Implement integration tests for module system
- [ ] Add browser compatibility tests

## Future Enhancements

### 13. New Features
- [ ] Add module versioning support
- [ ] Implement module hot-reloading
- [ ] Create plugin system for extending modules
- [ ] Add internationalization support for UI