@homie-rocks/studio 0.18.0 → 0.18.2

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.0",
+  "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/index.ts

@@ -8,6 +8,9 @@
  *                keys on computers, a floating stick and small buttons on phones
  *   groundBasis / screenToGround / PlayerYaw
  *                the camera rules: input on screen axes, a yaw only the player turns
+ *   fitView / easeView / toScreen / createLabels
+ *                a flat world on every screen (the whole of it, or filling an upright phone and following the
+ *                player) and name labels that never pile up
  *   exposePort   what `homie-studio port check` reads (owner tests)
  *   createHud    a minimal clock / scores / results overlay
  *   BotBrain, seek, nearest, rubberBand
@@ -26,6 +29,7 @@ export { createKeys, synthKey, holdKey, tapKey, keyInfo, releaseAllSynthKeys, ty
 export { createTouchControls, type TouchControls, type TouchOptions, type TouchButton } from './touch';
 export { createControls, type Controls, type ControlsOptions } from './controls';
 export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLike } from './camera';
+export { fitView, easeView, toScreen, createLabels, type Fit, type FitOptions, type LabelIn, type LabelOut, type LabelOptions, type LabelBox } from './view';
 export { exposePort, type PortProbeOptions, type View } from './probe';
 export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
 export { createHud, type HudOptions } from './hud';

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/port/view.ts

