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.

ui/src/lib/app.svelte.ts

@@ -61,8 +61,10 @@ export const app = $state<{
   localeLocked: boolean;
   /** Pending incoming friend requests, for the lobby ⚙️ badge and the Settings Friends tab. */
   notifications: number;
-  /** Unread chat-message count per game id, for the in-game score-bar and 💬 badges. */
-  chatUnread: Record<string, number>;
+  /** Per-game flag: the player has at least one unread chat entry (message or nudge) in that
+   *  game, for the lobby and in-game unread dot. Seeded from the authoritative REST views and
+   *  raised by live chat/nudge events; cleared (with a backend ack) on opening the history/chat. */
+  chatUnread: Record<string, boolean>;
   /** Whether an operator feedback reply awaits the player, for the lobby ⚙️ badge (combined
    *  with friend requests) and the Settings → Info badge. */
   feedbackReplyUnread: boolean;
@@ -149,9 +151,29 @@ export function dismissStaleInvite(): void {
   app.staleInvite = false;
 }
 
-/** clearChatUnread resets a game's unread chat-message count (called when its chat is opened). */
-export function clearChatUnread(gameId: string): void {
-  if (app.chatUnread[gameId]) app.chatUnread = { ...app.chatUnread, [gameId]: 0 };
+/**
+ * seedChatUnread sets a game's unread flag from an authoritative per-viewer REST view (the lobby
+ * list, a game's state, or a move result). The live-event GameView omits the flag, so the live
+ * stream raises unread (bumpChatUnread) rather than seeding it from a GameView.
+ */
+export function seedChatUnread(gameId: string, unread: boolean): void {
+  if ((app.chatUnread[gameId] ?? false) !== unread) {
+    app.chatUnread = { ...app.chatUnread, [gameId]: unread };
+  }
+}
+
+/**
+ * markChatRead clears a game's unread badge and tells the backend the player has read the chat —
+ * called when the move history or the chat opens. It hits the backend only when something is
+ * actually unread, so opening the history does not call the backend on every tap. The clear is
+ * optimistic; a failed ack restores the badge so a later open retries.
+ */
+export function markChatRead(gameId: string): void {
+  if (!app.chatUnread[gameId]) return;
+  app.chatUnread = { ...app.chatUnread, [gameId]: false };
+  void gateway.markChatRead(gameId).catch(() => {
+    app.chatUnread = { ...app.chatUnread, [gameId]: true };
+  });
 }
 
 /** handleError maps a GatewayError to a toast; an invalid session logs out. A connectivity
@@ -220,15 +242,18 @@ function openStream(): void {
           (router.route.name === 'gameChat' || router.route.name === 'gameCheck') &&
           router.route.params.id === e.message.gameId;
         if (!inComms) {
-          if (e.message.kind !== 'nudge') {
-            const gid = e.message.gameId;
-            app.chatUnread = { ...app.chatUnread, [gid]: (app.chatUnread[gid] ?? 0) + 1 };
-          }
+          app.chatUnread = { ...app.chatUnread, [e.message.gameId]: true };
           showToast(e.message.kind === 'nudge' ? t('chat.nudge') : e.message.body, 'info');
         }
       } else if (e.kind === 'nudge') {
-        // Name the nudger (their per-game seat name, carried on the event), so the toast reads
-        // "<opponent>: …" like the your-turn toast; fall back to the plain phrase when absent.
+        // A nudge only reaches the awaited player; raise their unread badge for the game (unless
+        // they are already in its chat), then toast — naming the nudger (their per-game seat name,
+        // carried on the event), so it reads "<opponent>: …" like the your-turn toast; fall back to
+        // the plain phrase when absent.
+        const inComms =
+          (router.route.name === 'gameChat' || router.route.name === 'gameCheck') &&
+          router.route.params.id === e.gameId;
+        if (!inComms) app.chatUnread = { ...app.chatUnread, [e.gameId]: true };
         showToast(e.senderName ? t('chat.nudgeBy', { name: e.senderName }) : t('chat.nudge'), 'info');
       } else if (e.kind === 'your_turn') {
         // Name the player who moved just before this one (the previous seat in turn order), so the

ui/src/lib/client.ts

@@ -102,6 +102,9 @@ export interface GatewayClient {
   chatPost(gameId: string, body: string): Promise<ChatMessage>;
   chatList(gameId: string): Promise<ChatMessage[]>;
   nudge(gameId: string): Promise<ChatMessage>;
+  /** Acknowledge the caller has read the game's chat (sent when they open the move history
+   *  or chat), so the backend clears their unread bits and records the read latency. */
+  markChatRead(gameId: string): Promise<void>;
 
   // --- feedback ---
   /** feedbackSubmit sends a feedback message with an optional single attachment. */

ui/src/lib/codec.test.ts

@@ -237,6 +237,7 @@ describe('codec', () => {
     fb.GameView.addSeats(b, seats);
     fb.GameView.addLastActivityUnix(b, BigInt(1717000000));
     fb.GameView.addVsAi(b, true);
+    fb.GameView.addUnreadChat(b, true);
     const game = fb.GameView.endGameView(b);
     const games = fb.GameList.createGamesVector(b, [game]);
     fb.GameList.startGameList(b);
@@ -251,6 +252,7 @@ describe('codec', () => {
     expect(gl.games[0].seats[0].score).toBe(13);
     expect(gl.games[0].lastActivityUnix).toBe(1717000000);
     expect(gl.games[0].vsAi).toBe(true);
+    expect(gl.games[0].unreadChat).toBe(true);
     expect(gl.atGameLimit).toBe(true);
   });
 

ui/src/lib/codec.ts

@@ -248,6 +248,7 @@ function decodeGameView(g: fb.GameView): GameView {
     endReason: s(g.endReason()),
     lastActivityUnix: Number(g.lastActivityUnix()),
     vsAi: g.vsAi(),
+    unreadChat: g.unreadChat(),
     seats,
   };
 }
@@ -813,6 +814,7 @@ function emptyGame(): GameView {
     endReason: '',
     lastActivityUnix: 0,
     vsAi: false,
+    unreadChat: false,
     seats: [],
   };
 }

ui/src/lib/gamecache.test.ts

@@ -8,6 +8,7 @@ function gameView(id: string): GameView {
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status: 'active',
     players: 2,
     toMove: 0,

ui/src/lib/gamedelta.test.ts

@@ -9,6 +9,7 @@ function gameView(moveCount: number, over = false): GameView {
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status: over ? 'finished' : 'active',
     players: 2,
     toMove: 1,

ui/src/lib/lobbycache.test.ts

@@ -25,6 +25,7 @@ function gameView(id: string, status: GameView['status'] = 'active', toMove = 0)
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status,
     players: 2,
     toMove,

ui/src/lib/lobbysort.test.ts

@@ -18,6 +18,7 @@ function game(id: string, status: GameView['status'], toMove: number, lastActivi
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status,
     players: 2,
     toMove,

ui/src/lib/mock/client.ts

@@ -180,6 +180,7 @@ export class MockGateway implements GatewayClient {
           endReason: '',
           lastActivityUnix: Math.floor(Date.now() / 1000),
           vsAi: true,
+          unreadChat: false,
           seats: [
             { seat: 0, accountId: ME, displayName: 'You', score: 0, hintsUsed: 0, isWinner: false },
             { seat: 1, accountId: 'robot', displayName: 'Robot', score: 0, hintsUsed: 0, isWinner: false },
@@ -211,6 +212,7 @@ export class MockGateway implements GatewayClient {
         endReason: '',
         lastActivityUnix: Math.floor(Date.now() / 1000),
         vsAi: false,
+        unreadChat: false,
         seats: [
           { seat: 0, accountId: ME, displayName: 'You', score: 0, hintsUsed: 0, isWinner: false },
           { seat: 1, accountId: '', displayName: '', score: 0, hintsUsed: 0, isWinner: false },
@@ -487,6 +489,10 @@ export class MockGateway implements GatewayClient {
     this.feedbackReplyUnread = true;
     this.emit({ kind: 'notify', sub: 'admin_reply' });
   }
+  // The mock holds no server-side unread state; the read ack is a no-op (the client clears its
+  // own unread flag optimistically).
+  async markChatRead(): Promise<void> {}
+
   async nudge(gameId: string): Promise<ChatMessage> {
     const g = this.game(gameId);
     const msg: ChatMessage = {

ui/src/lib/mock/data.ts

@@ -140,6 +140,7 @@ function activeGame(): MockGame {
       variant: 'scrabble_en',
       dictVersion: 'v1',
       vsAi: false,
+      unreadChat: false,
       status: 'active',
       players: 2,
       toMove: 0,
@@ -176,6 +177,7 @@ function finishedG2(): MockGame {
       variant: 'scrabble_en',
       dictVersion: 'v1',
       vsAi: false,
+      unreadChat: false,
       status: 'finished',
       players: 2,
       toMove: 0,
@@ -213,6 +215,7 @@ function finishedG3(): MockGame {
       variant: 'scrabble_ru',
       dictVersion: 'v1',
       vsAi: false,
+      unreadChat: false,
       status: 'finished',
       players: 2,
       toMove: 0,

ui/src/lib/model.ts

@@ -47,6 +47,10 @@ export interface GameView {
   lastActivityUnix: number;
   /** true = an honest-AI game: the opponent is shown as 🤖 and chat/nudge/add-friend are disabled. */
   vsAi: boolean;
+  /** Per-viewer flag: the requesting player has at least one unread chat entry (message or
+   *  nudge) in this game. Set on the authoritative REST views (lobby list, game state,
+   *  move result); the live-event GameView leaves it false (events bump unread instead). */
+  unreadChat: boolean;
   seats: Seat[];
 }
 

ui/src/lib/preload.test.ts

@@ -20,6 +20,7 @@ function gameView(id: string, status: GameView['status'] = 'active'): GameView {
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status,
     players: 2,
     toMove: 0,

ui/src/lib/result.test.ts

@@ -17,6 +17,7 @@ function game(seats: Seat[], status = 'finished', toMove = 0): GameView {
     variant: 'scrabble_en',
     dictVersion: 'v1',
     vsAi: false,
+    unreadChat: false,
     status,
     players: seats.length,
     toMove,

ui/src/lib/transport.ts

@@ -143,6 +143,9 @@ export function createTransport(baseUrl: string): GatewayClient {
     async nudge(id) {
       return codec.decodeChatMessage(await exec('chat.nudge', codec.encodeGameAction(id)));
     },
+    async markChatRead(id) {
+      await exec('chat.read', codec.encodeGameAction(id));
+    },
     async feedbackSubmit(body, attachment, attachmentName, channel) {
       await exec('feedback.submit', codec.encodeFeedbackSubmit(body, attachment, attachmentName, channel));
     },