@homie-rocks/studio 0.18.1 → 0.18.2

package/README.md

@@ -110,8 +110,8 @@ are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.18.1 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.18.1 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.18.2 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.18.2 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -278,7 +278,7 @@ npx homie-studio agents pass night-rush --label Claude
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.18.1 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.18.2 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 

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,52 @@
      "## 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"
+      }
+     }
+    }
    }
   }
  }

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.18.2",
   "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
 

package/starters/ember-vale/src/main.ts

@@ -15,6 +15,12 @@
  * hero and saves it. A hardcore hero who falls becomes a memorial in the Hall of the Fallen, and its save is wiped
  * in the same step (saves.fall). Canvas 2D on purpose: the point is the pattern, in a few hundred lines.
  *
+ * NAMES: the room knows a person by their seat's name (their account's, else a two-word handle such as "Velvet
+ * Comet"); the vale shows their HERO's name, over their head and in the night's ranking, for them and for everyone
+ * else. Each hero's browser tells the host its hero's name (a `hero` event); the host keeps every seat's in the keyed
+ * state `heroes`, which a new host and a late joiner have already. On a kids server nobody's typed name reaches
+ * anyone else (NETPLAY.md section 17): there the others are shown by their handles, as the room has them.
+ *
  * A watcher (/<game>/watch, contract revision 5) has no hero and makes none: `room.viewSeat()` is the hero it
  * follows, drawn in gold as a hero's own browser draws itself, with that hero's panel; nobody followed, the vale.
  * The host says who slew what (`slain`), so a watcher on Auto cuts to the kill.
@@ -31,7 +37,7 @@
  * none, or between its decisions, `decide` below is the floor. A guide's line is drawn as a bubble from agents.json,
  * never from a model; "Quiet AI" hides them.
  */
