Initial Commit

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

@@ -0,0 +1,139 @@
+# OpenSpec Change: enterprise-gaming-react-game-hud
+
+- **Change ID**: enterprise-gaming-react-game-hud
+- **Package**: `@suaveplan/react-game-hud`
+- **Category**: gaming/react
+- **Target path**: `gaming/react/react-game-hud`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-game-hud.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-game-hud` on the genesis branch from scratch at enterprise quality. The package is a headless React layer for in-game HUD overlays: health bar, ammo counter, mini-map widget, objective tracker, kill-feed, and XP/level display. A `HudStateManager` aggregates state from `@suaveplan/combat`, `@suaveplan/weapons`, `@suaveplan/progression`, and `@suaveplan/quest` into a single typed store; `useHud()` exposes it via `useSyncExternalStore`. All component primitives are unstyled (className/style passthrough) for game-specific theming. Genesis adds Storybook stories for every component, Vitest DOM tests, 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/combat` (`workspace:^`) | Health/shield state |
+| `@suaveplan/weapons` (`workspace:^`) | Ammo/reload state |
+| `@suaveplan/progression` (`workspace:^`) | XP/level state |
+| `@suaveplan/quest` (`workspace:^`) | Active objectives |
+| `@suaveplan/events` (`workspace:^`) | State update subscriptions |
+| `react` (`catalog:react`) | React 18 |
+
+---
+
+## Public API surface
+
+```ts
+interface HudState {
+  health: number
+  maxHealth: number
+  shield: number
+  maxShield: number
+  armor: number
+  ammo: number
+  maxAmmo: number
+  isReloading: boolean
+  level: number
+  xp: number
+  xpToNext: number
+  activeObjectives: ActiveObjective[]
+  killFeed: KillFeedEntry[]
+}
+
+function createHudStateManager(options: HudStateOptions): HudStateManager
+interface HudStateManager {
+  getSnapshot(): HudState
+  subscribe(cb: () => void): () => void
+  update(partial: Partial<HudState>): void
+}
+
+function useHud(): HudState
+
+// Components (headless unstyled)
+function HealthBar(props: HealthBarProps): JSX.Element
+function AmmoDisplay(props: AmmoDisplayProps): JSX.Element
+function XpBar(props: XpBarProps): JSX.Element
+function ObjectiveList(props: ObjectiveListProps): JSX.Element
+function KillFeed(props: KillFeedProps): JSX.Element
+function HudOverlay(props: HudOverlayProps): JSX.Element   // container
+```
+
+---
+
+## File layout
+
+```text
+gaming/react/react-game-hud/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    types/common.ts
+    types/common.md
+    state/
+      hud-state-manager.ts
+      hud-state-manager.md
+      hud-state-manager.test.ts
+    hooks/
+      use-hud.ts
+      use-hud.md
+      use-hud.test.ts
+    components/
+      health-bar/
+        health-bar.tsx
+        health-bar.md
+        health-bar.test.tsx
+        health-bar.stories.tsx
+        index.ts
+      ammo-display/
+        ammo-display.tsx
+        ammo-display.md
+        ammo-display.test.tsx
+        ammo-display.stories.tsx
+        index.ts
+      xp-bar/
+        xp-bar.tsx
+        xp-bar.md
+        xp-bar.test.tsx
+        xp-bar.stories.tsx
+        index.ts
+      objective-list/
+        objective-list.tsx
+        objective-list.md
+        objective-list.test.tsx
+        objective-list.stories.tsx
+        index.ts
+      kill-feed/
+        kill-feed.tsx
+        kill-feed.md
+        kill-feed.test.tsx
+        kill-feed.stories.tsx
+        index.ts
+      hud-overlay/
+        hud-overlay.tsx
+        hud-overlay.md
+        hud-overlay.test.tsx
+        hud-overlay.stories.tsx
+        index.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: game apps compose HUD components over R3F canvas. Prerequisites: `@suaveplan/combat`, `@suaveplan/weapons`, `@suaveplan/progression`, `@suaveplan/quest`, `@suaveplan/events`, react.