Stage 13: alphabet on the wire (UI alphabet-agnostic, TODO-4)

Live play now exchanges per-variant alphabet indices instead of concrete
letters (rack out; submit-play, evaluate, exchange, word-check in). The client
caches each variant's (index, letter, value) table behind
StateRequest.include_alphabet and renders the rack and blank chooser from it,
dropping the hardcoded value/alphabet tables. History, the durable journal and
GCG stay decoded concrete characters (ARCHITECTURE §9.1, unchanged).

- pkg/fbs: new AlphabetEntry + PlayTile; StateView.rack -> [ubyte] + alphabet;
  StateRequest.include_alphabet; SubmitPlay/Eval tiles -> [PlayTile];
  Exchange tiles + CheckWord word -> [ubyte] (committed Go + TS regenerated).
- engine: AlphabetTable + a cached per-variant codec (LetterForIndex/EncodeRack/
  DecodeTiles/DecodeWord) + BlankIndex sentinel; Go parity test.
- backend server edge maps index<->letter (new thin game.Service.GameVariant);
  game.Service domain methods, engine.Game and the robot keep one letter-based
  play path. The gateway forwards indices verbatim (no alphabet table).
- ui: lib/alphabet.ts in-memory cache; codec encodes/decodes indices; premiums.ts
  is geometry-only; the mock seeds a fixture table; the UI normalises display to
  upper case (codec + cache), leaving placement/board/checkword unchanged.

Parity moved to the Go engine.AlphabetTable test; premiums.ts loses its value
tables. Discharges TODO-4.

backend/internal/server/dto.go

@@ -101,13 +101,24 @@ type moveResultDTO struct {
 	Game gameDTO       `json:"game"`
 }
 
-// stateDTO is a player's view of a game.
+// alphabetEntryDTO is one letter of a variant's alphabet (its index, concrete letter and
+// tile value), embedded in the state view for display only when the client requests it
+// (Stage 13).
+type alphabetEntryDTO struct {
+	Index  int    `json:"index"`
+	Letter string `json:"letter"`
+	Value  int    `json:"value"`
+}
+
+// stateDTO is a player's view of a game. Rack carries wire alphabet indices (Stage 13; a
+// blank is engine.BlankIndex). Alphabet is present only when the request asked for it.
 type stateDTO struct {
-	Game           gameDTO  `json:"game"`
-	Seat           int      `json:"seat"`
-	Rack           []string `json:"rack"`
-	BagLen         int      `json:"bag_len"`
-	HintsRemaining int      `json:"hints_remaining"`
+	Game           gameDTO            `json:"game"`
+	Seat           int                `json:"seat"`
+	Rack           []int              `json:"rack"`
+	BagLen         int                `json:"bag_len"`
+	HintsRemaining int                `json:"hints_remaining"`
+	Alphabet       []alphabetEntryDTO `json:"alphabet,omitempty"`
 }
 
 // matchDTO reports whether the caller has been paired into a game.
@@ -217,15 +228,32 @@ func moveResultDTOFrom(r game.MoveResult) moveResultDTO {
 	return moveResultDTO{Move: moveRecordDTOFrom(r.Move), Game: gameDTOFromGame(r.Game)}
 }
 
