refactor: modularize frontend state with event-driven UI updates

Backend: extract Client, Handler, ProtocolError from monolithic Hub into
separate modules under internal/signal/.

Frontend: introduce state/ layer (roomState, mediaState, peersState) with
subscribe/notify mechanism. State mutations automatically trigger UI refresh
via coarse-grained subscriptions with anti-reentrancy guard. Remove 21
manual updateControls() calls scattered across controllers.

New modules: protocol/message.js (shared contract), webrtc/peerState.js
(Perfect Negotiation), controllers/chat.js (DataChannel messaging).

Tests: 65 passing (was 34), including subscribe/notify unit tests.

Author: LessUp

CONTEXT.md

@@ -0,0 +1,122 @@
+# LessUp WebRTC 领域词汇表
+
+本文档定义项目的核心领域概念，用于指导架构讨论和代码命名。
+
+---
+
+## 核心领域
+
+### Room（房间）
+
+一个虚拟的通信空间，客户端加入后可以与其他成员进行 WebRTC 通话。
+
+- 每个房间有唯一的名称（最长 64 字符）
+- 房间自动创建（首个客户端加入时）和销毁（最后一个离开时）
+- 房间容量上限：50 个客户端
+- 系统房间上限：1000 个房间
+
+### Client（客户端）
+
+连接到信令服务器的 WebSocket 连接，代表一个用户的信令身份。
+
+- 客户端 ID：用户提供的唯一标识符（最长 64 字符）
+- 连接 ID：服务器分配的内部标识符（用于日志追踪）
+- 身份绑定：首次加入房间后，ID 和房间不可更改
+
+### Peer（对等方）
+
+WebRTC 连接的远端参与者，存储在本地状态中。
+
+- 每个 Peer 对应一个 RTCPeerConnection
+- 包含连接状态、媒体流、UI 元素引用
+- 与特定 Client ID 关联（同一用户可能有多条 Peer 连接）
+
+### Signal（信令）
+
+用于建立 WebRTC 连接的消息交换机制。
+
+- 通过 WebSocket 传输
+- 消息类型：join、offer、answer、candidate、hangup
+- 信令服务器只转发，不解析 SDP/ICE 内容
+
+### Media Stream（媒体流）
+
+音视频数据的实时流。
+
+- 本地流：来自摄像头/麦克风的采集
+- 远端流：从 Peer 接收的流
+- 屏幕流：来自屏幕共享的流
+
+### DataChannel（数据通道）
+
+WebRTC 的双向数据传输通道。
+
+- 用于聊天消息传输
+- 在发起呼叫时创建
+- 支持 open/message/close 事件
+
+---
+
+## 系统边界
+
+### 后端（Go）
+
+| 模块 | 职责 |
+|:-----|:-----|
+| Signal Hub | 房间管理、消息路由、身份验证 |
+| Client | WebSocket 连接生命周期、速率限制 |
+| Message | 信令消息结构定义、类型常量 |
+| ProtocolError | 协议错误领域模型、错误码定义 |
+
+### 前端（JavaScript）
+
+| 模块 | 职责 |
+|:-----|:-----|
+| app.js | 应用入口、控制器组装 |
+| state/ | 领域状态管理（roomState、mediaState、peersState） |
+| signaling.js | WebSocket 连接、消息处理 |
+| peers.js | Peer 连接管理、SDP/ICE 协商 |
+| chat.js | DataChannel 聊天消息收发 |
+| media.js | 媒体流管理、录制 |
+| ui.js | DOM 操作、视图渲染 |
+| stats.js | WebRTC 统计信息收集 |
+
+---
+
+## 状态机
+
+### 房间状态（roomState）
+
+```
+idle → connecting → joined ⇄ reconnecting → idle
+```
+
+### Peer 连接状态（connectionState）
+
+```
+new → connecting → connected → disconnected → closed/failed
+```
+
+---
+
+## 错误码
+
+信令服务器定义的错误码：
+
+| 错误码 | 含义 |
+|:-------|:-----|
+| `invalid_id` | 客户端 ID 格式无效 |
+| `invalid_room` | 房间名格式无效 |
+| `invalid_join` | 加入请求缺少必要字段 |
+| `duplicate_id` | 房间内 ID 已存在 |
+| `room_full` | 房间已满（50 人） |
+| `room_limit_reached` | 系统房间上限（1000） |
+| `room_missing` | 房间不存在 |
+| `already_joined` | 已在房间中 |
+| `identity_locked` | 身份已绑定不可更改 |
+| `not_joined` | 未加入房间 |
+| `invalid_target` | 目标客户端无效 |
+| `target_not_found` | 目标客户端不在房间 |
+| `membership_lost` | 客户端已从房间移除 |
+| `unknown_type` | 消息类型不支持 |
+| `rate_limited` | 消息发送过快 |