@@ -0,0 +1,213 @@
+/*
+ * A flat world on every screen: a phone held upright, the same phone on its side, a computer and a television.
+ * Two pieces for a top-down canvas game (both starters use them):
+ *
+ *   fitView(o)            where the camera looks and how close. The whole world where it fits at a size that reads
+ *                         (a computer, a TV); elsewhere (most of all a phone held upright, where "fit" drew a strip
+ *                         a quarter of the screen tall) the world FILLS the screen and follows the player, never
+ *                         past the world's edge, except as far as it takes to keep the player clear of the HUD.
+ *   createLabels()        name labels that never pile up. Each label wants its spot above its body; when that spot
+ *                         is taken it tries a row higher, then under the body, else it fades out. The player's own
+ *                         label is placed first and nothing covers it; a moved label keeps its new spot while it is
+ *                         free (no flicker), and labels fade in and out rather than pop.
+ *
+ * Everything is in CSS pixels (screen) and world units; the game draws. See the starters (gem-rush, ember-vale).
+ */
+
+export interface FitOptions {
+  /** The world's size, in world units. */
+  world: { w: number; h: number };
+  /** The screen (the canvas's CSS size). */
+  screen: { w: number; h: number };
+  /** CSS px per world unit below which the whole world is too small to play (bodies too small to see, names too small
+   *  to read): under it the camera follows `focus`. 0: never show the whole world unless `whole`. */
+  readable: number;
+  /** How close a following camera is, in CSS px per world unit (default `readable`). It is never less than what
+   *  fills the screen, so a following camera never shows an empty band beside the world. */
+  zoom?: number;
+  /** Where a following camera looks, in world units (the player's body, or the player a watcher follows). null: the
+   *  world's middle. */
+  focus?: { x: number; y: number } | null;
+  /** Show the whole world whatever its size (an overview: a watcher following nobody). */
+  whole?: boolean;
+  /** CSS px of HUD along each edge: a following camera slides past the world's edge (up to this much) only when the
+   *  player would otherwise be under the HUD, at the very edge of the world. */
+  inset?: { top?: number; right?: number; bottom?: number; left?: number };
+}
+
+export interface Fit {
+  /** CSS px per world unit. */
+  scale: number;
+  /** The world point at the screen's centre. */
+  x: number;
+  y: number;
+  /** True when the camera follows (the whole world is not on screen). */
+  follow: boolean;
+}
+
+/** Where the camera should look this frame (ease towards it: a cut only at a round start or a respawn). */
+export function fitView(o: FitOptions): Fit {
+  const W = o.world.w; const H = o.world.h;
+  const sw = Math.max(1, o.screen.w); const sh = Math.max(1, o.screen.h);
+  const contain = Math.min(sw / W, sh / H);
+  if (o.whole || (o.readable > 0 && contain >= o.readable)) return { scale: contain, x: W / 2, y: H / 2, follow: false };
+  const cover = Math.max(sw / W, sh / H);
+  const scale = Math.max(cover, o.zoom ?? o.readable);
+  const f = o.focus ?? { x: W / 2, y: H / 2 };
+  const i = { top: 0, right: 0, bottom: 0, left: 0, ...(o.inset ?? {}) };
+  const hw = sw / 2 / scale; const hh = sh / 2 / scale;
+  const within = (v: number, lo: number, hi: number): number => (lo > hi ? (lo + hi) / 2 : Math.max(lo, Math.min(hi, v)));
+  // Centred on the focus, kept inside the world; then moved just enough that the focus is clear of the HUD's margins.
+  const clear = (c: number, focus: number, half: number, lo: number, hi: number): number => {
+    const at = (half + focus - c) * scale; // the focus on screen, from the near edge
+    const span = 2 * half * scale;
+    if (at < lo) return c - (lo - at) / scale;
+    if (at > span - hi) return c + (at - (span - hi)) / scale;
+    return c;
+  };
+  return {
+    scale,
+    x: clear(within(f.x, hw, W - hw), f.x, hw, i.left, i.right),
+    y: clear(within(f.y, hh, H - hh), f.y, hh, i.top, i.bottom),
+    follow: true,
+  };
+}
+
+/** A world point on screen (CSS px) under a camera. */
+export function toScreen(fit: Fit, screen: { w: number; h: number }, x: number, y: number): { x: number; y: number } {
+  return { x: screen.w / 2 + (x - fit.x) * fit.scale, y: screen.h / 2 + (y - fit.y) * fit.scale };
+}
+
+/** Ease a camera towards where it should be (frame-rate independent; `rate` about 8 to 12 a second). */
+export function easeView(cam: Fit | null, want: Fit, dt: number, rate = 10): Fit {
+  if (!cam) return { ...want };
+  const k = 1 - Math.exp(-Math.max(0, dt) * rate);
+  return { scale: cam.scale + (want.scale - cam.scale) * k, x: cam.x + (want.x - cam.x) * k, y: cam.y + (want.y - cam.y) * k, follow: want.follow };
+}
+
+export interface LabelBox { left: number; top: number; right: number; bottom: number }
+
+export interface LabelIn {
+  /** Stable per body (its slot): a label keeps its spot and its fade from frame to frame. */
+  key: string | number;
+  text: string;
+  /** The label's centre x and its BOTTOM edge where it wants to sit (above its body), CSS px. */
+  x: number;
+  y: number;
+  /** Its size as drawn, CSS px (measureText's width; the font's line height). */
+  w: number;
+  h: number;
+  /** Where its bottom edge goes if it sits under its body instead (CSS px); omitted: never under. */
+  below?: number;
+  /** Its body on screen (with its bars): other labels keep off it when they can. */
+  body?: LabelBox;
+  /** The player's own label (or the player a watcher follows): placed first, never covered, never faded. */
+  self?: boolean;
+  /** Lower first: who keeps their spot when two want it (people before AI before bots, near before far). */
+  rank?: number;
+}
+
+export interface LabelOut extends LabelIn, LabelBox {
+  /** The text's centre (draw with textAlign center, textBaseline middle). */
+  cx: number;
+  cy: number;
+  /** 0..1: 1 shown, 0 gone (no room for it). */
+  alpha: number;
+  /** Not in its own spot above its body (draw a thin line to the body, so whose it is stays plain). */
+  moved: boolean;
+}
+
+export interface LabelOptions {
+  /** CSS px kept clear between two labels (default 3). */
+  gap?: number;
+  /** CSS px kept clear round the player's own label, for a chip drawn behind it (default 4). */
+  selfPad?: number;
+  /** How fast a label fades in (default 8 a second). One with no room left goes at once if it would touch another. */
+  fade?: number;
+  /** The screen, so a label is never pushed off it (default the window). */
+  screen?: () => { w: number; h: number };
+  /** Boxes labels must keep clear of (the game's own speech bubbles, a panel), CSS px. */
+  avoid?: () => LabelBox[];
+}
+
+/**
+ * Name labels that never pile up. Call `place(labels, dt)` each frame with every label that wants drawing; draw what
+ * comes back (skip alpha 0). The order of the input does not matter: `self` first, then `rank`.
+ *
+ * Each label tries, in order: its own spot above its body, a row higher, under its body, two rows higher; first
+ * clear of every placed label and of other bodies, then clear of labels only. A label that moved keeps its new spot
+ * until its own is clear by a margin, so labels do not flicker between two spots as bodies jostle.
+ */
+export function createLabels(opts: LabelOptions = {}): { place(labels: LabelIn[], dt: number): LabelOut[]; reset(): void } {
+  const gap = opts.gap ?? 3;
+  const selfPad = opts.selfPad ?? 4;
+  const fadeRate = opts.fade ?? 8;
+  const state = new Map<string | number, { spot: number; alpha: number }>();
+  const screen = opts.screen ?? ((): { w: number; h: number } => ({ w: typeof innerWidth === 'number' ? innerWidth : 1e9, h: typeof innerHeight === 'number' ? innerHeight : 1e9 }));
+  const hits = (a: LabelBox, b: LabelBox, m = gap): boolean => a.left < b.right + m && b.left < a.right + m && a.top < b.bottom + m && b.top < a.bottom + m;
+  return {
+    reset() { state.clear(); },
+    place(labels, dt) {
+      const { w: sw, h: sh } = screen();
+      const order = [...labels].sort((a, b) => Number(Boolean(b.self)) - Number(Boolean(a.self)) || (a.rank ?? 0) - (b.rank ?? 0));
+      const taken: LabelBox[] = [...(opts.avoid?.() ?? [])];
+      const bodies = labels.filter((l) => l.body).map((l) => ({ key: l.key, box: l.body as LabelBox }));
+      const out: LabelOut[] = [];
+      const seen = new Set<string | number>();
+      const k = 1 - Math.exp(-Math.max(0, dt) * fadeRate);
+      for (const l of order) {
+        seen.add(l.key);
+        // Spots: 0 its own (above the body), 1 a row higher, 2 under the body, 3 two rows higher.
+        const bottoms = [l.y, l.y - l.h - gap, l.below, l.y - 2 * (l.h + gap)];
+        const boxAt = (spot: number): LabelBox | null => {
+          const b = bottoms[spot];
+          if (b === undefined) return null;
+          const half = l.w / 2;
+          // Kept on screen sideways; a spot off the top or the bottom is not a spot.
+          const cx = Math.max(half + 2, Math.min(sw - half - 2, l.x));
+          const box = { left: cx - half, top: b - l.h, right: cx + half, bottom: b };
+          return box.top < 0 || box.bottom > sh ? null : box;
+        };
+        const clear = (b: LabelBox, strict: boolean, m = gap): boolean => !taken.some((t) => hits(b, t, m)) && (!strict || !bodies.some((o) => o.key !== l.key && hits(b, o.box, 0)));
+        const st = state.get(l.key) ?? { spot: 0, alpha: l.self ? 1 : 0 };
+        let spot = -1; let box: LabelBox | null = null;
+        if (l.self) {
+          spot = boxAt(0) ? 0 : boxAt(2) ? 2 : 0;
+          box = boxAt(spot) ?? { left: l.x - l.w / 2, top: l.y - l.h, right: l.x + l.w / 2, bottom: l.y };
+        } else {
+          // Home first (back home only with room to spare, once moved), then last frame's spot, then the rest.
+          const home = boxAt(0);
+          const tries = [st.spot, 1, 2, 3].filter((x, i, all) => x !== 0 && all.indexOf(x) === i);
+          for (const strict of [true, false]) {
+            if (home && clear(home, strict, st.spot === 0 ? gap : gap + 8)) { spot = 0; box = home; break; }
+            for (const x of tries) { const b = boxAt(x); if (b && clear(b, strict)) { spot = x; box = b; break; } }
+            if (box) break;
+          }
+        }
+        if (box) {
+          st.spot = spot;
+          st.alpha = l.self ? 1 : st.alpha + (1 - st.alpha) * k;
+          taken.push(l.self ? { left: box.left - selfPad, top: box.top - selfPad, right: box.right + selfPad, bottom: box.bottom + selfPad } : box);
+        } else {
+          // No room: it fades where it was, or goes at once if it would touch a label that has room.
+          const was = boxAt(st.spot);
+          st.alpha = !was || taken.some((t) => hits(was, t, 0)) ? 0 : st.alpha * (1 - k);
+          if (st.alpha < 0.05) st.alpha = 0;
+        }
+        state.set(l.key, st);
+        const shown = box ?? boxAt(st.spot) ?? boxAt(0) ?? { left: l.x - l.w / 2, top: l.y - l.h, right: l.x + l.w / 2, bottom: l.y };
+        out.push({ ...l, ...shown, cx: (shown.left + shown.right) / 2, cy: (shown.top + shown.bottom) / 2, alpha: Math.round(st.alpha * 100) / 100, moved: st.spot !== 0, ...(box ? {} : { fading: true }) });
+      }
+      // A name fading out never touches a name that has its place, nor another one fading (whatever their order).
+      const kept: LabelBox[] = [...taken];
+      for (const o of out as (LabelOut & { fading?: boolean })[]) {
+        if (!o.fading) continue;
+        delete o.fading;
+        if (o.alpha > 0 && kept.some((t) => hits(o, t, 0))) { o.alpha = 0; (state.get(o.key) as { alpha: number }).alpha = 0; }
+        if (o.alpha > 0) kept.push(o);
+      }
+      for (const key of [...state.keys()]) if (!seen.has(key)) state.delete(key);
+      return out;
+    },
+  };
+}

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/index.html

