Initial Commit

openspec/changes/enterprise-gaming-react-game-map/proposal.md

@@ -0,0 +1,103 @@
+# 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.

openspec/changes/enterprise-gaming-react-game-map/tasks.md

@@ -0,0 +1,39 @@
+# Tasks: enterprise-gaming-react-game-map
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/react/react-game-map/` (`@suaveplan/react-game-map`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 3 — Map state manager
+
+- [ ] `src/state/map-state-manager.ts` — viewport/markers/fog/overlays with subscribe/update
+- [ ] Tests + docs
+
+## Phase 4 — `useGameMap` hook
+
+- [ ] Tests + docs
+
+## Phase 5 — Components
+
+- [ ] `GameMapCanvas` — canvas with viewport pan/zoom, tile background
+- [ ] `MapMarkerLayer` — SVG overlay for entity markers
+- [ ] `FogOfWarLayer` — masked unrevealed cells
+- [ ] `MiniMap` — thumbnail viewport with current position indicator
+- [ ] Tests + Storybook stories for each
+
+## Phase 6 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-game-map` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/react-game-map`