feat(messages): stream history one-message-per-WS-frame instead of 50-row batch

- backend: add streamMany generator (paginated, yields one record at a time)
  + messagesService.streamMessages + WS 'stream_messages' handler emitting
  'message_snapshot' per message, 'message_snapshot_end' with nextCursor
- frontend: useMessagesStream hook accumulates snapshots into SWR list,
  SSR getMessages seeds first paint, WsHook gains sendText
- add stream-many.test.ts locking the one-at-a-time + cursor contract

services/backend/src/modules/messages/messages.repository.ts

@@ -172,6 +172,71 @@ export class MessagesRepository {
     return { data, nextCursor };
   }
 
+  /**
+   * Async generator that yields messages ONE AT A TIME for WS streaming.
+   * Each `.next()` runs its own bounded DB query (limit+1) advancing on the
+   * `created_at` cursor, so memory stays flat and the caller can emit one WS
+   * frame per message (no 50-row batch). Stops when a page returns < limit.
+   */
+  async *streamMany(
+    query: MessageQuery,
+    pageSize = 50,
+  ): AsyncGenerator<ReturnType<typeof mapMessageRow>, void, unknown> {
+    const conditions: SQL[] = [];
+
+    if (query.guildId) {
+      conditions.push(eq(pgMessagesTable.guild_id, query.guildId));
+    }
+    if (query.channelId) {
+      conditions.push(eq(pgMessagesTable.channel_id, query.channelId));
+    }
+    if (query.userId) {
+      conditions.push(eq(pgMessagesTable.user_id, query.userId));
+    }
+    if (query.status) {
+      conditions.push(eq(pgMessagesTable.ai_status, query.status));
+    }
+    if (EXCLUDED_THREAD_IDS.length > 0) {
+      const excludeThreads = or(
+        isNull(pgMessagesTable.thread_id),
+        notInArray(pgMessagesTable.thread_id, EXCLUDED_THREAD_IDS),
+      );
+      if (excludeThreads) conditions.push(excludeThreads);
+    }
+
+    const where = conditions.length > 0 ? and(...conditions) : undefined;
+    let cursor: string | undefined = query.cursor;
+
+    while (true) {
+      const pageConditions = where ? [where] : [];
+      if (cursor) {
+        pageConditions.push(lt(pgMessagesTable.created_at, Number(cursor)));
+      }
+      const pageWhere =
+        pageConditions.length > 0 ? and(...pageConditions) : undefined;
+
+      const db = getDatabase();
+      const rows = await db
+        .select()
+        .from(pgMessagesTable)
+        .where(pageWhere)
+        .orderBy(desc(pgMessagesTable.created_at))
+        .limit(pageSize + 1);
+
+      if (rows.length === 0) return;
+
+      const hasMore = rows.length > pageSize;
+      const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+
+      for (const r of pageRows) {
+        yield mapMessageRow(r as Record<string, unknown>);
+      }
+
+      if (!hasMore) return;
+      cursor = String(rows[pageSize - 1].created_at);
+    }
+  }
+
   async create(data: MessageCreate) {
     const db = getDatabase();
     const id = crypto.randomUUID();

services/backend/src/modules/messages/messages.service.ts

@@ -15,6 +15,14 @@ export class MessagesService {
     return messagesRepository.findMany(query);
   }
 
+  /**
+   * Stream messages one at a time (no 50-row batch). The WS handler iterates
+   * this generator and emits one `message_snapshot` frame per message.
+   */
+  streamMessages(query: MessageQuery, pageSize = 50) {
+    return messagesRepository.streamMany(query, pageSize);
+  }
+
   async getMessagesByChannel(channelId: string, query: MessageQuery) {
     if (!channelId) {
       throw new ValidationError("channelId is required");

services/backend/src/ws/server.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, Server } from "node:http";
 import type { Duplex } from "node:stream";
 import { WebSocket, WebSocketServer } from "ws";
+import { messagesService } from "../modules/messages/messages.service.js";
 import { config } from "../shared/config/index.js";
 import { BACKEND_COMMAND, BACKEND_VOICE_TRANSMIT } from "../shared/index.js";
 import { createChildLogger } from "../shared/logger/index.js";
@@ -140,6 +141,73 @@ export function createWebSocketServer(server: Server): WebSocketServer {
     );
   });
 