internal/signal/client.go

@@ -0,0 +1,174 @@
+package signal
+
+import (
+	"errors"
+	"log"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// Client represents a connected WebSocket client.
+type Client struct {
+	mu        sync.RWMutex
+	id        string
+	room      string
+	connID    uint64
+	conn      *websocket.Conn
+	send      chan Message
+	closed    chan struct{}
+	closeOnce sync.Once
+	// Rate limiting
+	msgCount    int
+	msgWindow   time.Time
+	rateLimited bool
+}
+
+// identity returns the client's ID and room.
+func (c *Client) identity() (userID, userRoom string) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.id, c.room
+}
+
+// setIdentity sets the client's ID and room.
+func (c *Client) setIdentity(id, room string) {
+	c.mu.Lock()
+	c.id = id
+	c.room = room
+	c.mu.Unlock()
+}
+
+// setRoom sets the client's room.
+func (c *Client) setRoom(room string) {
+	c.mu.Lock()
+	c.room = room
+	c.mu.Unlock()
+}
+
+// checkRateLimit implements token bucket rate limiting.
+// Returns true if the message should be allowed, false if rate limited.
+// Allows burst up to RateLimitBurst (50), then enforces MaxMessagesPerSecond (30/sec).
+func (c *Client) checkRateLimit() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	now := time.Now()
+	// Reset window if more than 1 second has passed
+	if now.Sub(c.msgWindow) >= time.Second {
+		c.msgWindow = now
+		c.msgCount = 0
+		c.rateLimited = false
+	}
+
+	c.msgCount++
+
+	// First check: absolute burst limit (hard cap at 50)
+	if c.msgCount > RateLimitBurst {
+		if !c.rateLimited {
+			c.rateLimited = true
+			log.Printf("signal: rate limiting client conn=%d (burst exceeded)", c.connID)
+		}
+		return false
+	}
+
+	// Second check: per-second rate limit after initial burst window
+	// Only enforce if we're past the burst allowance (30) within the first second
+	if c.msgCount > MaxMessagesPerSecond && now.Sub(c.msgWindow) < time.Second {
+		if !c.rateLimited {
+			c.rateLimited = true
+			log.Printf("signal: rate limiting client conn=%d (rate exceeded)", c.connID)
+		}
+		return false
+	}
+
+	return true
+}
+
+// sendError sends an error message to the client.
+func (c *Client) sendError(err *ProtocolError) error {
+	_, room := c.identity()
+	return c.enqueue(Message{Type: MsgTypeError, Room: room, Code: err.Code, Error: err.Message})
+}
+
+// enqueue queues a message for sending to the client.
+func (c *Client) enqueue(msg Message) error {
+	select {
+	case <-c.closed:
+		return errClientClosed
+	default:
+	}
+
+	timer := time.NewTimer(SendTimeout)
+
+	select {
+	case <-c.closed:
+		timer.Stop()
+		return errClientClosed
+	case c.send <- msg:
+		// Drain timer to prevent resource leak
+		if !timer.Stop() {
+			select {
+			case <-timer.C:
+			default:
+			}
+		}
+		return nil
+	case <-timer.C:
+		return errors.New("send timeout")
+	}
+}
+
+// close closes the client's WebSocket connection.
+func (c *Client) close() {
+	c.closeOnce.Do(func() {
+		close(c.closed)
+		if c.conn == nil {
+			return
+		}
+		defer func() {
+			if r := recover(); r != nil {
+				log.Printf("signal: conn close panic conn=%d: %v", c.connID, r)
+			}
+		}()
+		_ = c.conn.Close()
+	})
+}
+
+// writePump handles sending messages to the WebSocket connection.
+func (c *Client) writePump() {
+	ticker := time.NewTicker(PingPeriod)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.closed:
+			return
+		case msg := <-c.send:
+			if err := c.conn.SetWriteDeadline(time.Now().Add(WriteWait)); err != nil {
+				log.Printf("signal: set write deadline failed conn=%d: %v", c.connID, err)
+				c.close()
+				return
+			}
+			if err := c.conn.WriteJSON(msg); err != nil {
+				id, room := c.identity()
+				log.Printf("signal: write message error room=%s id=%s conn=%d: %v", room, id, c.connID, err)
+				c.close()
+				return
+			}
+		case <-ticker.C:
+			if err := c.conn.SetWriteDeadline(time.Now().Add(WriteWait)); err != nil {
+				log.Printf("signal: set ping deadline failed conn=%d: %v", c.connID, err)
+				c.close()
+				return
+			}
+			if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+				id, room := c.identity()
+				log.Printf("signal: ping failed room=%s id=%s conn=%d: %v", room, id, c.connID, err)
+				c.close()
+				return
+			}
+		}
+	}
+}

