castle-web-cli 0.4.169 → 0.4.171

package/kits/base/sdk/transport.js

@@ -7,7 +7,7 @@
 //   - web     → window.parent.postMessage; responses via 'message' events
 //   - local   → the castle-web serve dev server, over runtime.ts's websocket
 // Error reconstruction is uniform here so callers always get a CastleError.
-import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, unloadRequestId, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { sendLocalCommand } from "./runtime";
@@ -22,6 +22,7 @@ const INTERACTIVE_COMMANDS = new Set([
 let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
+let unloadHandler = null;
 export async function hostRequest(command, params) {
     try {
         const channel = resolveChannel();
@@ -67,6 +68,26 @@ export function hostNotify(event) {
     };
     sendEnvelope(channel, envelope);
 }
+// Reply to a host unload request. One-way like hostNotify, but it carries the
+// handshake's whole point, so it posts even with no state: the host is holding
+// its teardown open until this arrives or its cap runs out.
+export function postUnloadDone(unloadId, state) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        unloadDone: state === undefined ? { unloadId } : { unloadId, state },
+    };
+    sendEnvelope(channel, envelope);
+}
+// Registered by unloadHandshake.ts rather than imported from it, so this module
+// keeps no dependency on the one that depends on it.
+export function setUnloadHandler(handler) {
+    unloadHandler = handler;
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -82,7 +103,7 @@ function resolveChannel() {
     return window.parent && window.parent !== window ? "web" : "local";
 }
 function postCommand(channel, command, params) {
-    installResponseListener();
+    installHostListener();
     const requestId = `csdk_${nextRequestId++}`;
     return new Promise((resolve, reject) => {
         const timeout = INTERACTIVE_COMMANDS.has(command)
@@ -106,15 +127,28 @@ function sendEnvelope(channel, envelope) {
 }
 // The mobile host can't dispatch a DOM 'message' event, so it calls this global
 // directly with the parsed envelope. The web host posts a 'message' event.
-function installResponseListener() {
+//
+// Exported because a deck that only registers an unload subscriber never posts a
+// command, and without this the global would never exist — the host's inject
+// would land on nothing and its handshake would run out its cap in silence.
+export function installHostListener() {
     if (listenersInstalled || typeof window === "undefined")
         return;
     listenersInstalled = true;
-    window.__castleSdkHost = { receive: (message) => settle(message) };
+    window.__castleSdkHost = { receive: (message) => receive(message) };
     window.addEventListener("message", (event) => {
-        settle(event.data);
+        receive(event.data);
     });
 }
+function receive(message) {
+    if (isResponseEnvelope(message)) {
+        settle(message);
+        return;
+    }
+    const unloadId = unloadRequestId(message);
+    if (unloadId !== null)
+        unloadHandler?.(unloadId);
+}
 function settle(message) {
     if (!isResponseEnvelope(message))
         return;

package/kits/base/sdk/unloadHandshake.d.ts

@@ -0,0 +1,6 @@
+export interface UnloadContext {
+    state?: string;
+}
+export type UnloadSubscriber = (ctx: UnloadContext) => void;
+export declare function onHostUnload(subscriber: UnloadSubscriber): () => void;
+export declare function notifyUnloadInterest(): void;

package/kits/base/sdk/unloadHandshake.js

@@ -0,0 +1,47 @@
+// The host-driven half of "this page is about to go away".
+//
+// `unloadFlush.ts` is the browser-event half — pagehide / visibilitychange,
+// which a deck's own document raises. This one is the host's: an RN WebView
+// being torn down on a feed swipe never raises those reliably, so the mobile
+// host sends an explicit unload request first and holds its teardown open,
+// briefly, for the reply.
+//
+// Subscribers run synchronously and the reply goes out in the same tick. That
+// is the contract that makes the host's wait short: it is waiting on one
+// postMessage, not on whatever work a subscriber might want to do. A subscriber
+// with host-bound work of its own must post it BEFORE returning — deck→host
+// messages are FIFO per WebView, so anything posted first arrives first.
+import { hostNotify, installHostListener, postUnloadDone, setUnloadHandler } from "./transport";
+const subscribers = new Set();
+let installed = false;
+let interestSent = false;
+export function onHostUnload(subscriber) {
+    subscribers.add(subscriber);
+    if (!installed) {
+        installed = true;
+        installHostListener();
+        setUnloadHandler(runHandshake);
+    }
+    return () => subscribers.delete(subscriber);
+}
+// Tells the host this deck has something to hand over, so it runs the handshake
+// (and pays its bounded wait) for this deck instead of skipping it. Sent once;
+// the host doesn't care which subscriber prompted it.
+export function notifyUnloadInterest() {
+    if (interestSent)
+        return;
+    interestSent = true;
+    hostNotify("unloadInterest");
+}
+function runHandshake(unloadId) {
+    const ctx = {};
+    for (const subscriber of subscribers) {
+        try {
+            subscriber(ctx);
+        }
+        catch (error) {
+            console.warn("Castle unload subscriber threw.", error);
+        }
+    }
+    postUnloadDone(unloadId, ctx.state);
+}

package/kits/base/sdk/user.d.ts

@@ -3,8 +3,12 @@ export interface CastleUser {
     username: string;
     isAnonymous: boolean;
     isActive: boolean;
+    photoUrl: string | null;
+    frameUrl: string | null;
+    color: string | null;
 }
 export interface CastleUserApi {
     getCurrent(): Promise<CastleUser>;
+    get(userId: string): Promise<CastleUser | null>;
 }
 export declare const User: CastleUserApi;

package/kits/base/sdk/user.js

@@ -2,8 +2,12 @@ import { CastleError } from "./errors";
 import { hostRequest } from "./transport";
 let currentUser = null;
 let currentUserPromise = null;
+// Profiles by user id. A profile changes rarely, and a multiplayer deck asks for
+// the same few ids every time a player joins.
+const profiles = new Map();
 export const User = {
     getCurrent,
+    get,
 };
 async function getCurrent() {
     if (currentUser)
@@ -25,15 +29,46 @@ async function fetchCurrentUser() {
         });
     }
     const username = requiredString(user.username, "user.username", operation);
+    const userId = requiredString(user.userId, "user.userId", operation);
+    // The host answers identity from what it already knows. The profile fields
+    // come from the same read `get` does; a host that predates that command
+    // leaves them null.
+    const profile = await get(userId).catch(() => null);
     return {
-        userId: requiredString(user.userId, "user.userId", operation),
+        userId,
         username,
         // A host that predates the flag omits it; anonymous account usernames are
         // always minted as `anonymous-user-<uuid>`, so the prefix is the fallback.
         isAnonymous: user.isAnonymous === true || username.toLowerCase().startsWith("anonymous-user-"),
         isActive: true,
+        photoUrl: profile?.photoUrl ?? null,
+        frameUrl: profile?.frameUrl ?? null,
+        color: profile?.color ?? null,
     };
 }
+// One user by id, or null when no such user exists. Throws `CastleError` on a
+// host that predates the command (`UNKNOWN_COMMAND`).
+async function get(userId) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "User.get(userId) needs a user id.",
+            operation: "User.get",
+        });
+    }
+    let pending = profiles.get(userId);
+    if (!pending) {
+        pending = fetchProfile(userId);
+        profiles.set(userId, pending);
+        // A failed read is not kept, so the next call asks again.
+        pending.catch(() => profiles.delete(userId));
+    }
+    return pending;
+}
+async function fetchProfile(userId) {
+    const { user } = await hostRequest("user.get", { userId });
+    return user ? { ...user, isActive: true } : null;
+}
 function requiredString(value, field, operation) {
     if (typeof value === "string" && value.length > 0)
         return value;

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

@@ -30,10 +30,19 @@ then `Smoothing.smooth(…)`. File names stay lowercase.
   builds a matter world from the deck's own `scenes/main.scene` and steps it at
   `tickRate` (30). Never fork it.
 - **A game is added as hooks, not by replacing anything.** Write
-  `code/server/game.js` with a default export of up to six functions --
+  `code/server/game.js` with a default export of up to six gameplay functions --
   `ready(sim)`, `message(session, player, data)`, `place(sim, handovers)`,
   `step(sim, handovers)`, `join(sim)`, `delta(sim)` -- and it is found by glob.
   `code/client/game.js` is the browser half. Both optional.
+- **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.
+- **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.
+- `restore(sim, saved)` receives the last `save` result before `ready`. Storage
+  is keyed by deck, so the deck must be published; `castle-web serve` brokers it
+  as the deck's creator.
 - `place` runs BEFORE the physics step; a write that only reaches a body at the
   next step belongs there. `delta` returning news is its own reason to broadcast,
   so a tick where nothing moved but a round ended still reaches players.
@@ -55,8 +64,9 @@ then `Smoothing.smooth(…)`. File names stay lowercase.
 - The kit ships `code/systems/multiplayer.js`, the frame loop. A deck that writes
   its own file of that path gets its own instead; most decks should not.
 - Two players is the test that matters: `castle-web serve`, then the play URL in
-  two tabs. The session process holds the room, so restart the serve for a fresh
-  one.
+  two tabs. The room persists in deck storage across serve restarts; a fresh one
+  means removing its `world:<room>`, `game:<room>` and `player:<room>:*` rows
+  (the local serve's room is `dev`).
 
 ## Layout
 
@@ -137,11 +147,13 @@ and then, all optional, all found by root-anchored glob in
 | `code/server/game.js`           | the game, as six hooks on a default export          |
 | `code/server/deckComponents.js` | `export const componentDefaults = { Cargo: {...} }` |
 
-The kit draws no HUD, with one exception: when the join fell back to solo,
+The kit draws no HUD, with two exceptions. When the join fell back to solo,
 `castle.real-time`'s `soloBadge.js` shows a small fixed badge naming why
 (`status().soloReason`: a private deck, no published server, or plain
 unavailable), so a creator testing their own deck is told rather than left to
-guess. A deck's `soloBadge(status)` client hook hides (`false`) or rewords it.
+guess; a deck's `soloBadge(status)` client hook hides (`false`) or rewords it.
+While joining, its `joinOverlay.js` covers the card with "Joining…" until the
+session's first snapshot places the player, ten seconds at most.
 
 The six server hooks: `ready(sim)`, `message(session, player, data)`,
 `place(sim, handovers)`, `step(sim, handovers)`, `join(sim)`, `delta(sim)`.
@@ -156,10 +168,9 @@ node ../../cli/dist/index.js serve . --port 5762 --detach
 node test/two-client-test.mjs
 ```
 
-The session process holds the room's state, so crates stay where the last run
-pushed them. Restart the serve for a fresh room. Each client publishes what it
-believes about the room on `globalThis.__multiplayer`, which is what the test
-reads.
+The room's state persists, so crates stay where the last run pushed them. Each
+client publishes what it believes about the room on `globalThis.__multiplayer`,
+which is what the test reads.
 
 ## Rules for editing this kit
 

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

@@ -15,15 +15,15 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-05T01:31:28.578Z"
+      "version": "2026-09-10T19:46:34.652Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-01T01:02:46.041Z"
+      "version": "2026-09-10T00:57:31.408Z"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-05T01:31:11.287Z"
+      "version": "2026-09-10T00:56:59.388Z"
     }
   },
   "autoUpdateWhenImported": true,
@@ -35,5 +35,5 @@
   },
   "deckId": "oiFu96LkwZ09",
   "cardId": "nkJgrvrCby3H",
-  "publishedVersion": "2026-09-05T01:32:45.261Z"
+  "publishedVersion": "2026-09-10T20:10:36.784Z"
 }

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

@@ -17,16 +17,21 @@ import { addBody } from './world.js';
 //   facing   radians, as the client sent them
 //   clamped  true only on the tick a move was refused
 //   movedAt  the simulation time of that acceptance
-function newPlayer(entry, at) {
+//   settled  whether this connection has ever reported a pose the server took
+function newPlayer(entry, at, movedAt) {
   // Spread the body's offset data beside the report-validation state.
-  return { ...entry, at, facing: 0, clamped: false, movedAt: 0 };
+  return { ...entry, at, facing: 0, clamped: false, movedAt, settled: false };
 }
 
 // Add a character body for a session player. world.step writes `player.at`
 // before each physics step. The engine represents a kinematic body as a static
 // Matter body moved through explicit position writes.
-export function addPlayer(sim, playerId) {
-  const at = spawnPoint(sim);
+//
+// `pose` is where a returning player left off, as `[x, y, facing]`. Without one
+// the character starts on the spawn ring.
+export function addPlayer(sim, playerId, pose) {
+  const resumed = pose ? Limits.readPoint(pose) : null;
+  const at = resumed ?? spawnPoint(sim);
   const template = sim.template?.components;
 
   // Reuse the authored Player shape and material while forcing the server body
@@ -40,8 +45,15 @@ export function addPlayer(sim, playerId) {
     },
   };
 
-  // addBody returns the centre offset needed to translate Layout reports.
-  sim.players.set(playerId, newPlayer(addBody(sim, actor), at));
+  // addBody returns the centre offset needed to translate Layout reports. The
+  // movement allowance runs from now: a body that starts where a player left off
+  // would otherwise let that player's first report cover half a second of travel
+  // back to wherever their own copy of the scene put them.
+  const player = newPlayer(addBody(sim, actor), at, sim.timeMs);
+  if (resumed) {
+    player.facing = number(pose[2]);
+  }
+  sim.players.set(playerId, player);
 }
 
 // Remove a departing player's body and its entry.
@@ -82,6 +94,15 @@ export function setPose(sim, playerId, message) {
     // An accepted move becomes the target written before the next Matter step.
     player.at = asked;
     player.clamped = false;
+    player.settled = true;
+    return;
+  }
+
+  // The first report moves nothing. A client starts its own character from the
+  // scene and does not know yet where the session put this player, so the server
+  // position stands until the client has agreed with it once.
+  if (!player.settled) {
+    player.clamped = true;
     return;
   }
 

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

@@ -9,7 +9,7 @@ import {
   pointsBounds,
 } from '@imports/castle.physics-2d/engine/collider.js';
 import { packPose } from '../client/poses.js';
-import { MAX_STEPS_PER_TICK, STEP } from '@imports/castle.real-time/code/server/limits.js';
+import { MAX_STEPS_PER_TICK, STEP, number } from '@imports/castle.real-time/code/server/limits.js';
 import { readScene } from './sceneBodies.js';
 import * as Limits from './limits.js';
 
@@ -326,6 +326,29 @@ export function objectPoses(sim) {
   return out;
 }
 
+// Put saved poses back on the bodies they were read from. An id the scene no
+// longer has is skipped. Velocities are cleared: a restored body starts at rest.
+// Returns how many poses were applied.
+export function restorePoses(sim, poses) {
+  let applied = 0;
+  for (const pose of poses) {
+    const entry = sim.objects.get(pose?.[0]);
+    const at = entry ? Limits.readPoint(pose.slice(1)) : null;
+    if (!at) {
+      continue;
+    }
+    Matter.Body.setPosition(entry.body, {
+      x: at.x + entry.offset.dx,
+      y: at.y + entry.offset.dy,
+    });
+    Matter.Body.setAngle(entry.body, number(pose[3]));
+    Matter.Body.setVelocity(entry.body, { x: 0, y: 0 });
+    Matter.Body.setAngularVelocity(entry.body, 0);
+    applied += 1;
+  }
+  return applied;
+}
+
 // A body's pose in the terms the client writes onto a Layout box. The offset is
 // not rotated with the body, matching how the engine writes its own bodies back.
 export function layoutOf(entry) {

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

@@ -15,7 +15,11 @@ import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js';
 import * as Poses from '../client/poses.js';
 import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
 import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
+import { showJoinOverlay } from '@imports/castle.real-time/code/client/joinOverlay.js';
 import { STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
+
+// How long the joining overlay may hold the card before giving up.
+const JOIN_WAIT_MS = 10000;
 import { game } from '@imports/castle.real-time/code/client/gameHooks.js';
 
 // How much of a refused move is taken back per frame, and the distance past
@@ -51,6 +55,11 @@ class MultiplayerSystem {
   constructor() {
     // The transport is created on the first stepped frame.
     this.net = null;
+    // False until a server snapshot carries this player's pose. The overlay
+    // stays up from the first stepped frame until then, or until JOIN_WAIT_MS
+    // after the join began if the session never answers.
+    this.joined = false;
+    this.joinStartedAt = 0;
 
     // `starting` keeps a second join attempt out while the first is pending.
     this.starting = false;
@@ -83,6 +92,7 @@ class MultiplayerSystem {
     // Connecting on the first stepped frame keeps the editor's own runtimes out
     // of the session: it builds them and never steps them.
     if (!this.net) {
+      showJoinOverlay(this.joiningOverlayWanted());
       return void this.start();
     }
 
@@ -105,7 +115,9 @@ class MultiplayerSystem {
     this.acceptClamp(scene, local);
 
     game.beforeReport?.(scene, local, this);
-    if (game.report) {
+    if (!this.joined) {
+      // Nothing reported until the session has placed this player.
+    } else if (game.report) {
       game.report(scene, local, this);
     } else {
       this.report(scene, local);
@@ -113,6 +125,7 @@ class MultiplayerSystem {
     game.afterFrame?.(scene, dt, this);
     this.publish(scene, local);
     updateSoloBadge(this.net.status(), game);
+    showJoinOverlay(this.joiningOverlayWanted());
   }
 
   // Join the public session once. Scene resets retain this transport.
@@ -121,6 +134,7 @@ class MultiplayerSystem {
       return;
     }
     this.starting = true;
+    this.joinStartedAt ||= performance.now();
     try {
       this.net = await connectSession({ onLog: (text) => console.log(`[multiplayer] ${text}`) });
     } catch (err) {
@@ -141,6 +155,10 @@ class MultiplayerSystem {
 
       // Pair server simulation time with page arrival time before filing samples.
       Clock.noteArrival(this.clock, msg.t, msg.localMs);
+      if (!this.joined && (msg.k === WORLD || (msg.ps ?? []).some((pose) => pose[0] === selfId))) {
+        this.joined = true;
+        console.log('[multiplayer] placed by the session');
+      }
 
       // Apply ownership before poses so a newly granted object stops consuming
       // network poses on the first frame of local simulation.
@@ -148,9 +166,11 @@ class MultiplayerSystem {
       for (const [id, x, y, facing, clamped] of msg.ps ?? []) {
         if (id !== selfId) {
           sample(this.players, msg, id, [x, y, facing]);
-        } else if (clamped) {
-          // Store this client's returned pose only when the server marks the
-          // report clamped. Accepted movement remains client-simulated.
+        } else if (clamped || msg.k === WORLD) {
+          // Store this client's returned pose when the server marks the report
+          // clamped, and on the WORLD snapshot that starts a session: that one
+          // carries where this player left off. Accepted movement remains
+          // client-simulated.
           this.clampedTo = { x, y };
         }
       }
@@ -374,12 +394,33 @@ class MultiplayerSystem {
     this.clampedTo = null;
   }
 
+  // Whether the overlay should be up: joining or connected, not solo, and not
+  // yet placed. A session that never answers releases it after JOIN_WAIT_MS so
+  // the deck is not stuck behind it.
+  joiningOverlayWanted() {
+    if (this.joined || this.net?.status().solo) {
+      return false;
+    }
+    if (this.joinStartedAt && performance.now() - this.joinStartedAt > JOIN_WAIT_MS) {
+      if (!this.joinWarned) {
+        this.joinWarned = true;
+        console.warn('[multiplayer] no snapshot from the session yet; playing unplaced');
+      }
+      return false;
+    }
+    return true;
+  }
+
+  // Release scene resources and leave the session when the engine runtime ends.
   dispose(scene) {
     // Runtime disposal also closes transport resources retained across resets.
     game.dispose?.(scene, this);
     this.reset(scene);
     this.net?.close();
     this.net = null;
+    this.joined = false;
+    this.joinStartedAt = 0;
+    showJoinOverlay(false);
     // The badge is a fixed element outside the scene, so a disposed runtime
     // (an editor preview closing, say) has to take it down explicitly.
     showSoloBadge(null);

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

@@ -18,6 +18,7 @@
         "@fortawesome/free-solid-svg-icons": "^5.15.4",
         "@lezer/highlight": "^1.2.3",
         "castle-web-fonts": "^1.0.0",
+        "castle-web-sdk": "file:../../sdk",
         "codemirror": "^6.0.2",
         "matter-js": "^0.20.0",
         "react": "^19.2.4",
@@ -29,7 +30,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.26",
+      "version": "0.4.27",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",
@@ -151,7 +152,6 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -308,7 +308,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
       "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -318,7 +317,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
       "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },

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

@@ -19,6 +19,7 @@
     "@fortawesome/free-solid-svg-icons": "^5.15.4",
     "@lezer/highlight": "^1.2.3",
     "castle-web-fonts": "^1.0.0",
+    "castle-web-sdk": "file:../../sdk",
     "codemirror": "^6.0.2",
     "matter-js": "^0.20.0",
     "react": "^19.2.4",

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

@@ -51,10 +51,27 @@ File names stay lowercase.
   builds a rapier world from the deck's own `scenes/main.scene` and steps it at
   `tickRate` (30). Never fork it.
 - **A game is added as hooks, not by replacing anything.** Write
-  `code/server/game.js` with a default export of up to six functions --
+  `code/server/game.js` with a default export of up to six gameplay functions --
   `ready(sim)`, `message(session, player, data)`, `place(sim, handovers)`,
   `step(sim, handovers)`, `join(sim)`, `delta(sim)` -- and it is found by glob.
   Optional, as is `code/server/deckComponents.js` for component defaults.
+- **What persists.** Object poses, the ids of despawned scene actors, each
+  player's last pose and `scene.persistent` block by account, and whatever the
+  optional `save(sim)` hook returns. Written every ten seconds when something
+  moved and at a clean shutdown. Nothing to configure.
+- **A despawn is for everyone.** The client system reports a scene actor a
+  behavior despawned (a collected pickup); the session removes it for every
+  player, now and on every later visit.
+- **`scene.persistent` must stay JSON** -- no Sets, no actors. It rides in the
+  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.
+- **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.
+- `restore(sim, saved)` receives the last `save` result before `ready`. Storage
+  is keyed by deck, so the deck must be published; `castle-web serve` brokers it
+  as the deck's creator.
 - `place` runs BEFORE the physics step, which is where a write through a deferred
   channel (`player.at`, `setNextKinematicTranslation`) has to happen to reach the
   body this tick. `message` is dispatched before the world exists, so a lobby
@@ -78,8 +95,9 @@ File names stay lowercase.
 - The kit ships `code/systems/multiplayer.js`, the frame loop. A deck that writes
   its own file of that path gets its own instead; most decks should not.
 - Two players is the test that matters: `castle-web serve`, then the play URL in
-  two tabs. The session process holds the room, so restart the serve for a fresh
-  one.
+  two tabs. The room persists in deck storage across serve restarts; a fresh one
+  means removing its `world:<room>`, `game:<room>` and `player:<room>:*` rows
+  (the local serve's room is `dev`).
 
 ## Layout
 
@@ -238,12 +256,13 @@ Map())` — and the next `showPlayer` respawns it.
 - **The player blueprint itself.** The kit spawns a scene from the deck's own
   root; the deck ships it. `blueprints/other-player.scene` is only the name it
   looks for when the deck names none.
-- **Any HUD.** Five decks wrote five HUDs with no shared lines. The one
-  on-screen element the kit does draw is the solo badge
-  (`castle.real-time`'s `soloBadge.js`): when the join fell back to solo it
-  names why (`status().soloReason`), so a creator testing a private or
-  unpublished deck is told rather than left to guess. A deck's
-  `soloBadge(status)` client hook hides or rewords it.
+- **Any HUD.** Five decks wrote five HUDs with no shared lines. The kit draws
+  two on-screen elements, both `castle.real-time`'s: the solo badge
+  (`soloBadge.js`) names why a join fell back to solo (`status().soloReason`),
+  so a creator testing a private or unpublished deck is told rather than left
+  to guess -- a deck's `soloBadge(status)` client hook hides or rewords it; and
+  the join overlay (`joinOverlay.js`) covers the card with "Joining…" until the
+  session's first snapshot places the player, ten seconds at most.
 - **Gameplay verbs** — carry, vehicle, round, lobby. Measured across six decks
   and none of them survived contact; see the audit.