This commit adds a comprehensive external API system that allows external tools
(wikis, web UIs, etc.) to control and synchronize with Fantasy Map Generator.
New Features:
- External API Bridge (modules/external-api.js)
- Event-driven architecture with EventEmitter
- Map lifecycle control (create, load, save)
- Data access methods (rivers, cultures, states, burgs)
- Data mutation methods with auto-redraw
- Export support (SVG, PNG, JSON)
- Change detection with automatic event emission
- PostMessage Communication Layer
- Auto-enables when FMG is embedded in iframe
- Bidirectional message passing
- Request/response pattern with promise support
- Automatic event forwarding to parent window
- REST API Server (api-server/)
- Express.js server with full CRUD operations
- WebSocket support via Socket.IO for real-time updates
- File upload support for map and CSV import
- In-memory storage (can be replaced with database)
- CORS enabled for cross-origin requests
- Comprehensive endpoints for all map data
- Client Library (api-server/client.js)
- Simple JavaScript client for REST API
- Promise-based async methods
- Works in browser and Node.js
- Demo Pages (demos/)
- PostMessage integration demo with full UI
- REST API demo with interactive testing
- WebSocket demo for real-time events
- Documentation
- Comprehensive integration guide (EXTERNAL_API_INTEGRATION.md)
- API reference with TypeScript interfaces
- Multiple integration examples
- Troubleshooting guide
Integration Methods:
1. PostMessage Bridge - For iframe embedding
2. REST API - For server-side integration
3. Direct JavaScript API - For same-origin apps
Use Cases:
- Wiki pages that need to display and control maps
- Web UIs that want to edit map data
- External tools that need to sync with FMG
- Real-time collaborative map editing
- Batch operations and automation
Technical Details:
- Zero dependencies for external-api.js (pure JS)
- Auto-initializes on DOMContentLoaded
- Throttled change detection (500ms debounce)
- Deep cloning for data access (prevents mutations)
- Error handling throughout
- Version tagged (v1.0.0)
Updated Files:
- index.html: Added script tag to load external-api module
All APIs are backward compatible and don't affect existing functionality.
Created extensive wiki documentation covering all aspects of the Fantasy Map Generator:
- Home.md: Wiki homepage with overview and navigation
- Getting-Started.md: Complete beginner's guide for users and developers
- Architecture.md: System architecture, design patterns, and technology stack
- Data-Model.md: Detailed data structures and relationships
- Generation-Process.md: Step-by-step map generation pipeline
- Modules-Reference.md: Documentation for all 20+ modules
- Features-and-UI.md: Complete feature list and UI guide
- README.md: Wiki directory overview
The documentation includes:
- High-level architecture and design patterns
- Detailed data structures with typed arrays
- 17-stage generation pipeline with algorithms
- All core modules (generators, renderers, UI, I/O)
- 41+ UI editors and features
- Code examples and usage patterns
- Developer setup and contribution guidelines
- User tutorials and quick start guides
This wiki provides comprehensive documentation for both users wanting to create maps and developers wanting to understand or contribute to the codebase.
