castle-web-cli 0.4.170 → 0.4.172

package/kits/turn-based/CLAUDE.md

@@ -37,8 +37,24 @@ This kit adds no engine and no editors. What it holds:
   `createRoom({ seats, idleMs, graceMs })` from
   `@imports/castle.turn-based/room.js`. Copy the kit's server as the starting
   point -- it is the shape a game of this kind has.
-- `room.join(session, player)` and `room.leave(session, player)` both return
-  `{ table }`. One table per `session.sessionId`, made on demand.
+- `room.joinAsync(session, player)` and `room.leave(session, player)` return
+  `{ table }`. One table per `session.sessionId`, made on demand. `joinAsync` is
+  the join to use: it reads the saved table first, which the synchronous
+  `room.join` cannot.
+- **A claimed square shows its holder's avatar.** The state carries `users`,
+  seat -> userId, and `Board.jsx` swaps the square's `Sprite.file` for the
+  avatar from `castle.physics-2d`'s `engine/avatarArt.js`; a holder with no
+  photo keeps the seat tint.
+- **A room comes back.** `table.game`, the seat each account held, and the time
+  of the last accepted move are saved to deck storage on every accepted move, on
+  every leave, and from `room.save(session)` in `onShutdown`. Storage belongs to
+  a published deck; a serve brokers it as the deck's creator, so a kit served as
+  its own deck has none.
+- One row per room -- `table:<sessionId>`, or `table:public` shared by every
+  public shard. `named` and `party` always resume; a public room resumes only
+  while its last move is inside `idleMs`. A seat goes back to the `userId` that
+  held it, on whatever connection; a second connection from an account that is
+  still seated is an arrival, and watches or takes a free seat.
 - **The deck owns its game.** `table.game` starts null and a clear puts it back
   to null, so the deck's join handler is `if (!table.game) { table.game = ... }`.
   The kit never builds or reads it.
