castle-web-cli 0.4.171 → 0.4.172

package/dist/devSessionServer.js

@@ -326,6 +326,15 @@ class DevSessionServerImpl {
             this.clearReadyWaiters();
             return;
         }
+        // A storage request is answered whenever it arrives. The session's `onStart`
+        // runs inside boot, before the child reports ready, and a read made there
+        // would otherwise never settle.
+        if (frame.t === 'storageRequest' &&
+            typeof frame.reqId === 'string' &&
+            typeof frame.op === 'string') {
+            void this.handleStorageRequest(frame.reqId, frame.op, asRecord(frame.args));
+            return;
+        }
         if (!this.runtimeReady)
             return;
         if (frame.t === 'sendTo' && typeof frame.playerId === 'string') {
@@ -359,11 +368,6 @@ class DevSessionServerImpl {
         else if (frame.t === 'kick' && typeof frame.playerId === 'string') {
             this.kick(frame.playerId, typeof frame.reason === 'string' ? frame.reason : undefined);
         }
-        else if (frame.t === 'storageRequest' &&
-            typeof frame.reqId === 'string' &&
-            typeof frame.op === 'string') {
-            void this.handleStorageRequest(frame.reqId, frame.op, asRecord(frame.args));
-        }
     }
     async handleStorageRequest(reqId, op, args) {
         const deckId = readCastleJson(this.projectDir)?.deckId;

package/kits/multiplayer-2d/CLAUDE.md

@@ -37,6 +37,10 @@ then `Smoothing.smooth(…)`. File names stay lowercase.
 - **What persists.** Object poses, each player's last pose by account, and
   whatever the optional `save(sim)` hook returns are written every ten seconds
   when something moved and at a clean shutdown. Nothing to configure.
+- **Players wear their Castle avatar.** A player's `Box` draws their profile
+  photo in the circle, turned to their facing (`castle.physics-2d`'s
+  `engine/avatarArt.js`, through `User.get`). A player with no photo keeps the
+  box's color and facing dot.
 - **A returning player starts where they left off.** A second connection from
   the same account while the first is still playing gets a new character at the
   spawn. The room is `session.sessionId`; every `public` shard shares one.

package/kits/multiplayer-2d/behaviors/Box.jsx

@@ -1,6 +1,9 @@
 // The Box behavior draws an actor as a filled rectangle with an optional facing
-// marker and label. The class declares editable properties first, then provides
-// the engine drawing methods and local canvas helpers.
+// marker and label. A player's actor carries their avatar on
+// `actor.runtime.avatar` (a canvas from the engine's `avatarArt.js`), and then
+// the box is that picture in a circle, turned to the facing. The class declares
+// editable properties first, then provides the engine drawing methods and local
+// canvas helpers.
 
 export class Box {
   // The engine registers behavior classes by this stable scene component name.
@@ -36,15 +39,19 @@ export class Box {
   draw(actor, scene, ctx) {
     const { x, y, width, height } = actor.components.Layout;
     ctx.save();
-    ctx.fillStyle = this.props.color;
     ctx.strokeStyle = this.props.edge;
     ctx.lineWidth = 2;
-    roundRect(ctx, x, y, width, height, this.props.radius);
-    ctx.fill();
-    ctx.stroke();
-
-    if (this.props.showFacing) {
-      this.drawFacing(ctx, x + width / 2, y + height / 2, Math.min(width, height) / 2);
+    const avatar = actor.runtime?.avatar;
+    if (avatar) {
+      this.drawAvatar(ctx, avatar, x + width / 2, y + height / 2, Math.min(width, height) / 2);
+    } else {
+      ctx.fillStyle = this.props.color;
+      roundRect(ctx, x, y, width, height, this.props.radius);
+      ctx.fill();
+      ctx.stroke();
+      if (this.props.showFacing) {
+        this.drawFacing(ctx, x + width / 2, y + height / 2, Math.min(width, height) / 2);
+      }
     }
     if (this.props.label) {
       this.drawLabel(ctx, scene, x + width / 2, y);
@@ -52,6 +59,22 @@ export class Box {
     ctx.restore();
   }
 
+  // Draw the avatar in a circle, rotated to the facing so the picture itself
+  // shows which way the player is moving.
+  drawAvatar(ctx, avatar, cx, cy, radius) {
+    ctx.save();
+    ctx.translate(cx, cy);
+    ctx.rotate(this.props.facing ?? 0);
+    ctx.beginPath();
+    ctx.arc(0, 0, radius, 0, Math.PI * 2);
+    ctx.clip();
+    ctx.drawImage(avatar, -radius, -radius, radius * 2, radius * 2);
+    ctx.restore();
+    ctx.beginPath();
+    ctx.arc(cx, cy, radius, 0, Math.PI * 2);
+    ctx.stroke();
+  }
+
   // Draw a marker toward the edge in the movement direction. The square body
   // has no other directional feature.
   drawFacing(ctx, cx, cy, reach) {

package/kits/multiplayer-2d/castle.json

@@ -15,11 +15,11 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-10T19:46:34.652Z"
+      "version": "2026-09-10T20:27:27.032Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-10T00:57:31.408Z"
+      "version": "2026-09-10T20:21:12.665Z"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
@@ -35,5 +35,5 @@
   },
   "deckId": "oiFu96LkwZ09",
   "cardId": "nkJgrvrCby3H",
-  "publishedVersion": "2026-09-10T20:10:36.784Z"
+  "publishedVersion": "2026-09-10T20:28:48.461Z"
 }

package/kits/multiplayer-2d/code/client/avatars.js

@@ -4,6 +4,9 @@
 // player behind them.
 
 import { applyCharacterPose } from './poses.js';
+import { avatarCanvas } from '@imports/castle.physics-2d/engine/avatarArt.js';
+
+export { avatarCanvas };
 
 // The blueprint spawned when the caller names none.
 const BLUEPRINT = 'blueprints/other-player.scene';
@@ -29,7 +32,8 @@ export function makeAvatars() {
 
 // Create or update one other player and return its actor. The multiplayer
 // system calls this once per other player per frame with the smoothed network
-// pose. A `username` of null draws no label.
+// pose. A `username` of null draws no label. Options are `blueprint`, the scene
+// to spawn from, and `userId`, whose avatar the Box draws.
 export function showPlayer(avatars, scene, playerId, username, pose, options = {}) {
   const blueprint = options.blueprint ?? defaultBlueprint(scene);
   const actor = ensureActor(avatars, scene, playerId, pose, blueprint);
@@ -40,6 +44,7 @@ export function showPlayer(avatars, scene, playerId, username, pose, options = {
     // A blueprint may omit Box; such an avatar still receives its Layout pose.
     actor.components.Box.label = username === null ? '' : shortName(username);
   }
+  actor.runtime.avatar = avatarCanvas(options.userId);
   return actor;
 }
 

package/kits/multiplayer-2d/code/systems/multiplayer.js

@@ -232,6 +232,7 @@ class MultiplayerSystem {
       }
       Avatars.showPlayer(this.avatars, scene, playerId, look.username ?? null, pose, {
         blueprint: look.blueprint,
+        userId: this.net.userId(playerId),
       });
     }
 
@@ -321,6 +322,7 @@ class MultiplayerSystem {
     if (local.components.Box) {
       local.components.Box.label = Avatars.shortName(this.net.status().you);
     }
+    local.runtime.avatar = Avatars.avatarCanvas(this.net.userId(this.net.selfId()));
   }
 
   // `[id, centre]` for every scene object the server has sent a pose for. The

package/kits/multiplayer-3d/CLAUDE.md

@@ -66,6 +66,10 @@ File names stay lowercase.
   move report when it changes, capped at 4 KB, and comes back in the WORLD
   snapshot before the Player behavior runs, which is how the camera angle and
   score return.
+- **Players wear their Castle avatar.** The name tag over every player,
+  the local one included, carries their profile photo and frame
+  (`castle.physics-2d`'s `engine/avatarArt.js`, through `User.get`). A player
+  with no photo gets the name alone.
 - **A returning player starts where they left off.** A second connection from
   the same account while the first is still playing gets a new character at the
   spawn. The room is `session.sessionId`; every `public` shard shares one.

package/kits/multiplayer-3d/castle.json

@@ -14,7 +14,7 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-10T19:46:34.652Z"
+      "version": "2026-09-10T20:27:27.032Z"
     },
     "castle.physics-3d": {
       "deckId": "JH0SclbPVP0y",
@@ -22,7 +22,7 @@
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-10T00:57:31.408Z",
+      "version": "2026-09-10T20:21:12.665Z",
       "via": "castle.physics-3d"
     },
     "castle.base": {
@@ -33,7 +33,7 @@
   "autoUpdateWhenImported": true,
   "deckId": "ZwA_P_-VO-Qh",
   "cardId": "bvRmCzyUpt_a",
-  "publishedVersion": "2026-09-10T20:10:41.318Z",
+  "publishedVersion": "2026-09-10T20:28:53.356Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

package/kits/multiplayer-3d/code/client/avatars.js

@@ -4,6 +4,7 @@
 
 import * as NameTags from './nameTags.js';
 import { applyPose } from './poses.js';
+import { avatarCanvas } from '@imports/castle.physics-2d/engine/avatarArt.js';
 
 // The blueprint spawned when a caller names none. A deck's own file wins; a deck
 // scaffolded from this kit has no blueprints yet, so the kit's copy stands in
@@ -33,7 +34,8 @@ export function makeAvatars() {
 //
 // A `username` of null draws no label. Options are `blueprint`, the scene to
 // spawn from (default `blueprints/other-player.scene`, the deck's own or the kit's),
-// and `tagHeight`, how far over the body the label floats.
+// `tagHeight`, how far over the body the label floats, and `userId`, whose
+// avatar the label carries.
 export function showPlayer(avatars, scene, playerId, username, pose, options = {}) {
   // The actor keeps the blueprint used at creation; `ensureActor` only spawns
   // when this player has no live actor in the current scene.
@@ -46,19 +48,20 @@ export function showPlayer(avatars, scene, playerId, username, pose, options = {
   if (username === null) {
     dropTag(avatars, scene, playerId);
   } else {
-    showTag(avatars, scene, playerId, username, transform, options.tagHeight);
+    showTag(avatars, scene, playerId, username, transform, options);
   }
   return actor;
 }
 
 // Update the local player's label over the engine's local Player actor. The SDK
 // roster can arrive several frames after connection, so an empty username
-// leaves the label absent until the roster supplies one.
-export function showSelf(avatars, scene, username, transform, tagHeight) {
+// leaves the label absent until the roster supplies one. Options are
+// `tagHeight` and `userId`, as for `showPlayer`.
+export function showSelf(avatars, scene, username, transform, options = {}) {
   if (!username) {
     return;
   }
-  showTag(avatars, scene, 'self', username, transform, tagHeight);
+  showTag(avatars, scene, 'self', username, transform, options);
 }
 
 // Despawn the actor and dispose the tag of every player absent from `present`.
@@ -106,20 +109,21 @@ function ensureActor(avatars, scene, playerId, pose, blueprint) {
   return spawned;
 }
 
-// Create a tag when the displayed text changes, then place it over the actor.
-// Each redraw allocates a canvas, texture, and sprite, so unchanged text reuses
-// the existing resources.
-function showTag(avatars, scene, key, username, transform, tagHeight) {
+// Create a tag when the displayed text or the avatar changes, then place it over
+// the actor. Each redraw allocates a canvas, texture, and sprite, so an unchanged
+// tag reuses the existing resources.
+function showTag(avatars, scene, key, username, transform, { tagHeight, userId } = {}) {
   const label = NameTags.shortName(username);
+  const avatar = avatarCanvas(userId);
   let tag = avatars.tags.get(key);
 
   // Compare against the shortened text stored on the tag. An
   // `anonymous-user-<uuid>` differs from the `anon-xxxxxx` string on the sprite.
-  if (!tag || tag.text !== label) {
+  if (!tag || tag.text !== label || tag.avatar !== avatar) {
     if (tag) {
       NameTags.disposeNameTag(scene.three, tag);
     }
-    tag = NameTags.makeNameTag(scene.three, label);
+    tag = NameTags.makeNameTag(scene.three, label, avatar);
     avatars.tags.set(key, tag);
   }
 

package/kits/multiplayer-3d/code/client/nameTags.js

@@ -1,6 +1,8 @@
-// Floating username-label sprites for other players and the local player. This module
-// draws text to a canvas, attaches the resulting sprite directly to the engine's
-// three.js scene, scales it by camera distance, and disposes its GPU resources.
+// Floating name tags for other players and the local player: the player's round
+// avatar over their username. This module draws them to a canvas, attaches the
+// resulting sprite directly to the engine's three.js scene, scales it by camera
+// distance, and disposes its GPU resources. A sprite always faces the camera,
+// so the avatar reads from every side.
 
 import * as THREE from 'three';
 
@@ -8,6 +10,11 @@ import * as THREE from 'three';
 const HEIGHT_ABOVE = 1.25;
 const PIXELS_PER_UNIT = 200;
 
+// Canvas pixels of the name pill, and of the avatar drawn above it.
+const LABEL_PX = 68;
+const AVATAR_PX = 112;
+const GAP_PX = 8;
+
 // The distance at which the label is the size it was drawn to be: 68 canvas
 // pixels over 200 per unit is 0.34m, which on a 500x700 card at fov 55 is 29px.
 // This reference distance matches the common camera placement in kit decks.
@@ -16,11 +23,12 @@ const SAME_SIZE_M = 8;
 // The minimum scale keeps a label readable when the camera is near the player.
 const MIN_SCALE = 0.35;
 
-// Create `{ sprite, text, width, height }` and add the sprite to the engine's
-// three.js scene. The engine actor-to-mesh sync does not update these directly
-// attached sprites, so callers move them each frame with `moveNameTag`.
-export function makeNameTag(world, text) {
-  const canvas = drawLabel(text);
+// Create `{ sprite, text, avatar, width, height, lift }` and add the sprite to
+// the engine's three.js scene. `avatar` is the canvas from `avatarArt.js`, or
+// null for a name alone. The engine actor-to-mesh sync does not update these
+// directly attached sprites, so callers move them each frame with `moveNameTag`.
+export function makeNameTag(world, text, avatar = null) {
+  const canvas = drawLabel(text, avatar);
   const texture = new THREE.CanvasTexture(canvas);
   texture.colorSpace = THREE.SRGBColorSpace;
   const sprite = new THREE.Sprite(
@@ -41,8 +49,11 @@ export function makeNameTag(world, text) {
   world.scene.add(sprite);
 
   // `text` is the string actually drawn, not the username it came from. The
-  // caller compares against it to decide whether a name changed.
-  return { sprite, text, width, height };
+  // caller compares against it, and against `avatar`, to decide whether to
+  // redraw. `lift` raises the sprite's centre so the name pill stays at
+  // `heightAbove` when an avatar is stacked over it.
+  const lift = (height - LABEL_PX / PIXELS_PER_UNIT) / 2;
+  return { sprite, text, avatar, width, height, lift };
 }
 
 // Move and scale a tag after its player pose is drawn for the current frame.
@@ -61,6 +72,7 @@ export function moveNameTag(tag, transform, camera, heightAbove = HEIGHT_ABOVE)
   // 0.8m 286px -> 100, 2m 114px -> 40, 4m 57px -> 29, 8m 29px -> 29, 20m 11 -> 11.
   const scale = Math.max(MIN_SCALE, Math.min(1, away / SAME_SIZE_M));
   tag.sprite.scale.set(tag.width * scale, tag.height * scale, 1);
+  tag.sprite.position.y += tag.lift * scale;
 }
 
 // Remove a tag from the three.js scene and release its texture and material.
@@ -78,24 +90,31 @@ export function shortName(username) {
   return anon ? `anon-${anon[1].replace(/-/g, '').slice(-6)}` : (username ?? 'player');
 }
 
-// Rasterize one display name into the canvas used as the sprite texture.
-function drawLabel(text) {
+// Rasterize one display name, with the avatar centred above it, into the canvas
+// used as the sprite texture.
+function drawLabel(text, avatar) {
   const canvas = document.createElement('canvas');
   const ctx = canvas.getContext('2d');
   const font = '600 44px Inter, system-ui, sans-serif';
   ctx.font = font;
-  const width = Math.ceil(ctx.measureText(text).width) + 40;
+  const pillWidth = Math.ceil(ctx.measureText(text).width) + 40;
+  const width = avatar ? Math.max(pillWidth, AVATAR_PX) : pillWidth;
+  const top = avatar ? AVATAR_PX + GAP_PX : 0;
 
   // Canvas resizing clears the context state, so measure before resizing and
   // restore the font before drawing.
   canvas.width = width;
-  canvas.height = 68;
+  canvas.height = top + LABEL_PX;
   ctx.font = font;
+  if (avatar) {
+    ctx.drawImage(avatar, (width - AVATAR_PX) / 2, 0, AVATAR_PX, AVATAR_PX);
+  }
+  const left = (width - pillWidth) / 2;
   ctx.fillStyle = 'rgba(12,12,16,0.72)';
-  ctx.roundRect(0, 0, width, 68, 16);
+  ctx.roundRect(left, top, pillWidth, LABEL_PX, 16);
   ctx.fill();
   ctx.fillStyle = '#f2f2f5';
   ctx.textBaseline = 'middle';
-  ctx.fillText(text, 20, 36);
+  ctx.fillText(text, left + 20, top + LABEL_PX / 2);
   return canvas;
 }

package/kits/multiplayer-3d/code/systems/multiplayer.js

@@ -262,6 +262,7 @@ class MultiplayerSystem {
       }
       Avatars.showPlayer(this.avatars, scene, playerId, look.username ?? null, pose, {
         blueprint: look.blueprint,
+        userId: this.net.userId(playerId),
       });
     }
     Avatars.dropMissing(this.avatars, scene, others);
@@ -350,7 +351,9 @@ class MultiplayerSystem {
     if (this.net.sendMove(Poses.packMove(me), owned, claims, releases, state) && state) {
       this.sentState = stateJson;
     }
-    Avatars.showSelf(this.avatars, scene, this.net.status().you, me);
+    Avatars.showSelf(this.avatars, scene, this.net.status().you, me, {
+      userId: this.net.userId(this.net.selfId()),
+    });
   }
 
   // Return `[id, Transform]` for every scene object known from server snapshots.

package/kits/physics-2d/castle.json

@@ -72,7 +72,7 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-09-10T20:09:53.271Z",
+  "publishedVersion": "2026-09-10T20:28:41.310Z",
   "imports": {
     "castle.base": {
       "deckId": "yRcmH4_aYllE",

package/kits/physics-2d/engine/avatarArt.js

@@ -0,0 +1,91 @@
+// A player's round avatar for drawing in a scene: the photo clipped to a circle
+// with their frame over it, as a canvas. Read through `User.get` once per user
+// id and kept for the page. A player with no photo has no avatar, and a caller
+// keeps its default look.
+//
+// `avatarCanvas` is for code that draws with a canvas context, like a name tag.
+// `avatarSpritePath` registers the same picture as image art in `scene.sprites`,
+// so a `Sprite` component can show it by file path.
+
+import { User } from 'castle-web-sdk';
+import { imageArt } from './art';
+
+const SIZE = 128;
+
+// A frame is drawn around a photo two thirds its size, the proportion Castle's
+// own profile views use.
+const FRAMED_INSET = SIZE / 6;
+
+// userId -> { canvas }, present from the first ask; `canvas` fills in when the
+// read completes.
+const avatars = new Map();
+
+// The avatar for one user id, or null until it is loaded or when there is none.
+export function avatarCanvas(userId) {
+  if (!userId) {
+    return null;
+  }
+  let entry = avatars.get(userId);
+  if (!entry) {
+    entry = { canvas: null };
+    avatars.set(userId, entry);
+    void load(userId, entry);
+  }
+  return entry.canvas;
+}
+
+// The `scene.sprites` path holding this user's avatar, or null while there is
+// none. A `Sprite` with this `file` draws it.
+export function avatarSpritePath(scene, userId) {
+  const canvas = avatarCanvas(userId);
+  if (!canvas) {
+    return null;
+  }
+  const path = `avatars/${userId}.png`;
+  if (!scene.sprites[path]) {
+    scene.sprites[path] = imageArt(path, canvas.toDataURL());
+  }
+  return path;
+}
+
+async function load(userId, entry) {
+  try {
+    const user = await User.get(userId);
+    const [photo, frame] = await Promise.all([loadImage(user?.photoUrl), loadImage(user?.frameUrl)]);
+    if (photo) {
+      entry.canvas = compose(photo, frame);
+    }
+  } catch {
+    // A failed read leaves the entry without a canvas; the next page asks again.
+  }
+}
+
+function loadImage(url) {
+  if (!url) {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => resolve(null);
+    image.src = url;
+  });
+}
+
+function compose(photo, frame) {
+  const canvas = document.createElement('canvas');
+  canvas.width = SIZE;
+  canvas.height = SIZE;
+  const ctx = canvas.getContext('2d');
+  const inset = frame ? FRAMED_INSET : 0;
+  ctx.save();
+  ctx.beginPath();
+  ctx.arc(SIZE / 2, SIZE / 2, SIZE / 2 - inset, 0, Math.PI * 2);
+  ctx.clip();
+  ctx.drawImage(photo, inset, inset, SIZE - 2 * inset, SIZE - 2 * inset);
+  ctx.restore();
+  if (frame) {
+    ctx.drawImage(frame, 0, 0, SIZE, SIZE);
+  }
+  return canvas;
+}

package/kits/real-time/castle.json

@@ -15,5 +15,5 @@
   "autoUpdateWhenImported": true,
   "deckId": "xFVr-afOLuUQ",
   "cardId": "w6G45sy3_P_m",
-  "publishedVersion": "2026-09-10T20:10:30.302Z"
+  "publishedVersion": "2026-09-10T20:28:42.134Z"
 }

package/kits/real-time/code/client/connection.js

@@ -12,6 +12,7 @@ const SEND_MS = 1000 / Messages.MOVE_HZ;
 //   connection  the SDK connection
 //   inbox       arrived messages, each with `localMs` added
 //   roster      playerId -> username, as the platform last reported it
+//   userIds     playerId -> userId, from the same roster
 //   you         the SDK's entry for the local player, null until a roster has it
 //   sentAt      `performance.now()` of the last move, so sends stay at MOVE_HZ
 //   claims      ids asked for since the last send, held until it goes
@@ -21,6 +22,7 @@ function makeNet(connection) {
     connection,
     inbox: [],
     roster: new Map(),
+    userIds: new Map(),
     you: null,
     sentAt: 0,
     claims: new Set(),
@@ -48,6 +50,7 @@ export async function connectSession({ onLog = () => {} } = {}) {
 
     // Replace the map from the complete SDK roster so departures disappear.
     net.roster = new Map(players.map((player) => [player.playerId, player.username]));
+    net.userIds = new Map(players.map((player) => [player.playerId, player.userId]));
     net.you = you;
   });
 
@@ -61,6 +64,9 @@ export async function connectSession({ onLog = () => {} } = {}) {
     // A stable fallback until the SDK roster includes this player.
     username: (playerId) => net.roster.get(playerId) ?? 'player',
 
+    // The account behind a player, for `User.get`; null until the roster has it.
+    userId: (playerId) => net.userIds.get(playerId) ?? null,
+
     // Every other player's roster entry. The local player is simulated by this client,
     // so the deck draws only these from network samples.
     others: () => new Map([...net.roster].filter(([id]) => id !== connection.playerId)),

package/kits/real-time/code/server/session.js

@@ -80,12 +80,18 @@ function newServer(parts) {
 export function makeSession(parts) {
   const server = newServer(parts);
 
-  // Castle's handlers remain available while `createSimulation` is pending.
+  // Castle's handlers remain available while `createSimulation` is pending. A
+  // build that fails is logged here; `buildWorld` sees the same rejection when
+  // the first tick awaits it.
   server.building = server.world.createSimulation();
+  server.building.catch((err) => {
+    console.error(`[${server.label}] simulation failed to build: ${err?.stack ?? err}`);
+  });
   return {
-    onStart(session) {
-      attach(server, session);
-    },
+    // The world is built from the first tick or join, not here: `onStart` runs
+    // while the process is still booting, and a storage read made then can go
+    // unanswered.
+    onStart() {},
 
     // Joins are logged here; the simulation's players are reconciled from the
     // full session roster on the next tick.
@@ -124,8 +130,8 @@ export function makeSession(parts) {
   };
 }
 
-// Keep the first session a callback carries and build the world with it. The
-// room the session persists under is not known before this.
+// Keep the first session a tick or join carries and build the world with it.
+// The room the session persists under is not known before this.
 function attach(server, session) {
   if (server.session) {
     return;

package/kits/turn-based/CLAUDE.md

@@ -41,6 +41,10 @@ This kit adds no engine and no editors. What it holds:
   `{ 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

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-10T20:10:44.202Z",
+  "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),
   };

package/kits/turn-based/room.js

@@ -178,6 +178,8 @@ function createTable(settings, session) {
     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.171",
+  "version": "0.4.172",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"