@homie-rocks/studio 0.18.0 → 0.18.1

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.17.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.17.0 upgrade --apply  # after the person agrees
+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
 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.17.0 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.18.1 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 
@@ -288,9 +288,16 @@ with the studio's own Wrangler, and the account's email verified: a deploy that
 deploy refused for it is remembered), Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and
 fal (and, in Claude Code, the status line). Each row is green, missing or "do this now", says what it
 unlocks, and gives the exact fix: a command the AI runs or a page the person taps. It only reads, answers in
-seconds, and never prints a key, a token or an account's name. A studio the Claude app's setup card made
+seconds, and never prints a key, a token or an account's name or id. A studio the Claude app's setup card made
 (`setup attach`) counts as connected to Cloudflare and GitHub there. `--json` gives the rows.
 
+When a server's AI guides think with Workers AI (0.18.1), a **Workers AI** row checks that the model they use
+(`HOMIE_BRAIN_MODEL` in wrangler.jsonc `vars`, else `@cf/meta/llama-3.1-8b-instruct-fp8-fast`) answers on the
+studio's account: one tiny call through Cloudflare's API with the studio's own Wrangler login (a one-word prompt,
+one token out: about 0.1 of the 10,000 free neurons a day; `lib/brain-probe.mjs`). A model Cloudflare moved to
+Workers Paid (error 5035) or retired (5007) is named, with what to do: pick another model, or, the person's money,
+Workers Paid. A spent daily allowance (3036) is said as that, not as a broken model.
+
 ## The Game Codex
 
 `games/<id>/CODEX.md` is a game's plan: Markdown with a small frontmatter for its look (palette, fonts, a
@@ -459,7 +466,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
-| `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
+| `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`; `fitView` and `createLabels` (`port/view.ts`): a flat world on every screen (the whole of it where it reads, else filling a phone held upright and following the player) and names that never pile up when bodies crowd (yours placed first, the rest moved or faded). |
 | `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/<game>/watch` watches a live room from any player's view (NETPLAY.md section 16); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site's files or, once moved, from the studio's R2 at the same address; a loose file from `media put` at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
 | `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |

package/lib/brain-probe.mjs