@@ -96,18 +112,26 @@ function freshGame() {
 }
 
 export default {
-  onPlayerJoin(session, player) {
-    const { table } = room.join(session, player);
+  async onPlayerJoin(session, player) {
+    const { table } = await room.joinAsync(session, player);
     if (!table.game) {
       table.game = freshGame();
     }
     push(session, table);
   },
-  onPlayerLeave(session, player) {
-    push(session, room.leave(session, player).table);
+  async onPlayerLeave(session, player) {
+    const { table, saved } = room.leave(session, player);
+    push(session, table);
+    await saved;
+  },
+  async onShutdown(session) {
+    await room.save(session);
   },
   onMessage(session, player, data) {
     const table = room.table(session);
+    if (!table.game) {
+      return; // still reading the saved table
+    }
     // ... validate against table.seatOf(player.playerId) and table.game,
     // then table.keepAlive() only once the move is accepted.
   },
@@ -131,9 +155,15 @@ export default {
 ### `room`
 
 - `room.table(session)` -- the table for this session, made if new.
-- `room.join(session, player)` -> `{ table }`. Everyone past the last seat
-  watches.
-- `room.leave(session, player)` -> `{ table }`.
+- `room.joinAsync(session, player)` -> `Promise<{ table }>`. Reads the saved
+  table on the first join into this process, then seats the player. Everyone
+  past the last seat watches.
+- `room.join(session, player)` -> `{ table }`. The same join without the read,
+  for a deck that does not want persistence.
+- `room.leave(session, player)` -> `{ table, saved }`. `saved` is the write this
+  leave started; it never rejects.
+- `room.save(session)` -> a promise that never rejects. What `onShutdown` calls.
+- `room.restore(session)` -> the read `joinAsync` does, on its own.
 
 ### `table`
 
@@ -148,19 +178,30 @@ export default {
   copies the name into its own state when it deals.
 - `table.seatNames()` -> `{ [seat]: name | null }`, ready to send.
 - `table.spectatorCount(session)` -- people in the session holding no seat.
-- `table.keepAlive()` -- stamp the idle clock. **Past every rejection, never
-  before one.** A rematch is the deck's own `table.game = fresh()` plus this.
+- `table.keepAlive()` -- stamp the idle clock and save the table. **Past every
+  rejection, never before one.** A rematch is the deck's own
+  `table.game = fresh()` plus this. It returns the save, which a caller that can
+  await one does; a failed write is logged and never thrown into the game loop.
+- `table.seatsByUserId` -- the seat each account last held. Saved with the game.
 - `table.lastActivityAt`, `table.sessionId`, `table.seats`, `table.departed` are
   readable for a status line or a test.
 
 ## The rules, stated
 
+On the **first join** into a process that has no table for this session,
+`joinAsync` reads the saved room first. A `named` room and a party always
+resume. A public room resumes only while its saved last move is inside `idleMs`;
+past that it starts clean. The join rules below then run over whatever came back,
+which is why a stranger walking alone into a resumed room still clears it.
+
 On **join**, in this order:
 
 1. Expired departure records are pruned.
 2. If this player already holds a seat, or has a departure record inside
-   `graceMs` whose seat is still free, they get it back and this join is a
-   **return**.
+   `graceMs` whose seat is still free, or last held a free seat under the same
+   `userId`, they get it back and this join is a **return**. The account lookup
+   is what a page reload and a restarted server both come back through; in a
+   public room it is bounded by `idleMs` too.
 3. The table is cleared iff: the mode is not `party`, AND this is not a return,
    AND either (a) they arrived alone, or (b) fewer than `minPlayers` seats are
    held by present players and nothing has been accepted for `idleMs`. A clear
@@ -169,8 +210,12 @@ On **join**, in this order:
 4. They take the first free seat in declared order, or watch.
 
 On **leave**: their seat, if any, is recorded in `departed` and freed; every
-other present player without a seat is moved into one, in roster order; and
-nothing else -- `game` is not touched.
+other present player without a seat is moved into one, in roster order; the table
+is saved; and nothing else -- `game` is not touched.
+
+A second connection from an account that is still seated finds its own seat
+taken, so it arrives as a stranger and watches or takes a free one. It never
+takes the seat over.
 
 Promotion is why a present person outranks a seat held for a connection that may
 never come back, and step 2 of join gives way once the seat is taken. It is also
@@ -230,9 +275,10 @@ import { checkRoom, printRoomChecks } from '@imports/castle.turn-based/testing.j
 
 process.exit(
   printRoomChecks(
-    checkRoom({
+    await checkRoom({
       server,
       seats: 2,
+      reload: () => import(`../server/index.js?fresh=${Date.now()}`).then((m) => m.default),
       idleMs: 3 * 60 * 1000,
       graceMs: 45 * 1000,
       play: (h, seated) => {
@@ -252,6 +298,13 @@ process.exit(
 );
 ```
 
+`checkRoom` returns a promise, and `harness.join` / `harness.leave` do too: a
+join reads storage. Await them.
+
+`reload` returns a fresh import of the deck's server, which is a restarted
+process -- new tables over the same storage. The three resume checks need it and
+are skipped without it.
+
 Two hooks are worth reading twice:
 
 - `snapshot` is the **public projection of the game**, not the player's own view
@@ -267,23 +320,30 @@ Two hooks are worth reading twice:
   is handed to refreshes the idle clock and fails the check that says refused
   messages do not.
 
-Twenty-three checks, covering seating and spectators, promotion, the grace
+Thirty-three checks, covering seating and spectators, promotion, the grace
 window, present-beats-ghost, lone arrivals, the idle window, the long think, the
-`party` / `named` / `public` split, and that two sessions do not share a table.
+`party` / `named` / `public` split, that two sessions do not share a table, and
+the resume rules -- a move is saved, a seat comes back to its account, a second
+connection does not take it, and a named or recent public room comes back on a
+fresh process.
 Run against the tic-tac-toe deck as it shipped BEFORE this kit existed, it
 reports six failures, all from one line that cleared the board when a seated
 player dropped.
 
 The rest of `testing.js` stands on its own:
 
-- `createSessionHarness(server, { mode, sessionId, deckId })` ->
+- `createSessionHarness(server, { mode, sessionId, deckId, storage })` ->
   `{ session, start(), join(playerId, identity?), leave(player),
-message(player, data), sent(playerId), last(playerId, match?), outbox }`. It
+message(player, data), shutdown(), sent(playerId), last(playerId, match?),
+outbox, storage }`. `join` and `leave` are async. It
   mirrors the real wrapper where it counts: roster timing around the callbacks,
   keying by playerId, and JSON round-tripping every message so a payload holding
   a live reference to server state arrives as a copy.
 - `createTestClock(startAt?)` -> `{ now, advance(ms), set(at), install(),
 uninstall() }`. `install()` points the kit's clock at it.
+- `createTestStorage()` -> deck storage in memory, with its rows readable at
+  `.rows`. Each harness makes its own; two harnesses handed the same one are two
+  processes of one deck. `settleStorage()` waits for the saves nobody awaited.
 
 It is not a transport. A two-client game over a real `castle-web serve` is still
 the thing that proves a deck -- `tic-tac-toe/tools/live.mjs` is a

package/kits/turn-based/castle.json

@@ -17,7 +17,7 @@
   "imports": {
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-10T00:57:31.408Z"
+      "version": "2026-09-10T20:21:12.665Z"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
@@ -28,7 +28,7 @@
   "autoUpdateWhenImported": true,
   "deckId": "K6-Xs7dCoMVi",
   "cardId": "Kh_08IYATpC3",
-  "publishedVersion": "2026-09-10T00:58:22.840Z",
+  "publishedVersion": "2026-09-10T20:28:55.394Z",
   "server": {
     "main": "code/server/index.js",
     "maxPlayers": 8,

package/kits/turn-based/code/behaviors/Board.jsx

@@ -3,8 +3,10 @@
 // multiplayer session, send square claims, tint actors and format status text.
 
 import { Multiplayer } from 'castle-web-sdk';
+import { avatarSpritePath } from '@imports/castle.physics-2d/engine/avatarArt';
 
-// Sprite tint multiplies these seat colors over each square's own artwork.
+// A claimed square shows its holder's avatar. Until that has loaded, or when the
+// holder has none, the seat's tint multiplies the square's own artwork instead.
 const SEAT_TINT = { A: '#ea323cff', B: '#0cf1ffff' };
 const UNCLAIMED_TINT = '#ffffffff';
 
@@ -130,10 +132,18 @@ function paintSquares(scene, state) {
   for (const squareActor of scene.actorsWith('Square')) {
     // Square.index selects the same slot in the server's sixteen-element array.
     const seat = state.squares[squareActor.components.Square.index];
-    // Sprite tint multiplies the editable `drawings/square.sprite` pixels.
-    // White preserves their colors; a seat tint displays the square's owner.
-    // A game with separate pieces can spawn piece actors over these square actors.
-    squareActor.components.Sprite.tint = seat ? SEAT_TINT[seat] : UNCLAIMED_TINT;
+    const sprite = squareActor.components.Sprite;
+
+    // The square's own art is remembered the first time, since `file` is
+    // swapped for an avatar below and back again when the square is cleared.
+    squareActor.runtime.squareFile ??= sprite.file;
+    const avatar = seat ? avatarSpritePath(scene, state.users?.[seat]) : null;
+    sprite.file = avatar ?? squareActor.runtime.squareFile;
+
+    // Sprite tint multiplies the pixels. White preserves their colors; a seat
+    // tint displays the owner of a square without an avatar. A game with
+    // separate pieces can spawn piece actors over these square actors.
+    sprite.tint = seat && !avatar ? SEAT_TINT[seat] : UNCLAIMED_TINT;
   }
 }
 

package/kits/turn-based/code/server/index.js

@@ -91,6 +91,7 @@ function stateFor(session, table, playerId) {
     turn: table.game.turn,
     winner: table.game.winner,
     names: table.seatNames(),
+    users: table.seatUsers(),
     watching: table.spectatorCount(session),
     you: table.seatOf(playerId),
   };
@@ -110,9 +111,10 @@ export default {
     room.table(session);
   },
 
-  onPlayerJoin(session, player) {
-    // Room.join restores or assigns a seat and may clear an idle table.
-    const { table } = room.join(session, player);
+  async onPlayerJoin(session, player) {
+    // Room.joinAsync reads the saved table on the first join, then restores or
+    // assigns a seat and may clear an idle table.
+    const { table } = await room.joinAsync(session, player);
 
     // New and cleared tables have null game state for the deck to initialize.
     if (!table.game) {
@@ -121,16 +123,26 @@ export default {
     pushState(session, table);
   },
 
-  onPlayerLeave(session, player) {
+  async onPlayerLeave(session, player) {
     // Room.leave releases the seat and may promote a spectator. It preserves
     // `table.game`, so remaining players continue the same game.
-    const { table } = room.leave(session, player);
+    const { table, saved } = room.leave(session, player);
     pushState(session, table);
+    await saved;
+  },
+
+  async onShutdown(session) {
+    await room.save(session);
   },
 
   onMessage(session, player, data) {
     // Room.table makes the table on demand, so no null check is needed here.
     const table = room.table(session);
+
+    // A message can arrive while the first join is still reading the saved table.
+    if (!table.game) {
+      return;
+    }
     // A sync request returns only to its sender and does not update activity.
     if (data?.type === 'sync') {
       session.send(player.playerId, stateFor(session, table, player.playerId));

package/kits/turn-based/package.json

@@ -6,7 +6,8 @@
     "restart": "node /Users/nikki/Development/castle-xyz/castle-experimental-web/cli/dist/index.js restart .",
     "screenshot": "node /Users/nikki/Development/castle-xyz/castle-experimental-web/cli/dist/index.js screenshot .",
     "save-deck": "node /Users/nikki/Development/castle-xyz/castle-experimental-web/cli/dist/index.js save-deck .",
-    "draw": "node imports/castle.physics-2d/scripts/draw.mjs"
+    "draw": "node imports/castle.physics-2d/scripts/draw.mjs",
+    "check": "eslint . && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
   },
   "dependencies": {
     "@codemirror/commands": "^6.10.3",

package/kits/turn-based/room.js

@@ -9,8 +9,12 @@
 // departure and promotes a watcher. Clearing happens on join, where there is
 // someone to hand a clean table to.
 //
-// Laid out as: the clock, then the room and its tables, then seats, then the
-// join and leave rules.
+// A table is also saved to deck storage, so a room comes back after the process
+// holding it ends. The kit stores `table.game` opaquely and still never reads
+// inside it.
+//
+// Laid out as: the clock, then storage, then the room and its tables, then
+// seats, then the join and leave rules.
 
 // --- the clock ------------------------------------------------------------
 //
@@ -23,6 +27,84 @@ export function setClock(fn) {
   readClock = fn ?? (() => Date.now());
 }
 
+// --- storage --------------------------------------------------------------
+//
+// One row per room in the server-owned deck scope: the deck's game, the seat
+// each account last held, and when the table was last played. Every public
+// shard shares one row; a named room and a party each have their own.
+//
+// A deck has storage only once it is published, and a serve brokers it as the
+// deck's creator. A kit served as its own deck has none; writes fail and are
+// logged.
+
+const STORAGE_PREFIX = 'table:';
+
+function storageKey(session) {
+  return STORAGE_PREFIX + (session.mode === 'public' ? 'public' : session.sessionId);
+}
+
+function deckStorage(session) {
+  return session.storage?.deck ?? null;
+}
+
+function logStorageFailure(what, error) {
+  console.error(`turn-based: table ${what} failed: ${error?.message ?? error}`);
+}
+
+// Saves run one after another, so a slow write cannot land on a newer one. The
+// returned promise never rejects.
+function saveTable(session, table) {
+  const storage = deckStorage(session);
+  if (!storage) {
+    return Promise.resolve();
+  }
+  const row = {
+    game: table.game ?? null,
+    seatsByUserId: Object.fromEntries(table.seatsByUserId),
+    lastActivityAt: table.lastActivityAt,
+  };
+  table.saving = table.saving
+    .then(() => storage.set({ [storageKey(session)]: row }))
+    .catch((error) => logStorageFailure('save', error));
+  return table.saving;
+}
+
+// Read once per table: the first join into a process pays for it.
+function restoreTable(settings, session, table) {
+  if (!table.restoring) {
+    table.restoring = readTable(settings, session, table);
+  }
+  return table.restoring;
+}
+
+// `named` and `party` always resume. A public room resumes only while its last
+// accepted move is inside `idleMs`.
+async function readTable(settings, session, table) {
+  const storage = deckStorage(session);
+  if (!storage) {
+    return;
+  }
+  const key = storageKey(session);
+  let row = null;
+  try {
+    row = (await storage.get([key]))?.[key] ?? null;
+  } catch (error) {
+    logStorageFailure('restore', error);
+    return;
+  }
+
+  // A game built while the read was in flight is the newer one.
+  if (!row || table.game) {
+    return;
+  }
+  if (session.mode === 'public' && readClock() - (row.lastActivityAt ?? 0) > settings.idleMs) {
+    return;
+  }
+  table.game = row.game ?? null;
+  table.seatsByUserId = new Map(Object.entries(row.seatsByUserId ?? {}));
+  table.lastActivityAt = row.lastActivityAt ?? table.lastActivityAt;
+}
+
 // --- the room -------------------------------------------------------------
 
 // `config`:
@@ -44,7 +126,15 @@ export function createRoom(config) {
   return {
     table,
     join: (session, player) => joinTable(table(session), settings, session, player),
+
+    // Reads the saved table first. `join` is the same without the read.
+    joinAsync: async (session, player) => {
+      await restoreTable(settings, session, table(session));
+      return joinTable(table(session), settings, session, player);
+    },
     leave: (session, player) => leaveTable(table(session), settings, session, player),
+    restore: (session) => restoreTable(settings, session, table(session)),
+    save: (session) => saveTable(session, table(session)),
   };
 }
 
@@ -55,14 +145,14 @@ function tableFor(tables, settings, session) {
   if (existing) {
     return existing;
   }
-  const table = createTable(settings, session.sessionId);
+  const table = createTable(settings, session);
   tables.set(session.sessionId, table);
   return table;
 }
 
-function createTable(settings, sessionId) {
+function createTable(settings, session) {
   const table = {
-    sessionId,
+    sessionId: session.sessionId,
 
     // The deck's own game, null until the deck makes one and again after a
     // clear. The kit never reads it.
@@ -75,19 +165,30 @@ function createTable(settings, sessionId) {
 
     // playerId -> { seat, holder, at }, for the grace window.
     departed: new Map(),
+
+    // userId -> seat, so a player coming back on a new connection finds it.
+    seatsByUserId: new Map(),
+
+    // The tail of the save chain, and the one read of the saved table.
+    saving: Promise.resolve(),
+    restoring: null,
   };
   return Object.assign(table, {
     seatOf: (playerId) => seatOf(table, playerId),
     playerAt: (seat) => table.seats[seat] ?? null,
     seatNames: () =>
       Object.fromEntries(settings.seats.map((seat) => [seat, table.seats[seat]?.name ?? null])),
+    seatUsers: () =>
+      Object.fromEntries(settings.seats.map((seat) => [seat, table.seats[seat]?.userId ?? null])),
     spectatorCount: (session) => spectatorCount(table, session),
 
     // Call this past every rejection, never before one. A refused message is not
     // a sign of life, and a client able to refresh the clock with junk could keep
     // a dead table alive indefinitely.
+    // Returns the save it starts, so a caller that can await one does.
     keepAlive: () => {
       table.lastActivityAt = readClock();
+      return saveTable(session, table);
     },
   });
 }
@@ -119,6 +220,14 @@ function seatEntry(settings, player) {
   };
 }
 
+// A `playerId` is a connection and does not survive a page load; the account
+// is what a returning player is found by.
+function rememberSeat(table, player, seat) {
+  if (typeof player.userId === 'string' && player.userId) {
+    table.seatsByUserId.set(player.userId, seat);
+  }
+}
+
 // A seat is held by a connection, not an account. One account joining twice
 // from two tabs is two players at the table.
 function takeSeat(settings, table, player) {
@@ -130,6 +239,7 @@ function takeSeat(settings, table, player) {
       continue;
     }
     table.seats[seat] = seatEntry(settings, player);
+    rememberSeat(table, player, seat);
     return seat;
   }
   return null;
@@ -161,31 +271,59 @@ function othersIn(session, player) {
 //
 // `playerId` survives a transport reconnect (see CLAUDE.md, "What a reconnect
 // is"), so a blipped connection comes back as the same player.
-function reclaimSeat(settings, table, player) {
+function reclaimSeat(settings, table, session, player) {
   // Still seated, so nothing was lost.
   if (seatOf(table, player.playerId)) {
     return true;
   }
+  const seat =
+    reclaimByConnection(settings, table, player) ??
+    reclaimByAccount(settings, table, session, player);
+  if (!seat) {
+    return false;
+  }
+  rememberSeat(table, player, seat);
+  return true;
+}
 
+// The seat this connection left, or null.
+function reclaimByConnection(settings, table, player) {
   const record = table.departed.get(player.playerId);
   if (!record) {
-    return false;
+    return null;
   }
 
   // The record is spent either way. A player who missed the window is an
   // arrival, and arriving twice should not consume a second grace period.
   table.departed.delete(player.playerId);
   if (readClock() - record.at > settings.graceMs) {
-    return false;
+    return null;
   }
 
   // A watcher was promoted into the seat while this player was away.
   if (table.seats[record.seat]) {
-    return false;
+    return null;
   }
 
   table.seats[record.seat] = record.holder;
-  return true;
+  return record.seat;
+}
+
+// The seat goes back to the account that held it, on whatever connection it
+// arrives on. A second connection from someone still seated finds the seat
+// taken and arrives as a stranger.
+function reclaimByAccount(settings, table, session, player) {
+  const seat = table.seatsByUserId.get(player.userId);
+  if (!seat || table.seats[seat]) {
+    return null;
+  }
+
+  // A public room hands a seat back only inside the idle window.
+  if (session.mode === 'public' && readClock() - table.lastActivityAt > settings.idleMs) {
+    return null;
+  }
+  table.seats[seat] = seatEntry(settings, player);
+  return seat;
 }
 
 // Called on both join and leave, so the map cannot grow across a long session.
@@ -244,6 +382,18 @@ function clearTable(settings, table, present) {
       table.seats[seat] = null;
     }
   }
+  rememberHeldSeats(settings, table);
+}
+
+// After a clear the account map names only the seats that survived it.
+function rememberHeldSeats(settings, table) {
+  table.seatsByUserId = new Map();
+  for (const seat of settings.seats) {
+    const holder = table.seats[seat];
+    if (holder) {
+      rememberSeat(table, holder, seat);
+    }
+  }
 }
 
 // Returns `{ table }`. A deck knows to build a fresh game from `table.game`
@@ -256,7 +406,7 @@ function joinTable(table, settings, session, player) {
   const others = othersIn(session, player);
 
   // Before the clear decision, which asks whether this is a return.
-  const returning = reclaimSeat(settings, table, player);
+  const returning = reclaimSeat(settings, table, session, player);
 
   if (shouldClear(settings, table, others, returning, session.mode)) {
     clearTable(settings, table, others);
@@ -268,7 +418,8 @@ function joinTable(table, settings, session, player) {
   return { table };
 }
 
-// Returns `{ table }`. It does not touch `game`; see the file header.
+// Returns `{ table, saved }`, where `saved` is the write this leave started. It
+// does not touch `game`; see the file header.
 function leaveTable(table, settings, session, player) {
   const seat = seatOf(table, player.playerId);
   if (seat) {
@@ -285,5 +436,5 @@ function leaveTable(table, settings, session, player) {
     takeSeat(settings, table, other);
   }
   pruneDeparted(settings, table);
-  return { table };
+  return { table, saved: saveTable(session, table) };
 }