castle-web-cli 0.4.171 → 0.4.173

package/dist/assetCompression.d.ts

@@ -0,0 +1,3 @@
+import type { Connect } from 'vite';
+/** Compress assets, never the token-bearing shell bootstrap or control API. */
+export declare function createAssetCompression(): Connect.NextHandleFunction;

package/dist/assetCompression.js

@@ -0,0 +1,30 @@
+import compression from 'compression';
+/** Compress assets, never the token-bearing shell bootstrap or control API. */
+export function createAssetCompression() {
+    // compression supports plain Node HTTP/Connect; its DefinitelyTyped signature
+    // unnecessarily requires Express request/response extensions.
+    return compression({
+        threshold: 1024,
+        filter(req, res) {
+            const requestPath = (req.url || '/').split('?')[0];
+            if ((req.method !== 'GET' && req.method !== 'HEAD') ||
+                requestPath === '/' ||
+                (requestPath.startsWith('/__castle/') &&
+                    !requestPath.startsWith('/__castle/ide/assets/')) ||
+                req.headers.range ||
+                res.hasHeader('Content-Range')) {
+                return false;
+            }
+            // Conditional responses must retain the representation's Vary header,
+            // but must never start a compressor or acquire a body.
+            if (res.statusCode === 304) {
+                if (res.getHeader('Vary') !== '*')
+                    res.appendHeader('Vary', 'Accept-Encoding');
+                return false;
+            }
+            return (res.statusCode === 200 &&
+                !String(res.getHeader('Content-Type')).startsWith('text/event-stream') &&
+                compression.filter(req, res));
+        },
+    });
+}

package/dist/castleJson.d.ts