@@ -21,20 +21,25 @@
   .panel li { margin: 4px 0; color: #e7d9b4; }
   .panel li small { color: #a39a80; }
   .panel .close { float: right; background: none; border: 0; color: #c9c0a6; font-size: 20px; cursor: pointer; }
-  /* Asking a guide: buttons (agents.json "asks"), never a text box. Bottom centre, clear of the stick and STRIKE. */
+  /* Asking a guide: buttons (agents.json "asks"), never a text box. On a computer: bottom centre. */
   .asks { left: 50%; transform: translateX(-50%); bottom: calc(14px + env(safe-area-inset-bottom)); max-width: min(560px, calc(100vw - 200px)); box-sizing: border-box; padding: 8px 10px; border-radius: 14px; background: rgba(10,20,18,.84); border: 1px solid rgba(127,216,200,.45); text-align: center; }
   .asks .who { font: 700 12.5px/1.2 inherit; font-family: inherit; color: #7fd8c8; margin: 0 0 6px; }
   .asks .list { display: flex; flex-wrap: wrap; gap: 6px; justify-content: center; }
   .asks button { min-height: 34px; padding: 0 12px; border-radius: 999px; border: 1px solid rgba(127,216,200,.5); background: rgba(127,216,200,.12); color: #e9fff9; font: 600 13px/1 inherit; font-family: inherit; cursor: pointer; }
   .asks button.sent { background: #7fd8c8; color: #0b1512; }
-  @media (max-width: 540px) { .asks { max-width: calc(100vw - 168px); bottom: calc(10px + env(safe-area-inset-bottom)); } .asks button { min-height: 40px; padding: 0 10px; } }
+  /* On a touch screen (body.touch: the touch kit drew STRIKE), either way up: a column right above STRIKE (68 px, 24 px
+     up from the bottom, 18 px in), where the thumb that strikes reaches it, clear of the stick and of the vale's
+     middle, where your hero is. */
+  .touch .asks { left: auto; transform: none; right: calc(12px + env(safe-area-inset-right)); bottom: calc(106px + env(safe-area-inset-bottom)); width: min(232px, calc(100vw - 24px)); max-width: none; max-height: calc(100vh - 166px); overflow: auto; }
+  .touch .asks .list { flex-direction: column; flex-wrap: nowrap; }
+  .touch .asks button { min-height: 40px; padding: 4px 10px; line-height: 1.15; }
   [hidden] { display: none !important; }
 </style>
 </head>
 <body>
 <canvas id="c"></canvas>
 <div class="ui pill"><button type="button" id="who"></button><button type="button" id="hall-btn">Hall of the Fallen</button></div>
-<div class="ui asks" id="asks" hidden aria-live="polite"><p class="who" id="asks-who"></p><div class="list" id="asks-list"></div></div>
+<div class="ui asks" id="asks" hidden aria-live="polite" data-touch-pass><p class="who" id="asks-who"></p><div class="list" id="asks-list"></div></div>
 <div class="ui panel" id="make" hidden>
   <h2>A new hero</h2>
   <p>Your hero keeps every level and coin, on every device you play on.</p>