OpenSpec Change: enterprise-gaming-react-game-map

Change ID: enterprise-gaming-react-game-map
Package: @suaveplan/react-game-map
Category: gaming/react
Target path: gaming/react/react-game-map
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-game-map.md

Summary

Deliver @suaveplan/react-game-map on the genesis branch from scratch at enterprise quality. The package provides headless state management for 2D world maps in games. A MapStateManager tracks the world-space viewport, entity marker positions, fog-of-war revealed cells, custom icons, and overlays; useGameMap() exposes it via useSyncExternalStore. Canvas rendering helpers paint the background tile layer, entity markers, and fog-of-war cells. Storybook stories demonstrate a scrollable interactive map with entity tracking. Genesis adds typed schemas, structured errors, and 100% coverage.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`GameMapError`
`@suaveplan/events` (`workspace:^`)	Entity position update subscriptions
`react` (`catalog:react`)	React 18

Public API surface

interface MapState {
  viewport: { x: number; y: number; zoom: number }
  markers: MapMarker[]
  fogCells: Set<string>   // "cx,cy" revealed cell keys
  overlays: MapOverlay[]
}

interface MapMarker {
  id: string
  x: number; y: number
  icon: string
  label?: string
  color?: string
}

function createMapStateManager(options: MapStateOptions): MapStateManager
function useGameMap(): MapState

// Components
function GameMapCanvas(props: GameMapCanvasProps): JSX.Element
function MapMarkerLayer(props: MapMarkerLayerProps): JSX.Element
function FogOfWarLayer(props: FogOfWarLayerProps): JSX.Element
function MiniMap(props: MiniMapProps): JSX.Element

File layout

gaming/react/react-game-map/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    types/common.ts
    types/common.md
    state/
      map-state-manager.ts
      map-state-manager.md
      map-state-manager.test.ts
    hooks/
      use-game-map.ts
      use-game-map.md
      use-game-map.test.ts
    components/
      game-map-canvas/
        game-map-canvas.tsx
        game-map-canvas.md
        game-map-canvas.test.tsx
        game-map-canvas.stories.tsx
        index.ts
      mini-map/
        mini-map.tsx
        mini-map.md
        mini-map.test.tsx
        mini-map.stories.tsx
        index.ts

Impact

Downstream: composed with @suaveplan/r3f-minimap for 3D map overlay. Prerequisites: @suaveplan/error, @suaveplan/events, react.

2.7 KiB Raw Blame History