# OpenSpec Change: enterprise-gaming-react-social-game

- **Change ID**: enterprise-gaming-react-social-game
- **Package**: `@suaveplan/react-social-game`
- **Category**: gaming/react
- **Target path**: `gaming/react/react-social-game`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-social-game.md`

---

## Summary

Deliver `@suaveplan/react-social-game` on the genesis branch from scratch at enterprise quality. The package provides social game state management: friends lists, friend requests, user blocking, online-status tracking, activity strings, and search. A framework-agnostic `FriendListManager` class (built on `@suaveplan/events`) manages state; `useSocialGame()` backed by `useSyncExternalStore` provides React access; components render a friend panel, search results, status badges, and activity labels. Genesis adds Storybook stories, Vitest DOM tests, and 100% coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/events` (`workspace:^`) | Social state change events |
| `@suaveplan/party` (`workspace:^`) | Party invite integration |
| `react` (`catalog:react`) | React 18 |

---

## Public API surface

```ts
type OnlineStatus = 'online' | 'away' | 'busy' | 'offline'

interface Friend {
  playerId: string
  displayName: string
  status: OnlineStatus
  activity?: string
  avatarUrl?: string
}

function createFriendListManager(options?: { playerId: string }): FriendListManager

interface FriendListManager {
  getSnapshot(): SocialState
  subscribe(cb: () => void): () => void
  addFriend(friend: Friend): void
  removeFriend(playerId: string): void
  updateStatus(playerId: string, status: OnlineStatus, activity?: string): void
  blockPlayer(playerId: string): void
  unblockPlayer(playerId: string): void
  sendFriendRequest(toId: string): void
  acceptFriendRequest(fromId: string): void
  search(query: string): Friend[]
}

function useSocialGame(): SocialState & { manager: FriendListManager }

// Components
function FriendPanel(props): JSX.Element
function FriendRow(props): JSX.Element
function StatusBadge(props): JSX.Element
function FriendSearch(props): JSX.Element
function FriendRequestList(props): JSX.Element
```

---

## File layout

```text
gaming/react/react-social-game/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    types/common.ts + md
    state/friend-list-manager.ts + md + test
    hooks/use-social-game.ts + md + test
    components/
      friend-panel/ (tsx + md + test + stories + index)
      friend-row/ (tsx + md + test + stories + index)
      status-badge/ (tsx + md + test + stories + index)
      friend-search/ (tsx + md + test + stories + index)
      friend-request-list/ (tsx + md + test + stories + index)
```

---

## Impact

**Downstream**: composable in game lobby and social hub UIs. Prerequisites: `@suaveplan/events`, `@suaveplan/party`, react.