@@ -0,0 +1,154 @@
+/**
+ * `homie-studio doctor`'s Workers AI row: when a server's AI guides think with Workers AI (brain `workers-ai`), is the
+ * model they use (wrangler.jsonc var HOMIE_BRAIN_MODEL, else worker/brain.mjs DEFAULT_MODEL) one this studio's
+ * Cloudflare account can run? Cloudflare moves models to the Workers Paid plan from time to time (three on 2026-07-28,
+ * error 5035) and retires others (5007); either way the guides fall back to the game's script without a word, so the
+ * doctor asks once.
+ *
+ * The check is ONE tiny call to the model through Cloudflare's REST API (`POST /accounts/:id/ai/run/:model`, a
+ * one-word prompt, max_tokens 1: about 0.1 of the 10,000 free neurons a day), with the studio's own Wrangler login
+ * (`wrangler auth token`, held in this process only) or CLOUDFLARE_API_TOKEN. It never prints the token, the account's
+ * id or its name. A call that cannot be made (not signed in, several accounts and none named) says so and spends
+ * nothing.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_MODEL } from '../worker/brain.mjs';
+import { configPath, workerDir } from './studio.mjs';
+
+const MODELS = 'https://developers.cloudflare.com/workers-ai/models/';
+/** A Workers AI model id: @cf/<maker>/<model> (or @hf/…); nothing that could leave the API path. */
+export const MODEL_ID = /^@[a-z0-9-]+\/[A-Za-z0-9._-]+\/[A-Za-z0-9._:-]+$/;
+
+const parseJson = (text) => { const s = String(text ?? ''); const i = s.search(/[[{]/); if (i < 0) return null; try { return JSON.parse(s.slice(i)); } catch { return null; } };
+
+/** The model the studio's guides think with: wrangler.jsonc "vars".HOMIE_BRAIN_MODEL, else the toolkit's default. */
+export function brainModelOf(root) {
+  try {
+    const json = JSON.parse(readFileSync(configPath(root), 'utf8').replace(/^\s*\/\/.*$/gm, ''));
+    const v = json?.vars?.HOMIE_BRAIN_MODEL;
+    if (typeof v === 'string' && v.trim()) return { model: v.trim(), set: true };
+  } catch { /* no config: the default */ }
+  return { model: DEFAULT_MODEL, set: false };
+}
+
+/**
+ * Whether any open server of the studio's games thinks with Workers AI: a game.json seed in the built catalogue, or a
+ * row in the live database (one read-only `wrangler d1 execute --remote`). A database without the servers table, or
+ * one that cannot be read, says no.
+ */
+export async function usesWorkersAi(root, { exec, env = process.env, accountId = null, bin } = {}) {
+  try {
+    const cat = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8'));
+    if ((cat.games ?? []).some((g) => (g.servers ?? []).some((s) => s.brain === 'workers-ai'))) return true;
+  } catch { /* not built */ }
+  if (!bin || !existsSync(bin)) return false;
+  let db = 'DB';
+  try { db = JSON.parse(readFileSync(configPath(root), 'utf8').replace(/^\s*\/\/.*$/gm, ''))?.d1_databases?.[0]?.binding ?? 'DB'; } catch { /* the default binding */ }
+  const r = await exec(bin, ['d1', 'execute', db, '--remote', '--json', '--command', "SELECT COUNT(*) AS n FROM servers WHERE brain = 'workers-ai' AND state = 'open'"], {
+    cwd: workerDir(root), timeout: 25_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1', ...(accountId ? { CLOUDFLARE_ACCOUNT_ID: accountId } : {}) },
+  });
+  if (r.code !== 0) return false;
+  const parsed = parseJson(r.stdout);
+  return Number((Array.isArray(parsed) ? parsed[0] : parsed)?.results?.[0]?.n) > 0;
+}
+
+/** How to call Cloudflare's API as this computer's Wrangler login: headers, or null. Never printed. */
+export async function cloudflareAuth({ exec, env = process.env, bin, cwd } = {}) {
+  if (env.CLOUDFLARE_API_TOKEN) return { authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}` };
+  if (env.CLOUDFLARE_API_KEY && env.CLOUDFLARE_EMAIL) return { 'x-auth-key': env.CLOUDFLARE_API_KEY, 'x-auth-email': env.CLOUDFLARE_EMAIL };
+  if (!bin || !existsSync(bin)) return null;
+  const r = await exec(bin, ['auth', 'token', '--json'], { cwd, timeout: 15_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
+  if (r.code !== 0) return null;
+  const j = parseJson(r.stdout);
+  if (typeof j?.token === 'string' && j.token) return { authorization: `Bearer ${j.token}` };
+  if (typeof j?.key === 'string' && typeof j?.email === 'string') return { 'x-auth-key': j.key, 'x-auth-email': j.email };
+  return null;
+}
+
+/**
+ * What Cloudflare's answer to the probe means (its errors: developers.cloudflare.com/workers-ai/platform/errors/):
+ * `{ why, state }` with why one of ok, paid-only, missing, not-allowed, agreement, allowance, busy, auth, other.
+ */
+export function classifyProbe(status, body) {
+  const errs = Array.isArray(body?.errors) ? body.errors : [];
+  const codes = errs.map((e) => Number(e?.code)).filter(Number.isFinite);
+  const msg = errs.map((e) => String(e?.message ?? '')).filter(Boolean).join('; ');
+  const has = (c) => codes.includes(c);
+  if (status >= 200 && status < 300 && body?.success !== false) return { why: 'ok', state: 'ok', msg };
+  if (has(5035) || (status === 403 && /workers paid|paid plan|upgrade/i.test(msg))) return { why: 'paid-only', state: 'act', msg };
+  if (has(5007) || /no such model/i.test(msg) || status === 404) return { why: 'missing', state: 'act', msg };
+  if (has(5018)) return { why: 'not-allowed', state: 'act', msg };
+  if (has(5016) || /agree/i.test(msg)) return { why: 'agreement', state: 'act', msg };
+  if (has(3036) || (status === 429 && /free allocation|neurons/i.test(msg))) return { why: 'allowance', state: 'later', msg };
+  if (has(3040) || status === 429 || status >= 500) return { why: 'busy', state: 'unknown', msg };
+  if (status === 401 || has(10000) || has(10001) || (status === 403 && /auth/i.test(msg))) return { why: 'auth', state: 'unknown', msg };
+  if (status === 400) return { why: 'input', state: 'act', msg };
+  return { why: 'other', state: 'unknown', msg };
+}
+
+/**
+ * The one call. `{ status, body }`, or `{ error }` when the network failed. `fetchFn` stands in for the network in
+ * tests; the call is a one-word prompt with max_tokens 1.
+ */
+export async function probeModel({ model, accountId, headers, fetchFn = globalThis.fetch, base = 'https://api.cloudflare.com/client/v4', ms = 12_000 }) {
+  try {
+    const res = await fetchFn(`${String(base).replace(/\/+$/, '')}/accounts/${encodeURIComponent(accountId)}/ai/run/${model}`, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json', accept: 'application/json', 'user-agent': 'homie-studio-doctor' },
+      body: JSON.stringify({ messages: [{ role: 'user', content: 'Say OK.' }], max_tokens: 1 }),
+      signal: AbortSignal.timeout(ms),
+    });
+    return { status: res.status, body: await res.json().catch(() => null) };
+  } catch (error) {
+    return { error: String(error?.name === 'TimeoutError' ? `no answer in ${Math.round(ms / 1000)} s` : error?.message ?? error) };
+  }
+}
+
+/**
+ * The doctor's row, or null when no server thinks with Workers AI. `who`: the doctor's Wrangler answer
+ * (`signedIn`, `accountIds`); `bin`: the studio's own Wrangler; `remote`: the studio is live, so its database may be
+ * read; `exec`, `fetchFn` replaceable for tests.
+ */
+export async function workersAiRow({ root, studio, env = process.env, exec, fetchFn = globalThis.fetch, who = {}, bin, remote = false, cli = 'npx --no-install homie-studio' }) {
+  if (!root) return null;
+  const accountId = env.CLOUDFLARE_ACCOUNT_ID || studio?.cloudflare?.accountId || (who.accountIds?.length === 1 ? who.accountIds[0] : null);
+  if (!(await usesWorkersAi(root, { exec, env, accountId, bin: remote ? bin : null }))) return null;
+  const { model, set } = brainModelOf(root);
+  const row = {
+    id: 'workers-ai', label: 'Workers AI', need: 'for AI guides', model,
+    unlocks: 'AI guides that think and talk on servers whose brain is workers-ai, on the studio\'s own Workers AI (free: 10,000 neurons a day for the account)',
+  };
+  const where = set ? 'HOMIE_BRAIN_MODEL in wrangler.jsonc' : 'the toolkit\'s default';
+  const pick = (lead) => ({
+    who: 'ai', open: MODELS,
+    say: `${lead}Pick a model the account can run: set HOMIE_BRAIN_MODEL in wrangler.jsonc "vars" to a text-generation model from ${MODELS} that is not marked Workers Paid${set && model !== DEFAULT_MODEL ? ` (or remove it for the default, ${DEFAULT_MODEL})` : ''}, run \`${cli} doctor\` again, then \`npm run deploy\`. Until then the guides answer from the game's script.`,
+  });
+  const money = ' Moving the account to Workers Paid ($5 a month) also works, but that is the person\'s money: ask them, never decide it.';
+  if (!MODEL_ID.test(model)) return { ...row, state: 'act', detail: `${where} is "${model.slice(0, 80)}", which is not a Workers AI model id (@cf/<maker>/<model>)`, fix: pick('') };
+  if (who.signedIn === false && !env.CLOUDFLARE_API_TOKEN) return { ...row, state: 'later', detail: `${model} (${where}): checked once Wrangler is signed in`, fix: null };
+  if (!accountId) return { ...row, state: 'unknown', detail: `${model}: this login reaches several Cloudflare accounts and studio.json does not say which is the studio's (cloudflare.accountId, written at the first deploy)`, fix: null };
+  const headers = await cloudflareAuth({ exec, env, bin, cwd: workerDir(root) });
+  if (!headers) return { ...row, state: 'unknown', detail: `${model}: could not ask Cloudflare (no sign-in to call its API with)`, fix: { who: 'ai', run: 'npx wrangler login', say: 'Sign in to Cloudflare again (you approve once in the browser), then run doctor again.' } };
+  const answer = await probeModel({ model, accountId, headers, fetchFn, base: env.CLOUDFLARE_API_BASE_URL || undefined });
+  // Cloudflare's own words, without the account's id, and short.
+  const plain = (s) => String(s ?? '').split(accountId).join('<account>').replace(/\s+/g, ' ').trim().slice(0, 160);
+  if (answer.error) return { ...row, state: 'unknown', detail: `${model}: this computer's request to Cloudflare failed (${plain(answer.error)}); run doctor again`, fix: null };
+  const c = classifyProbe(answer.status, answer.body);
+  const said = c.msg ? ` (Cloudflare: "${plain(c.msg)}")` : '';
+  switch (c.why) {
+    case 'ok': return { ...row, state: 'ok', detail: `${model} answers on this studio's Cloudflare account (${where}; one tiny call just now)`, fix: null };
+    case 'paid-only': {
+      const fix = pick(model === DEFAULT_MODEL ? 'The toolkit\'s default model is paid-only now. ' : '');
+      return { ...row, state: 'act', detail: `${model} needs the Workers Paid plan, and this account is on Workers Free: every guide on a workers-ai server answers from the game's script${said}`, fix: { ...fix, say: fix.say + money } };
+    }
+    case 'missing': return { ...row, state: 'act', detail: `Cloudflare has no model ${model} (renamed or retired)${said}`, fix: pick('') };
+    case 'not-allowed': return { ...row, state: 'act', detail: `this account may not use ${model} (a private model)${said}`, fix: pick('') };
+    case 'agreement': return { ...row, state: 'act', detail: `${model} asks for its maker's licence to be agreed once before it is used${said}`, fix: pick('Agreeing to a licence is the person\'s to do, never yours; or simply: ') };
+    case 'input': return { ...row, state: 'act', detail: `${model} did not take a chat message: the guides need a text-generation model${said}`, fix: pick('') };
+    case 'allowance': return { ...row, state: 'later', detail: `today's free Workers AI allowance (10,000 neurons for the account) is used up, so ${model} could not be checked; the guides answer from the script until 00:00 UTC`, fix: { who: 'person', say: `Nothing to do now: run doctor again after 00:00 UTC. The studio's daily budget (\`${cli} agents brain <game> <server> workers-ai --budget <neurons>\`) keeps the guides under the allowance.` } };
+    case 'busy': return { ...row, state: 'unknown', detail: `Workers AI was busy just now (status ${answer.status})${said}; run doctor again in a minute`, fix: null };
+    case 'auth': return { ...row, state: 'unknown', detail: `Cloudflare did not let this sign-in run Workers AI (status ${answer.status})${said}`, fix: { who: 'ai', run: 'npx wrangler login', say: 'Sign in to Cloudflare again (the login includes Workers AI), then run doctor again.' } };
+    default: return { ...row, state: 'unknown', detail: `${model}: Cloudflare answered ${answer.status}${said}`, fix: null };
+  }
+}

