suaveplan/openspec/changes/enterprise-gaming-react-social-game/proposal.md

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

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

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.