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/game/Game.svelte

@@ -12,7 +12,7 @@
   import { app, handleError, showToast } from '../lib/app.svelte';
   import { GatewayError } from '../lib/client';
   import { t } from '../lib/i18n/index.svelte';
-  import type { ChatMessage, Direction, EvalResult, MoveRecord, StateView } from '../lib/model';
+  import type { ChatMessage, Direction, EvalResult, MoveRecord, StateView, Tile } from '../lib/model';
   import { replay } from '../lib/board';
   import { centre, premiumGrid } from '../lib/premiums';
   import { variantNameKey } from '../lib/variants';
@@ -33,6 +33,7 @@
     toSubmit,
     type Placement,
   } from '../lib/placement';
+  import { liveDraftTiles, parseDraft, serializeDraft, validRackOrder } from '../lib/draft';
 
   let { id }: { id: string } = $props();
 
@@ -127,15 +128,43 @@
       view = st;
       moves = hist.moves;
       setCachedGame(id, st, hist.moves);
-      placement = newPlacement(st.rack);
-      rackIds = st.rack.map((_, i) => i);
-      preview = null;
       selected = null;
       dirOverride = undefined;
+      await applyDraft(st);
+      recompute();
     } catch (e) {
       handleError(e);
     }
   }
+  let draftSaveTimer: ReturnType<typeof setTimeout> | null = null;
+  // scheduleDraftSave persists the composition (rack order + pending tiles) after a short
+  // debounce; best-effort, so a failed save never interrupts play (Stage 17).
+  function scheduleDraftSave() {
+    if (draftSaveTimer) clearTimeout(draftSaveTimer);
+    draftSaveTimer = setTimeout(() => {
+      void gateway.draftSave(id, serializeDraft(rackIds, placement.pending)).catch(() => {});
+    }, 500);
+  }
+  // applyDraft restores the player's saved composition over a freshly loaded state: the rack
+  // order (when still a valid permutation of the rack) and the board tiles whose cell is still
+  // free. Best-effort — a draft fetch never blocks opening the game.
+  async function applyDraft(st: StateView) {
+    let order = st.rack.map((_, i) => i);
+    let tiles: Tile[] = [];
+    try {
+      const parsed = parseDraft(await gateway.draftGet(id));
+      if (parsed) {
+        order = validRackOrder(parsed.rackOrder, st.rack.length) ?? order;
+        const committed = replay(moves);
+        tiles = liveDraftTiles(parsed.tiles, (r, c) => !!committed[r]?.[c]);
+      }
+    } catch {
+      /* best-effort */
+    }
+    rackIds = order;
+    const rack = order.map((i) => st.rack[i]);
+    placement = tiles.length ? placementFromHint(tiles, rack) : newPlacement(rack);
+  }
   async function loadChat() {
     try {
       messages = await gateway.chatList(id);
@@ -226,13 +255,16 @@
     drag = null;
   }
   function onRackDown(e: PointerEvent, index: number) {
-    if (!isMyTurn || busy) return;
+    // Tiles may be arranged on the opponent's turn too (Stage 17 #5): only placement is
+    // relaxed — the preview and Make-move stay your-turn-only, so an off-turn draft is
+    // position-only (never scored or submitted).
+    if (busy || gameOver) return;
     beginDrag({ from: 'rack', index }, e);
   }
   // A pending tile can be dragged back to the rack, but only on the unzoomed board: when
   // zoomed the one-finger gesture scrolls the board, so recall there is via double-tap.
   function onBoardDown(e: PointerEvent, row: number, col: number) {
-    if (!isMyTurn || busy || zoomed) return;
+    if (busy || zoomed || gameOver) return;
     beginDrag({ from: 'board', row, col }, e);
   }
   function cellUnder(x: number, y: number): { row: number; col: number } | null {
@@ -274,6 +306,7 @@
     rackIds = order.map((i) => rackIds[i] ?? i);
     placement = newPlacement(order.map((i) => placement.rack[i]));
     selected = null;
+    scheduleDraftSave();
   }
   function onWinMove(e: PointerEvent) {
     if (!downInfo) return;
@@ -342,6 +375,7 @@
         // Dropped a pending tile back onto the rack → recall it to its original slot.
         placement = recallAt(placement, di.src.row, di.src.col);
         recompute();
+        scheduleDraftSave();
       }
       swallowClick = true;
       setTimeout(() => (swallowClick = false), 60);
@@ -359,6 +393,11 @@
     window.removeEventListener('pointerdown', onExtraPointer);
     clearHover();
     clearReorder();
+    // Flush a pending draft save so leaving mid-composition still persists it (Stage 17).
+    if (draftSaveTimer) {
+      clearTimeout(draftSaveTimer);
+      void gateway.draftSave(id, serializeDraft(rackIds, placement.pending)).catch(() => {});
+    }
     telegramClosingConfirmation(false);
   });
 