package/lib/doctor.mjs

@@ -8,6 +8,9 @@
  *                                  Homie tools are there: --connector yes|no)
  *   Cloudflare         to go online: signed in, and the account's email verified (Cloudflare checks that at the
  *                                  first deploy; a deploy that went through proves it)
+ *   Workers AI         for AI guides  only when a server's guides think with Workers AI: the model they use
+ *                                  (HOMIE_BRAIN_MODEL, else the default) answers on the studio's account, not paid-only
+ *                                  or retired (lib/brain-probe.mjs: one tiny call, about 0.1 of the free daily neurons)
  *   Chrome             for checks  the two-browser check, the look pictures and playtests
  *   ffmpeg             recommended sound effects and the theme, trailers and hero footage
  *   GitHub             optional    a private backup, publishing by pull request, building from the Claude app
@@ -17,12 +20,14 @@
  *
  * It is safe at any time, inside a studio or before one exists: it only reads (local files, `--version` of a few
  * tools, `wrangler whoami`, `gh auth status`, `elevenlabs auth status`, one GET to the directory and, when a fal key
- * is set, fal's free pricing API), never changes anything, and never prints a key, a token or an account's name.
+ * is set, fal's free pricing API; when a server's AI guides use Workers AI, one read of the live database and one
+ * one-word call to the model), never changes anything, and never prints a key, a token or an account's name or id.
  * Every check has a time limit, so it answers in seconds even with no network.
  */
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { workersAiRow } from './brain-probe.mjs';
 import { findChrome } from './chrome.mjs';
 import { whyFailed } from './net.mjs';
 import { isOurs } from './statusline.mjs';
