Stage 17 round 6 (#4/#5/#6): draft persistence wire + gateway + UI

Complete the client-side draft feature on top of the shipped backend
foundation (the game_drafts store/service):

- FB: DraftRequest{game_id,json} + DraftView{json} (a draft get reuses
  GameActionRequest); regenerated committed Go + TS bindings.
- Backend REST: GET/PUT /games/:id/draft, a draftDTO
  (rack_order/board_tiles) mapped to game.Draft.
- Gateway: draft.get/draft.save transcode forwarding the composition
  JSON verbatim (json.RawMessage both ways -- no double-encode).
- UI: debounced save of the rack order + board tiles and restore on
  load (lib/draft.ts), plus #5 -- tiles may be arranged on the
  opponent's turn (placement relaxed; the preview and Make-move stay
  your-turn-only, so an off-turn draft is position-only).

Tests: backend handler validation, gateway pass-through round-trip, UI
draft/codec units, and a draft-restore e2e.

ui/src/lib/client.ts

@@ -83,6 +83,13 @@ export interface GatewayClient {
   checkWord(gameId: string, word: string, variant: Variant): Promise<WordCheckResult>;
   complaint(gameId: string, word: string, note: string): Promise<void>;
 
+  // --- draft (Stage 17) ---
+  /** The player's server-persisted client-side composition (rack order + board tiles), so a
+   *  reload or a second device resumes the same arrangement. The JSON is opaque to the
+   *  gateway; the client owns the {rack_order, board_tiles} shape. */
+  draftGet(gameId: string): Promise<string>;
+  draftSave(gameId: string, json: string): Promise<void>;
+
   // --- chat ---
   chatPost(gameId: string, body: string): Promise<ChatMessage>;
   chatList(gameId: string): Promise<ChatMessage[]>;

ui/src/lib/codec.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import * as fb from '../gen/fbs/scrabblefb';
 import { BLANK_INDEX, setAlphabet } from './alphabet';
 import {
+  decodeDraftView,
   decodeFriendList,
   decodeGameList,
   decodeInvitation,
@@ -11,6 +12,7 @@ import {
   decodeStateView,
   decodeStats,
   encodeCheckWord,
+  encodeDraftSave,
   encodeExchange,
   encodeStateRequest,
   encodeSubmitPlay,
@@ -18,6 +20,20 @@ import {
 } from './codec';
 
 describe('codec', () => {
+  it('round-trips a draft save request and view (Stage 17)', () => {
+    const json = '{"rack_order":"1,0","board_tiles":[]}';
+    const req = fb.DraftRequest.getRootAsDraftRequest(new ByteBuffer(encodeDraftSave('g1', json)));
+    expect(req.gameId()).toBe('g1');
+    expect(req.json()).toBe(json);
+
+    const b = new Builder(64);
+    const j = b.createString('{"x":1}');
+    fb.DraftView.startDraftView(b);
+    fb.DraftView.addJson(b, j);
+    b.finish(fb.DraftView.endDraftView(b));
+    expect(decodeDraftView(b.asUint8Array())).toBe('{"x":1}');
+  });
+
   it('encodes a SubmitPlayRequest with alphabet indices (Stage 13)', () => {
     setAlphabet('english', [
       { index: 0, letter: 'a', value: 1 },

ui/src/lib/codec.ts

@@ -73,6 +73,18 @@ export function encodeStateRequest(gameId: string, includeAlphabet: boolean): Ui
   return finish(b, fb.StateRequest.endStateRequest(b));
 }
 
+// encodeDraftSave wraps the player's composition JSON (Stage 17). The string is opaque on the
+// wire — the gateway forwards it verbatim and only the client reads {rack_order, board_tiles}.
+export function encodeDraftSave(gameId: string, json: string): Uint8Array {
+  const b = new Builder(256);
+  const gid = b.createString(gameId);
+  const j = b.createString(json);
+  fb.DraftRequest.startDraftRequest(b);
+  fb.DraftRequest.addGameId(b, gid);
+  fb.DraftRequest.addJson(b, j);
+  return finish(b, fb.DraftRequest.endDraftRequest(b));
+}
+
 export function encodeSubmitPlay(
   gameId: string,
   dir: 'H' | 'V',
@@ -359,6 +371,13 @@ export function decodeWordCheck(buf: Uint8Array): WordCheckResult {
   return { word: s(r.word()), legal: r.legal() };
 }
 
+// decodeDraftView returns the player's stored composition JSON (empty when none is stored or
+// for the save acknowledgement); the caller parses {rack_order, board_tiles}.
+export function decodeDraftView(buf: Uint8Array): string {
+  const v = fb.DraftView.getRootAsDraftView(new ByteBuffer(buf));
+  return v.json() ?? '';
+}
+
 export function decodeHistory(buf: Uint8Array): History {
   const h = fb.History.getRootAsHistory(new ByteBuffer(buf));
   const moves: MoveRecord[] = [];

ui/src/lib/draft.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { liveDraftTiles, parseDraft, serializeDraft, validRackOrder } from './draft';
+import type { PendingTile } from './placement';
+
+describe('draft', () => {
+  it('round-trips the rack order and board tiles', () => {
+    const pending: PendingTile[] = [
+      { rackIndex: 2, row: 7, col: 7, letter: 'Q', blank: false },
+      { rackIndex: 0, row: 7, col: 8, letter: 'I', blank: true },
+    ];
+    const parsed = parseDraft(serializeDraft([3, 0, 1, 2], pending));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.rackOrder).toEqual([3, 0, 1, 2]);
+    expect(parsed!.tiles).toEqual([
+      { row: 7, col: 7, letter: 'Q', blank: false },
+      { row: 7, col: 8, letter: 'I', blank: true },
+    ]);
+  });
+
+  it('parses an empty or malformed draft as null', () => {
+    expect(parseDraft('')).toBeNull();
+    expect(parseDraft('not json')).toBeNull();
+  });
+
+  it('parses a draft with no rack order or tiles', () => {
+    expect(parseDraft(JSON.stringify({ rack_order: '', board_tiles: [] }))).toEqual({ rackOrder: [], tiles: [] });
+  });
+
+  it('accepts a valid rack permutation and rejects a stale one', () => {
+    expect(validRackOrder([2, 0, 1], 3)).toEqual([2, 0, 1]);
+    expect(validRackOrder([0, 1], 3)).toBeNull(); // wrong length (the rack changed)
+    expect(validRackOrder([0, 0, 1], 3)).toBeNull(); // a duplicate, not a permutation
+    expect(validRackOrder([0, 1, 3], 3)).toBeNull(); // an index out of range
+  });
+
+  it('drops draft tiles whose cell is now occupied', () => {
+    const tiles = [
+      { row: 7, col: 7, letter: 'A', blank: false },
+      { row: 7, col: 8, letter: 'B', blank: false },
+    ];
+    expect(liveDraftTiles(tiles, (r, c) => r === 7 && c === 7)).toEqual([
+      { row: 7, col: 8, letter: 'B', blank: false },
+    ]);
+  });
+});

ui/src/lib/draft.ts

@@ -0,0 +1,59 @@
+// Draft (client-side composition) serialization, kept pure for unit tests. The server stores
+// the JSON opaquely (Stage 17); only the client interprets {rack_order, board_tiles}. The rack
+// order is a comma-joined permutation of the server rack's indices, in the player's visual
+// order; the board tiles are the tiles laid but not yet submitted.
+
+import type { Tile } from './model';
+import type { PendingTile } from './placement';
+
+interface DraftData {
+  rack_order: string;
+  board_tiles: Tile[];
+}
+
+/** serializeDraft builds the JSON to persist: the rack order and the pending board tiles. */
+export function serializeDraft(rackOrder: number[], pending: PendingTile[]): string {
+  const data: DraftData = {
+    rack_order: rackOrder.join(','),
+    board_tiles: pending.map((p) => ({ row: p.row, col: p.col, letter: p.letter, blank: p.blank })),
+  };
+  return JSON.stringify(data);
+}
+
+/** parseDraft decodes a stored draft, or null when empty or malformed. */
+export function parseDraft(json: string): { rackOrder: number[]; tiles: Tile[] } | null {
+  if (!json) return null;
+  try {
+    const d = JSON.parse(json) as Partial<DraftData>;
+    const rackOrder = String(d.rack_order ?? '')
+      .split(',')
+      .filter((s) => s !== '')
+      .map(Number);
+    const tiles = Array.isArray(d.board_tiles) ? d.board_tiles : [];
+    return { rackOrder, tiles };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * validRackOrder returns order when it is a permutation of [0, len), else null — so a stale
+ * order (the rack changed since the draft was saved) is ignored and the server order is kept.
+ */
+export function validRackOrder(order: number[], len: number): number[] | null {
+  if (order.length !== len) return null;
+  const seen = new Set<number>();
+  for (const i of order) {
+    if (!Number.isInteger(i) || i < 0 || i >= len || seen.has(i)) return null;
+    seen.add(i);
+  }
+  return order;
+}
+
+/**
+ * liveDraftTiles drops saved tiles whose cell is now occupied on the committed board (the
+ * opponent has since played there) — the position-only reconcile after a refresh.
+ */
+export function liveDraftTiles(tiles: Tile[], occupied: (row: number, col: number) => boolean): Tile[] {
+  return tiles.filter((t) => !occupied(t.row, t.col));
+}

ui/src/lib/mock/client.ts

@@ -93,6 +93,7 @@ export class MockGateway implements GatewayClient {
   private blocks: AccountRef[] = [];
   private invitations: Invitation[] = mockInvitations();
   private readonly stats: Stats = { ...MOCK_STATS };
+  private readonly drafts = new Map<string, string>();
 
   constructor() {
     // Seed the per-variant alphabet cache the rack, blank chooser and scoring read, so the
@@ -230,6 +231,7 @@ export class MockGateway implements GatewayClient {
     g.rack.push(...draw(variant, drawn));
     g.bagLen -= drawn;
     g.view.toMove = (seat + 1) % g.view.players;
+    this.drafts.delete(gameId);
     this.scheduleOpponentReply(gameId);
     return { move: structuredClone(move), game: structuredClone(g.view) };
   }
@@ -263,6 +265,7 @@ export class MockGateway implements GatewayClient {
     };
     g.moves.push(move);
     g.view.moveCount += 1;
+    this.drafts.delete(gameId);
     if (action === 'resign') {
       g.view.status = 'finished';
       g.view.endReason = 'resignation';
@@ -319,6 +322,15 @@ export class MockGateway implements GatewayClient {
   }
   async complaint(): Promise<void> {}
 
+  // --- draft (Stage 17): an in-memory composition store, so the reload/off-turn flow is
+  // exercised without a backend. A committed move clears the actor's own draft, as on the server.
+  async draftGet(gameId: string): Promise<string> {
+    return this.drafts.get(gameId) ?? '';
+  }
+  async draftSave(gameId: string, json: string): Promise<void> {
+    this.drafts.set(gameId, json);
+  }
+
   // --- chat ---
   async chatPost(gameId: string, body: string): Promise<ChatMessage> {
     const g = this.game(gameId);

ui/src/lib/transport.ts

@@ -114,6 +114,12 @@ export function createTransport(baseUrl: string): GatewayClient {
     async complaint(id, word, note) {
       await exec('game.complaint', codec.encodeComplaint(id, word, note));
     },
+    async draftGet(id) {
+      return codec.decodeDraftView(await exec('draft.get', codec.encodeGameAction(id)));
+    },
+    async draftSave(id, json) {
+      await exec('draft.save', codec.encodeDraftSave(id, json));
+    },
 
     async chatPost(id, body) {
       return codec.decodeChatMessage(await exec('chat.post', codec.encodeChatPost(id, body)));