# 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.