+  // Stream historical messages one-by-one over WS (no 50-row batch).
+  // The frontend requests it once per channel switch; the backend emits one
+  // `message_snapshot` frame per message so the UI renders progressively.
+  jsonHandlers.set("stream_messages", async (ws, message) => {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    const payload = (message.payload ?? {}) as {
+      guildId?: string;
+      channelId?: string;
+      cursor?: string;
+      limit?: number;
+    };
+    const guildId = payload.guildId;
+    const channelId = payload.channelId;
+    if (!guildId && !channelId) {
+      logger.warn({ payload }, "stream_messages requires guildId or channelId");
+      return;
+    }
+
+    const pageSize = 50; // internal DB page size; still emitted one frame at a time
+    const maxFrames = Math.min(payload.limit ?? 200, 500);
+
+    let sent = 0;
+    let nextCursor: string | null = null;
+    try {
+      for await (const msg of messagesService.streamMessages(
+        {
+          guildId,
+          channelId,
+          cursor: payload.cursor,
+        } as never,
+        pageSize,
+      )) {
+        if (ws.readyState !== WebSocket.OPEN) break;
+        // Streamed DESC (newest first); the oldest emitted carries the smallest
+        // created_at, which is exactly the next-page cursor for "load older".
+        const createdAt = (msg as { created_at?: number }).created_at;
+        if (createdAt !== undefined) nextCursor = String(createdAt);
+        ws.send(
+          JSON.stringify({
+            type: "message_snapshot",
+            data: msg,
+          }),
+        );
+        sent++;
+        if (sent >= maxFrames) break;
+      }
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            type: "message_snapshot_end",
+            data: { sent, nextCursor },
+          }),
+        );
+      }
+    } catch (err) {
+      logger.error({ err }, "stream_messages failed");
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            type: "message_snapshot_end",
+            data: { sent, nextCursor, error: true },
+          }),
+        );
+      }
+    }
+  });
+
   wss.on("connection", (ws: WebSocket, req) => {
     // Parse auth token from query string
     const rawUrl = req.url ?? "/";

services/backend/tests/stream-many.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+
+/**
+ * Lock the contract that the WS `stream_messages` handler + frontend
+ * `useMessagesStream` depend on.
+ *
+ * Real behavior (src/modules/messages/messages.repository.ts → streamMany, and
+ * src/ws/server.ts stream_messages handler):
+ *  - ONE `stream_messages` request streams the WHOLE history for the scope,
+ *    internally paging `limit+1` at a time (cursor = oldest created_at of the
+ *    page) until exhausted or maxFrames is hit.
+ *  - Messages are emitted ONE AT A TIME, DESC (newest first).
+ *  - The final `message_snapshot_end` carries `nextCursor` = the OLDEST emitted
+ *    row's `created_at`, so the FE's next "load older" request pages forward.
+ *
+ * We replicate streamMany's pagination algorithm over an in-memory array so the
+ * test needs no DB.
+ */
+
+type Row = { id: string; created_at: number; guild_id: string };
+
+function makeStream(
+  rows: Row[],
+  query: { guildId?: string; channelId?: string; cursor?: string },
+  pageSize = 50,
+): () => Generator<Row, void, unknown> {
+  return function* () {
+    let cursor = query.cursor;
+    while (true) {
+      const page = rows
+        .filter((r) => (query.guildId ? r.guild_id === query.guildId : true))
+        .filter((r) => (cursor ? r.created_at < Number(cursor) : true))
+        .sort((a, b) => b.created_at - a.created_at)
+        .slice(0, pageSize + 1);
+
+      if (page.length === 0) return;
+      const hasMore = page.length > pageSize;
+      const pageRows = hasMore ? page.slice(0, pageSize) : page;
+      for (const r of pageRows) yield r;
+      if (!hasMore) return;
+      cursor = String(page[pageSize - 1].created_at);
+    }
+  };
+}
+
+function streamAll(
+  rows: Row[],
+  query: { guildId?: string; channelId?: string; cursor?: string },
+  pageSize = 50,
+  maxFrames = Infinity,
+): { data: Row[]; nextCursor: string | null } {
+  const data: Row[] = [];
+  let nextCursor: string | null = null;
+  for (const r of makeStream(rows, query, pageSize)()) {
+    nextCursor = String(r.created_at);
+    data.push(r);
+    if (data.length >= maxFrames) break;
+  }
+  return { data, nextCursor };
+}
+
+const mk = (id: string, created_at: number, guild_id = "g1"): Row => ({
+  id,
+  created_at,
+  guild_id,
+});
+
+describe("messages.streamMany contract", () => {
+  it("emits newest-first and sets nextCursor to oldest created_at", () => {
+    const rows = [mk("a", 300), mk("b", 200), mk("c", 100)];
+    const { data, nextCursor } = streamAll(rows, { guildId: "g1" });
+    expect(data.map((r) => r.id)).toEqual(["a", "b", "c"]);
+    expect(nextCursor).toBe("100"); // oldest emitted
+  });
+
+  it("streams the entire history in one request, one frame at a time", () => {
+    // 120 rows; one request must yield all 120 (no 50-row batch boundary).
+    const rows = Array.from({ length: 120 }, (_, i) => mk(`m${i}`, 1000 - i));
+    const { data, nextCursor } = streamAll(rows, { guildId: "g1" }, 50);
+    expect(data).toHaveLength(120);
+    expect(data[0].id).toBe("m0"); // newest first
+    expect(nextCursor).toBe("881"); // oldest = m119 (1000-119)
+  });
+
+  it("honors a frame cap and leaves nextCursor mid-history", () => {
+    const rows = Array.from({ length: 120 }, (_, i) => mk(`m${i}`, 1000 - i));
+    const { data, nextCursor } = streamAll(rows, { guildId: "g1" }, 50, 60);
+    expect(data).toHaveLength(60);
+    // nextCursor = 60th oldest = m59 (1000-59=941)
+    expect(nextCursor).toBe("941");
+  });
+
+  it("paginates correctly across subsequent load-older requests", () => {
+    const rows = Array.from({ length: 120 }, (_, i) => mk(`m${i}`, 1000 - i));
+    const first = streamAll(rows, { guildId: "g1" }, 50, 50);
+    expect(first.data).toHaveLength(50);
+    expect(first.nextCursor).toBe("951"); // 50th oldest = m49
+
+    const older = streamAll(
+      rows,
+      { guildId: "g1", cursor: first.nextCursor ?? undefined },
+      50,
+      50,
+    );
+    expect(older.data[0].id).toBe("m50"); // continues right after m49
+    expect(older.nextCursor).toBe("901"); // 100th oldest
+  });
+
+  it("filters by guild", () => {
+    const rows = [mk("x", 500, "g1"), mk("y", 400, "g2")];
+    const { data } = streamAll(rows, { guildId: "g2" });
+    expect(data.map((r) => r.id)).toEqual(["y"]);
+  });
+});