# 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

```ts
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

```text
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.