feat(chat): unread read-receipts with lobby/game dot and history-open ack

Persist per-message read state as a chat_messages.unread_seats bitmask
(migration 00008): a text message seeds every recipient seat's bit, a nudge
only the awaited seat's. A seat's bit clears when the player opens the move
history or chat (POST /games/:id/chat/read, sent only when something is
unread), and a nudge additionally clears when its recipient answers by moving
(a wired game NudgeClearer, dependency-inverted so game keeps off social).

UI shows a per-viewer unread dot in the lobby (next to the opponent) and the
game score bar — the unread_chat game-view flag seeds it from authoritative
REST views, live chat/nudge events raise it. Opening the move history counts
as reading (even without entering chat): the 💬 fade-blinks twice and the
client acks. Admin Messages gains an unread-only filter, a read/unread column,
and a per-message card with the per-seat read breakdown. Observability:
chat_read_duration histogram + chat_unread_messages gauge + social tracing.

backend/internal/server/handlers_admin_console.go

@@ -3,6 +3,7 @@ package server
 import (
 	"bytes"
 	"encoding/csv"
+	"errors"
 	"fmt"
 	"html/template"
 	"net/http"
@@ -82,6 +83,7 @@ func (s *Server) registerConsole(router *gin.Engine) {
 	}
 	gm.GET("/messages", s.consoleMessages)
 	gm.GET("/messages.csv", s.consoleMessagesCSV)
+	gm.GET("/messages/:id", s.consoleChatMessageDetail)
 	gm.GET("/dictionary", s.consoleDictionary)
 	gm.POST("/dictionary/upload", s.consoleUploadDictionary)
 	gm.POST("/dictionary/install", s.consoleInstallDictionary)
@@ -187,10 +189,11 @@ func (s *Server) consoleMessages(c *gin.Context) {
 	gameID, _ := uuid.Parse(strings.TrimSpace(c.Query("game")))
 	userID, _ := uuid.Parse(strings.TrimSpace(c.Query("user")))
 	filter := social.AdminMessageFilter{
-		GameID:   gameID,
-		SenderID: userID,
-		NameMask: c.Query("name"),
-		ExtMask:  c.Query("ext"),
+		GameID:     gameID,
+		SenderID:   userID,
+		NameMask:   c.Query("name"),
+		ExtMask:    c.Query("ext"),
+		UnreadOnly: c.Query("unread") == "1",
 	}
 	total, _ := s.social.AdminCountMessages(ctx, filter)
 	items, err := s.social.AdminListMessages(ctx, filter, adminPageSize, (page-1)*adminPageSize)
@@ -211,10 +214,14 @@ func (s *Server) consoleMessages(c *gin.Context) {
 	if strings.TrimSpace(filter.ExtMask) != "" {
 		q.Set("ext", filter.ExtMask)
 	}
+	if filter.UnreadOnly {
+		q.Set("unread", "1")
+	}
 	view := adminconsole.MessagesView{
 		Pager:       adminconsole.NewPager(page, adminPageSize, total),
 		NameMask:    filter.NameMask,
 		ExtMask:     filter.ExtMask,
+		UnreadOnly:  filter.UnreadOnly,
 		FilterQuery: template.URL(q.Encode()),
 	}
 	if filter.GameID != uuid.Nil {
@@ -227,12 +234,41 @@ func (s *Server) consoleMessages(c *gin.Context) {
 		view.Items = append(view.Items, adminconsole.MessageRow{
 			ID: m.ID.String(), SenderID: m.SenderID.String(), SenderName: m.SenderName,
 			Source: m.Source, IP: m.SenderIP, Body: m.Body,
-			GameID: m.GameID.String(), CreatedAt: fmtTime(m.CreatedAt),
+			GameID: m.GameID.String(), CreatedAt: fmtTime(m.CreatedAt), Unread: m.UnreadSeats != 0,
 		})
 	}
 	s.renderConsole(c, "messages", "messages", "Messages", view)
 }
 
+// consoleChatMessageDetail renders one chat message with the per-seat read breakdown of
+// its game (who has read it, who has not).
+func (s *Server) consoleChatMessageDetail(c *gin.Context) {
+	id, ok := s.consoleUUID(c, "/_gm/messages")
+	if !ok {
+		return
+	}
+	card, err := s.social.AdminMessageDetail(c.Request.Context(), id)
+	if err != nil {
+		if errors.Is(err, social.ErrMessageNotFound) {
+			s.renderConsoleMessage(c, "Not found", "no such message", "/_gm/messages")
+			return
+		}
+		s.consoleError(c, err)
+		return
+	}
+	view := adminconsole.ChatMessageDetailView{
+		ID: card.ID.String(), GameID: card.GameID.String(), SenderID: card.SenderID.String(),
+		SenderName: card.SenderName, Source: card.Source, Kind: card.Kind, Body: card.Body,
+		IP: card.SenderIP, CreatedAt: fmtTime(card.CreatedAt), Unread: card.UnreadSeats != 0,
+	}
+	for _, st := range card.Seats {
+		view.Seats = append(view.Seats, adminconsole.ChatSeatStatusRow{
+			Seat: st.Seat, AccountID: st.AccountID.String(), DisplayName: st.DisplayName, Role: st.Role,
+		})
+	}
+	s.renderConsole(c, "chatmessage", "messages", "Message", view)
+}
+
 // adminMessagesExportCap bounds the CSV export row count (the moderated chat volume is small).
 const adminMessagesExportCap = 100000
 
@@ -243,10 +279,11 @@ func (s *Server) consoleMessagesCSV(c *gin.Context) {
 	gameID, _ := uuid.Parse(strings.TrimSpace(c.Query("game")))
 	userID, _ := uuid.Parse(strings.TrimSpace(c.Query("user")))
 	filter := social.AdminMessageFilter{
-		GameID:   gameID,
-		SenderID: userID,
-		NameMask: c.Query("name"),
-		ExtMask:  c.Query("ext"),
+		GameID:     gameID,
+		SenderID:   userID,
+		NameMask:   c.Query("name"),
+		ExtMask:    c.Query("ext"),
+		UnreadOnly: c.Query("unread") == "1",
 	}
 	items, err := s.social.AdminListMessages(ctx, filter, adminMessagesExportCap, 0)
 	if err != nil {
@@ -256,12 +293,16 @@ func (s *Server) consoleMessagesCSV(c *gin.Context) {
 	c.Header("Content-Type", "text/csv; charset=utf-8")
 	c.Header("Content-Disposition", `attachment; filename="messages.csv"`)
 	w := csv.NewWriter(c.Writer)
-	_ = w.Write([]string{"time", "source", "sender_id", "sender", "ip", "message", "game_id"})
+	_ = w.Write([]string{"time", "source", "sender_id", "sender", "ip", "message", "game_id", "read"})
 	for _, m := range items {
+		read := "read"
+		if m.UnreadSeats != 0 {
+			read = "unread"
+		}
 		// The sender name and message body are user-controlled; defuse spreadsheet formula
 		// injection so a moderator opening the export can't trigger a formula.
 		_ = w.Write([]string{
-			fmtTime(m.CreatedAt), m.Source, m.SenderID.String(), csvSafe(m.SenderName), csvSafe(m.SenderIP), csvSafe(m.Body), m.GameID.String(),
+			fmtTime(m.CreatedAt), m.Source, m.SenderID.String(), csvSafe(m.SenderName), csvSafe(m.SenderIP), csvSafe(m.Body), m.GameID.String(), read,
 		})
 	}
 	w.Flush()