Skip to content

Latest commit

 

History

History
45 lines (36 loc) · 2.37 KB

ARCHITECTURE.md

File metadata and controls

45 lines (36 loc) · 2.37 KB

Architecture

The Dungeon Mapper editor remains a client-only React + TypeScript + Vite application. The planned optional GitHub publisher is a separate first-party publishing page/service, not a move of this editor or its local storage. A loopback-only Node authentication and metadata-planning simulation now lives under publisher/, outside the Pages build. Its separate browser bundle reuses creator ZIP inspection. Planning sends scalar metadata only; a separately consented loopback ZIP submission is independently checked by a Node child with publisher-only DOM/native-image dependencies. A fake-publication engine and local SQLite metadata journal exercise branch writing/readback and restart reconciliation. With an explicit journal path, authenticated simulation endpoints and browser confirmation/recovery connect only to the in-memory test provider. No backend or real account connection has been deployed.

High-level layers

  • UI components (src/components): toolbar, dialogs, canvas, inspector, and shell layout
  • State hooks (src/hooks): map state/history, level management, persistence, and input helpers
  • Domain utilities (src/utils): generators, rendering, rasterizers, fog/FOV, export, and art systems
  • Type model (src/types/map.ts): core map/project schema shared across features
  • Themes (src/themes): tile rendering logic and theme-specific visual behavior

Core flow

  1. User actions trigger callbacks in UI components.
  2. Hooks update project/map state.
  3. Canvas rendering uses derived render data from map + overlays.
  4. Persistence auto-saves to IndexedDB.
  5. Export paths render to PNG/SVG/JSON outputs.

Key subsystems

  • MapCanvas: interaction-heavy canvas view for drawing, selection, overlays, and navigation
  • useMapState: central state transitions for tiles, notes, tokens, room shapes, and rivers
  • Generators: deterministic seeded generation pipeline for rooms, terrain, cavern, and village
  • Room/River vector layers: editable vectors rasterized onto the tile grid for final rendering
  • Accessibility: keyboard shortcuts, focus-visible behavior, aria-live announcements, and contrast helpers

Testing strategy

  • Unit tests for pure utilities and generators
  • Integration-style component tests for major UI behavior
  • Regression tests for rendering/export paths and roadmap audit guardrails