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

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

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.

3.8 KiB Raw Permalink Blame History