internal/signal/errors.go

@@ -0,0 +1,39 @@
+package signal
+
+// ProtocolError 表示信令协议级别的错误，包含错误码和可读消息。
+// 错误码用于客户端程序化处理，消息用于人类阅读。
+type ProtocolError struct {
+	Code    string
+	Message string
+}
+
+func (e *ProtocolError) Error() string { return e.Message }
+
+// 信令协议错误定义
+// 这些错误码与 openspec/specs/signaling/spec.md 中定义的错误码保持同步。
+var (
+	// 客户端身份相关错误
+	ErrInvalidID      = &ProtocolError{Code: "invalid_id", Message: "invalid client id"}
+	ErrDuplicateID    = &ProtocolError{Code: "duplicate_id", Message: "client id already exists in room"}
+	ErrIdentityLocked = &ProtocolError{Code: "identity_locked", Message: "connection identity is immutable"}
+
+	// 房间相关错误
+	ErrInvalidRoom      = &ProtocolError{Code: "invalid_room", Message: "invalid room name"}
+	ErrRoomFull         = &ProtocolError{Code: "room_full", Message: "room is full"}
+	ErrRoomLimitReached = &ProtocolError{Code: "room_limit_reached", Message: "room limit reached"}
+	ErrRoomMissing      = &ProtocolError{Code: "room_missing", Message: "room no longer exists"}
+
+	// 加入相关错误
+	ErrInvalidJoin   = &ProtocolError{Code: "invalid_join", Message: "room and id are required"}
+	ErrAlreadyJoined = &ProtocolError{Code: "already_joined", Message: "leave the current room before joining another"}
+	ErrNotJoined     = &ProtocolError{Code: "not_joined", Message: "join a room first"}
+
+	// 消息路由相关错误
+	ErrInvalidTarget  = &ProtocolError{Code: "invalid_target", Message: "invalid target client"}
+	ErrTargetNotFound = &ProtocolError{Code: "target_not_found", Message: "target client is not in the room"}
+	ErrMembershipLost = &ProtocolError{Code: "membership_lost", Message: "client is no longer registered in room"}
+
+	// 消息处理相关错误
+	ErrUnknownType = &ProtocolError{Code: "unknown_type", Message: "unsupported message type"}
+	ErrRateLimited = &ProtocolError{Code: "rate_limited", Message: "too many messages, please slow down"}
+)