@homie-rocks/studio 0.18.1 → 0.19.0

package/lib/scaffold.mjs

@@ -110,6 +110,7 @@ directory lists its games; homie.rocks does not host them.
 | \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
 | \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
 | \`changes/\` | One small file per change that went out through a pull request (\`homie-studio progress pr\` writes it): the site lists the newest, so the Claude app can tell when a merged change is live. |
+| \`perf/\` | Performance reports, one folder per game (the Homie plugin's \`perf\` skill): \`README.md\` (the goal, before and after with the noise, every change tried and why it was kept or reverted), \`numbers.json\` and \`before-after/\`. The raw runs, screenshots and CPU profiles stay in \`.perf/\`, which git ignores. |
 | \`studio.json\` | The studio's name, slug, Cloudflare resource names, custom domain and stats sharing. \`.studio/\` (git-ignored) is this computer's own state. |
 | \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
 
@@ -134,6 +135,11 @@ studio's pinned copy, never a registry lookup of the bare name.
   never \`pkill\` by name, which stops other projects' dev servers too).
 - \`npx --no-install homie-studio check <id> --url <site>\` — two headless browsers press Play and must
   land in the same room and finish a round. Run it before you say a game works.
+- \`npx --no-install homie-studio perf <id> --url <site>\` — how fast a game runs, on a computer and an emulated
+  phone, with two browsers in a room (the host and a replica): frame times, the game's JavaScript and the main thread
+  per frame, time to playable, what it downloads, the heap, netplay messages a second (files under \`.perf/\`). The
+  Homie plugin's \`perf\` skill runs the whole loop: one change at a time, kept only when it is better beyond the noise
+  and \`check\` still passes, and a report in \`perf/<id>/\`.
 - \`npx --no-install homie-studio deploy --plan\` — says what deploy will create on Cloudflare and what it
   costs, and changes nothing. Tell the person before the first deploy.
 - \`npm run deploy\` — the site on this studio's Cloudflare: one Worker, one D1 database, two
@@ -456,6 +462,8 @@ site/.wrangler/
 games/*/.port/
 # Screenshots from check and look runs.
 .checks/
+# Performance runs (homie-studio perf, the perf skill): numbers, screenshots and CPU profiles of each run.
+.perf/
 # Large media lives in this studio's storage (R2, after storage add: media move) or is served by the site; the manifests beside it (which name each file's R2 copy) are committed.
 # Working files of the music and video skills (frames, captures, provider answers) stay on this computer.
 music/**/work/

package/lib/template-history.json

@@ -1,6 +1,6 @@
 {
  "v": 1,
- "about": "Fingerprints of every studio template version (scripts/studio-template-history.mjs): homie-studio upgrade replaces a file or an AGENTS.md section only when it is exactly one of these.",
+ "about": "Fingerprints of every studio template version (scripts/studio-template-history.mjs): homie-studio upgrade replaces a file or an AGENTS.md section only when it is exactly one of these. A version's named entries are for a studio the template itself names (lib/upgrade.mjs NAMED_IN_TEMPLATE), as that studio reads them.",
  "versions": {
   "0.2.0": {
    "files": {
@@ -138,14 +138,23 @@
     "music/README.md": "b8a828de9311bd28",
     "videos/README.md": "70614388cbb203c7",
     "posts/README.md": "37841aae476bd540",
-    "site/README.md": "0fd152a20a3eb55f",
+    "site/README.md": [
+     "0fd152a20a3eb55f",
+     "ca131cd0472464fb"
+    ],
     "site/src/worker.mjs": "ca3f1630f2420ad3"
    },
    "sections": {
     "AGENTS.md": {
      "(intro)": "214aa46eb3a895d5",
-     "## Layout": "b5f801e112d163a9",
-     "## Commands (all through the pinned CLI in node_modules)": "63833b7006efdef4",
+     "## Layout": [
+      "b5f801e112d163a9",
+      "dc8ce5f6276d369e"
+     ],
+     "## Commands (all through the pinned CLI in node_modules)": [
+      "2af7c804c1e81d86",
+      "63833b7006efdef4"
+     ],
      "## The site": "7d3525ba39b7f262",
      "## Making games": "c204473d9b468f49",
      "## Rules": "969318425c99f5a5",
@@ -252,24 +261,44 @@
    "files": {
     "CLAUDE.md": "ddf2b2a0376202f6",
     "README.md": "684b3cca8001673c",
-    "games/README.md": "5e5e942baa7e0372",
+    "games/README.md": [
+     "5ad32fe80c61f117",
+     "5e5e942baa7e0372"
+    ],
     "music/README.md": "b8a828de9311bd28",
     "videos/README.md": "70614388cbb203c7",
     "posts/README.md": "37841aae476bd540",
     "site/README.md": "ca131cd0472464fb",
-    "site/src/worker.mjs": "ca3f1630f2420ad3"
+    "site/src/worker.mjs": "ca3f1630f2420ad3",
+    "HANDOFF.md": "ce7a8fd91c6bbee2"
    },
    "sections": {
     "AGENTS.md": {
      "(intro)": "214aa46eb3a895d5",
      "## Layout": "f14d641159480e6c",
-     "## Commands (all through the pinned CLI in node_modules)": "3a3d3bef7e8d1a50",
-     "## The site": "7d3525ba39b7f262",
+     "## Commands (all through the pinned CLI in node_modules)": [
+      "3a3d3bef7e8d1a50",
+      "e579cd6ce3ce342a"
+     ],
+     "## The site": [
+      "7c1618431bae6324",
+      "7d3525ba39b7f262"
+     ],
      "## Making games": "63069b31c87a2aa2",
      "## The Game Codex and progress": "0738ef719cef3a4c",
      "## Running live games (the back office)": "f0566f07cff04113",
      "## Rules": "969318425c99f5a5",
-     "## Beta": "9d02638207a26e73"
+     "## Beta": "9d02638207a26e73",
+     "## Continuing a build from the Claude app": "0d68081e924ca419"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
     }
    }
   },
@@ -298,6 +327,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.14.1": {
@@ -325,6 +363,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.14.2": {
@@ -352,6 +399,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.14.3": {
@@ -379,6 +435,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.14.4": {
@@ -406,6 +471,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.15.0": {
@@ -433,6 +507,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.16.0": {
@@ -461,6 +544,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.16.1": {
@@ -489,6 +581,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.17.0": {
@@ -517,6 +618,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "befe520937e71984"
+      }
+     }
+    }
    }
   },
   "0.18.0": {
@@ -545,6 +655,15 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "eedef844b7aaf7ad"
+      }
+     }
+    }
    }
   },
   "0.18.1": {
@@ -573,6 +692,89 @@
      "## Rules": "969318425c99f5a5",
      "## Beta": "9d02638207a26e73"
     }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "eedef844b7aaf7ad"
+      }
+     }
+    }
+   }
+  },
+  "0.18.2": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "eb1942414b8af7f8",
+     "## Commands (all through the pinned CLI in node_modules)": "9c51f189412e6a9f",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "eedef844b7aaf7ad"
+      }
+     }
+    }
+   }
+  },
+  "0.19.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8dc97df0d77e655e",
+     "## Commands (all through the pinned CLI in node_modules)": "a06ab13fc385ab25",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "677ee39dc13485e0"
+      }
+     }
+    }
    }
   }
  }

package/lib/upgrade.mjs

@@ -9,8 +9,8 @@
  *
  *   added      a file, an AGENTS.md section, a .gitignore line or a package.json script the studio does not have;
  *   updated    a file or an AGENTS.md section the studio never changed since an older template wrote it (its text
- *              is exactly an earlier version's: lib/template-history.json keeps a fingerprint of every one), so the
- *              template's newer text replaces it;
+ *              is exactly an earlier version's: lib/template-history.json keeps a fingerprint of every one, and of
+ *              every one as a studio the template itself names reads it), so the template's newer text replaces it;
  *   kept       anything the studio changed, or wrote itself: never touched. The plan says it differs, and
  *              `--diff` prints the difference, so the person can take the template's words by hand.
  *
@@ -42,6 +42,14 @@ export const ADD_ONLY = ['music/manifest.json', 'videos/manifest.json', '.claude
 const MIGRATIONS = /^site\/migrations\/[^/]+\.sql$/;
 /** The name and slug stand-ins the history is fingerprinted with. */
 export const STAND_IN = { name: '{{studio.name}}', slug: '{{studio.slug}}' };
+/**
+ * Studios the template's own words name: `demo` plays a live game "on Homie Arcade" (the Commands section). A
+ * studio's text is compared with its own name and slug made neutral (normalize), so for the studio that IS Homie
+ * Arcade that mention turns into the stand-in too, and no stand-in fingerprint could ever match its untouched text:
+ * it read as changed by the studio, and kept the template's older words for good. The history also keeps, for each of
+ * these names, the fingerprints that differ when the template is written for that studio (`named`).
+ */
+export const NAMED_IN_TEMPLATE = Object.freeze([Object.freeze({ name: 'Homie Arcade', slug: 'homie-arcade' })]);
 const INTRO = '(intro)';
 
 /** A text as the template compares it: line ends, trailing spaces and the studio's own name and slug made neutral. */
@@ -64,9 +72,9 @@ export function sections(text) {
   return out.map((s) => ({ heading: s.heading, text: s.lines.join('\n') })).filter((s, i) => i > 0 || s.text.trim());
 }
 
-/** What the history keeps of one template: a fingerprint of every whole file and every AGENTS.md section. */
-export function templatePrint(files) {
-  const who = STAND_IN;
+/** What the history keeps of one template: a fingerprint of every whole file and every AGENTS.md section, as `who`
+ * (the stand-ins, or a studio the template names) reads them. */
+export function templatePrint(files, who = STAND_IN) {
   return {
     files: Object.fromEntries(TEMPLATE_FILES.filter((f) => f !== 'AGENTS.md' && files[f] !== undefined).map((f) => [f, fingerprint(files[f], who)])),
     sections: { 'AGENTS.md': Object.fromEntries(sections(files['AGENTS.md']).map((s) => [s.heading, fingerprint(s.text, who)])) },
@@ -77,14 +85,33 @@ export function readHistory() {
   try { return JSON.parse(readFileSync(new URL('./template-history.json', import.meta.url), 'utf8')); } catch { return { v: 1, versions: {} }; }
 }
 
-/** Every fingerprint an older template wrote, per file and per AGENTS.md section. */
-function known(history) {
+/**
+ * A template as the studios it names read it (NAMED_IN_TEMPLATE): for each, the fingerprints that differ from the
+ * stand-ins' (only a file or section that names it does). `render(who)` is what `homie-studio new` writes for `who`.
+ */
+export function namedPrint(render, plain = templatePrint(render(STAND_IN))) {
+  const named = {};
+  for (const who of NAMED_IN_TEMPLATE) {
+    const p = templatePrint(render(who), who);
+    const files = Object.fromEntries(Object.entries(p.files).filter(([f, h]) => plain.files[f] !== h));
+    const secs = Object.fromEntries(Object.entries(p.sections['AGENTS.md']).filter(([s, h]) => plain.sections['AGENTS.md'][s] !== h));
+    if (Object.keys(files).length || Object.keys(secs).length) named[who.name] = { ...(Object.keys(files).length ? { files } : {}), sections: { 'AGENTS.md': secs } };
+  }
+  return named;
+}
+
+/** Every fingerprint an older template wrote, per file and per AGENTS.md section, as this studio (`who`) reads it. */
+function known(history, who = {}) {
   const files = new Map();
   const secs = new Map();
   for (const v of Object.values(history.versions ?? {})) {
-    // A version may hold more than one hash for a file (two templates published under it): a list.
-    for (const [f, h] of Object.entries(v.files ?? {})) for (const x of [h].flat()) (files.get(f) ?? files.set(f, new Set()).get(f)).add(x);
-    for (const [heading, h] of Object.entries(v.sections?.['AGENTS.md'] ?? {})) for (const x of [h].flat()) (secs.get(heading) ?? secs.set(heading, new Set()).get(heading)).add(x);
+    // A studio the template names reads those mentions as its own name: its fingerprints are kept beside the rest.
+    const as = who.name && v.named && Object.hasOwn(v.named, who.name) ? v.named[who.name] : null;
+    for (const p of as ? [v, as] : [v]) {
+      // A version may hold more than one hash for a file (two templates published under it): a list.
+      for (const [f, h] of Object.entries(p.files ?? {})) for (const x of [h].flat()) (files.get(f) ?? files.set(f, new Set()).get(f)).add(x);
+      for (const [heading, h] of Object.entries(p.sections?.['AGENTS.md'] ?? {})) for (const x of [h].flat()) (secs.get(heading) ?? secs.set(heading, new Set()).get(heading)).add(x);
+    }
   }
   return { files, secs };
 }
@@ -137,7 +164,7 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   if (!name || !slug) return { ok: false, command: 'upgrade', why: 'studio.json has no name or slug; this does not look like a studio made with homie-studio new' };
   const who = { name, slug };
   const tmpl = studioFiles({ name, slug, homie: studio.homie?.directory ?? 'https://homie.rocks' });
-  const { files: oldFiles, secs: oldSecs } = known(history);
+  const { files: oldFiles, secs: oldSecs } = known(history, who);
   const changes = [];
   const kept = [];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/port/room.ts

@@ -34,7 +34,7 @@ import {
 export interface BodyBase { slot: number; seat: number | null; name: string; bot: boolean; score: number; agent?: Slot['agent'] }
 
 export interface RoomSnap<F = unknown> { r: [n: number, phase: number, startedAt: number, endsAt: number]; b: number[][]; w?: F }
-export interface RoomCkpt<B, S> { round: RoundInfo | null; roster: Slot[]; bodies: B[]; world: S | null; tick: number }
+export interface RoomCkpt<B, S> { round: RoundInfo | null; roster: Slot[]; bodies: B[]; world: S | null; tick: number; spawns?: [slot: number, index: number][] }
 
 export interface RoomOptions<B extends BodyBase, F = unknown, S = unknown> {
   /** The game id (the relay's logs). */
@@ -50,7 +50,11 @@ export interface RoomOptions<B extends BodyBase, F = unknown, S = unknown> {
   /** Results on screen between rounds (default 7). */
   breakSeconds?: number;
   botName?: (slot: number) => string;
-  /** A fresh body for a slot. `index` counts bodies at a round start (spread the spawns with it). */
+  /**
+   * A fresh body for a slot. Spread the spawns with `index`: at a round start the bodies get 0, 1, 2… in slot order; a
+   * body that arrives mid-round (a joiner with no bot to take over, a guide's seat) gets the lowest index no body in
+   * the room holds, so two bodies never get the same one.
+   */
   spawn: (slot: Slot, index: number) => B;
   /** The body's fast fields for the snapshot, after [slot, seat, score]: small numbers only (use q()). */
   pack: (b: B) => number[];
@@ -143,6 +147,8 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
   const policy = (): Policy => net.policy;
   let roster = new Roster({ min, max, botName, policy });
   let bodies = new Map<number, B>();
+  /** The index each body was spawned with (slot → index), so a body that arrives mid-round never gets one in use. */
+  let spawned = new Map<number, number>();
   let round: RoundInfo | null = null;
   let hosting = false;
   let tick = 0;
@@ -150,7 +156,7 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
   const net = createNetplay<RoomSnap<F>, unknown[], RoomCkpt<B, S>>({
     game: opts.game, maxPlayers: max, movement: opts.movement ?? 'owner',
     snapshotHz: 20, inputHz: 20, checkpointMs: 1000,
-    checkpoint: () => ({ round, roster: roster.toJSON(), bodies: [...bodies.values()].map((b) => ({ ...b })), world: opts.saveWorld ? opts.saveWorld() : null, tick }),
+    checkpoint: () => ({ round, roster: roster.toJSON(), bodies: [...bodies.values()].map((b) => ({ ...b })), world: opts.saveWorld ? opts.saveWorld() : null, tick, spawns: [...spawned].filter(([slot]) => bodies.has(slot)) }),
     ...(opts.netplay ?? {}),
     // createRoom claims an AI's slot for it (its join passes `p.agent`), so its host can move an AI's body.
     caps: [...new Set([...(opts.netplay?.caps ?? []), 'agents' as const])],
@@ -163,17 +169,31 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     return null;
   };
 
-  function syncBodies(atIndex = 0): void {
+  /** The lowest spawn index no body in the room holds. */
+  function freeIndex(): number {
+    const held = new Set<number>();
+    for (const slot of bodies.keys()) { const i = spawned.get(slot); if (i !== undefined) held.add(i); }
+    let i = 0;
+    while (held.has(i)) i += 1;
+    return i;
+  }
+
+  function syncBodies(): void {
     const seen = new Set<number>();
-    let i = atIndex;
     for (const s of roster.slots) {
       seen.add(s.slot);
       const b = bodies.get(s.slot);
-      if (!b) { const nb = opts.spawn(s, i++); nb.slot = s.slot; nb.seat = s.seat; nb.name = s.name; nb.bot = s.bot; nb.score = nb.score ?? 0; if (s.agent) nb.agent = { ...s.agent }; bodies.set(s.slot, nb); continue; }
+      if (!b) {
+        // Mid-round (a joiner, a guide's seat): never an index another body holds, so never another body's spot.
+        const i = freeIndex();
+        const nb = opts.spawn(s, i); nb.slot = s.slot; nb.seat = s.seat; nb.name = s.name; nb.bot = s.bot; nb.score = nb.score ?? 0; if (s.agent) nb.agent = { ...s.agent };
+        bodies.set(s.slot, nb); spawned.set(s.slot, i);
+        continue;
+      }
       b.seat = s.seat; b.name = s.name; b.bot = s.bot;
       if (s.agent) b.agent = { ...s.agent }; else delete b.agent;
     }
-    for (const k of [...bodies.keys()]) if (!seen.has(k)) bodies.delete(k);
+    for (const k of [...bodies.keys()]) if (!seen.has(k)) { bodies.delete(k); spawned.delete(k); }
   }
 
   function moved(b: B): void {
@@ -195,7 +215,9 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     roster.trim();
     syncBodies();
     let i = 0;
+    spawned = new Map();
     for (const s of [...roster.slots].sort((a, c) => a.slot - c.slot)) {
+      spawned.set(s.slot, i);
       const fresh = opts.spawn(s, i++);
       fresh.slot = s.slot; fresh.seat = s.seat; fresh.name = s.name; fresh.bot = s.bot; fresh.score = 0;
       if (s.agent) fresh.agent = { ...s.agent };
@@ -228,11 +250,14 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     if (ck) {
       roster = Roster.from(ck.roster, { min, max, botName, policy });
       bodies = new Map(ck.bodies.map((b) => [b.slot, { ...b }]));
+      // A checkpoint from before spawns were kept: the round start's order (slot order) is the best guess.
+      spawned = new Map(ck.spawns ?? [...bodies.keys()].sort((a, c) => a - c).map((slot, i) => [slot, i]));
       round = ck.round;
       tick = ck.tick;
     } else {
       roster = Roster.from(e.roster ?? [], { min, max, botName, policy });
       bodies = new Map();
+      spawned = new Map();
       syncBodies();
     }
     // The snapshot is newer than the checkpoint (20 Hz vs 1 Hz): positions and scores from it.
@@ -243,8 +268,9 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
         let b = bodies.get(slot);
         if (!b) {
           const sl = roster.slots.find((r) => r.slot === slot) ?? { slot, seat: seat >= 0 ? seat : null, name: seat >= 0 ? `Player ${seat + 1}` : botName(slot), bot: seat < 0 };
-          b = opts.spawn(sl, slot); b.slot = slot; b.seat = sl.seat; b.name = sl.name; b.bot = sl.bot;
-          bodies.set(slot, b);
+          const i = freeIndex();
+          b = opts.spawn(sl, i); b.slot = slot; b.seat = sl.seat; b.name = sl.name; b.bot = sl.bot;
+          bodies.set(slot, b); spawned.set(slot, i);
         }
         b.score = score;
         opts.unpack(row.slice(3), b);
@@ -268,6 +294,7 @@ export function createRoom<B extends BodyBase, F = unknown, S = unknown>(opts: R
     else {
       roster = new Roster({ min, max, botName, policy });
       bodies = new Map();
+      spawned = new Map();
       const seat = mySeat();
       if (seat !== null) roster.claim(seat, net.offline ? 'You' : net.name);
       syncBodies();

package/saves/SAVES.md

@@ -23,7 +23,10 @@ The pattern (the `ember-vale` starter does exactly this):
 1. When the player arrives, **load** the hero from saves; until it loads, play as a level-1 body.
 2. The host decides what happened (who killed what) and tells **that player's own browser** (a netplay event
    to its seat). Only the hero's own browser changes the hero and **saves** it.
-3. The room carries what the others need to see (my level, so my health bar is right), never the save itself.
+3. The room carries what the others need to see (my level, so my health bar is right; my hero's name, so it is
+   the name over my head), never the save itself. The name goes to the host as an event, and the host keeps every
+   seat's in keyed state (`net.state('heroes', { [seat]: name })`), which a new host and a late joiner already have.
+   On a kids server nobody's typed name reaches anyone else: the others keep seeing the room's handles.
 
 ## Quick start