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/dto.go

@@ -108,6 +108,10 @@ type gameDTO struct {
 	// game, the finish time once finished.
 	LastActivityUnix int64     `json:"last_activity_unix"`
 	Seats            []seatDTO `json:"seats"`
+	// UnreadChat is a per-viewer flag: the requesting player has at least one unread chat
+	// entry (message or nudge) in this game. It seeds the lobby and in-game unread badge.
+	// gameDTOFromGame leaves it false (it has no viewer); the handlers fill it.
+	UnreadChat bool `json:"unread_chat"`
 }
 
 // moveResultDTO is the outcome of a committed move. Rack carries the actor's refilled rack as

backend/internal/server/handlers.go

@@ -96,6 +96,7 @@ func (s *Server) registerRoutes() {
 	if s.social != nil {
 		u.POST("/games/:id/chat", s.handleChatPost)
 		u.GET("/games/:id/chat", s.handleChatList)
+		u.POST("/games/:id/chat/read", s.handleChatRead)
 		u.POST("/games/:id/nudge", s.handleNudge)
 		u.GET("/friends", s.handleListFriends)
 		u.GET("/friends/incoming", s.handleIncomingRequests)

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()

backend/internal/server/handlers_game.go

@@ -439,10 +439,16 @@ func (s *Server) handleListGames(c *gin.Context) {
 		return
 	}
 	memo := map[string]string{}
+	// One query seeds the lobby's per-card unread badge for every listed game.
+	var unread map[uuid.UUID]bool
+	if s.social != nil {
+		unread, _ = s.social.UnreadGames(c.Request.Context(), uid)
+	}
 	out := make([]gameDTO, 0, len(games))
 	for _, g := range games {
 		dto := gameDTOFromGame(g)
 		s.fillSeatNames(c.Request.Context(), &dto, memo)
+		dto.UnreadChat = unread[g.ID]
 		out = append(out, dto)
 	}
 	c.JSON(http.StatusOK, gameListDTO{Games: out, AtGameLimit: atLimit})
@@ -480,6 +486,22 @@ func (s *Server) handleNudge(c *gin.Context) {
 	c.JSON(http.StatusOK, chatDTOFrom(msg))
 }
 
+// handleChatRead marks every chat entry the caller has not yet read in the game as read
+// — the acknowledgement the client sends when the player opens the move history or chat
+// — and records each entry's publish-to-read latency. The client calls it only when it
+// believes something is unread, so the backend is not hit on every history open.
+func (s *Server) handleChatRead(c *gin.Context) {
+	uid, gameID, ok := s.userGame(c)
+	if !ok {
+		return
+	}
+	if _, err := s.social.MarkRead(c.Request.Context(), gameID, uid); err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, okResponse{OK: true})
+}
+
 // userGame reads the authenticated account and the :id game param, aborting with the
 // right status when either is missing. ok is false when the request was aborted.
 func (s *Server) userGame(c *gin.Context) (uuid.UUID, uuid.UUID, bool) {
@@ -504,5 +526,24 @@ func (s *Server) writeMoveResult(c *gin.Context, res game.MoveResult) {
 		return
 	}
 	s.fillSeatNames(c.Request.Context(), &dto.Game, map[string]string{})
+	if uid, ok := userID(c); ok {
+		s.setUnreadChat(c.Request.Context(), &dto.Game, uid)
+	}
 	c.JSON(http.StatusOK, dto)
 }
+
+// setUnreadChat fills the per-game unread-chat flag for viewer uid on one game's DTO,
+// when the social domain is present. It is best-effort: a lookup error leaves the flag
+// false (a missing badge) rather than failing the surrounding game response.
+func (s *Server) setUnreadChat(ctx context.Context, g *gameDTO, uid uuid.UUID) {
+	if s.social == nil {
+		return
+	}
+	gid, err := uuid.Parse(g.ID)
+	if err != nil {
+		return
+	}
+	if unread, err := s.social.HasUnread(ctx, gid, uid); err == nil {
+		g.UnreadChat = unread
+	}
+}

backend/internal/server/handlers_user.go

@@ -130,6 +130,7 @@ func (s *Server) handleGameState(c *gin.Context) {
 		return
 	}
 	s.fillSeatNames(c.Request.Context(), &dto.Game, map[string]string{})
+	s.setUnreadChat(c.Request.Context(), &dto.Game, uid)
 	c.JSON(http.StatusOK, dto)
 }