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.
