@homie-rocks/studio 0.30.2 → 0.31.1

package/worker/parts.mjs

@@ -0,0 +1,275 @@
+/**
+ * THE STUDIO'S SHARED GAME PARTS, AS ITS SITE SERVES THEM (parts/PARTS.md section 4).
+ *
+ *   /.well-known/homie-parts.json     what the hub and `parts add` read: the shared parts, each with the game it came from
+ *   /parts/<id>/<version>/<file>      a packed version's files, exactly as hashed: immutable, CORS open for GET
+ *   /parts/  and  /parts/<id>/        the studio's own pages, in its own look: the list, and one part with its preview
+ *   a game's landing                  a "Parts from this game" band of its own (partsBand)
+ *
+ * A PRIVATE PART IS NEVER REACHABLE. Two things hold that: the build copies only shared parts into the site
+ * (lib/parts-build.mjs), and nothing here answers a file the built index does not name, so a file that reached the
+ * assets some other way is still not served from /parts/.
+ */
+import { esc, icon, layout, notFoundPage } from './site.mjs';
+
+const PART_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
+const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,40})?$/;
+/** A packed part's files: framed by the part's own page and by the hub, so they keep their own frame rule (index.mjs finish). */
+export const PART_FILES = /^\/parts\/[a-z0-9][a-z0-9-]{0,47}\/\d{1,6}\.\d{1,6}\.\d{1,6}[^/]*\//;
+export const PARTS_WELL_KNOWN = '/.well-known/homie-parts.json';
+export const isPartsPath = (path) => path === PARTS_WELL_KNOWN || path === '/parts' || path.startsWith('/parts/');
+
+const CORS = { 'access-control-allow-origin': '*', 'x-content-type-options': 'nosniff' };
+const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8', ...headers } });
+const TYPES = { html: 'text/html; charset=utf-8', htm: 'text/html; charset=utf-8', js: 'text/javascript; charset=utf-8', mjs: 'text/javascript; charset=utf-8', ts: 'text/plain; charset=utf-8', tsx: 'text/plain; charset=utf-8', json: 'application/json; charset=utf-8', css: 'text/css; charset=utf-8', md: 'text/plain; charset=utf-8', txt: 'text/plain; charset=utf-8', glsl: 'text/plain; charset=utf-8', wgsl: 'text/plain; charset=utf-8', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', glb: 'model/gltf-binary', gltf: 'model/gltf+json', bin: 'application/octet-stream', mp3: 'audio/mpeg', ogg: 'audio/ogg', wav: 'audio/wav', m4a: 'audio/mp4', woff2: 'font/woff2', ktx2: 'image/ktx2', hdr: 'application/octet-stream' };
+
+/** The built index (site/dist/parts/index.json): only shared parts are ever in it. An older build has none. */
+export async function partsIndex(env, origin) {
+  try {
+    const res = await env.ASSETS.fetch(new Request(`${origin}/parts/index.json`));
+    if (!res.ok) return { v: 1, studio: {}, parts: [] };
+    const body = await res.json();
+    return body && Array.isArray(body.parts) ? body : { v: 1, studio: {}, parts: [] };
+  } catch { return { v: 1, studio: {}, parts: [] }; }
+}
+
+/**
+ * One index entry as the world sees it: how to add it, and the game it came out of with its page and Play address.
+ * Only a PUBLIC game is named (a private or invite-only game's parts are still shared, without saying where from).
+ */
+function entryOf(p, cat, url) {
+  const g = p.from?.game ? (cat.games ?? []).find((x) => x.id === p.from.game) : null;
+  const { from, ...rest } = p;
+  return {
+    ...rest,
+    ...(g ? { from: { game: g.id, name: g.name ?? g.id, studio: cat.studio?.name ?? from.studio ?? null, page: `${url.origin}/${g.id}/`, play: `${url.origin}/${g.id}/play` } } : {}),
+    add: `${url.host}/${p.id}`,
+  };
+}
+
+export async function partsRoutes(request, env, url, { catalogueOf }) {
+  const path = url.pathname;
+  const read = request.method === 'GET' || request.method === 'HEAD';
+  if (path === PARTS_WELL_KNOWN) {
+    if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: { ...CORS, 'access-control-allow-methods': 'GET, HEAD' } });
+    if (!read) return json({ ok: false, error: 'method' }, 405, { allow: 'GET, HEAD', ...CORS });
+    const [index, cat] = await Promise.all([partsIndex(env, url.origin), catalogueOf()]);
+    return json({ v: 1, studio: { name: cat.studio?.name ?? index.studio?.name ?? null, url: url.origin }, parts: index.parts.map((p) => entryOf(p, cat, url)) }, 200, { ...CORS, 'cache-control': 'public, max-age=300' });
+  }
+  const segs = path.split('/').filter(Boolean);
+  // /parts/<id>/<version>/<file…>: a packed file, only when the index names that part and that version.
+  if (segs.length >= 4 && PART_ID.test(segs[1]) && VERSION.test(segs[2])) {
+    if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: { ...CORS, 'access-control-allow-methods': 'GET, HEAD' } });
+    if (!read) return new Response('GET only', { status: 405, headers: { allow: 'GET, HEAD', ...CORS } });
+    const index = await partsIndex(env, url.origin);
+    const part = index.parts.find((p) => p.id === segs[1]);
+    let file;
+    try { file = segs.slice(3).map(decodeURIComponent).join('/'); } catch { file = '..'; }
+    const gone = () => new Response('not found', { status: 404, headers: { ...CORS, 'cache-control': 'no-store' } });
+    if (!part || !(part.versions ?? []).includes(segs[2]) || file.split('/').some((s) => !s || s === '..' || s.startsWith('.'))) return gone();
+    const res = await env.ASSETS.fetch(new Request(`${url.origin}/parts/${segs[1]}/${segs[2]}/${file.split('/').map(encodeURIComponent).join('/')}`));
+    if (!res.ok) return gone();
+    const ext = file.split('.').pop().toLowerCase();
+    const html = ext === 'html' || ext === 'htm';
+    return new Response(request.method === 'HEAD' ? null : res.body, {
+      headers: {
+        'content-type': TYPES[ext] ?? 'application/octet-stream',
+        // A version's bytes never change (lib/parts.mjs packPart refuses), so a year and immutable is true.
+        'cache-control': `public, max-age=31536000, immutable${html ? ', no-transform' : ''}`,
+        ...CORS,
+        // A preview page runs with no origin of its own: none of this site's cookies or storage, framable anywhere.
+        ...(html ? { 'content-security-policy': 'sandbox allow-scripts allow-pointer-lock' } : {}),
+      },
+    });
+  }
+  if (!read) return null;
+  const cat = await catalogueOf();
+  // A game called "parts" keeps its own address; its studio's parts are still in the well-known file.
+  if ((cat.games ?? []).some((g) => g.id === 'parts')) return null;
+  if (path === '/parts') return Response.redirect(`${url.origin}/parts/`, 301);
+  const index = await partsIndex(env, url.origin);
+  const parts = index.parts.map((p) => entryOf(p, cat, url));
+  if (path === '/parts/') return parts.length ? partsPage(cat, parts, url) : notFoundPage('This studio shares no game parts yet.', cat);
+  if (segs.length === 2 && PART_ID.test(segs[1])) {
+    const part = parts.find((p) => p.id === segs[1]);
+    // The same answer for a private part and one that never existed: nothing says which.
+    if (!part) return notFoundPage('There is no shared part at this address.', cat);
+    if (!path.endsWith('/')) return Response.redirect(`${url.origin}/parts/${part.id}/`, 301);
+    return partPage(cat, part, url);
+  }
+  return notFoundPage('There is no shared part at this address.', cat);
+}
+
+/* ------------------------------------------------------------------ the pages */
+
+const KIND_WORDS = { character: 'Character', rig: 'Rig', clips: 'Animation clips', environment: 'Environment', effect: 'Effect', sound: 'Sound', ui: 'UI', mechanic: 'Mechanic', shader: 'Shader', 'level-generator': 'Level generator', 'bot-brain': 'Bot brain', 'audio-pack': 'Audio pack', 'set-piece': 'Set piece' };
+const kindOf = (p) => KIND_WORDS[p.kind] ?? 'Part';
+const CSS = `<style>
+.pgrid{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:18px;margin:8px 0 0;padding:0;list-style:none}
+.pcard{display:flex;flex-direction:column;gap:8px;padding:18px;border:1px solid color-mix(in srgb,var(--fg) 14%,transparent);border-radius:16px;text-decoration:none;color:inherit;background:color-mix(in srgb,var(--fg) 3%,transparent)}
+.pcard:hover{border-color:var(--fg)}
+.pcard img{width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:10px}
+.pcard h3{margin:0;font:800 19px/1.2 var(--display)}
+.pcard p{margin:0;color:var(--dim);font-size:14px}
+.ptag{font:600 11px/1.4 var(--mono);letter-spacing:.14em;text-transform:uppercase;color:var(--dim)}
+.pframe{display:block;width:100%;aspect-ratio:16/9;border:1px solid color-mix(in srgb,var(--fg) 14%,transparent);border-radius:16px;background:#000}
+.pview{container-type:inline-size}
+.pview .pframe{aspect-ratio:var(--pv,16/9)}
+@container (max-width:599.98px){.pview .pframe{min-height:min(320px,70vh);min-height:min(320px,70svh)}.pview.pview-own .pframe{aspect-ratio:var(--pvn,var(--pv,16/9));min-height:0}}
+.popen{display:inline-flex;align-items:center;gap:8px;min-height:44px;margin:8px 0 0;color:inherit;font-weight:600;text-decoration:underline;text-underline-offset:3px}
+.popen svg{width:16px;height:16px}
+.popen:focus-visible{outline:3px solid var(--fg);outline-offset:3px;border-radius:6px}
+.pfacts{display:grid;grid-template-columns:max-content 1fr;gap:8px 20px;margin:0}
+.pfacts dt{color:var(--dim);font-size:14px}.pfacts dd{margin:0;overflow-wrap:anywhere}
+.pband{max-width:calc(1180px + 2 * var(--gutter));margin:0 auto;padding:clamp(40px,6vw,80px) var(--gutter)}
+.pband h2{margin:6px 0 10px;font:800 clamp(28px,4vw,44px)/1.05 var(--display)}
+.pband .plead,.plead{max-width:62ch;color:var(--dim);margin:0 0 18px}
+.psay{display:flex;align-items:center;justify-content:space-between;gap:14px;margin:18px 0;padding:14px 16px;border:1px solid color-mix(in srgb,var(--fg) 14%,transparent);border-radius:14px}
+.psay code{display:block;margin-top:4px;font:500 15px/1.4 var(--mono);overflow-wrap:anywhere}
+.pcopy{display:inline-flex;align-items:center;gap:8px;min-height:40px;padding:0 14px;border:1px solid color-mix(in srgb,var(--fg) 24%,transparent);border-radius:10px;background:none;color:inherit;font:600 14px/1 var(--body,inherit);cursor:pointer}
+.pcopy svg{width:16px;height:16px}
+</style>`;
+const head = (kicker, title, lead, extra = '') => `<header class="head"><p class="kicker">${esc(kicker)}</p><h1>${esc(title)}</h1>${lead ? `<p class="lead">${esc(lead)}</p>` : ''}${extra}</header>`;
+const studioOf = (cat) => cat.studio?.name ?? 'Studio';
+const fromLine = (p) => (p.from?.game ? `From <a href="/${esc(p.from.game)}/">${esc(p.from.name ?? p.from.game)}</a>` : '');
+/** What a person says to their AI to get the part, in plain words with its name and reference: no command to type. */
+const sayAdd = (p) => `Add the "${p.name}" part from ${p.add} to my game`;
+const sayRow = (label, say) => `<div class="psay"><div><span class="ptag">${esc(label)}</span><code>${esc(say)}</code></div><button class="pcopy" type="button" data-copy="${esc(say)}">${icon('copy')}<span data-copy-word>Copy</span></button></div>`;
+
+function card(p) {
+  const img = p.preview?.image ? `<img src="${esc(`${p.url}${p.preview.image}`)}" alt="" loading="lazy">` : '';
+  return `<li><a class="pcard" href="/parts/${esc(p.id)}/">${img}<span class="ptag">${esc(kindOf(p))} · ${esc(p.license ?? '')}</span><h3>${esc(p.name)}</h3><p>${esc(p.summary ?? '')}</p>${p.from?.game ? `<p>From ${esc(p.from.name ?? p.from.game)}</p>` : ''}</a></li>`;
+}
+
+export function partsPage(cat, parts, url) {
+  const name = studioOf(cat);
+  // Grouped by the game each came out of: a mashup starts from "the creature in that game".
+  const groups = new Map();
+  for (const p of parts) { const k = p.from?.game ?? ''; if (!groups.has(k)) groups.set(k, []); groups.get(k).push(p); }
+  const body = [...groups].sort(([a], [b]) => (a === '' ? 1 : b === '' ? -1 : a.localeCompare(b))).map(([k, list]) => `<p class="sec"${k ? ` id="from-${esc(k)}"` : ''}>${k ? `From ${esc(list[0].from.name ?? k)}` : 'More parts'}</p><ul class="pgrid">${list.map(card).join('')}</ul>`).join('');
+  return layout(cat, {
+    title: `Game parts · ${name}`, description: `Pieces of ${name}'s games that other studios can use in their own: creatures, levels, mechanics, sounds. Each with its licence.`, origin: url.origin, path: '/parts/', page: 'parts', head: CSS,
+    main: `${head('Game parts', 'Take a piece, make a game', `Pieces of ${name}'s games, shared one by one. Take the creature from one game, the level from another and the bot brain from a third, and make something new. Each part says its licence and who to credit.`)}
+<div class="wrap">${body}</div>`,
+  });
+}
+
+function requiresRows(p) {
+  const r = p.requires ?? {};
+  const rows = [];
+  for (const [k, v] of Object.entries(r.packages && typeof r.packages === 'object' ? r.packages : {})) rows.push(`${esc(k)} ${esc(v)} (a package, from npm)`);
+  for (const x of Array.isArray(r.parts) ? r.parts : []) rows.push(`${esc(x)} (another part)`);
+  return rows;
+}
+function costLine(c) {
+  if (!c || typeof c !== 'object') return '';
+  const bits = [];
+  if (Number.isFinite(c.bytes)) bits.push(`${c.bytes >= 1048576 ? `${(c.bytes / 1048576).toFixed(1)} MB` : `${Math.max(1, Math.round(c.bytes / 1024))} KB`} to download`);
+  if (Number.isFinite(c.triangles)) bits.push(`${c.triangles.toLocaleString('en')} triangles`);
+  if (Number.isFinite(c.drawCalls)) bits.push(`${c.drawCalls} draw calls`);
+  if (Number.isFinite(c.textureMB)) bits.push(`${c.textureMB} MB of textures`);
+  return `${bits.join(' · ')}${c.measuredOn ? ` (measured on ${String(c.measuredOn).slice(0, 80)})` : ''}`;
+}
+
+/**
+ * A preview's declared shape ("4:3") as two whole numbers, or null. The same reading as previewAspect() in
+ * lib/parts.mjs (a Worker cannot import that file: it reads the disk); test/parts.test.mjs holds the two together.
+ * The page's CSS is built from these NUMBERS, never from the text in part.json, so nothing a part declares can
+ * write CSS or HTML of its own.
+ */
+export function aspectOf(value) {
+  const m = typeof value === 'string' ? /^([1-9]\d?):([1-9]\d?)$/.exec(value) : null;
+  if (!m) return null;
+  const w = Number(m[1]); const h = Number(m[2]);
+  return w > 32 || h > 32 || w > 3 * h || h > 2 * w ? null : { w, h };
+}
+
+/**
+ * The part's interactive preview: its frame in the shape the part declares, and a plain link out of the frame.
+ *
+ * THE SHAPE. `preview.aspect` (default 16:9), and `preview.phoneAspect` when the frame is under 600 px wide. With no
+ * phone shape declared a narrow frame still gets a minimum height: 16:9 across a 390 px phone is about 197 px,
+ * which hides whatever a preview draws under its heading and controls.
+ *
+ * THE LINK opens the same preview file in a tab of its own, at the size of the screen. That file is this studio's
+ * own packed part on this studio's own address, and it is answered with `content-security-policy: sandbox
+ * allow-scripts allow-pointer-lock` (above), so a tab of its own gives it nothing the frame did not: no origin, so
+ * none of the site's cookies or storage, no forms, no pop-ups, no navigating the page that opened it (and
+ * rel="noopener" gives it no handle on that page either). It is a link, so it needs no script and a keyboard reaches it.
+ */
+function previewOf(p) {
+  const src = esc(`${p.url}${p.preview.page}`);
+  const shape = aspectOf(p.preview.aspect) ?? { w: 16, h: 9 };
+  const phone = aspectOf(p.preview.phoneAspect);
+  const vars = `--pv:${Number(shape.w)}/${Number(shape.h)}${phone ? `;--pvn:${Number(phone.w)}/${Number(phone.h)}` : ''}`;
+  return `<div class="pview${phone ? ' pview-own' : ''}" style="${vars}"><iframe class="pframe" title="${esc(p.name)}: try it" src="${src}" sandbox="allow-scripts allow-pointer-lock" loading="lazy" referrerpolicy="no-referrer"></iframe></div>
+<a class="popen" href="${src}" target="_blank" rel="noopener noreferrer">${icon('arrow')}<span>Open the preview in its own tab</span></a>`;
+}
+
+export function partPage(cat, p, url) {
+  const name = studioOf(cat);
+  const preview = p.preview?.page
+    ? previewOf(p)
+    : p.preview?.image ? `<img class="pframe" src="${esc(`${p.url}${p.preview.image}`)}" alt="${esc(p.name)}">` : '';
+  const facts = [
+    ['Kind', esc(kindOf(p))],
+    p.from?.game ? ['From the game', `<a href="/${esc(p.from.game)}/">${esc(p.from.name ?? p.from.game)}</a> · <a href="/${esc(p.from.game)}/play">Play it</a>`] : null,
+    ['Licence', `${esc(p.license ?? 'none named')}${p.license && !/^LicenseRef-/.test(p.license) ? ` · <a href="https://spdx.org/licenses/${esc(p.license)}.html" rel="noopener">what it allows</a>` : ''}`],
+    p.attribution ? ['Credit', esc(p.attribution)] : null,
+    ['Version', `${esc(p.version)}${(p.versions ?? []).length > 1 ? ` (also ${esc(p.versions.filter((v) => v !== p.version).join(', '))})` : ''}`],
+    requiresRows(p).length ? ['Builds on', requiresRows(p).join('<br>')] : null,
+    costLine(p.cost) ? ['Costs', esc(costLine(p.cost))] : null,
+    p.physical ? ['Size', esc([p.physical.units ? `in ${p.physical.units}` : '', Number.isFinite(p.physical.scale) ? `scale ${p.physical.scale}` : '', p.physical.pivot ? `pivot at the ${p.physical.pivot}` : '', p.physical.collision ? 'with collision data' : ''].filter(Boolean).join(', '))] : null,
+    p.skeleton?.rig ? ['Skeleton', esc(`${p.skeleton.rig}${(p.skeleton.clips ?? []).length ? `: ${p.skeleton.clips.join(', ')}` : ''}`)] : null,
+    p.contract?.netplay ? ['In a room', esc({ 'host-authoritative': 'the host decides; everyone else is shown the result', replicated: 'every player runs it from shared state', local: 'each screen runs its own' }[p.contract.netplay] ?? p.contract.netplay)] : null,
+    p.provenance?.source ? ['Made', esc({ original: `by ${name}`, generated: `generated on ${name}'s own account`, imported: `brought in by ${name}${p.provenance.origin ? ` from ${p.provenance.origin}` : ''}` }[p.provenance.source] ?? p.provenance.source)] : null,
+    (p.tags ?? []).length ? ['Tags', esc(p.tags.join(', '))] : null,
+  ].filter(Boolean);
+  return layout(cat, {
+    title: `${p.name} · a game part from ${name}`, description: `${p.summary ?? ''} A ${kindOf(p).toLowerCase()} from ${name}${p.from?.name ? `'s ${p.from.name}` : ''}, shared under ${p.license ?? 'its own terms'}.`.trim(), origin: url.origin, path: `/parts/${p.id}/`, page: 'part', head: CSS,
+    image: p.preview?.image ? `${p.url}${p.preview.image}` : null,
+    main: `${head(`${kindOf(p)} · game part`, p.name, p.summary ?? '', `<div class="keys"><a class="ghost" href="/parts/">${icon('arrow')}<span>All parts</span></a>${p.from?.game ? `<a class="ghost" href="/${esc(p.from.game)}/play">${icon('games')}<span>Play ${esc(p.from.name ?? p.from.game)}</span></a>` : ''}</div>`)}
+<div class="wrap">
+${preview ? `<p class="sec">Try it</p>${preview}` : ''}
+<p class="sec">Use it in your game</p>
+<p class="plead">In a chat with your Homie studio open, ask for it by name:</p>
+${sayRow('Say', sayAdd(p))}
+<p class="plead">Your AI fetches the files, checks every one, copies them into your studio and credits ${esc(name)} in your game. They are yours to tune from there.</p>
+<p class="sec">About this part</p>
+<dl class="pfacts">${facts.map(([k, v]) => `<dt>${esc(k)}</dt><dd>${v}</dd>`).join('')}</dl>
+</div>`,
+  });
+}
+
+/* ------------------------------------------------------------------ a game's landing: "Parts from this game" */
+
+/**
+ * A band of its own on a game's landing: the SHARED parts that came out of this game, and what to ask an AI for to
+ * build something new from them. Empty when the game shared none. It stands by itself: its own markup and styles.
+ */
+export function partsBand(g, parts, host) {
+  const mine = parts.filter((p) => p.from?.game === g.id);
+  if (!mine.length) return '';
+  const say = mine.length === 1 ? sayAdd({ ...mine[0], add: `${host}/${mine[0].id}` }) : `Make a new game in my Homie studio with these parts of ${g.name}: ${mine.slice(0, 4).map((p) => `${host}/${p.id}`).join(', ')}`;
+  return `${CSS}<section class="pband" aria-labelledby="parts-title" data-parts-band>
+  <p class="ptag">Take a piece</p>
+  <h2 id="parts-title">Parts from this game</h2>
+  <p class="plead">Pieces of ${esc(g.name)} you can put in a game of your own, each with its licence. Mix them with parts from other games: a creature from here, a level from there.</p>
+  <ul class="pgrid">${mine.map(card).join('')}</ul>
+  ${sayRow('In a chat with your Homie studio open, say', say)}
+  <div class="keys"><a class="btn" href="/parts/#from-${esc(g.id)}">${icon('spark')}<span>See the parts</span></a></div>
+</section>`;
+}
+
+/** A game's landing with its parts band, when it has shared parts (worker/index.mjs calls this on the landing it built). */
+export async function withPartsBand(res, env, url, g) {
+  try {
+    if (!res || res.status !== 200 || !/text\/html/i.test(res.headers.get('content-type') ?? '')) return res;
+    const index = await partsIndex(env, url.origin);
+    const band = partsBand(g, index.parts.map((p) => ({ ...p, from: p.from?.game === g.id ? { ...p.from, name: g.name } : p.from })), url.host);
+    if (!band) return res;
+    const html = await res.text();
+    const at = html.lastIndexOf('</main>');
+    return new Response(at < 0 ? html : `${html.slice(0, at)}${band}\n${html.slice(at)}`, { status: res.status, headers: res.headers });
+  } catch { return res; }
+}

package/worker/room.mjs

@@ -49,7 +49,49 @@ import { CHAT_LIMITS, CHAT_RATES, HELD_WORDS, allows, cleanText, floor, normaliz
 
 export const NET_VERSION = 1;
 /** The contract revision this relay speaks (NETPLAY.md): optional fields, frames and refusals; the wire stays `v: 1`. */
-export const NET_REVISION = 8;
+export const NET_REVISION = 9;
+/**
+ * Revision 9 (NETPLAY.md sections 22 and 23). STALL: how long a host may send no snapshot, while others are present,
+ * before the room is handed on: 1.5 s unless the game names its own (game.json `netplay.stallMs`), never under
+ * 1.5 s (a shorter one swaps hosts on a single slow frame) and never over 10 s (a frozen host must still be replaced
+ * while its players are watching a still picture).
+ */
+export const STALL = Object.freeze({ ms: 1500, min: 1500, max: 10_000 });
+/** A game's own stall time, held to STALL's bounds; null when it names none (or not a number). */
+export function stallOf(v) {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) && n > 0 ? Math.max(STALL.min, Math.min(STALL.max, n)) : null;
+}
+const VERSION_TEXT = /^[A-Za-z0-9._-]{1,32}$/;
+/** A game revision (game.json `netplay.version`): 1 to 32 of A-Z a-z 0-9 . _ -, a number as its digits; else null. */
+export function versionOf(v) {
+  const t = typeof v === 'number' && Number.isFinite(v) ? String(v) : typeof v === 'string' ? v.trim() : '';
+  return VERSION_TEXT.test(t) ? t : null;
+}
+const FEATURE_TEXT = /^[a-z0-9][a-z0-9-]{0,23}$/;
+/** What a build says it can do (`hello.feat`): up to 8 short lowercase words. */
+export function featuresOf(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const x of list) { const k = String(x ?? '').toLowerCase(); if (FEATURE_TEXT.test(k) && !out.includes(k)) out.push(k); if (out.length >= 8) break; }
+  return out;
+}
+/**
+ * A SOCKET THAT WENT AWAY IS NOT A FAILED ROOM. A browser that closes its tab, loses its network or is replaced by a
+ * new host ends its socket without a goodbye, and the runtime reports that as an error ("Network connection lost",
+ * "WebSocket peer disconnected"…). Those are departures: the room has already handled them (the seat is held, the
+ * host is replaced). Anything else thrown while the room was doing something IS a failure, and is logged with the
+ * room and what it was doing. `departure(error)` says which; the transport (the Table) asks it at its boundary.
+ */
+const DEPARTURE = /network connection lost|connection (?:was )?(?:closed|reset|aborted|lost)|peer disconnected|websocket (?:is )?(?:closed|closing|not open|already closed)|socket (?:is )?closed|client disconnected|disconnected|broken pipe|econnreset|epipe|aborted|cancell?ed|the script will never generate a response|durable object reset/i;
+export function departure(error) {
+  const text = typeof error === 'string' ? error : `${error?.name ?? ''} ${error?.message ?? ''} ${error?.code ?? ''}`;
+  return DEPARTURE.test(text);
+}
+/** An error as a log line carries it: its name and message, cut short. Never the frame it was thrown for. */
+export function errorLine(error) {
+  return String(error?.stack && typeof error.stack === 'string' ? error.stack.split('\n').slice(0, 4).join(' | ') : error?.message ?? error).slice(0, 400);
+}
 const POLICY_KINDS = ['open', 'humans-only', 'hybrid', 'beginner'];
 /**
  * A room's policy before the Worker says anything (and the public server's with nothing set): today's behaviour.
@@ -220,7 +262,8 @@ export class NetRoom {
    * @param {number} [o.persistMs]  the checkpoint/round/state are saved at most this often
    * @param {{save: (o: object) => void, clear?: () => void} | null} [o.store]
    * @param {() => number} [o.now]
-   * @param {(line: object) => void} [o.log]
+   * @param {(line: object) => void} [o.log]  one line per lifecycle event (hello, leave, elect, a failed operation),
+   *   each stamped `at` (ISO time) with its room; never a token, a ticket, a browser key or a frame's contents
    */
   constructor({
     code, maxPlayers = 8, maxScreens = 16, perIp = 12, stallMs = 1500, silentMs = 2500, idleMs = 10_000,
@@ -257,7 +300,16 @@ export class NetRoom {
     this.persistMs = persistMs;
     this.store = store;
     this.now = now;
-    this.log = log;
+    // Every line says when: a departure and a failure seconds apart are told apart by their times.
+    const stamp = () => { try { return new Date(now()).toISOString(); } catch { return new Date().toISOString(); } };
+    this.log = (line) => { try { log({ at: stamp(), ...line }); } catch { /* a log that throws never takes the room with it */ } };
+    /**
+     * Revision 9, section 23: the build this room runs (undefined: nobody has come yet), the build that is live now
+     * (the Worker's word with every socket; undefined: nobody says), and the count of stays in a seat (`peer.occ`).
+     */
+    this.gameVer = undefined;
+    this.currentVer = undefined;
+    this.occSeq = 0;
     /** id → client (including sockets that have not said hello yet) */
     this.clients = new Map();
     /** seat → { token, name, since, present } */
@@ -346,15 +398,35 @@ export class NetRoom {
       badge: typeof conn.badge === 'string' && conn.badge.length <= 16 ? conn.badge : null,
       // Revision 7: the latest view the host showed this AI (what its arguments are checked against), and its pace.
       lastView: null, viewAt: 0, doAt: 0,
+      // Revision 9: the game revision this socket's page was served with. The Worker's word (it is in the socket's
+      // address, so a helper from before revisions carries it too) when the transport gives one, else the hello's.
+      verWord: 'ver' in conn ? versionOf(conn.ver) : undefined, ver: null, feat: [], staleTold: false,
     };
     this.clients.set(c.id, c);
     return {
       id: c.id,
-      onMessage: (text) => this.onMessage(c, text),
-      onClose: () => this.onClose(c, 'closed'),
+      onMessage: (text) => this.guard(c, 'message', () => this.onMessage(c, text), text),
+      /** `via`: how the transport learned it (`close`, or `error`: the socket failed, which is how a lost network arrives). */
+      onClose: (via = 'close') => this.guard(c, 'close', () => this.onClose(c, 'closed', via)),
     };
   }
 
+  /**
+   * The boundary every socket callback crosses. A room operation that throws is logged with what the room was doing
+   * (the frame's type, never its contents: a hello carries a seat token) and never reaches the transport, where the
+   * runtime would print it as an uncaught error with no room and no time on it. The socket's client stays as it is:
+   * one bad frame does not end a seat.
+   */
+  guard(c, op, fn, text = null) {
+    try { return fn(); } catch (error) {
+      let frame = null;
+      if (typeof text === 'string') { const m = /^\s*\{\s*"t"\s*:\s*"([a-z-]{1,16})"/.exec(text.slice(0, 64)); frame = m ? m[1] : null; }
+      this.stats.failed = (this.stats.failed ?? 0) + 1;
+      this.log({ ev: 'failed', room: this.code, op, ...(frame ? { frame } : {}), id: c?.id ?? null, seat: c?.seat ?? null, role: c && c.helloed ? this.roleOf(c) : null, clients: this.clients.size, error: errorLine(error) });
+      return undefined;
+    }
+  }
+
   /**
    * The shell's watch socket: the room's facts, and (revision 6) the party's vote from the play page's card. A vote
    * from it counts as the seat of the client in this room with the same browser key (`conn.browser`).
@@ -403,7 +475,11 @@ export class NetRoom {
   host() { return this.hostId ? this.clients.get(this.hostId) ?? null : null; }
   hostRef() { const h = this.host(); return h ? { id: h.id, seat: h.seat } : null; }
   roleOf(c) { return c.id === this.hostId ? 'host' : c.seat === null ? 'screen' : 'replica'; }
-  peer(c) { return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}), ...(c.badge && !c.agent ? { badge: c.badge } : {}) }; }
+  peer(c) {
+    // Revision 9: which stay in the seat this is (`occ`), the peer's game revision and what its build can do.
+    const occ = c.seat !== null ? this.seats.get(c.seat)?.occ : undefined;
+    return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}), ...(c.badge && !c.agent ? { badge: c.badge } : {}), ...(Number.isInteger(occ) ? { occ } : {}), ...(c.ver ? { ver: c.ver } : {}), ...(c.feat.length ? { feat: [...c.feat] } : {}) };
+  }
   /** A hands-`host` agent (section 17): no game client of its own, so no snapshots, checkpoints or state. */
   lite(c) { return Boolean(c.agent && c.agent.hands === 'host'); }
   seatedHumans() { return this.live().filter((c) => c.seat !== null && !c.agent); }
@@ -513,7 +589,10 @@ export class NetRoom {
         this.stats.snaps += 1;
         this.snapTimes.push(now);
         while (this.snapTimes.length && this.snapTimes[0] < now - 1000) this.snapTimes.shift();
-        const out = JSON.stringify({ t: 'snap', from: c.seat, ...snap });
+        // A heartbeat (revision 9): the host's last state again while its frames hitch. It counts as a snapshot here
+        // (the host is alive), and replicas are told which it is.
+        const out = JSON.stringify({ t: 'snap', from: c.seat, ...snap, ...(m.hb === 1 ? { hb: 1 } : {}) });
+        if (m.hb === 1) this.stats.heartbeats = (this.stats.heartbeats ?? 0) + 1;
         this.lastSnapText = out;
         for (const o of this.others(c)) {
           if (this.lite(o)) continue; // an agent with no game client draws nothing
@@ -720,6 +799,33 @@ export class NetRoom {
       c.agent = { pass: String(a.pass ?? '').slice(0, 16), role: ['party', 'guide', 'player'].includes(a.role) ? a.role : 'party', hands: a.hands === 'host' ? 'host' : 'self', by: ['studio', 'guest', 'service'].includes(a.by) ? a.by : 'studio' };
       c.agentName = aiName(a.name ?? a.label ?? 'Agent');
     }
+    // REVISIONS (section 23): a room runs one build of its game at a time. A client with no game code of its own (an
+    // AI the host moves) has no build.
+    c.ver = c.verWord !== undefined ? c.verWord : versionOf(m.ver);
+    c.feat = featuresOf(m.feat);
+    const lite = Boolean(c.agentWord && c.agentWord.hands === 'host');
+    if (!lite) {
+      const here = live.filter((o) => !this.lite(o));
+      const cur = this.currentVer;
+      if (here.length && (this.gameVer ?? null) !== c.ver) {
+        if (cur !== undefined && c.ver !== cur) {
+          // The newcomer is the old one (a tab open since before a deploy): it is told to reload, for good.
+          this.log({ ev: 'stale', room: this.code, id: c.id, ver: c.ver, room_ver: this.gameVer ?? null, current: cur });
+          return refuse('stale', 'This game was updated. Reload to play the new version.', { ver: cur });
+        }
+        // The room is the old one: its players are told a new build is live (once each), and the newcomer waits for
+        // it (not final: its helper knocks again, and is let in once nobody on the old build is left).
+        for (const o of here) if (cur !== undefined && o.ver !== cur && !o.staleTold) { o.staleTold = true; this.send(o, { t: 'stale', ver: cur }); }
+        this.log({ ev: 'room-stale', room: this.code, id: c.id, ver: c.ver, room_ver: this.gameVer ?? null, current: cur ?? null });
+        return refuse('room-stale', 'This room is still running another version of the game. It opens to this one when its players reload.', { ver: this.gameVer ?? null });
+      }
+      if (!here.length) {
+        // Nobody on the other build is left: the room is this build's now, and starts fresh. A checkpoint, a snapshot
+        // and keyed state written by other code are exactly what a new build must not read.
+        if (this.gameVer !== undefined && this.gameVer !== c.ver) this.forgetWorld(c.ver);
+        this.gameVer = c.ver;
+      }
+    }
     if (this.perIp && c.ip && live.filter((o) => o.ip === c.ip).length >= this.perIp) return refuse('too-many', `at most ${this.perIp} sockets per address in one room`);
     if (live.length >= this.maxPlayers + this.maxScreens) return refuse('room-full', 'this room is full; try another');
     c.device = m.device === 'phone' || m.device === 'tv' ? m.device : 'desk';
@@ -792,9 +898,12 @@ export class NetRoom {
       this.stats.elections.push({ at: now, id: c.id, seat: c.seat, why });
       if (this.stats.elections.length > 32) this.stats.elections.shift();
     }
-    const lite = this.lite(c);
+    // An older build let in to its own room (it was here first, or the room was empty): it plays, and is told.
+    const behind = !lite && this.currentVer !== undefined && c.ver !== this.currentVer;
+    if (behind) c.staleTold = true;
     this.send(c, {
       t: 'welcome', v: NET_VERSION, rev: NET_REVISION, id: c.id, room: this.code, seat: c.seat, token: c.token, name: c.name, colour: c.colour,
+      ...(this.gameVer ? { ver: this.gameVer } : {}), ...(behind ? { stale: { ver: this.currentVer } } : {}), stall: this.stallMs,
       role, why, host: this.hostRef(), peers: this.peers(), st: now, max: this.maxPlayers,
       round: this.lastRound, roster: this.lastRoster, snap: lite ? null : this.lastSnap, state: lite ? {} : this.stateObject(),
       ...(role === 'host' ? { ckpt: this.lastCkpt } : {}),
@@ -814,7 +923,7 @@ export class NetRoom {
     }
     // A roster from before an agent sat is labelled again now (its seat is an AI's).
     if (c.agent && Array.isArray(this.lastRoster)) this.lastRoster = this.labelRoster(this.lastRoster);
-    this.log({ ev: 'hello', room: this.code, id: c.id, seat: c.seat, device: c.device, want: c.want, role, why, full, resumed: typeof m.token === 'string' && m.token === c.token, ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: c.agent.hands } : {}) });
+    this.log({ ev: 'hello', room: this.code, id: c.id, seat: c.seat, device: c.device, want: c.want, role, why, full, resumed: typeof m.token === 'string' && m.token === c.token, clients: this.live().length, ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: c.agent.hands } : {}), ...(c.ver ? { ver: c.ver } : {}) });
     this.persist(now); // a new seat (or a new host) is written now, not on the next tick: a deploy can come any moment
     this.tellWatchers();
   }
@@ -853,7 +962,8 @@ export class NetRoom {
    */
   seatFor(token, kind = 'human') {
     if (token) for (const [seat, s] of this.seats) if (s.token === token && Boolean(s.agent) === (kind === 'agent')) return seat;
-    const fresh = () => ({ token: randomId(18), name: '', since: this.now(), present: true, agent: null });
+    // Every new holder of a seat is a new stay in it (`peer.occ`): a host tells "they came back" from "somebody new".
+    const fresh = () => ({ token: randomId(18), name: '', since: this.now(), present: true, agent: null, occ: (this.occSeq += 1) });
     const reserve = this.reserve();
     const order = [];
     if (kind === 'agent') {
@@ -1247,17 +1357,20 @@ export class NetRoom {
     }
   }
 
-  onClose(c, why) {
+  onClose(c, why, via = null) {
     if (this.clients.get(c.id) !== c) return;
     this.clients.delete(c.id);
     if (!c.helloed) return;
+    const wasHost = c.id === this.hostId;
     const now = this.now();
     if (c.seat !== null) {
       const s = this.seats.get(c.seat);
       if (s && s.token === c.token) { s.present = false; s.since = now; }
     }
     for (const o of this.others(c)) this.send(o, { t: 'leave', id: c.id, seat: c.seat, why });
-    this.log({ ev: 'leave', room: this.code, id: c.id, seat: c.seat, why });
+    // One line per departure, with what the room looked like. A `leave` is a departure (a closed tab, a lost network
+    // arriving as the socket's error, a host that was replaced); a `failed` line (guard) is a room operation that threw.
+    this.log({ ev: 'leave', room: this.code, id: c.id, seat: c.seat, why, ...(via ? { via } : {}), role: wasHost ? 'host' : c.seat === null ? 'screen' : 'replica', left: this.live().length });
     if (c.id === this.hostId) {
       this.hostId = null;
       this.elect(null, why === 'replaced' ? 'host-replaced' : why === 'silent' ? 'host-stalled' : 'host-left');
@@ -1372,6 +1485,8 @@ export class NetRoom {
       this.lastSnap = null; this.lastSnapText = null; this.lastCkpt = null; this.lastRound = null; this.lastRoster = null;
       this.state.clear(); this.stateBytes = 0; this.seats.clear(); this.preferHost = null;
       this.emptySince = 0; this.openedAt = 0; this.askedMax = null;
+      // The room is nobody's build again (section 23): the next visitor's is its build.
+      this.gameVer = undefined;
       // The party's dial and vote are the room's: a new party starts from the server's level.
       this.level = null; this.levelBy = null; this.vote = null; this.agentsOut = null;
       // Room chat (section 19): an empty room forgets what was said, as it forgets everything else.
@@ -1602,7 +1717,8 @@ export class NetRoom {
   saved(now = this.now()) {
     return {
       v: NET_VERSION, room: this.code, savedAt: now, maxPlayers: this.maxPlayers, hostSeat: this.host()?.seat ?? null, openedAt: this.openedAt || null,
-      seats: [...this.seats].map(([seat, s]) => (s.agent ? [seat, s.token, s.name, s.agent] : [seat, s.token, s.name])),
+      seats: [...this.seats].map(([seat, s]) => [seat, s.token, s.name, s.agent ?? null, s.occ ?? null]),
+      occSeq: this.occSeq, ...(this.gameVer !== undefined ? { gameVer: this.gameVer } : {}),
       ckpt: this.lastCkpt, round: this.lastRound, roster: this.lastRoster, state: this.stateObject(),
       // Section 17: a deploy keeps the room's policy, the party's dial and what its game reads.
       policy: this.policy, level: this.level, levelBy: this.levelBy, caps: [...this.caps],
@@ -1619,7 +1735,10 @@ export class NetRoom {
     if (!saved || saved.v !== NET_VERSION || !(now - Number(saved.savedAt) < 120_000)) return false;
     if (Number.isInteger(saved.maxPlayers)) this.maxPlayers = Math.max(1, Math.min(this.seatCap, saved.maxPlayers));
     if (Number.isFinite(saved.openedAt) && saved.openedAt > 0) this.openedAt = saved.openedAt;
-    for (const [seat, token, name, agent] of saved.seats ?? []) this.seats.set(seat, { token, name, since: now, present: false, agent: agent && typeof agent === 'object' ? agent : null });
+    for (const [seat, token, name, agent, occ] of saved.seats ?? []) this.seats.set(seat, { token, name, since: now, present: false, agent: agent && typeof agent === 'object' ? agent : null, ...(Number.isInteger(occ) ? { occ } : {}) });
+    // A stay's number is never given twice while a checkpoint may still name it.
+    this.occSeq = Math.max(this.occSeq, Number.isInteger(saved.occSeq) ? saved.occSeq : 0, ...[...this.seats.values()].map((x) => x.occ ?? 0));
+    if ('gameVer' in saved) this.gameVer = versionOf(saved.gameVer);
     const pol = normalizePolicy(saved.policy);
     if (pol) this.policy = pol;
     if (Number.isInteger(saved.level)) { this.level = Math.max(1, Math.min(this.policy.levelMax, saved.level)); this.levelBy = saved.levelBy === 'owner' ? 'owner' : 'vote'; }
@@ -1911,6 +2030,28 @@ export class NetRoom {
    * The room's seats, changed while it runs (the owner's "max players per room"). Players already seated above the
    * new number keep their seat until they leave; nobody new is seated there. Never above the room's own cap.
    */
+  /** The game's own stall time (game.json `netplay.stallMs`), held to STALL's bounds; anything else: the default. */
+  setStall(ms) {
+    this.stallMs = stallOf(ms) ?? STALL.ms;
+    return this.stallMs;
+  }
+
+  /** The build that is live now (the Worker's word, from the catalogue): a string, or null when the game names none. */
+  setCurrent(ver) {
+    this.currentVer = ver === undefined ? undefined : versionOf(ver);
+  }
+
+  /**
+   * The room changes build (section 23): everything the old build's rules wrote is dropped, so the new build's first
+   * host starts a fresh round. Seats keep their tokens and names (a player who reloads comes back to their seat).
+   */
+  forgetWorld(next) {
+    this.log({ ev: 'build-changed', room: this.code, from: this.gameVer ?? null, to: next ?? null });
+    this.lastSnap = null; this.lastSnapText = null; this.lastCkpt = null; this.lastRound = null; this.lastRoster = null;
+    this.state.clear(); this.stateBytes = 0; this.preferHost = null;
+    this.persistDirty = true;
+  }
+
   setSeats(n, perIp = null) {
     this.seatCap = Math.max(1, Math.floor(n));
     this.maxPlayers = Math.max(1, Math.min(this.seatCap, this.askedMax ?? this.seatCap));
@@ -2009,6 +2150,8 @@ export class NetRoom {
       policy: this.policyOut(),
       ...(this.vote ? { vote: this.voteView() } : {}),
       caps: [...this.caps],
+      // Revision 9: the build this room runs (null: the game names none, or nobody is here) and its stall time.
+      ver: this.gameVer ?? null, stallMs: this.stallMs,
       // Revision 7: whether this room's game has a vocabulary its AI may speak (agents.json).
       vocab: Boolean(this.vocab),
       memory: {