feat(multiplayer): host color preference (white/black/random)

Feature 1 of post-epic-deferrals. Lets the room creator pick which
color they play: white, black, or random. Joiner always takes the
remaining color (no joiner-side preference in v1 per plan decision
1b).

Protocol:
  - RoomCreatePayloadSchema gains an optional preferredColor field
    with the three-value enum. Omitting the field defaults to
    'white' on the server — byte-identical to pre-F1 behaviour so
    legacy clients are untouched.
  - Client type mirror (packages/chess/src/net/types.ts) kept in
    sync; exports PreferredColor type alias.

Server:
  - RoomRegistry.createRoom gains a preferredColor parameter.
    'random' is resolved at room creation via Math.random() and
    never leaks beyond this function — the concrete color is stored
    on room.creatorColor + room.joinerColor so reconnects surface
    the same assignment.
  - Room interface adds creatorColor + joinerColor fields.
  - JoinResult success variant widens from 'color: "black"' to
    'color: Color' to accept either assignment.
  - broadcast.ts threads payload.preferredColor through to
    createRoom.

UI:
  - Lobby.tsx adds a 3-button radiogroup ('Play as: White / Black /
    Random') between LayoutPicker and the modifier-profile picker.
    Active button is filled (bg-neutral-900), inactive is ghost.
    Omits the field from the room.create payload when left at the
    default so old servers keep working.
  - data-testid='color-preference-{white,black,random}' for e2e.

Tests:
  - 7 new protocol.test.ts cases: each enum value accepted,
    omitted valid, invalid strings rejected, composition with
    existing fields.
  - 5 new rooms.test.ts cases: back-compat default, explicit
    white, explicit black, random distribution across 40 samples,
    random-resolved color stored idempotently.
  - 4 new multiplayer.spec.ts cases: host=black flow, host=random
    disjoint-color assertion, back-compat no-field flow, UI
    buttons render + toggle with correct aria-checked state.

Verification: 1663 unit tests (+12) + 87/87 Playwright (+4).
Typecheck + lint clean across chess + server.

Plan: .sisyphus/plans/post-epic-deferrals.md Feature 1 complete.

packages/server/src/broadcast.ts

@@ -388,10 +388,14 @@ function handleRoomCreate(
   }
 
   const rulesetIds = payload.rulesetIds ?? [];
+  // F1: thread the host's color preference through. Omission defaults
+  // to `"white"` matching legacy behaviour — no change for pre-F1
+  // clients that never sent the field.
   const { code, token, color } = roomRegistry.createRoom(
     [...rulesetIds],
     resolvedLayout,
     profile,
+    payload.preferredColor,
   );
   sessionRegistry.create(code, rulesetIds, resolvedLayout, profile);
   ws.data.roomCode = code;

packages/server/src/protocol.test.ts

@@ -428,6 +428,44 @@ describe("validateMessage — rejections", () => {
 // validateMessageString — raw-string entry point
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// F1.1 — preferredColor on room.create (post-epic Feature 1)
+// ---------------------------------------------------------------------------
+
+describe("RoomCreatePayloadSchema preferredColor", () => {
+  it("accepts 'white'", () => {
+    const r = RoomCreatePayloadSchema.safeParse({ preferredColor: "white" });
+    expect(r.success).toBe(true);
+  });
+  it("accepts 'black'", () => {
+    const r = RoomCreatePayloadSchema.safeParse({ preferredColor: "black" });
+    expect(r.success).toBe(true);
+  });
+  it("accepts 'random'", () => {
+    const r = RoomCreatePayloadSchema.safeParse({ preferredColor: "random" });
+    expect(r.success).toBe(true);
+  });
+  it("omitted is valid (backward compat with pre-F1 clients)", () => {
+    const r = RoomCreatePayloadSchema.safeParse({});
+    expect(r.success).toBe(true);
+  });
+  it("rejects invalid color strings", () => {
+    const r = RoomCreatePayloadSchema.safeParse({ preferredColor: "grey" });
+    expect(r.success).toBe(false);
+  });
+  it("rejects non-string preferredColor", () => {
+    const r = RoomCreatePayloadSchema.safeParse({ preferredColor: 1 });
+    expect(r.success).toBe(false);
+  });
+  it("composes with rulesetIds + layout + profile", () => {
+    const r = RoomCreatePayloadSchema.safeParse({
+      preferredColor: "random",
+      rulesetIds: ["piece-hp"],
+    });
+    expect(r.success).toBe(true);
+  });
+});
+
 describe("validateMessageString", () => {
   it("parses a valid JSON string frame", () => {
     const msg: ClientMessage = {

packages/server/src/protocol.ts

@@ -285,6 +285,21 @@ type _ModifierProfileKeyCheck = _AssertKeyEq<
 const _modifierProfileKeyCheck: _ModifierProfileKeyCheck = true;
 void _modifierProfileKeyCheck;
 
+/**
+ * Preference for which color the ROOM CREATOR plays.
+ *   - "white"  → creator plays white, joiner plays black (default,
+ *                matches legacy behaviour for old clients).
+ *   - "black"  → creator plays black, joiner plays white.
+ *   - "random" → server flips a coin at room creation; creator gets
+ *                the result, joiner gets the other color.
+ *
+ * Joiner-side preference is NOT supported in v1 (see
+ * `.sisyphus/plans/post-epic-deferrals.md` Feature 1). The joiner
+ * always takes whichever color the creator didn't take.
+ */
+export const PreferredColorSchema = z.enum(["white", "black", "random"]);
+export type PreferredColor = z.infer<typeof PreferredColorSchema>;
+
 export const RoomCreatePayloadSchema = z.object({
   rulesetIds: z.array(z.string()).optional(),
   layout: LayoutRequestSchema.optional(),
@@ -295,6 +310,13 @@ export const RoomCreatePayloadSchema = z.object({
    * turn boundary (server-enforced).
    */
   profile: ModifierProfileSchema.optional(),
+  /**
+   * Color the creator wants to play. Server resolves `"random"` at
+   * room-creation time; the joiner takes the remaining color.
+   * Omitting the field defaults to `"white"` — backward-compatible
+   * with legacy clients that never sent a preference.
+   */
+  preferredColor: PreferredColorSchema.optional(),
 });
 export type RoomCreatePayload = z.infer<typeof RoomCreatePayloadSchema>;
 

packages/server/src/rooms.test.ts

@@ -38,6 +38,67 @@ describe("RoomRegistry.createRoom", () => {
     const { code } = reg.createRoom();
     expect(reg.getRoom(code)?.rulesetIds).toEqual([]);
   });
+
+  // F1 (post-epic-deferrals): host color preference.
+
+  it("F1: defaults to creator=white when preferredColor omitted (back-compat)", () => {
+    const reg = new RoomRegistry();
+    const { code, color } = reg.createRoom();
+    expect(color).toBe("white");
+    const room = reg.getRoom(code);
+    expect(room?.creatorColor).toBe("white");
+    expect(room?.joinerColor).toBe("black");
+  });
+
+  it("F1: preferredColor=\"white\" → creator=white, joiner=black", () => {
+    const reg = new RoomRegistry();
+    const { color } = reg.createRoom([], undefined, undefined, "white");
+    expect(color).toBe("white");
+    const join = reg.joinRoom(
+      reg.getRoomCount() === 1
+        ? [...(reg as unknown as { rooms: Map<string, unknown> }).rooms.keys()][0]!
+        : "",
+    );
+    if ("error" in join) throw new Error(join.error);
+    expect(join.color).toBe("black");
+  });
+
+  it("F1: preferredColor=\"black\" → creator=black, joiner=white", () => {
+    const reg = new RoomRegistry();
+    const { code, color } = reg.createRoom([], undefined, undefined, "black");
+    expect(color).toBe("black");
+    const room = reg.getRoom(code);
+    expect(room?.creatorColor).toBe("black");
+    expect(room?.joinerColor).toBe("white");
+    const join = reg.joinRoom(code);
+    if ("error" in join) throw new Error(join.error);
+    expect(join.color).toBe("white");
+  });
+
+  it("F1: preferredColor=\"random\" produces both outcomes across many rooms", () => {
+    // Sample 40 rooms; a fair coin should yield AT LEAST one of each
+    // color well within this window (failure probability < 2^-39).
+    const reg = new RoomRegistry();
+    const outcomes = new Set<string>();
+    for (let i = 0; i < 40; i++) {
+      const { color } = reg.createRoom([], undefined, undefined, "random");
+      outcomes.add(color);
+      if (outcomes.size === 2) break;
+    }
+    expect(outcomes).toEqual(new Set(["white", "black"]));
+  });
+
+  it("F1: random-resolved color is stored (no re-rolling on reconnect)", () => {
+    const reg = new RoomRegistry();
+    const { code, color } = reg.createRoom([], undefined, undefined, "random");
+    const room = reg.getRoom(code);
+    expect(room?.creatorColor).toBe(color);
+    expect(room?.joinerColor).toBe(color === "white" ? "black" : "white");
+    // Joining reads the stored joinerColor — never re-rolls.
+    const join = reg.joinRoom(code);
+    if ("error" in join) throw new Error(join.error);
+    expect(join.color).toBe(color === "white" ? "black" : "white");
+  });
 });
 
 describe("RoomRegistry.joinRoom", () => {

packages/server/src/rooms.ts

@@ -45,6 +45,23 @@ export interface Room {
    * their tab retains host permissions.
    */
   hostToken: string;
+  /**
+   * Color the room creator plays. Resolved from the `preferredColor`
+   * field on `room.create` at creation time — in particular,
+   * `"random"` is collapsed to a concrete color here and never leaks
+   * beyond `createRoom`.
+   *
+   * Feature 1 of `post-epic-deferrals`. Prior to F1 this was
+   * hardcoded to `"white"`.
+   */
+  creatorColor: Color;
+  /**
+   * Color the eventual joiner plays. Computed as the opposite of
+   * `creatorColor` at room creation and stored so `joinRoom()` can
+   * return it without re-deriving the complement. Pre-F1 this was
+   * hardcoded to `"black"`.
+   */
+  joinerColor: Color;
   /** Unix milliseconds the room was created — used for TTL/eviction later. */
   createdAt: number;
   /** Rule presets activated for this game (from room.create payload). */
@@ -131,7 +148,12 @@ export interface Room {
 export type JoinResult =
   | {
       token: string;
-      color: "black";
+      /**
+       * Post-F1 (`post-epic-deferrals` Feature 1) this can be either
+       * color — whichever color the creator DIDN'T take. Was
+       * literal-typed `"black"` before F1.
+       */
+      color: Color;
       activeRules: string[];
       layout: StartingLayout;
       profile?: ModifierProfile;
@@ -183,8 +205,8 @@ export class RoomRegistry {
   private readonly rooms = new Map<string, Room>();
 
   /**
-   * Create a fresh room. The caller becomes white and receives a UUID v4
-   * token that authenticates every subsequent message.
+   * Create a fresh room. The caller receives a UUID v4 token that
+   * authenticates every subsequent message.
    *
    * `layout` is the resolved (already-validated) starting layout.
    * Callers construct this via `resolveLayoutRequest` in ./layouts.ts.
@@ -193,23 +215,51 @@ export class RoomRegistry {
    * start. Callers are responsible for validating it via
    * `validateProfile` from @paratype/chess BEFORE handing it here —
    * this registry trusts its inputs.
+   *
+   * `preferredColor` (Feature 1 of `post-epic-deferrals`) picks the
+   * creator's color:
+   *   - `"white"` (DEFAULT when omitted) → creator plays white,
+   *     joiner plays black. Matches pre-F1 hardcoded behaviour
+   *     exactly so legacy clients are unaffected.
+   *   - `"black"` → creator plays black, joiner plays white.
+   *   - `"random"` → server flips a fair coin here; creator gets
+   *     the result, joiner gets the complement. The random draw
+   *     happens exactly once per room creation — the concrete
+   *     assignment is then stored on the room so reconnects
+   *     surface the same color.
+   *
+   * Joiner-side preference is NOT supported (plan decision 1b);
+   * `joinRoom` just returns whatever color the creator didn't take.
    */
   createRoom(
     rulesetIds: string[] = [],
     layout?: StartingLayout,
     profile?: ModifierProfile,
+    preferredColor: "white" | "black" | "random" = "white",
   ): {
     code: string;
     token: string;
-    color: "white";
+    color: Color;
     layout: StartingLayout;
     profile?: ModifierProfile;
   } {
+    // Resolve random → concrete color. Math.random() is fine here:
+    // this is gameplay randomness (the joiner shouldn't be able to
+    // predict the draw, but nobody is paying for a CSPRNG) — no
+    // cryptographic guarantees needed.
+    const creatorColor: Color =
+      preferredColor === "random"
+        ? Math.random() < 0.5
+          ? "white"
+          : "black"
+        : preferredColor;
+    const joinerColor: Color = creatorColor === "white" ? "black" : "white";
+
     const code = this.allocateCode();
     const token = crypto.randomUUID();
     const player: RoomPlayer = {
       token,
-      color: "white",
+      color: creatorColor,
       connected: true,
       lastSeq: 0,
     };
@@ -222,6 +272,8 @@ export class RoomRegistry {
       code,
       players: new Map([[token, player]]),
       hostToken: token,
+      creatorColor,
+      joinerColor,
       createdAt: Date.now(),
       // Defensive copy — callers shouldn't be able to mutate our state.
       rulesetIds: [...rulesetIds],
@@ -232,7 +284,7 @@ export class RoomRegistry {
     return {
       code,
       token,
-      color: "white",
+      color: creatorColor,
       layout: resolvedLayout,
       ...(profile !== undefined ? { profile } : {}),
     };
@@ -250,16 +302,20 @@ export class RoomRegistry {
     if (!room) return { error: "ROOM_NOT_FOUND" };
     if (room.players.size >= 2) return { error: "ROOM_FULL" };
     const token = crypto.randomUUID();
+    // Post-F1: read the assigned color off the room. The creator
+    // picked at room.create (or let the server roll random) and the
+    // complement was stored as `joinerColor`.
+    const color = room.joinerColor;
     const player: RoomPlayer = {
       token,
-      color: "black",
+      color,
       connected: true,
       lastSeq: 0,
     };
     room.players.set(token, player);
     return {
       token,
-      color: "black",
+      color,
       // Defensive copy so joiners can't mutate the room's ruleset list.
       activeRules: [...room.rulesetIds],
       layout: room.layout,