@@ -98,7 +103,8 @@ export async function setupStatus({
       if (!bin || !existsSync(bin)) return { signedIn: null };
       const r = await exec(bin, ['whoami', '--json'], { cwd: root, timeout: 25_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
       if (r.code === 124) return { signedIn: null, why: 'Wrangler did not answer in time' };
-      try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null }; } catch { return { signedIn: false }; }
+      // The accounts' ids stay in this process (the Workers AI row calls the studio's own account); never printed.
+      try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null, accountIds: Array.isArray(d.accounts) ? d.accounts.map((a) => a?.id).filter(Boolean) : [] }; } catch { return { signedIn: false }; }
     })(),
     (async () => {
       const git = await exec('git', ['--version']);
@@ -182,6 +188,15 @@ export async function setupStatus({
     });
   }
 
+  // Workers AI, only when a server's AI guides think with it: does the model they use answer on this account?
+  {
+    const local = root ? readLocal(root) : {};
+    const live = Boolean(local.deployedAt || local.connectedAt || (studio?.cloudflare?.created ?? []).some((c) => String(c).startsWith('worker:')));
+    const bin = root ? join(root, 'node_modules', '.bin', win ? 'wrangler.cmd' : 'wrangler') : null;
+    const row = root ? await workersAiRow({ root, studio, env, exec, fetchFn, who, bin, remote: live && Boolean(who.signedIn || env.CLOUDFLARE_API_TOKEN), cli }) : null;
+    if (row) rows.push(row);
+  }
+
   // Chrome, for the checks.
   {
     const found = chrome();
@@ -254,6 +269,7 @@ export async function setupStatus({
     { feature: 'Backup and pull requests', state: ready(by.github.state), needs: ['github'] },
     { feature: 'Songs and game scores', state: ready(by.elevenlabs.state), needs: ['elevenlabs'] },
     { feature: 'Painted art and generated video', state: ready(by.fal.state), needs: ['fal'] },
+    ...(by['workers-ai'] ? [{ feature: 'AI guides that think (Workers AI)', state: ready(by['workers-ai'].state), needs: ['workers-ai'] }] : []),
   ];
   const now = rows.filter((r) => ['missing', 'act'].includes(r.state) && r.fix);
   const meanwhile = rows.filter((r) => r.fix?.open && r.state !== 'ok' && (r.fix.who === 'person' || r.state === 'later'));

package/lib/template-history.json

@@ -546,6 +546,34 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.18.1": {
+   "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"
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "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/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/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>

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

@@ -31,7 +31,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, createRoom, createSaves, exposePort, jitter, q, standoff, type BodyBase, type NetEvent, type Skill } from '@homie-rocks/studio/port';
+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 { useAgents, type Goal, type Vocabulary } from '@homie-rocks/studio/agents';
 import vocabulary from '../agents.json';
 
@@ -444,6 +444,8 @@ function stepSlimes(dt: number, now: number): void {
 
 /* ------------------------------------------------------------------ input */
 const input = createControls({ actions: { strike: ['Space', 'KeyJ', 'Enter'] }, touch: { buttons: [{ id: 'strike', label: 'STRIKE' }] } });
+// A touch screen has STRIKE at the bottom right: the ask panel stands right above it (index.html, .touch).
+document.body.classList.toggle('touch', input.touch.enabled);
 function stepMe(dt: number): void {
   const b = room.hosting ? room.mine() : null;
   const isDown = b ? Boolean(b.flags & DOWN) : Boolean(myViewBody()?.flags && (myViewBody()!.flags & DOWN));
@@ -458,22 +460,54 @@ function myViewBody(): Body | null { const s = room.mySeat(); return room.view()
 /* ------------------------------------------------------------------ drawing */
 const canvas = document.getElementById('c') as HTMLCanvasElement;
 const ctx = canvas.getContext('2d', { alpha: false }) as CanvasRenderingContext2D;
-let scale = 1; let ox = 0; let oy = 0;
+let dpr = 1; let vw = 1; let vh = 1;
 function resize(): void {
-  const dpr = Math.min(2, devicePixelRatio || 1);
-  canvas.width = Math.round(innerWidth * dpr); canvas.height = Math.round(innerHeight * dpr);
-  scale = Math.min(canvas.width / W, canvas.height / H); ox = (canvas.width - W * scale) / 2; oy = (canvas.height - H * scale) / 2;
+  dpr = Math.min(2, devicePixelRatio || 1); vw = innerWidth; vh = innerHeight;
+  canvas.width = Math.round(vw * dpr); canvas.height = Math.round(vh * dpr);
+  // The page's pills sit under the hero panel, which grows with the screen (a TV's would cover them).
+  const pills = document.querySelector<HTMLElement>('.pill');
+  if (pills) pills.style.top = `calc(${Math.max(86, Math.round(76 * hudScale() + 10))}px + env(safe-area-inset-top))`;
 }
+/** CSS px per HUD unit, from the screen's CSS size: 0.7 on a phone either way up, 0.8 on a computer, 1.2 on a TV. */
+function hudScale(): number { return Math.max(Math.min(vw, vh) <= 540 ? 0.7 : 0.8, Math.min(1.4, vh / 900, vw / 560)); }
 addEventListener('resize', resize);
 resize();
 let bannerText = ''; let bannerUntil = 0;
 function banner(t: string): void { bannerText = t; bannerUntil = performance.now() + 2600; }
 const SLIME = ['#7ad35a', '#e0a83a', '#c74bd8'];
 
+/*
+ * The camera (port/view.ts). Where the whole vale fits at a size that reads (a computer, a TV) it all shows, as it
+ * always did. Where it would be small (a phone, above all held upright, where the vale was a strip a quarter of the
+ * screen tall), the vale fills the screen and follows your hero (a watcher: the hero followed), never past the vale's
+ * edge, except as far as it takes to keep your hero clear of the panel at the top and STRIKE at the bottom.
+ */
+const READABLE = 0.62; // CSS px per vale unit: a body 27 px across, a name 12 px tall
+const INSET = { top: 124, bottom: 100 }; // the hero panel and its pills; STRIKE and the ask panel's foot
+let cam: Fit | null = null;
+let lastDraw = 0;
+// Names keep clear of the guides' bubbles and of the ask panel (a page element over the canvas).
+const labels = createLabels({ screen: () => ({ w: vw, h: vh }), avoid: () => { const p = document.getElementById('asks'); return p && !p.hidden ? [...bubbleBoxes, p.getBoundingClientRect()] : bubbleBoxes; } });
+let bubbleBoxes: { left: number; top: number; right: number; bottom: number }[] = [];
+let shownLabels: LabelOut[] = [];
+function aim(): Fit {
+  const v = lookOnly ? room.viewBody() : null;
+  const focus = !lookOnly && me.has ? { x: me.x, y: me.y } : v ? { x: v.x, y: v.y } : null;
+  const phone = Math.min(vw, vh) <= 540;
+  return fitView({ world: { w: W, h: H }, screen: { w: vw, h: vh }, readable: READABLE, zoom: Math.max(READABLE, Math.min(vw, vh) / (phone ? 560 : 820)), focus, whole: lookOnly && !v, inset: INSET });
+}
+
 function draw(t: number): void {
-  const s = scale;
+  const dt = lastDraw ? Math.min(0.1, (t - lastDraw) / 1000) : 0;
+  lastDraw = t;
+  const want = aim();
+  // A cut when the camera changes kind (a phone turned, a watcher's pick); else it glides.
+  cam = !cam || cam.follow !== want.follow ? want : easeView(cam, want, dt, 10);
+  const s = cam.scale;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
   ctx.fillStyle = '#0b0f0a'; ctx.fillRect(0, 0, canvas.width, canvas.height);
-  ctx.save(); ctx.translate(ox, oy); ctx.scale(s, s);
+  ctx.save();
+  ctx.setTransform(dpr * s, 0, 0, dpr * s, dpr * (vw / 2 - cam.x * s), dpr * (vh / 2 - cam.y * s));
   // The vale: moss, and embers that drift.
   ctx.fillStyle = '#16210f'; ctx.fillRect(0, 0, W, H);
   for (let i = 0; i < 70; i++) {
@@ -494,6 +528,15 @@ function draw(t: number): void {
   }
   // The hero whose view this is: my own, or the one a watcher follows (null: the vale, nobody in gold).
   const viewS = room.viewSeat();
+  const sx = (x: number): number => vw / 2 + (x - (cam as Fit).x) * s;
+  const sy = (y: number): number => vh / 2 + (y - (cam as Fit).y) * s;
+  // Names are drawn after the vale, on the screen, at a size that reads on any screen; they never pile up.
+  const fs = clamp(18 * s, 12, 20);
+  ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
+  const names: LabelIn[] = [];
+  const said: { x: number; y: number; head: number; text: string }[] = [];
+  const mine: ScreenBox[] = []; // your own hero and its name: no bubble covers them
+  const meAt = (() => { const v = room.view().find((b) => !b.bot && b.seat === viewS); return v ? { x: v.x, y: v.y } : null; })();
   for (const b of room.view()) {
     const self = !b.bot && b.seat === viewS;
     const local = self && !room.hosting && !net.watching;
@@ -508,72 +551,121 @@ function draw(t: number): void {
     ctx.fillStyle = 'rgba(0,0,0,.55)'; ctx.fillRect(x - 24, y - R - 12, 48, 5);
     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;
-    ctx.font = '600 18px ui-sans-serif, system-ui, sans-serif'; ctx.textAlign = 'center'; ctx.fillStyle = self ? '#ffcf6e' : '#e7d9b4';
     // An AI's name already ends in " · AI" (a guide, a companion); a plain bot says bot.
-    ctx.fillText(`${b.name}${b.bot && !b.name.endsWith(AI_MARK) ? ' · bot' : ''}${isGuide ? ' · guide' : ''} · ${b.level}`, x, y - R - 18);
-    const said = bubbles.get(b.slot);
-    if (said && said.until > performance.now()) bubble(x, y - R - 44, said.text);
+    const text = `${b.name}${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.
+    const body = { left: sx(x - 24), top: sy(y - R - 12), right: sx(x + 24), bottom: sy(y + R) };
+    if (body.right < 0 || body.left > vw || body.bottom < 0 || body.top > vh) continue; // off screen: no name at the edge
+    if (self) { const w = ctx.measureText(text).width; mine.push(body, { left: sx(x) - w / 2 - 6, top: body.top - 4 - fs * 1.2, right: sx(x) + w / 2 + 6, bottom: body.top }); }
+    names.push({ key: b.slot, text, x: sx(x), y: body.top - 3, w: ctx.measureText(text).width, h: fs * 1.2, below: body.bottom + 4 + fs * 1.2, body, self, rank: (b.bot ? (isGuide ? 1 : 2) : 0) * 10_000 + near });
+    const line = bubbles.get(b.slot);
+    // The bubble's tail stops just above the guide's own name, so the name keeps its spot while it speaks.
+    if (line && line.until > performance.now()) said.push({ x: sx(x), y: body.top - 3 - fs * 1.2 - 12, head: body.top, text: line.text });
   }
   ctx.restore();
+  // Speech bubbles first (labels keep clear of them), then the names; your own last, on a dark chip.
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  bubbleBoxes = said.map((b) => bubble(b.x, b.y, b.text, fs, b.head, mine));
+  ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
+  shownLabels = labels.place(names, dt);
+  ctx.textAlign = 'center'; ctx.textBaseline = 'middle'; ctx.lineJoin = 'round';
+  for (const l of [...shownLabels].sort((a, b) => Number(Boolean(a.self)) - Number(Boolean(b.self)))) {
+    if (l.alpha <= 0) continue;
+    ctx.globalAlpha = l.alpha;
+    if (l.moved) {
+      // Moved off its own spot: a thin line to its body says whose it is.
+      const under = l.top > l.y;
+      ctx.strokeStyle = 'rgba(231,217,180,.45)'; ctx.lineWidth = 1;
+      ctx.beginPath(); ctx.moveTo(l.cx, under ? l.top : l.bottom); ctx.lineTo(l.x, under ? (l.body?.bottom ?? l.top - 6) : l.y + 2); ctx.stroke();
+    }
+    if (l.self) { ctx.fillStyle = 'rgba(10,14,9,.72)'; ctx.beginPath(); ctx.roundRect(l.left - 5, l.top - 1, l.right - l.left + 10, l.bottom - l.top + 2, 6); ctx.fill(); }
+    else { ctx.strokeStyle = 'rgba(8,11,6,.8)'; ctx.lineWidth = 3; ctx.strokeText(l.text, l.cx, l.cy); }
+    ctx.fillStyle = l.self ? '#ffcf6e' : '#e7d9b4';
+    ctx.fillText(l.text, l.cx, l.cy);
+  }
+  ctx.globalAlpha = 1; ctx.textBaseline = 'alphabetic';
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
   hud(t);
 }
 
-/** A speech bubble: up to three short lines, above a guide. */
-function bubble(x: number, y: number, text: string): void {
-  ctx.font = '600 16px ui-sans-serif, system-ui, sans-serif';
+type ScreenBox = { left: number; top: number; right: number; bottom: number };
+const touches = (a: ScreenBox, b: ScreenBox): boolean => a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+/**
+ * A speech bubble: up to three short lines, above a guide (screen px). It never covers your own hero or its name
+ * (`clearOf`): it moves aside, or higher, and its tail runs down to the guide's head (`head`), so whose line it is
+ * stays plain. Returns the box it covers.
+ */
+function bubble(x: number, y: number, text: string, fs: number, head: number, clearOf: ScreenBox[]): ScreenBox {
+  const f = Math.max(12, fs - 1);
+  ctx.font = `600 ${f}px ui-sans-serif, system-ui, sans-serif`;
   const words = text.split(' ');
   const lines: string[] = [];
   let line = '';
   for (const w of words) { if ((line + ' ' + w).trim().length > 26 && line) { lines.push(line); line = w; } else line = (line + ' ' + w).trim(); }
   if (line) lines.push(line);
   const shown = lines.slice(0, 3);
-  const wid = Math.max(...shown.map((l) => ctx.measureText(l).width)) + 22;
-  const hgt = shown.length * 20 + 12;
+  const wid = Math.max(...shown.map((l) => ctx.measureText(l).width)) + 20;
+  const hgt = shown.length * f * 1.25 + 10;
+  // Where it goes: above the guide; else beside that, either way; else higher, over whatever it must keep clear of.
+  const above = Math.min(y, ...clearOf.map((c) => c.top - 12));
+  const spots = [y, above].flatMap((by) => [x, x + wid * 0.6 + 16, x - wid * 0.6 - 16].map((bx) => ({ bx: clamp(bx, wid / 2 + 4, vw - wid / 2 - 4), by })));
+  const at = spots.find((p) => p.by - hgt >= 0 && !clearOf.some((c) => touches({ left: p.bx - wid / 2, top: p.by - hgt, right: p.bx + wid / 2, bottom: p.by + 8 }, c))) ?? spots[0]!;
+  const cx = at.bx; const by = at.by;
+  const tail = clamp(x, cx - wid / 2 + 12, cx + wid / 2 - 12);
   ctx.fillStyle = 'rgba(14,30,27,.92)'; ctx.strokeStyle = 'rgba(127,216,200,.75)'; ctx.lineWidth = 2;
-  ctx.beginPath(); ctx.roundRect(x - wid / 2, y - hgt, wid, hgt, 10); ctx.fill(); ctx.stroke();
-  ctx.beginPath(); ctx.moveTo(x - 7, y); ctx.lineTo(x + 7, y); ctx.lineTo(x, y + 9); ctx.closePath(); ctx.fillStyle = 'rgba(14,30,27,.92)'; ctx.fill();
-  ctx.fillStyle = '#e9fff9'; ctx.textAlign = 'center';
-  shown.forEach((l, i) => ctx.fillText(l, x, y - hgt + 22 + i * 20));
+  ctx.beginPath(); ctx.roundRect(cx - wid / 2, by - hgt, wid, hgt, 10); ctx.fill(); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(tail - 6, by); ctx.lineTo(tail + 6, by); ctx.lineTo(tail, by + 8); ctx.closePath(); ctx.fillStyle = 'rgba(14,30,27,.92)'; ctx.fill();
+  if (head > by + 12 || tail !== x) { ctx.strokeStyle = 'rgba(127,216,200,.75)'; ctx.lineWidth = 2; ctx.beginPath(); ctx.moveTo(tail, by + 8); ctx.lineTo(x, head - 2); ctx.stroke(); }
+  ctx.fillStyle = '#e9fff9'; ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+  shown.forEach((l, i) => ctx.fillText(l, cx, by - hgt + 5 + f * 1.25 * (i + 0.5)));
+  ctx.textBaseline = 'alphabetic';
+  return { left: cx - wid / 2, top: by - hgt, right: cx + wid / 2, bottom: by + 8 };
 }
 
 function hud(t: number): void {
-  const k = Math.max(0.8, Math.min(1.4, canvas.height / 900));
+  // Device px per HUD unit: as before on an upright phone, a computer and a TV; readable on a phone on its side and on
+  // a high-density computer screen (it was sized by device pixels, so half as big there).
+  const k = dpr * hudScale();
   ctx.save(); ctx.scale(k, k);
   const x0 = 14; const y0 = 14;
-  ctx.fillStyle = 'rgba(10,14,9,.62)'; ctx.fillRect(x0, y0, 240, 62);
-  ctx.textAlign = 'left'; ctx.font = '700 16px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#ffcf6e';
-  if (lookOnly) {
-    // A watcher's panel is the followed hero's, as the room has them (their save stays in their own browser).
-    const v = room.viewBody();
-    if (v) {
-      ctx.fillText(`${v.name} · Lv ${v.level}`, x0 + 10, y0 + 22);
-      ctx.fillStyle = 'rgba(255,255,255,.12)'; ctx.fillRect(x0 + 10, y0 + 32, 140, 6);
-      ctx.fillStyle = '#7ad35a'; ctx.fillRect(x0 + 10, y0 + 32, (140 * clamp(v.hp, 0, v.maxHp)) / Math.max(1, v.maxHp), 6);
-      ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
-      ctx.fillText(`${v.score} xp tonight${v.flags & DOWN ? ' · down' : ''}`, x0 + 10, y0 + 54);
-    } else {
-      const heroes = room.view().filter((b) => !b.bot).length;
-      ctx.fillText('Watching the vale', x0 + 10, y0 + 22);
-      ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
-      ctx.fillText(`${heroes} ${heroes === 1 ? 'hero' : 'heroes'} · ${(room.fast() ?? []).length} slimes`, x0 + 10, y0 + 46);
-    }
-  } else ctx.fillText(hero ? `${hero.name}${hero.hardcore ? ' ☠' : ''} · Lv ${hero.level}` : heroLoaded ? 'No hero yet' : 'Loading your hero…', x0 + 10, y0 + 22);
-  if (hero && !lookOnly) {
+  const TITLE = '700 16px ui-sans-serif, system-ui, sans-serif';
+  const SMALL = '600 13px ui-sans-serif, system-ui, sans-serif';
+  // 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 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.
+  ctx.font = TITLE; const titleW = ctx.measureText(title).width;
+  ctx.font = SMALL; const subW = sub ? ctx.measureText(sub).width : 0;
+  const pw = Math.max(bar ? 140 : 0, titleW, subW) + 20;
+  ctx.fillStyle = 'rgba(10,14,9,.62)'; ctx.fillRect(x0, y0, pw, 62);
+  ctx.textAlign = 'left'; ctx.font = TITLE; ctx.fillStyle = '#ffcf6e';
+  ctx.fillText(title, x0 + 10, y0 + 22);
+  if (bar) {
     ctx.fillStyle = 'rgba(255,255,255,.12)'; ctx.fillRect(x0 + 10, y0 + 32, 140, 6);
-    ctx.fillStyle = '#ffcf6e'; ctx.fillRect(x0 + 10, y0 + 32, (140 * hero.xp) / xpFor(hero.level), 6);
-    ctx.font = '600 13px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#e7d9b4';
-    ctx.fillText(`${hero.gold} gold · ${hero.kills} slain`, x0 + 10, y0 + 54);
+    ctx.fillStyle = bar.colour; ctx.fillRect(x0 + 10, y0 + 32, 140 * clamp(bar.of, 0, 1), 6);
   }
+  if (sub) { ctx.font = SMALL; ctx.fillStyle = '#e7d9b4'; ctx.fillText(sub, x0 + 10, y0 + (bar ? 54 : 46)); }
   const c = room.clock();
-  ctx.textAlign = 'center'; ctx.font = '700 16px ui-sans-serif, system-ui, sans-serif'; ctx.fillStyle = '#f3ead2';
+  ctx.font = TITLE; ctx.fillStyle = '#f3ead2';
   const cw = canvas.width / k;
-  ctx.fillText(c.phase === 'over' ? `Dawn · night ${c.n + 1} in ${c.secondsLeft}s` : `Night ${c.n} · ${Math.floor(c.secondsLeft / 60)}:${String(c.secondsLeft % 60).padStart(2, '0')}`, cw / 2, 30);
+  const clock = c.phase === 'over' ? `Dawn · night ${c.n + 1} in ${c.secondsLeft}s` : `Night ${c.n} · ${Math.floor(c.secondsLeft / 60)}:${String(c.secondsLeft % 60).padStart(2, '0')}`;
+  // Top centre; on a narrow screen where that would touch the panel, just under it.
+  if (x0 + pw + 10 > cw / 2 - ctx.measureText(clock).width / 2) { ctx.textAlign = 'left'; ctx.fillText(clock, x0 + 10, y0 + 62 + 20); }
+  else { ctx.textAlign = 'center'; ctx.fillText(clock, cw / 2, 30); }
+  ctx.textAlign = 'center';
   if (c.phase === 'over') {
     const rows = room.results().slice(0, 5);
-    ctx.fillStyle = 'rgba(10,14,9,.78)'; ctx.fillRect(cw / 2 - 150, 44, 300, 30 + rows.length * 22);
-    ctx.fillStyle = '#ffcf6e'; ctx.fillText('Tonight\'s hunters', cw / 2, 66);
+    // Under the page's own pills on a narrow screen (they are buttons, above the canvas), else under the clock.
+    const top = vw <= 540 ? 132 * (dpr / k) : 44;
+    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, 90 + i * 22));
+    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));
   }
   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();
@@ -640,6 +732,7 @@ setInterval(() => { if (hero && document.visibilityState === 'visible') void sav
 /** The guide nearest my hero (within 340 px), and the asks I can make of it: drawn as buttons, four times a second. */
 let asksFor = -1;
 let asksSig = '';
+const askEls = new Map<string, HTMLButtonElement>();
 function paintAsks(): void {
   const panel = $('asks');
   const mySeat = room.mySeat();
@@ -649,18 +742,21 @@ function paintAsks(): void {
     for (const b of room.view()) {
       const sl = (net.slots ?? []).find((x) => x.slot === b.slot);
       if (!sl?.agent || sl.agent.role !== 'guide') continue;
+      // The guide the panel is for keeps it while it is in reach, unless another is much nearer: two guides at the
+      // party's side would otherwise swap it four times a second, and a thumb's tap would land on a button just redrawn.
       const d = Math.hypot(b.x - me.x, b.y - me.y);
-      if (d < 340 && (!best || d < best.d)) best = { slot: b.slot, name: b.name, d };
+      const rank = d - (b.slot === asksFor ? 120 : 0);
+      if (d < 340 && (!best || rank < best.d)) best = { slot: b.slot, name: b.name, d: rank };
     }
   }
   if (!best) { panel.hidden = true; asksFor = -1; asksSig = ''; return; }
   const quests = (net.stateOf<string[]>('quests') ?? (room.hosting ? openQuests() : ['slime-hunt'])).slice(0, 3);
-  // Help with each open quest, one place to be led to (not the one I am in), and "No thanks"; three on a phone.
+  // Help with each open quest, one place to be led to (not the one I am in), and "No thanks"; three on a phone (either way up).
   const zone = zoneOf(me.x, me.y);
   const all = agents.askButtons(best.slot, { quests });
   const lead = all.filter((b) => b.k === 'lead_me' && b.args['place'] !== zone).slice(0, 1);
   const order = [...all.filter((b) => b.k === 'ask_help'), ...lead, ...all.filter((b) => b.k === 'no_thanks')];
-  const buttons = order.slice(0, innerWidth < 540 ? 3 : 5);
+  const buttons = order.slice(0, Math.min(innerWidth, innerHeight) < 540 ? 3 : 5);
   const sig = `${best.slot}|${best.name}|${buttons.map((b) => b.text).join('|')}`;
   panel.hidden = false;
   if (sig === asksSig) return;
@@ -668,19 +764,29 @@ function paintAsks(): void {
   asksFor = best.slot;
   panel.dataset['slot'] = String(best.slot);
   $('asks-who').textContent = `${best.name} · guide`;
+  // A button that stays is the same element (a quest that opens or closes adds or takes one): a thumb's tap that lands
+  // while the list changes around it still counts.
   const list = $('asks-list');
-  list.textContent = '';
-  for (const b of buttons) {
-    const btn = document.createElement('button');
-    btn.type = 'button';
-    btn.textContent = b.text;
-    btn.dataset['ask'] = b.k;
-    btn.addEventListener('click', () => {
-      if (asksFor < 0) return;
-      if (agents.ask(asksFor, b.k, b.args)) { logGuide({ ev: 'asked', slot: asksFor, k: b.k, args: b.args }); btn.classList.add('sent'); setTimeout(() => btn.classList.remove('sent'), 900); }
-    });
-    list.append(btn);
-  }
+  const keep = new Set<string>();
+  buttons.forEach((b, i) => {
+    const key = `${b.k}|${JSON.stringify(b.args)}`;
+    keep.add(key);
+    let el = askEls.get(key);
+    if (!el) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.dataset['ask'] = b.k;
+      btn.addEventListener('click', () => {
+        if (asksFor < 0) return;
+        if (agents.ask(asksFor, b.k, b.args)) { logGuide({ ev: 'asked', slot: asksFor, k: b.k, args: b.args }); btn.classList.add('sent'); setTimeout(() => btn.classList.remove('sent'), 900); }
+      });
+      askEls.set(key, btn);
+      el = btn;
+    }
+    if (el.textContent !== b.text) el.textContent = b.text;
+    if (list.children[i] !== el) list.insertBefore(el, list.children[i] ?? null);
+  });
+  for (const [key, el] of askEls) if (!keep.has(key)) { el.remove(); askEls.delete(key); }
 }
 setInterval(paintAsks, 250);
 
@@ -707,6 +813,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).
+  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) })),
 });
 
 exposePort(net, {

package/starters/gem-rush/src/main.ts

@@ -32,8 +32,9 @@
  * Canvas 2D on purpose: the point is the contract, in ~700 readable lines.
  */
 import { createNetplay, Roster, q, lerp, capMove, PALETTE, AI_MARK, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
-// The port toolkit's probe: what `homie-studio port check` reads for the owner tests (and sandbox + audio shims).
-import { exposePort } from '@homie-rocks/studio/port';
+// The port toolkit: its probe (what `homie-studio port check` reads for the owner tests, and sandbox + audio shims),
+// and a flat world on every screen (port/view.ts: the camera, and name labels that never pile up).
+import { createLabels, exposePort, fitView, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
 
 /* ------------------------------------------------------------------ rules */
 const W = 1600;
@@ -601,6 +602,9 @@ addEventListener('resize', resize);
 resize();
 
 const cam = { x: W / 2, y: H / 2, scale: 0 };
+const labels = createLabels({ screen: () => ({ w: innerWidth, h: innerHeight }) });
+let shownLabels: LabelOut[] = [];
+let lastDraw = 0;
 /** Where a seat's body is drawn now (host: the real body; replica: interpolated), or null. */
 function seatPos(seat: number): { x: number; y: number } | null {
   if (seat === mySeat() && me.has && !net.watching) return me;
@@ -620,12 +624,17 @@ function draw(t: number): void {
   const view = viewSeat();
   const followed = net.watching && view !== null ? seatPos(view) : null;
   const overview = net.watching ? !followed : mySeat() === null;
-  const wantScale = overview ? Math.min(cw / (W + 80), ch / (H + 80)) : Math.min(cw, ch) / (phone ? 560 : 820);
+  // The camera: close on the body whose view this is, never past the arena's edge (except as far as it takes to keep
+  // that body clear of the HUD), and never so far out that an empty band shows beside the arena (held upright, a
+  // phone showed the arena as a band with a third of the screen dark below or above it; now the arena fills the
+  // screen). Following nobody: the whole arena.
+  const focus = net.watching ? followed : overview || !me.has ? null : me;
+  const want = overview ? { scale: Math.min(cw / (W + 80), ch / (H + 80)), x: W / 2, y: H / 2 }
+    : fitView({ world: { w: W, h: H }, screen: { w: cw, h: ch }, readable: 0, zoom: Math.min(cw, ch) / (phone ? 560 : 820), focus, inset: { top: 52, bottom: 36 } });
   // A watcher's switch glides: the zoom and the pan ease over a few frames, never a cut.
-  cam.scale = cam.scale ? cam.scale + (wantScale - cam.scale) * 0.12 : wantScale;
+  cam.scale = cam.scale ? cam.scale + (want.scale - cam.scale) * 0.12 : want.scale;
   const scale = cam.scale;
-  const target = net.watching ? (followed ?? { x: W / 2, y: H / 2 }) : overview || !me.has ? { x: W / 2, y: H / 2 } : me;
-  cam.x += (target.x - cam.x) * 0.2; cam.y += (target.y - cam.y) * 0.2;
+  cam.x += (want.x - cam.x) * 0.2; cam.y += (want.y - cam.y) * 0.2;
   ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
   const bg = ctx.createRadialGradient(cw / 2, ch / 2, 0, cw / 2, ch / 2, Math.max(cw, ch) * 0.8);
   bg.addColorStop(0, '#0d1426'); bg.addColorStop(1, '#04060c');
@@ -686,6 +695,11 @@ function draw(t: number): void {
       list.push({ slot: d.slot, seat: d.seat >= 0 ? d.seat : null, x: own && me.has ? me.x : d.x, y: own && me.has ? me.y : d.y, bot: d.seat < 0, name: s?.name ?? (d.seat >= 0 ? `Player ${d.seat + 1}` : botName(d.slot)), mine: isView(d.seat >= 0 ? d.seat : null, d.seat < 0) });
     }
   }
+  // Names go on after the arena, on the screen, so they read at one size on any screen and never pile up.
+  const fs = Math.round(Math.max(15, Math.min(22, (15 * Math.min(cw, ch)) / 720)));
+  ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
+  const tags: LabelIn[] = [];
+  const viewAt = list.find((a) => a.mine) ?? null;
   for (const a of list) {
     const colour = colourOf(a.slot, a.bot ? null : a.seat);
     ctx.globalAlpha = a.bot ? 0.62 : 1;
@@ -693,11 +707,32 @@ function draw(t: number): void {
     ctx.fillStyle = 'rgba(0,0,0,0.35)'; ctx.beginPath(); ctx.arc(a.x, a.y, R_AV * 0.45, 0, Math.PI * 2); ctx.fill();
     if (a.mine) { ctx.strokeStyle = '#ffffff'; ctx.lineWidth = 4; ctx.beginPath(); ctx.arc(a.x, a.y, R_AV + 7, 0, Math.PI * 2); ctx.stroke(); }
     ctx.globalAlpha = 1;
-    ctx.font = `600 ${Math.round(15 / Math.max(0.6, scale))}px ui-sans-serif, system-ui, sans-serif`;
-    ctx.textAlign = 'center'; ctx.fillStyle = a.mine ? '#ffffff' : 'rgba(232,236,245,0.8)';
-    ctx.fillText(a.mine && !net.watching ? 'You' : label(a.name, a.bot), a.x, a.y - R_AV - 12);
+    const text = a.mine && !net.watching ? 'You' : label(a.name, a.bot);
+    const sx = cw / 2 + (a.x - cam.x) * scale; const sy = ch / 2 + (a.y - cam.y) * scale; const r = (R_AV + (a.mine ? 7 : 0)) * scale;
+    if (sx + r < 0 || sx - r > cw || sy + r < 0 || sy - r > ch) continue; // off screen: no name at the edge
+    // People before bots, nearer the view's body first; each keeps off the others' bodies when it can.
+    tags.push({ key: a.slot, text, x: sx, y: sy - r - 5, w: ctx.measureText(text).width, h: fs * 1.2, below: sy + r + 4 + fs * 1.2, body: { left: sx - r, top: sy - r, right: sx + r, bottom: sy + r }, self: a.mine, rank: (a.bot ? 10_000 : 0) + (viewAt ? Math.hypot(a.x - viewAt.x, a.y - viewAt.y) : 0) });
   }
   ctx.restore();
+  shownLabels = labels.place(tags, Math.min(0.1, (t - (lastDraw || t)) / 1000));
+  lastDraw = t;
+  ctx.font = `600 ${fs}px ui-sans-serif, system-ui, sans-serif`;
+  ctx.textAlign = 'center'; ctx.textBaseline = 'middle'; ctx.lineJoin = 'round';
+  for (const l of [...shownLabels].sort((x, y) => Number(Boolean(x.self)) - Number(Boolean(y.self)))) {
+    if (l.alpha <= 0) continue;
+    ctx.globalAlpha = l.alpha;
+    if (l.moved) {
+      // Off its own spot: a thin line to its body says whose it is.
+      const under = l.top > l.y;
+      ctx.strokeStyle = 'rgba(232,236,245,0.4)'; ctx.lineWidth = 1;
+      ctx.beginPath(); ctx.moveTo(l.cx, under ? l.top : l.bottom); ctx.lineTo(l.x, under ? (l.body?.bottom ?? l.top - 6) : l.y + 2); ctx.stroke();
+    }
+    if (l.self) { ctx.fillStyle = 'rgba(6,10,20,0.7)'; ctx.beginPath(); ctx.roundRect(l.left - 5, l.top - 1, l.right - l.left + 10, l.bottom - l.top + 2, 6); ctx.fill(); }
+    else { ctx.strokeStyle = 'rgba(4,6,12,0.85)'; ctx.lineWidth = 3; ctx.strokeText(l.text, l.cx, l.cy); }
+    ctx.fillStyle = l.self ? '#ffffff' : 'rgba(232,236,245,0.85)';
+    ctx.fillText(l.text, l.cx, l.cy);
+  }
+  ctx.globalAlpha = 1; ctx.textBaseline = 'alphabetic';
 
   hud(cw, ch, phone, list);
   if (stick.active) {
@@ -797,6 +832,8 @@ net.expose({
   predictionError: () => predictionError,
   /** Where the camera looks and whose view it is (a watcher following a player: their body, under the camera). */
   camera: () => ({ x: cam.x, y: cam.y, scale: cam.scale, view: viewSeat() }),
+  /** The names as drawn (boxes, never the text): the e2e probe counts overlaps and checks your own. */
+  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) })),
   /** performance.now() of the first keyed-state value and the first live snapshot this browser received. */
   arrivals: () => ({ firstStateAt, firstSnapAt }),
   /** Harness hook (host only): knock the body of `seat` back, toward the middle of the arena. */

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.0';
+export const STUDIO_VERSION_TAG = '0.18.1';