What problem does it solve?
It solves the confusion and bugs caused by inconsistent Socket.IO event names, namespaces, payload shapes, and handler registration across the server and web client.
Core Features & Use Cases
- Event naming contract: Uses a consistent
type:subtype convention with strict directionality (C→S vs S→C) to avoid mismatches between client and server.
- Session workflow guidance: Documents the end-to-end lifecycle for
session:launch, session:join, session:resume, and the session:states broadcast, including expected payloads and callback behavior.
- Server handler patterns: Establishes a repeatable
apps/server/src/socket/handlers/<domain>-handler.ts registration structure and DI-backed handler context usage.
- Client handler patterns: Provides a matching approach for
apps/web/src/contexts/socket/handlers/<domain>.ts and how action hooks emit events (including callback usage).
- Validation and type safety: Recommends Zod schema validation at handler entry and typed Socket.IO event definitions via
packages/shared/src/socket-events.ts for reliable integration.
- Testing strategy: Includes a FakeClaude-based flow to validate that client requests trigger the expected server-to-client event sequence.
Quick Start
Use the socket-io skill as your reference when adding or updating a new Socket.IO event so you implement the correct namespace, payload schema validation, and typed client/server handlers consistently.