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.

gateway/internal/transcode/encode.go

@@ -252,6 +252,17 @@ func encodeWordCheck(r backendclient.WordCheckResp) []byte {
 	return b.FinishedBytes()
 }
 
+// encodeDraftView builds a DraftView payload wrapping the player's composition JSON. The
+// string is empty for the save acknowledgement (the client ignores that payload).
+func encodeDraftView(jsonStr string) []byte {
+	b := flatbuffers.NewBuilder(256)
+	j := b.CreateString(jsonStr)
+	fb.DraftViewStart(b)
+	fb.DraftViewAddJson(b, j)
+	b.Finish(fb.DraftViewEnd(b))
+	return b.FinishedBytes()
+}
+
 // encodeHistory builds a History payload (the decoded move journal).
 func encodeHistory(r backendclient.HistoryResp) []byte {
 	b := flatbuffers.NewBuilder(1024)

gateway/internal/transcode/transcode.go

@@ -7,6 +7,7 @@ package transcode
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 
 	"scrabble/gateway/internal/backendclient"
@@ -38,6 +39,8 @@ const (
 	MsgGameHistory    = "game.history"
 	MsgChatList       = "chat.list"
 	MsgChatNudge      = "chat.nudge"
+	MsgDraftGet       = "draft.get"
+	MsgDraftSave      = "draft.save"
 )
 
 // Request is one decoded Execute call.
@@ -108,6 +111,8 @@ func NewRegistry(backend *backendclient.Client, tg TelegramValidator, defaultLan
 	r.ops[MsgGameHistory] = Op{Handler: historyHandler(backend), Auth: true}
 	r.ops[MsgChatList] = Op{Handler: chatListHandler(backend), Auth: true}
 	r.ops[MsgChatNudge] = Op{Handler: nudgeHandler(backend), Auth: true}
+	r.ops[MsgDraftGet] = Op{Handler: getDraftHandler(backend), Auth: true}
+	r.ops[MsgDraftSave] = Op{Handler: saveDraftHandler(backend), Auth: true}
 	registerStage8(r, backend)
 	registerStage11(r, backend, tg, defaultLanguages)
 	return r
@@ -421,3 +426,28 @@ func nudgeHandler(backend *backendclient.Client) Handler {
 		return encodeChat(res), nil
 	}
 }
+
+// getDraftHandler returns the player's saved composition (Stage 17). It reuses
+// GameActionRequest for the game id and wraps the backend's raw JSON in a DraftView.
+func getDraftHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsGameActionRequest(req.Payload, 0)
+		raw, err := backend.GetDraft(ctx, req.UserID, string(in.GameId()))
+		if err != nil {
+			return nil, err
+		}
+		return encodeDraftView(string(raw)), nil
+	}
+}
+
+// saveDraftHandler upserts the player's composition (Stage 17), forwarding the opaque JSON
+// string verbatim. It echoes an empty DraftView as a well-formed acknowledgement.
+func saveDraftHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsDraftRequest(req.Payload, 0)
+		if err := backend.SaveDraft(ctx, req.UserID, string(in.GameId()), json.RawMessage(in.Json())); err != nil {
+			return nil, err
+		}
+		return encodeDraftView(""), nil
+	}
+}

gateway/internal/transcode/transcode_draft_test.go

@@ -0,0 +1,82 @@
+package transcode_test
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"testing"
+
+	flatbuffers "github.com/google/flatbuffers/go"
+
+	"scrabble/gateway/internal/transcode"
+	fb "scrabble/pkg/fbs/scrabblefb"
+)
+
+// TestDraftSaveForwardsRawJSON checks the save handler forwards the client's composition JSON
+// to the backend verbatim (the "no double-encode" contract, Stage 17) with the user header.
+func TestDraftSaveForwardsRawJSON(t *testing.T) {
+	const body = `{"rack_order":"1,0","board_tiles":[{"row":7,"col":7,"letter":"Q","blank":false}]}`
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut || r.URL.Path != "/api/v1/user/games/g-1/draft" {
+			t.Errorf("unexpected %s %s", r.Method, r.URL.Path)
+		}
+		if got := r.Header.Get("X-User-ID"); got != "u-3" {
+			t.Errorf("X-User-ID = %q, want u-3", got)
+		}
+		raw, _ := io.ReadAll(r.Body)
+		if string(raw) != body {
+			t.Errorf("forwarded body = %q, want %q (verbatim)", raw, body)
+		}
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, ok := reg.Lookup(transcode.MsgDraftSave)
+	if !ok {
+		t.Fatal("draft.save not registered")
+	}
+
+	b := flatbuffers.NewBuilder(64)
+	gid := b.CreateString("g-1")
+	j := b.CreateString(body)
+	fb.DraftRequestStart(b)
+	fb.DraftRequestAddGameId(b, gid)
+	fb.DraftRequestAddJson(b, j)
+	b.Finish(fb.DraftRequestEnd(b))
+
+	if _, err := op.Handler(context.Background(), transcode.Request{Payload: b.FinishedBytes(), UserID: "u-3"}); err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+}
+
+// TestDraftGetWrapsBackendJSON checks the get handler wraps the backend's stored draft JSON in
+// a DraftView verbatim (the gateway never interprets the shape).
+func TestDraftGetWrapsBackendJSON(t *testing.T) {
+	const stored = `{"rack_order":"2,0,1","board_tiles":[]}`
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || r.URL.Path != "/api/v1/user/games/g-2/draft" {
+			t.Errorf("unexpected %s %s", r.Method, r.URL.Path)
+		}
+		_, _ = w.Write([]byte(stored))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgDraftGet)
+
+	b := flatbuffers.NewBuilder(32)
+	gid := b.CreateString("g-2")
+	fb.GameActionRequestStart(b)
+	fb.GameActionRequestAddGameId(b, gid)
+	b.Finish(fb.GameActionRequestEnd(b))
+
+	payload, err := op.Handler(context.Background(), transcode.Request{Payload: b.FinishedBytes(), UserID: "u-4"})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	v := fb.GetRootAsDraftView(payload, 0)
+	if string(v.Json()) != stored {
+		t.Fatalf("DraftView.json = %q, want %q (verbatim)", v.Json(), stored)
+	}
+}