-import { AI_MARK, createControls, createLabels, createRoom, createSaves, easeView, exposePort, fitView, jitter, q, standoff, type BodyBase, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
+import { AI_MARK, createControls, createLabels, createRoom, createSaves, easeView, exposePort, fitView, jitter, q, standoff, stripAi, type BodyBase, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
 import { useAgents, type Goal, type Vocabulary } from '@homie-rocks/studio/agents';
 import vocabulary from '../agents.json';
 
@@ -46,6 +52,8 @@ const DOWN_MS = 4000;
 const DOWN = 1;
 const STRIKING = 2;
 const BOT_NAMES = ['Rook', 'Vex', 'Moth', 'Kilo', 'Juno', 'Pike', 'Nyx', 'Ash'];
+/** The eight spots round the camp, in the order bodies take them: any first few are spread all the way round. */
+const SPREAD = [0, 4, 2, 6, 1, 5, 3, 7];
 const xpFor = (level: number): number => Math.round(20 * level ** 1.5);
 const maxHpOf = (level: number): number => 60 + level * 12;
 const damageOf = (level: number): number => 10 + level * 3;
@@ -129,10 +137,13 @@ const room = createRoom<Body, SlimeRow[], { slimes: Slime[]; seq: number }>({
   roundSeconds: 90,
   breakSeconds: 8,
   botName: (slot) => BOT_NAMES[slot % BOT_NAMES.length] as string,
+  // createRoom gives every body in the room its own index (a mid-round arrival the lowest free one), so no two
+  // bodies ever spawn on one spot; SPREAD puts the first few far apart round the camp (0°, 180°, 90°, 270°…).
   spawn: (slot, i) => {
-    const a = (i / 8) * Math.PI * 2;
+    const a = ((SPREAD[i % SPREAD.length] as number) / SPREAD.length) * Math.PI * 2;
+    const ring = 1 + Math.floor(i / SPREAD.length) * 0.5;
     const lvl = slot.bot ? 1 + (slot.slot % 4) : 1;
-    const x = W / 2 + Math.cos(a) * 160; const y = H / 2 + Math.sin(a) * 120;
+    const x = W / 2 + Math.cos(a) * 160 * ring; const y = H / 2 + Math.sin(a) * 120 * ring;
     return { slot: slot.slot, seat: slot.seat, name: slot.name, bot: slot.bot, score: 0, x, y, hp: maxHpOf(lvl), maxHp: maxHpOf(lvl), level: lvl, face: a, flags: 0, downUntil: 0, atkAt: 0, strikeAt: 0, tx: x, ty: y };
   },
   pack: (b) => [q(b.x, 0), q(b.y, 0), Math.max(0, Math.round(b.hp)), b.maxHp, b.level, q(b.face, 2), b.flags],
@@ -157,6 +168,51 @@ const room = createRoom<Body, SlimeRow[], { slimes: Slime[]; seq: number }>({
 const net = room.net;
 const myLevel = (): number => hero?.level ?? 1;
 
+/* ------------------------------------------------------------------ heroes' names */
+/** A hero's name as the vale shows it: one line of at most 20 characters, never ending in an AI or bot mark. */
+const heroName = (raw: unknown): string =>
+  stripAi(String(raw ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g, ' ')).slice(0, 20).trim();
+/** On a kids server nobody's typed name reaches anyone else: the room's handles stay. */
+const kids = (): boolean => net.policy.kids === true;
+/** Every seat's hero name, as the host keeps it (keyed state `heroes`: seat → name). */
+const heroNames = (): Record<string, string> => net.stateOf<Record<string, string>>('heroes') ?? {};
+/** Host: one seat's hero name (null or '': none). */
+function setHeroName(seat: number, name: string | null): void {
+  const next = { ...heroNames() };
+  if (name && !kids()) next[seat] = name; else delete next[seat];
+  net.state('heroes', next);
+}
+/** The name over a body and in the ranking: a person's hero's (on your own screen, yours at once), else the room's. */
+function nameOf(b: { seat: number | null; bot: boolean; name: string; agent?: unknown }): string {
+  // A bot or an AI is always the room's name for it: an AI's ends in " · AI", and no hero name may hide that.
+  if (b.bot || b.agent || b.seat === null || net.isAgent(b.seat)) return b.name;
+  if (!lookOnly && hero && b.seat === room.mySeat()) return heroName(hero.name) || b.name;
+  return (kids() ? '' : heroNames()[b.seat]) || b.name;
+}
+/**
+ * Every frame: my hero's name goes to the host until the room has it (so a new host, a reload and a lost event all
+ * heal by themselves); the host keeps only seats a person still holds.
+ */
+let heroToldAt = 0;
+let heroesKeptAt = 0;
+function keepNames(now: number): void {
+  const seat = room.mySeat();
+  if (!lookOnly && seat !== null) {
+    const want = hero && !kids() ? heroName(hero.name) : '';
+    if ((heroNames()[seat] ?? '') !== want) {
+      if (room.hosting) setHeroName(seat, want);
+      else if (now - heroToldAt > 1500) { heroToldAt = now; net.send('hero', { name: want }); }
+    }
+  }
+  if (!room.hosting || now - heroesKeptAt < 1000) return;
+  heroesKeptAt = now;
+  const held = new Set([...net.peers.values()].filter((p) => p.seat !== null && !p.agent && !p.watch).map((p) => String(p.seat)));
+  if (seat !== null) held.add(String(seat));
+  const names = heroNames();
+  const keep = kids() ? {} : Object.fromEntries(Object.entries(names).filter(([k]) => held.has(k)));
+  if (Object.keys(keep).length !== Object.keys(names).length) net.state('heroes', keep);
+}
+
 /* ------------------------------------------------------------------ the guides' brain (agents.json) */
 type PartyRow = { seat: number; dist: number; hp: number; down: boolean };
 const greeted = new Map<number, Set<number>>();
@@ -223,6 +279,8 @@ net.on('event', (e: NetEvent) => {
   if (e.k === 'loot' && d.to === room.mySeat()) gain(Math.max(0, Number(d.xp) || 0), Math.max(0, Number(d.gold) || 0));
   if (e.k === 'down' && d.to === room.mySeat()) void fell(String(d.cause ?? 'a slime').slice(0, 40));
   if (e.k === 'slain' && typeof (e.d as { seat?: unknown })?.seat === 'number') net.spotlight((e.d as { seat: number }).seat);
+  // A hero's browser names its hero (its own seat only: the relay stamps who sent it).
+  if (e.k === 'hero' && room.hosting && typeof e.from === 'number' && !net.isAgent(e.from)) setHeroName(e.from, heroName((e.d as { name?: unknown } | null)?.name));
 });
 function tell(b: Body, k: 'loot' | 'down', d: Record<string, unknown>): void {
   if (b.bot || b.seat === null) return;
@@ -552,7 +610,7 @@ function draw(t: number): void {
     ctx.fillStyle = '#7ad35a'; ctx.fillRect(x - 24, y - R - 12, (48 * clamp(b.hp, 0, b.maxHp)) / Math.max(1, b.maxHp), 5);
     ctx.globalAlpha = 1;
     // An AI's name already ends in " · AI" (a guide, a companion); a plain bot says bot.
-    const text = `${b.name}${b.bot && !b.name.endsWith(AI_MARK) ? ' · bot' : ''}${isGuide ? ' · guide' : ''} · ${b.level}`;
+    const text = `${nameOf(b)}${b.bot && !b.name.endsWith(AI_MARK) ? ' · bot' : ''}${isGuide ? ' · guide' : ''} · ${b.level}`;
     const near = meAt ? Math.hypot(x - meAt.x, y - meAt.y) : 0;
     // Its spot is above its health bar; its body (and bar) is what other names keep off. People first, then guides,
     // then bots; nearer you first.
@@ -635,7 +693,7 @@ function hud(t: number): void {
   // A watcher's panel is the followed hero's, as the room has them (their save stays in their own browser).
   const v = lookOnly ? room.viewBody() : null;
   const heroes = room.view().filter((b) => !b.bot).length;
-  const title = lookOnly ? (v ? `${v.name} · Lv ${v.level}` : 'Watching the vale') : hero ? `${hero.name}${hero.hardcore ? ' ☠' : ''} · Lv ${hero.level}` : heroLoaded ? 'No hero yet' : 'Loading your hero…';
+  const title = lookOnly ? (v ? `${nameOf(v)} · Lv ${v.level}` : 'Watching the vale') : hero ? `${hero.name}${hero.hardcore ? ' ☠' : ''} · Lv ${hero.level}` : heroLoaded ? 'No hero yet' : 'Loading your hero…';
   const sub = lookOnly ? (v ? `${v.score} xp tonight${v.flags & DOWN ? ' · down' : ''}` : `${heroes} ${heroes === 1 ? 'hero' : 'heroes'} · ${(room.fast() ?? []).length} slimes`) : hero ? `${hero.gold} gold · ${hero.kills} slain` : '';
   const bar = v ? { colour: '#7ad35a', of: clamp(v.hp, 0, v.maxHp) / Math.max(1, v.maxHp) } : hero && !lookOnly ? { colour: '#ffcf6e', of: hero.xp / xpFor(hero.level) } : null;
   // The panel is as wide as what it says: on a phone the vale runs under it, and the clock sits beside it.
@@ -665,7 +723,7 @@ function hud(t: number): void {
     ctx.fillStyle = 'rgba(10,14,9,.78)'; ctx.fillRect(cw / 2 - 150, top, 300, 30 + rows.length * 22);
     ctx.font = TITLE; ctx.fillStyle = '#ffcf6e'; ctx.fillText('Tonight\'s hunters', cw / 2, top + 22);
     ctx.font = '600 14px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
-    rows.forEach((r, i) => ctx.fillText(`${r.place}. ${r.name}${r.bot && !r.name.endsWith(AI_MARK) ? ' (bot)' : ''} — ${r.score} xp`, cw / 2, top + 46 + i * 22));
+    rows.forEach((r, i) => ctx.fillText(`${r.place}. ${nameOf(r)}${r.bot && !r.name.endsWith(AI_MARK) ? ' (bot)' : ''} — ${r.score} xp`, cw / 2, top + 46 + i * 22));
   }
   if (performance.now() < bannerUntil) { ctx.font = '800 22px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#ffcf6e'; ctx.fillText(bannerText, cw / 2, canvas.height / k - 90); }
   const st = saves.status();
@@ -797,6 +855,7 @@ function frame(t: number): void {
   const dt = Math.min(0.05, (t - last) / 1000);
   last = t;
   stepMe(dt);
+  keepNames(t);
   if (room.hosting) stepHost(dt);
   draw(t);
   frames += 1;
@@ -813,9 +872,9 @@ net.expose({
     me: me.has ? { x: Math.round(me.x), y: me.y | 0 } : null,
     log: guideLog.slice(),
   }),
-  // Where the camera looks, and the names as drawn (boxes only: the e2e probe counts overlaps and checks your own).
+  // Where the camera looks, and the names as drawn (the e2e probe counts overlaps, checks your own, and reads them).
   camera: () => (cam ? { x: cam.x, y: cam.y, scale: cam.scale, follow: cam.follow } : null),
-  labels: () => shownLabels.map((l) => ({ self: Boolean(l.self), alpha: l.alpha, moved: l.moved, left: Math.round(l.left), top: Math.round(l.top), right: Math.round(l.right), bottom: Math.round(l.bottom) })),
+  labels: () => shownLabels.map((l) => ({ text: l.text, self: Boolean(l.self), alpha: l.alpha, moved: l.moved, left: Math.round(l.left), top: Math.round(l.top), right: Math.round(l.right), bottom: Math.round(l.bottom) })),
 });
 
 exposePort(net, {

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.18.1';
+export const STUDIO_VERSION_TAG = '0.18.2';