Initial Commit

openspec/changes/enterprise-gaming-chat/proposal.md

@@ -0,0 +1,157 @@
+# OpenSpec Change: enterprise-gaming-chat
+
+- **Change ID**: enterprise-gaming-chat
+- **Package**: `@suaveplan/chat`
+- **Category**: gaming/multiplayer
+- **Target path**: `gaming/multiplayer/chat`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/chat.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/chat` on the genesis branch from scratch at enterprise quality. The package provides in-game chat with named channels, whispers, configurable rate limiting, and a profanity filter. A `ChatManager` maintains typed `ChatChannel` objects (global, local, party, trade, custom); messages are validated against rate limit before dispatch; a `ProfanityFilter` uses a blocklist with configurable mask character; a `WhisperRouter` routes directed messages between two players. Genesis adds Zod message schemas, structured errors, OTel message-rate counter, injectable clock, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ChatError`; `CHAT.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock` |
+| `@suaveplan/events` (`workspace:^`) | `chat:message`, `chat:whisper`, `chat:muted` events |
+| `zod` (`catalog:forms`) | `ChatMessage`, `ChannelConfig` schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Messages-per-second counter |
+
+---
+
+## Public API surface
+
+```ts
+type ChannelType = 'global' | 'local' | 'party' | 'trade' | 'system' | 'custom'
+
+interface ChannelConfig {
+  id: string
+  type: ChannelType
+  displayName: string
+  maxHistory?: number      // message ring buffer size, default 100
+  rateLimitPerMin?: number // default 30
+}
+
+interface ChatMessage {
+  id: string
+  channelId: string
+  senderId: string
+  senderName: string
+  content: string
+  timestamp: number
+  filtered?: boolean
+}
+
+function createChatManager(options?: ChatManagerOptions): ChatManager
+
+interface ChatManagerOptions {
+  profanityFilter?: ProfanityFilter
+  clock?: Clock
+}
+
+interface ChatManager {
+  createChannel(config: ChannelConfig): ChatChannel
+  getChannel(id: string): ChatChannel | undefined
+  deleteChannel(id: string): void
+  sendMessage(channelId: string, senderId: string, senderName: string, content: string): ChatMessage
+  whisper(fromId: string, fromName: string, toId: string, content: string): ChatMessage
+  mute(playerId: string, durationMs?: number): void
+  unmute(playerId: string): void
+  isMuted(playerId: string): boolean
+  tick(dt: number): void   // expire mutes
+}
+
+interface ChatChannel {
+  readonly id: string
+  readonly config: ChannelConfig
+  getHistory(): ChatMessage[]
+  subscribe(playerId: string): void
+  unsubscribe(playerId: string): void
+  readonly subscribers: ReadonlySet<string>
+}
+
+// Profanity filter
+function createProfanityFilter(blocklist: string[], options?: FilterOptions): ProfanityFilter
+
+interface FilterOptions {
+  maskChar?: string    // default '*'
+  mode?: 'mask' | 'block'   // block throws, mask replaces
+}
+
+interface ProfanityFilter {
+  filter(text: string): { filtered: string; triggered: boolean }
+  addWord(word: string): void
+  removeWord(word: string): void
+}
+```
+
+### Error codes
+
+```ts
+type ChatErrorCode =
+  | 'CHAT_CHANNEL_NOT_FOUND'
+  | 'CHAT_RATE_LIMIT_EXCEEDED'
+  | 'CHAT_SENDER_MUTED'
+  | 'CHAT_CONTENT_BLOCKED'
+  | 'CHAT_RECIPIENT_NOT_FOUND'
+```
+
+---
+
+## File layout
+
+```text
+gaming/multiplayer/chat/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      chat-manager/
+        chat-manager.ts
+        chat-manager.md
+        chat-manager.types.ts
+        chat-manager.test.ts
+        index.ts
+      chat-channel/
+        chat-channel.ts
+        chat-channel.md
+        chat-channel.types.ts
+        chat-channel.test.ts
+        index.ts
+    utils/
+      profanity-filter.ts
+      profanity-filter.md
+      profanity-filter.test.ts
+      rate-limiter.ts
+      rate-limiter.md
+      rate-limiter.test.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/react-social-game` renders chat panel. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.