# Masoi Socket Contract

> Maintain the Ma Sói Socket.IO contract between server/index.js and client/src/hooks/useGame.js. Use when adding, renaming, removing, or changing payloads for socket events such as room_joined, role_assigned, phase_changed, night_resolved, wolf_target_updated, vote_resolved, room_reset, reconnect/resume, chat, or special-role events.

- Skill: `nobodyonlyc/masoi-socket-contract` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nobodyonlyc/masoi-socket-contract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nobodyonlyc/masoi-socket-contract/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nobodyonlyc (https://skillmd.com/u/nobodyonlyc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nobodyonlyc/masoi-socket-contract

---


# Ma Sói Socket Contract

## Workflow

1. Find server emits/listeners in `server/index.js`.
2. Find client listeners/actions in `client/src/hooks/useGame.js`.
3. Check UI consumers in `client/src/pages/*` and `client/src/components/*`.
4. Update `references/events.md` when the contract changes.
5. Preserve hidden-information boundaries in payloads.
6. Verify with:
   - `node --check server/index.js`
   - `cd client && npm run build`

## Contract Rules

- Every server `socket.emit` or `io.to(...).emit` used by gameplay must have a matching client listener unless intentionally one-way.
- Every client `socket.emit` action must have a matching server handler.
- Payload changes must be made server-first, then hook state, then UI.
- Reconnect/resume must re-emit enough state to rebuild the current screen.
- Do not expose all player roles to living non-spectator players before the game ends.

## Common Files

- Server handlers: `server/index.js`
- Client socket setup: `client/src/hooks/useSocket.jsx`
- Client game contract/state: `client/src/hooks/useGame.js`
- Main routing by phase: `client/src/App.jsx`

## References

Load `references/events.md` when changing Socket.IO payloads or reconnect behavior.