@@ -1,4 +1,4 @@
-export declare const STARTER_STYLE_FILES: string[];
+export declare const STARTER_THEME_FILES: string[];
 export declare const IMPORTS_DIR = "imports";
 export interface DeckImport {
     deckId?: string;

package/dist/castleJson.js

@@ -5,7 +5,7 @@ import picomatch from 'picomatch';
 // module with no imports of its own, because both the import machinery and the
 // fork overlay need it and importing it from either of those would close a
 // cycle.
-// Root-level style files a kit ships as a deck's starting point, seeded into a
+// Root-level theme files a kit ships as a deck's starting point, seeded into a
 // deck at scaffold (init.ts `writeStarterTheme`) and when an import newly brings
 // them (imports.ts `seedKitTheme`).
 //
@@ -18,7 +18,7 @@ import picomatch from 'picomatch';
 // `theme.style` names the deck's font, `fonts.generated.js` is what carries that
 // face's bytes into the bundle, and a deck given the first without the second
 // renders in the fallback while claiming otherwise.
-export const STARTER_STYLE_FILES = ['theme.style', 'fonts.generated.js'];
+export const STARTER_THEME_FILES = ['theme.style', 'fonts.generated.js'];
 export const IMPORTS_DIR = 'imports';
 export const DEFAULT_STARTER_SCENE = 'scenes/main.scene';
 export const DEFAULT_SERVER_TICK_RATE = 20;

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/dist/imports.js

@@ -6,7 +6,7 @@ import { runTar } from './save-deck.js';
 import { normalizeDeckPackageJson } from './normalize.js';
 import { getKitsDir } from './localPaths.js';
 import { writePlatformDocs } from './platformDoc.js';
-import { ensureVisibleGlob, IMPORTS_DIR, STARTER_STYLE_FILES, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
+import { ensureVisibleGlob, IMPORTS_DIR, STARTER_THEME_FILES, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
 // Adding another deck as a dependency (`castle-web add-import`; removing one is a
 // later command). Deliberately NOT `get-deck`: that one
 // replaces THIS deck's own source from the server (and carries guards for the
@@ -614,7 +614,7 @@ function seedKitTheme(deckDir, alias, log) {
     if (typeof main !== 'string' || !main.trim())
         return;
     const seeded = [];
-    for (const name of STARTER_STYLE_FILES) {
+    for (const name of STARTER_THEME_FILES) {
         const src = path.join(importDir, name);
         const dest = path.join(deckDir, name);
         if (!fs.existsSync(src) || fs.existsSync(dest))

package/dist/init.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { CLAUDE_MD_PLATFORM_SECTION } from './platformDoc.js';
 import { installDeps } from './install.js';
-import { deckMainFile, deckStarterScene, STARTER_STYLE_FILES } from './castleJson.js';
+import { deckMainFile, deckStarterScene, STARTER_THEME_FILES } from './castleJson.js';
 import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, } from './imports.js';
 import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
 import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
@@ -309,7 +309,7 @@ export function writeStarterScene(projectDir, kitDir, alias) {
     fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
     writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), rewrite(scene));
 }
-// A kit may ship starter style files (deck-level styling: the color palette,
+// A kit may ship starter theme files (deck-level theme: the color palette,
 // the deck font). Like the starter scene, they are deck content: the engine
 // reads them from the DECK root, and they are the creator's to edit -- so they
 // get seeded once at scaffold time rather than living read-only in the import.
@@ -317,11 +317,11 @@ export function writeStarterScene(projectDir, kitDir, alias) {
 // kit file paths, so no ref rewriting). Exported for the same two scaffold paths
 // as writeStarterScene.
 //
-// The set is STARTER_STYLE_FILES (castleJson.ts), which says why these two
+// The set is STARTER_THEME_FILES (castleJson.ts), which says why these two
 // travel together: a deck given the record without the generated module renders
 // in the fallback while claiming otherwise.
 export function writeStarterTheme(projectDir, kitDir) {
-    for (const name of STARTER_STYLE_FILES) {
+    for (const name of STARTER_THEME_FILES) {
         const src = path.join(kitDir, name);
         const dest = path.join(projectDir, name);
         if (!fs.existsSync(src) || fs.existsSync(dest))

package/dist/serve.js

@@ -19,6 +19,7 @@ import { graphql as castleGraphql } from './api.js';
 import { executeCommand } from './castle-host/host.js';
 import { ServeSecurity } from './serveSecurity.js';
 import { isSameOriginUpgrade } from './wsOrigin.js';
+import { createAssetCompression } from './assetCompression.js';
 import { resolveServerConfig } from './castleJson.js';
 import { startDevSessionServer, } from './devSessionServer.js';
 // The log is a tail, not an archive: append, and once it passes the cap drop
@@ -315,6 +316,7 @@ window.__castleShellOrigin=(function(){
             },
         },
         configureServer(server) {
+            server.middlewares.use(createAssetCompression());
             server.middlewares.use((req, res, next) => {
                 const reqPath = (req.url || '/').split('?')[0];
                 const trustedSurface = req.headers['x-castle-sandbox-surface'];

package/dist/serveSecurity.d.ts

@@ -18,6 +18,7 @@ export declare class ServeSecurity {
     private readonly contentProxyToken;
     private readonly signingKey;
     private readonly serveNonce;
+    private contentGrantExpiresAtSeconds;
     private readonly pathKey;
     private readonly tickets;
     private localContentPorts;
@@ -50,6 +51,7 @@ export declare class ServeSecurity {
         editOrigin: string;
         playOrigin: string;
     };
+    private contentGrantExpiry;
     /**
      * Origin a browser should use for a local content role.
      *

package/dist/serveSecurity.js

@@ -6,6 +6,7 @@ const CROCKFORD = '0123456789abcdefghjkmnpqrstvwxyz';
 const CONTENT_LABEL_RE = /^1([ep])([0-9a-z]{1,4})-([a-z0-9]{14})-([0-9a-z]{1,8})-([0-9a-hjkmnp-tv-z]{13})-([0-9a-hjkmnp-tv-z]{20})$/;
 const MAX_GRANT_SECONDS = 12 * 60 * 60;
 const GRANT_CLOCK_SKEW_SECONDS = 60;
+const MIN_CONTENT_GRANT_REMAINING_SECONDS = 11 * 60 * 60;
 const BROWSER_GRANT_SECONDS = 3 * 60;
 export const MOBILE_HOST_PROTOCOL = '2';
 // A signature covers the request path and nothing else, so every path it can
@@ -79,6 +80,7 @@ export class ServeSecurity {
     contentProxyToken = randomBytes(32).toString('base64url');
     signingKey = process.env.CASTLE_AGENT_TOKEN || randomBytes(32).toString('base64url');
     serveNonce = base32Lower(randomBytes(8));
+    contentGrantExpiresAtSeconds = 0;
     pathKey = randomBytes(32).toString('base64url');
     tickets = new Map();
     localContentPorts;
@@ -284,9 +286,7 @@ window.fetch=function(input,init){
                 : cloud
                     ? 'sandboxes.castlexyz.com'
                     : null;
-        // Leave room for small positive clock skew at the control plane. Ghost still
-        // enforces the hard 12-hour maximum when it resolves the capability.
-        const expiresAtSeconds = Math.floor(Date.now() / 1000) + MAX_GRANT_SECONDS - GRANT_CLOCK_SKEW_SECONDS;
+        const expiresAtSeconds = cloud && contentDomain ? this.contentGrantExpiry() : 0;
         const originFor = (role) => {
             // Safari on macOS 15 asks DNS to resolve `*.localhost`, where it fails.
             // Dedicated loopback ports are still distinct browser origins and need no DNS.
@@ -297,6 +297,20 @@ window.fetch=function(input,init){
         };
         return { editOrigin: originFor('edit'), playOrigin: originFor('play') };
     }
+    contentGrantExpiry() {
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const latestExpiry = nowSeconds + MAX_GRANT_SECONDS - GRANT_CLOCK_SKEW_SECONDS;
+        // Expiry is part of the hostname: reuse it so reopening the shell can reuse
+        // the browser's module cache. Until open shells support automatic refresh,
+        // keep at least 11 hours for every new shell (about an hour of cache reuse).
+        // Already-open shells keep their old, still-valid grants until expiry.
+        // Also remint after a backwards clock jump rather than exceed Ghost's cap.
+        if (this.contentGrantExpiresAtSeconds - nowSeconds < MIN_CONTENT_GRANT_REMAINING_SECONDS ||
+            this.contentGrantExpiresAtSeconds > latestExpiry) {
+            this.contentGrantExpiresAtSeconds = latestExpiry;
+        }
+        return this.contentGrantExpiresAtSeconds;
+    }
     /**
      * Origin a browser should use for a local content role.
      *

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:32:33.371Z"
     },
     "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-10T22:05:16.080Z"
 }

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/server/sceneBodies.js

@@ -34,7 +34,7 @@ const DEFAULTS = {
   Collider: { friction: 0.1, frictionStatic: 0.5, bounciness: 0, density: 0.001, isTrigger: false },
   RigidBody: {
     bodyType: 'dynamic',
-    gravityScale: 1,
+    gravityScale: 0,
     drag: 0.01,
     angularDrag: 0,
     freezeRotation: false,

package/kits/multiplayer-2d/code/server/world.js

@@ -190,7 +190,7 @@ function patchBody(body, actor) {
   body.frictionStatic = collider.frictionStatic ?? 0.5;
   body.isSensor = Boolean(collider.isTrigger);
   body.frictionAir = rigid?.drag ?? 0.01;
-  body.plugin.gravityScale = rigid?.gravityScale ?? 1;
+  body.plugin.gravityScale = rigid?.gravityScale ?? 0;
   body.plugin.angularDrag = rigid?.angularDrag ?? 0;
 
   // Density sets mass, and only a dynamic body may have it: on a static one it
@@ -261,7 +261,7 @@ function applyGravity(sim) {
     if (body.isStatic) {
       continue;
     }
-    const scale = (body.plugin.gravityScale ?? 1) * GRAVITY_SCALE;
+    const scale = (body.plugin.gravityScale ?? 0) * GRAVITY_SCALE;
     body.force.x += body.mass * sim.gravity.x * scale;
     body.force.y += body.mass * sim.gravity.y * scale;
   }

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

@@ -96,6 +96,18 @@ class MultiplayerSystem {
       return void this.start();
     }
 
+    // The session ended under this connection (the server was replaced, or the
+    // platform closed it). Everything drawn from it goes, and the next frame
+    // joins afresh behind the overlay.
+    if (this.net.closed()) {
+      this.reset(scene);
+      this.net = null;
+      this.joined = false;
+      this.joinStartedAt = 0;
+      this.starting = false;
+      return;
+    }
+
     // Player is a behavior component on the actor controlled by this browser.
     const local = scene.actorWith('Player');
 
@@ -232,6 +244,7 @@ class MultiplayerSystem {
       }
       Avatars.showPlayer(this.avatars, scene, playerId, look.username ?? null, pose, {
         blueprint: look.blueprint,
+        userId: this.net.userId(playerId),
       });
     }
 
@@ -321,6 +334,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-2d/fonts.generated.js

@@ -1,4 +1,4 @@
-// Generated by the Style editor. Do not edit -- picking a font rewrites it.
+// Generated by the Theme editor. Do not edit -- picking a font rewrites it.
 //
 // `theme.style` records that this deck's font is DMSans; this module is what
 // puts DMSans's bytes in the published bundle. It has to name the face in a

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

@@ -30,7 +30,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.27",
+      "version": "0.4.28",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",

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

@@ -66,6 +66,11 @@ 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.** Every player's profile photo, the
+  local one included, is the texture on the four side faces of their model's
+  `head` part (`castle.physics-2d`'s `engine/avatarArt.js`, through
+  `User.get`). A player with no photo, or a model with no `head`, keeps the
+  model's own face.
 - **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:32:33.371Z"
     },
     "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:37:41.733Z",
       "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-10T22:05:24.002Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

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

@@ -1,9 +1,12 @@
-// Other-player actors and their floating name tags. This module creates actors
-// from deck blueprints, updates their network poses, and removes their scene
-// resources when players leave.
+// Other-player actors, their floating name tags, and the avatar on their head.
+// This module creates actors from deck blueprints, updates their network poses,
+// and removes their scene resources when players leave.
 
 import * as NameTags from './nameTags.js';
 import { applyPose } from './poses.js';
+import { artReady } from '@imports/castle.physics-2d/engine/art.js';
+import { avatarFacePath } from '@imports/castle.physics-2d/engine/avatarArt.js';
+import { makeShapeMesh } from '@imports/castle.physics-3d/engine3d/materials.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 +36,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 goes on the model's head.
 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.
@@ -48,17 +52,20 @@ export function showPlayer(avatars, scene, playerId, username, pose, options = {
   } else {
     showTag(avatars, scene, playerId, username, transform, options.tagHeight);
   }
+  dressHead(scene, actor.id, options.userId);
   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) {
+// Update the local player's label and head 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. Options are
+// `tagHeight` and `userId`, as for `showPlayer`.
+export function showSelf(avatars, scene, local, username, transform, options = {}) {
+  dressHead(scene, local?.id, options.userId);
   if (!username) {
     return;
   }
-  showTag(avatars, scene, 'self', username, transform, tagHeight);
+  showTag(avatars, scene, 'self', username, transform, options.tagHeight);
 }
 
 // Despawn the actor and dispose the tag of every player absent from `present`.
@@ -127,6 +134,32 @@ function showTag(avatars, scene, key, username, transform, tagHeight) {
   NameTags.moveNameTag(tag, transform, scene.three?.camera, tagHeight);
 }
 
+// Put the player's photo, square and edge to edge, on the four side faces of
+// their model's head. The part is the one named `head`, the same convention
+// `pxmodel.js` animates by; a model without one shows no avatar. The materials
+// are rebuilt once per picture, when its art has loaded.
+function dressHead(scene, actorId, userId) {
+  const path = avatarFacePath(scene, userId);
+  const head = scene.three?.nodes?.get(actorId)?.node.userData.modelParts?.get('head');
+  const mesh = head?.children.find((child) => child.userData.partMesh === 'head');
+  if (!path || !mesh || mesh.userData.avatarPath === path || !artReady(scene.sprites[path])) {
+    return;
+  }
+
+  // White under the picture, so the head's skin color does not tint it.
+  const { width, height, depth } = mesh.geometry.parameters;
+  const dressed = makeShapeMesh(
+    { kind: 'box', width, height, depth, color: '#ffffff', art: { sides: path, front: path } },
+    scene.sprites,
+  );
+  for (const material of [].concat(mesh.material)) {
+    material.dispose();
+  }
+  mesh.material = dressed.material;
+  dressed.geometry.dispose();
+  mesh.userData.avatarPath = path;
+}
+
 function dropTag(avatars, scene, key) {
   const tag = avatars.tags.get(key);
   if (tag) {

package/kits/multiplayer-3d/code/server/sceneBodies.js

@@ -31,7 +31,7 @@ const blueprintTexts = import.meta.glob(['/blueprints/*.scene', '/imports/*/blue
 const DEFAULTS = {
   Transform: { x: 0, y: 0, z: 0, rotationX: 0, rotationY: 0, rotationZ: 0 },
   Shape: { kind: 'box', width: 1, height: 1, depth: 1, radius: 0.5, solid: false },
-  Body: { type: 'fixed', friction: 0.6, restitution: 0, gravityScale: 1, lockRotations: false },
+  Body: { type: 'fixed', friction: 0.6, restitution: 0, gravityScale: 0, lockRotations: false },
   Door: { range: 3, slide: 2.1, speed: 2.5 },
 
   // `Ball` marks a fast-moving actor. `world.js` enables continuous collision

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

@@ -98,6 +98,19 @@ class MultiplayerSystem {
       showJoinOverlay(this.joiningOverlayWanted());
       return void this.start();
     }
+
+    // The session ended under this connection (the server was replaced, or the
+    // platform closed it). Everything drawn from it goes, and the next frame
+    // joins afresh behind the overlay.
+    if (this.net.closed()) {
+      this.reset(scene);
+      this.net = null;
+      this.joined = false;
+      this.joinStartedAt = 0;
+      this.starting = false;
+      this.sentState = '';
+      return;
+    }
     const local = scene.actorWith('Player');
 
     // Drain all queued messages before choosing the render time for this frame.
@@ -262,6 +275,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 +364,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, local, 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/multiplayer-3d/fonts.generated.js

@@ -1,4 +1,4 @@
-// Generated by the Style editor. Do not edit -- picking a font rewrites it.
+// Generated by the Theme editor. Do not edit -- picking a font rewrites it.
 //
 // `theme.style` records that this deck's font is DMSans; this module is what
 // puts DMSans's bytes in the published bundle. It has to name the face in a

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

@@ -32,7 +32,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.27",
+      "version": "0.4.28",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",