Minor cleanup.

TODO.md

@@ -1,99 +1,106 @@
-# Project Implementation Plan
+# Module System Refactoring TODO
 
-## Phase 1: Project Setup and Basic Structure
-- [x] Define project goals and specifications
-- [x] Set up project structure
-  - [x] Create core directories (src, data, tests)
-  - [x] Initialize Node.js/npm project
-  - [x] Set up TypeScript configuration
-  - [ ] Configure ESLint and Prettier for code quality
-- [ ] Choose and set up testing framework
-- [x] Create basic documentation structure
+## High Priority (Critical Architectural Issues)
 
-## Phase 2: World Model Implementation
-- [ ] Define YAML schema for world elements
-  - [ ] Room schema (description, exits, objects, characters)
-  - [ ] Object schema (description, properties, allowed actions)
-  - [ ] NPC schema (description, dialogue, behavior)
-  - [ ] Action schema (conditions, effects)
-- [x] Implement YAML parser and validator
-- [ ] Create the world model core
-  - [ ] Game state management
-  - [ ] Room navigation
-  - [ ] Object interaction
-  - [ ] NPC interaction
-  - [ ] Action processing logic
-- [x] Create a simple test world in YAML format
-- [ ] Implement unit tests for world model
+### 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
 
-## Phase 3: LLM Integration
-- [x] Research and select appropriate OpenRouter model
-- [x] Implement OpenRouter API client
-  - [x] Configuration and authentication
-  - [x] API request/response handling
-  - [ ] Rate limiting and error handling
-- [ ] Design LLM prompting strategy
-  - [ ] System prompts for action translation
-  - [ ] System prompts for narrative generation
-  - [ ] Context management for conversation history
-- [ ] Create adapter between LLM and world model
-  - [ ] Define the interface for action translation
-  - [ ] Define the interface for narrative generation
+### 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
 
-## Phase 4: Game Engine Core
-- [x] Implement the game loop
-  - [x] Input handling
-  - [ ] Action processing via LLM
-  - [ ] World model updating
-  - [ ] Response generation via LLM
-  - [ ] Output formatting
-- [ ] Implement saving/loading game state
-- [ ] Add game configuration options
-- [ ] Implement logging for debugging
+### 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
 
-## Phase 5: User Interface
-- [x] Create a command-line interface
-  - [x] Input handling
-  - [x] Text output formatting
-  - [ ] Command history
-- [x] Implement a simple web interface
-  - [x] Basic HTML/CSS structure
-  - [x] JavaScript for interaction
-  - [x] Responsive design
-- [x] Text processing utilities
-  - [x] Implement smartypants.js for typographical improvements
-  - [ ] Add hyphenation support
+## Medium Priority (Functionality & Implementation Issues)
 
-## Phase 6: Advanced Features
-- [ ] Implement integration layer for Z-machine
-  - [ ] Research Z-machine libraries
-  - [ ] Create adapter for Z-machine to world model interface
-  - [ ] Test with classic Infocom games
-- [ ] Add advanced LLM features
-  - [ ] Character styles and narrative tones
-  - [ ] Memory and reference to past events
-  - [ ] Player character personality modeling
-- [ ] Create plugin system for extending world model capabilities
+### 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
 
-## Phase 7: Testing and Refinement
-- [ ] Comprehensive testing
-  - [ ] Unit tests for core components
-  - [ ] Integration tests for LLM integration
-  - [ ] End-to-end game flow tests
-  - [ ] User testing and feedback
-- [ ] Performance optimization
-  - [ ] Minimize LLM token usage
-  - [ ] Optimize world model for larger games
-- [ ] Refine prompting strategies based on testing
+### 5. Animation Queue Enhancements
+- [ ] Implement proper queue control mechanisms
+  - [ ] Add pause/resume functionality
+  - [ ] Implement more robust animation timing
+  - [ ] Add priority management for animations
 
-## Phase 8: Documentation and Release
-- [x] Complete user documentation
-  - [x] Installation guide
-  - [ ] World creation guide
-  - [ ] Configuration reference
-- [ ] Complete developer documentation
-  - [ ] Architecture overview
-  - [ ] API reference
-  - [ ] Extension guide
-- [ ] Create example worlds and games
-- [ ] Prepare for initial release
+### 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