ai.interactive.fiction/TODO.md

Module System Refactoring TODO

High Priority (Critical Architectural Issues)

1. Asynchronous Flow Control Improvements

• Remove all setTimeout calls used for synchronization in modules
  • Replace timeout in browser-tts-handler.js with proper Promise handling for voice loading
  • 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