@@ -378,6 +417,7 @@
   function onRecall(row: number, col: number) {
     placement = recallAt(placement, row, col);
     recompute();
+    scheduleDraftSave();
   }
   function attemptPlace(index: number, row: number, col: number) {
     if (board[row]?.[col]) return;
@@ -391,6 +431,7 @@
     placement = place(placement, index, row, col);
     telegramHaptic('select');
     recompute();
+    scheduleDraftSave();
   }
   function chooseBlank(letter: string) {
     if (!blankPrompt) return;
@@ -398,12 +439,15 @@
     blankPrompt = null;
     telegramHaptic('select');
     recompute();
+    scheduleDraftSave();
   }
 
   let previewTimer: ReturnType<typeof setTimeout> | null = null;
   function recompute() {
     preview = null;
     if (previewTimer) clearTimeout(previewTimer);
+    // Off-turn the composition is position-only: no score preview or evaluate (Stage 17 #5).
+    if (!isMyTurn) return;
     const sub = toSubmit(placement, dirOverride);
     if (!sub) return;
     previewTimer = setTimeout(async () => {
@@ -436,6 +480,7 @@
     preview = null;
     selected = null;
     dirOverride = undefined;
+    scheduleDraftSave();
   }
 
   async function doPass() {
@@ -507,6 +552,7 @@
     setTimeout(() => (shuffling = false), 600);
     // A short "shake": a few quick light taps rather than one.
     for (let i = 0; i < 4; i++) setTimeout(() => telegramHaptic('light'), i * 55);
+    scheduleDraftSave();
   }
   function openExchange() {
     resetPlacement();
@@ -729,7 +775,7 @@
         />
       </div>
       {#if !gameOver && placement.pending.length > 0}
-        <button class="make" onclick={commit} disabled={busy || (preview !== null && !preview.legal)} aria-label={t('game.makeMove')}>✅</button>
+        <button class="make" onclick={commit} disabled={busy || !isMyTurn || (preview !== null && !preview.legal)} aria-label={t('game.makeMove')}>✅</button>
       {/if}
     </div>
   {:else}

ui/src/gen/fbs/scrabblefb.ts

@@ -10,6 +10,8 @@ export { ChatPostRequest } from './scrabblefb/chat-post-request.js';
 export { CheckWordRequest } from './scrabblefb/check-word-request.js';
 export { ComplaintRequest } from './scrabblefb/complaint-request.js';
 export { CreateInvitationRequest } from './scrabblefb/create-invitation-request.js';
+export { DraftRequest } from './scrabblefb/draft-request.js';
+export { DraftView } from './scrabblefb/draft-view.js';
 export { EmailLoginRequest } from './scrabblefb/email-login-request.js';
 export { EmailRequestRequest } from './scrabblefb/email-request-request.js';
 export { EnqueueRequest } from './scrabblefb/enqueue-request.js';

ui/src/gen/fbs/scrabblefb/draft-request.ts

@@ -0,0 +1,60 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+export class DraftRequest {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):DraftRequest {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsDraftRequest(bb:flatbuffers.ByteBuffer, obj?:DraftRequest):DraftRequest {
+  return (obj || new DraftRequest()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsDraftRequest(bb:flatbuffers.ByteBuffer, obj?:DraftRequest):DraftRequest {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new DraftRequest()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+gameId():string|null
+gameId(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+gameId(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+json():string|null
+json(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+json(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 6);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+static startDraftRequest(builder:flatbuffers.Builder) {
+  builder.startObject(2);
+}
+
+static addGameId(builder:flatbuffers.Builder, gameIdOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, gameIdOffset, 0);
+}
+
+static addJson(builder:flatbuffers.Builder, jsonOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(1, jsonOffset, 0);
+}
+
+static endDraftRequest(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createDraftRequest(builder:flatbuffers.Builder, gameIdOffset:flatbuffers.Offset, jsonOffset:flatbuffers.Offset):flatbuffers.Offset {
+  DraftRequest.startDraftRequest(builder);
+  DraftRequest.addGameId(builder, gameIdOffset);
+  DraftRequest.addJson(builder, jsonOffset);
+  return DraftRequest.endDraftRequest(builder);
+}
+}

ui/src/gen/fbs/scrabblefb/draft-view.ts

@@ -0,0 +1,48 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+export class DraftView {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):DraftView {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsDraftView(bb:flatbuffers.ByteBuffer, obj?:DraftView):DraftView {
+  return (obj || new DraftView()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsDraftView(bb:flatbuffers.ByteBuffer, obj?:DraftView):DraftView {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new DraftView()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+json():string|null
+json(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+json(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+static startDraftView(builder:flatbuffers.Builder) {
+  builder.startObject(1);
+}
+
+static addJson(builder:flatbuffers.Builder, jsonOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, jsonOffset, 0);
+}
+
+static endDraftView(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createDraftView(builder:flatbuffers.Builder, jsonOffset:flatbuffers.Offset):flatbuffers.Offset {
+  DraftView.startDraftView(builder);
+  DraftView.addJson(builder, jsonOffset);
+  return DraftView.endDraftView(builder);
+}
+}

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