-// stateDTOFrom projects a player's state view into its DTO.
-func stateDTOFrom(v game.StateView) stateDTO {
-	return stateDTO{
+// stateDTOFrom projects a player's state view into its DTO, encoding the rack as wire
+// alphabet indices (Stage 13). When includeAlphabet is set it also embeds the variant's
+// display table, which the client caches per variant and renders the rack with.
+func stateDTOFrom(v game.StateView, includeAlphabet bool) (stateDTO, error) {
+	rack, err := engine.EncodeRack(v.Game.Variant, v.Rack)
+	if err != nil {
+		return stateDTO{}, err
+	}
+	dto := stateDTO{
 		Game:           gameDTOFromGame(v.Game),
 		Seat:           v.Seat,
-		Rack:           v.Rack,
+		Rack:           rack,
 		BagLen:         v.BagLen,
 		HintsRemaining: v.HintsRemaining,
 	}
+	if includeAlphabet {
+		tab, err := engine.AlphabetTable(v.Game.Variant)
+		if err != nil {
+			return stateDTO{}, err
+		}
+		dto.Alphabet = make([]alphabetEntryDTO, len(tab))
+		for i, e := range tab {
+			dto.Alphabet[i] = alphabetEntryDTO{Index: int(e.Index), Letter: e.Letter, Value: e.Value}
+		}
+	}
+	return dto, nil
 }
 
 // matchDTOFrom projects an enqueue/poll result into its DTO.

backend/internal/server/handlers_game.go

@@ -3,6 +3,7 @@ package server
 import (
 	"context"
 	"net/http"
+	"strconv"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -51,9 +52,10 @@ type chatListDTO struct {
 	Messages []chatDTO `json:"messages"`
 }
 
-// exchangeRequest swaps the given rack tiles back into the bag.
+// exchangeRequest swaps the given rack tiles back into the bag. Tiles are wire alphabet
+// indices (Stage 13); a blank is engine.BlankIndex.
 type exchangeRequest struct {
-	Tiles []string `json:"tiles"`
+	Tiles []int `json:"tiles"`
 }
 
 // complaintRequest disputes a word-check result.
@@ -125,7 +127,17 @@ func (s *Server) handleExchange(c *gin.Context) {
 		abortBadRequest(c, "invalid request body")
 		return
 	}
-	res, err := s.games.Exchange(c.Request.Context(), gameID, uid, req.Tiles)
+	variant, err := s.games.GameVariant(c.Request.Context(), gameID)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	tiles, err := engine.DecodeTiles(variant, req.Tiles)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	res, err := s.games.Exchange(c.Request.Context(), gameID, uid, tiles)
 	if err != nil {
 		s.abortErr(c, err)
 		return
@@ -180,9 +192,15 @@ func (s *Server) handleEvaluate(c *gin.Context) {
 		abortBadRequest(c, "dir must be H or V")
 		return
 	}
-	tiles := make([]engine.TileRecord, 0, len(req.Tiles))
-	for _, t := range req.Tiles {
-		tiles = append(tiles, engine.TileRecord{Row: t.Row, Col: t.Col, Letter: t.Letter, Blank: t.Blank})
+	variant, err := s.games.GameVariant(c.Request.Context(), gameID)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	tiles, err := tilesFromRequest(variant, req)
+	if err != nil {
+		s.abortErr(c, err)
+		return
 	}
 	ev, err := s.games.EvaluatePlay(c.Request.Context(), gameID, uid, dir, tiles)
 	if err != nil {
@@ -192,13 +210,29 @@ func (s *Server) handleEvaluate(c *gin.Context) {
 	c.JSON(http.StatusOK, evalResultDTO{Legal: ev.Valid, Score: ev.Score, Words: ev.Words})
 }
 
-// handleCheckWord looks a word up in the game's pinned dictionary.
+// handleCheckWord looks a word up in the game's pinned dictionary. The word arrives as
+// repeated ?idx= alphabet indices (Stage 13); the backend decodes them to the concrete
+// word for the lookup and echoes that concrete word back for the client's result cache.
 func (s *Server) handleCheckWord(c *gin.Context) {
 	_, gameID, ok := s.userGame(c)
 	if !ok {
 		return
 	}
-	word := c.Query("word")
+	idx, err := queryIndexes(c, "idx")
+	if err != nil {
+		abortBadRequest(c, "invalid word")
+		return
+	}
+	variant, err := s.games.GameVariant(c.Request.Context(), gameID)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	word, err := engine.DecodeWord(variant, idx)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
 	legal, err := s.games.CheckWord(c.Request.Context(), gameID, word)
 	if err != nil {
 		s.abortErr(c, err)
@@ -207,6 +241,21 @@ func (s *Server) handleCheckWord(c *gin.Context) {
 	c.JSON(http.StatusOK, wordCheckDTO{Word: word, Legal: legal})
 }
 
+// queryIndexes parses repeated integer query parameters (e.g. ?idx=2&idx=0) into a slice.
+// It carries a word-check query as alphabet indices on a GET (Stage 13).
+func queryIndexes(c *gin.Context, key string) ([]int, error) {
+	raw := c.QueryArray(key)
+	out := make([]int, 0, len(raw))
+	for _, s := range raw {
+		n, err := strconv.Atoi(s)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, n)
+	}
+	return out, nil
+}
+
 // handleComplaint files a word-check complaint into the admin review queue.
 func (s *Server) handleComplaint(c *gin.Context) {
 	uid, gameID, ok := s.userGame(c)

backend/internal/server/handlers_user.go

@@ -26,17 +26,33 @@ func (s *Server) handleProfile(c *gin.Context) {
 	c.JSON(http.StatusOK, profileResponseFor(acc))
 }
 
-// submitPlayRequest places tiles in a direction on the player's turn.
+// submitPlayRequest places tiles in a direction on the player's turn. Each tile's Letter
+// is a wire alphabet index (Stage 13); for a blank it is the designated letter's index.
 type submitPlayRequest struct {
 	Dir   string `json:"dir"`
 	Tiles []struct {
-		Row    int    `json:"row"`
-		Col    int    `json:"col"`
-		Letter string `json:"letter"`
-		Blank  bool   `json:"blank"`
+		Row    int  `json:"row"`
+		Col    int  `json:"col"`
+		Letter int  `json:"letter"`
+		Blank  bool `json:"blank"`
 	} `json:"tiles"`
 }
 
+// tilesFromRequest maps a play/evaluate request's index-addressed tiles to engine tile
+// records for the game's variant (Stage 13: a placed blank carries its designated letter's
+// index with Blank set). An out-of-range index surfaces as engine.ErrIllegalPlay (HTTP 400).
+func tilesFromRequest(variant engine.Variant, req submitPlayRequest) ([]engine.TileRecord, error) {
+	tiles := make([]engine.TileRecord, 0, len(req.Tiles))
+	for _, t := range req.Tiles {
+		letter, err := engine.LetterForIndex(variant, t.Letter)
+		if err != nil {
+			return nil, err
+		}
+		tiles = append(tiles, engine.TileRecord{Row: t.Row, Col: t.Col, Letter: letter, Blank: t.Blank})
+	}
+	return tiles, nil
+}
+
 // handleSubmitPlay validates, scores and commits a placement.
 func (s *Server) handleSubmitPlay(c *gin.Context) {
 	uid, ok := userID(c)
@@ -59,9 +75,15 @@ func (s *Server) handleSubmitPlay(c *gin.Context) {
 		abortBadRequest(c, "dir must be H or V")
 		return
 	}
-	tiles := make([]engine.TileRecord, 0, len(req.Tiles))
-	for _, t := range req.Tiles {
-		tiles = append(tiles, engine.TileRecord{Row: t.Row, Col: t.Col, Letter: t.Letter, Blank: t.Blank})
+	variant, err := s.games.GameVariant(c.Request.Context(), gameID)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	tiles, err := tilesFromRequest(variant, req)
+	if err != nil {
+		s.abortErr(c, err)
+		return
 	}
 	res, err := s.games.SubmitPlay(c.Request.Context(), gameID, uid, dir, tiles)
 	if err != nil {
@@ -88,7 +110,11 @@ func (s *Server) handleGameState(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	dto := stateDTOFrom(view)
+	dto, err := stateDTOFrom(view, c.Query("include_alphabet") == "true")
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
 	s.fillSeatNames(c.Request.Context(), &dto.Game, map[string]string{})
 	c.JSON(http.StatusOK, dto)
 }