@homie-rocks/studio 0.31.0 → 0.32.0

package/starters/hero-rush-3d/src/main.ts

@@ -49,6 +49,13 @@
  * byte). A model that is refused or not there is drawn as a stand-in in the same colours: a round never waits on, or
  * breaks for, a model.
  *
+ * HEADINGS, AND THERE ARE TWO: a body's facing (`fa`, drawn as `yaw`) is `Math.atan2(dx, dy)` in the game's own x and y, so yaw 0 faces +y
+ * (three.js's +z, the way the models are built) and it goes straight into `rotation.y`. That is also the yaw
+ * `@homie-rocks/camera` means (0 faces +Z, positive turns toward +X, radians), so a follow or chase camera from that
+ * package takes a body's facing as it stands. The knock and aim angles (`ang`, `base`) are the OTHER kind,
+ * `Math.atan2(dy, dx)`: 0 faces +x. Never hand one of those to a camera or to `rotation.y` without converting it:
+ * `headingFrom({ zero: '+x', toward: '+z' })` from `@homie-rocks/camera/heading.js` is the adapter.
+ *
  * PHONE BUDGETS: under 100 draw calls and 150k triangles a frame (the `drawCalls` and `triangles` probes read
  * renderer.info), the pixel ratio at most 1.5 on a phone and 2 on a computer, and no shadow map on a phone: a soft
  * disc under each body, coin, tree and rock (a computer draws the sun's real shadows). Repeated things are one
@@ -70,7 +77,7 @@ import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js
 import { createModels, instancedCopies, placeCopy, repaint, stylize, type Copies } from '@homie-rocks/studio/assets';
 // Characters that move well: clips from the skeleton's clip library, blended, layered and tuned (Game Lab tunables).
 import { crowd, loadCharacter, type Character } from '@homie-rocks/studio/animate';
-import { createNetplay, guardGestures, Roster, q, lerp, capMove, skillPreset, PALETTE, AI_MARK, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
+import { createNetplay, guardGestures, Roster, q, lerp, capMove, skillPreset, PALETTE, AI_MARK, type Peer, type RoleChange, type RoundInfo, type RoundResult, type Skill, type Slot, type Snapshot } from '@homie-rocks/studio/netplay';
 // The port toolkit: its probe (what `homie-studio port check` and `perf` read, and sandbox + audio shims), and name
 // labels that never pile up (port/view.ts).
 import { createBubbles, createLabels, exposePort, paintBubbles, type BubbleIn, type BubbleOut, type LabelIn, type LabelOut } from '@homie-rocks/studio/port';
@@ -246,9 +253,12 @@ function newZone(n: number): Zone {
 function setZone(z: Zone): void { zone = z; net.state('zone', z); }
 
 /** A round starts with every hero on its spawn ring facing the camera (fa 0): a line-up the hero intro opens on. */
-function startRound(n: number): void {
+function startRound(n: number, rollover = false): void {
   const now = net.now();
   roster.trim();
+  // The next round of a running room: the trim is what makes room (the seats a server no longer keeps for AI go
+  // here), so whoever was seated with no body is given one now, before the bodies are placed.
+  if (rollover && !net.offline) seatWaiting();
   syncBodiesFromRoster();
   let i = 0;
   for (const b of [...bodies.values()].sort((a, c) => a.slot - c.slot)) {
@@ -369,16 +379,31 @@ net.on('role', (e) => {
   if (e.role === 'host') becomeHost(e);
   else { hosting = false; }
 });
-net.on('join', (p) => {
-  if (!hosting || p.seat === null) return;
+/** Host: a body for somebody the relay seated. False when every body is somebody's (they wait: see seatWaiting). */
+function giveBody(p: Peer): boolean {
+  if (p.seat === null) return false;
   // An AI takes a seat kept for AI, a person never does (revision 6: the Roster needs p.agent for that).
   const c = roster.claim(p.seat, p.name, p.agent ? { role: p.agent.role, hands: p.agent.hands } : null, p.occ ?? null);
-  if (!c) return; // full: they watch
+  if (!c) return false;
   welcome(p.seat);
   syncBodiesFromRoster();
   const b = bodies.get(c.slot.slot);
   // The arriving human takes over the bot's body where it stands, score and all (reset = "adopt this position").
   if (b) { b.vx = 0; b.vy = 0; b.kvx = 0; b.kvy = 0; b.knockUntil = 0; hostMoved(b); }
+  return true;
+}
+/**
+ * SEAT WHOEVER IS WAITING (NETPLAY.md section 28). The relay seats a person; this host gives them a body. A claim that
+ * found every body taken (a server's AI seats were still kept, say) used to be tried once: that player watched for the
+ * rest of the visit, online, with nothing said. It is tried again whenever a body frees up and at every round start.
+ */
+function seatWaiting(): boolean {
+  let any = false;
+  for (const p of net.peers.values()) if (p.seat !== null && !roster.bySeat(p.seat) && giveBody(p)) any = true;
+  return any;
+}
+net.on('join', (p) => {
+  if (!hosting || !giveBody(p)) return;
   publishRoster();
   net.snapshot(buildSnap(), tick, true);
 });
@@ -387,7 +412,10 @@ net.on('leave', (p) => {
   roster.release(p.seat); // their body stays, driven by a bot
   firstRound.delete(p.seat); // whoever sits in this seat next is new here
   syncBodiesFromRoster();
+  // A body just went to a bot: somebody seated with none takes it now.
+  const seated = seatWaiting();
   publishRoster();
+  if (seated) net.snapshot(buildSnap(), tick, true);
 });
 // The server's policy changed: its AI seats come (or go between rounds) at once.
 net.on('policy', () => { if (!hosting) return; roster.fill(); syncBodiesFromRoster(); publishRoster(); });
@@ -889,7 +917,7 @@ function stepHost(dt: number): void {
       }
     }
     if (now >= round.endsAt) endRound();
-  } else if (round && round.phase === 'over' && now >= round.endsAt) startRound(round.n + 1);
+  } else if (round && round.phase === 'over' && now >= round.endsAt) startRound(round.n + 1, true);
   if (net.snapshotDue()) net.snapshot(buildSnap(), tick);
 }
 
@@ -2482,7 +2510,8 @@ function hud(cw: number, ch: number, phone: boolean, list: { slot: number; seat:
       ctx.fillText(`${TOGETHER ? '' : `${row.place}. `}${mine && !net.watching ? 'You' : label(row.name, row.bot)}${mine && net.watching ? ' ◂' : ''} — ${row.score}`, cw / 2, ry + 1);
     });
   }
-  if (!net.offline && !net.connected && net.role !== 'host') {
+  // Only a browser that WAS in its room is reconnecting; one still joining, or stopped for good, is not (section 22).
+  if (net.link === 'reconnecting' && net.role !== 'host') {
     ctx.textAlign = 'center'; ctx.font = `700 15px ${FONT_BODY}`;
     const text = 'Reconnecting…'; const tw = ctx.measureText(text).width;
     chip(cw / 2 - tw / 2 - 12, ch - pad - 24, tw + 24, 26);

package/worker/index.mjs

@@ -23,7 +23,8 @@
  *   /<game>/__game/...         the game's own files (index.html gets HOMIE_NET)
  *   /<game>/__net?room=        the room's netplay socket (Table Durable Object)
  *   /<game>/__watch?room=      the room's facts, for the shell
- *   /<game>/api/lobby          which public room to join (Lobby Durable Object); ?server=<id>: a room of that server
+ *   /<game>/api/lobby          which public room to join (Lobby Durable Object); ?server=<id>: a room of that server;
+ *                              the one answer a standalone copy's app may read (worker/standalone.mjs)
  *   /<game>/api/watch          which public room to watch: the busiest one now (nothing is reserved)
  *   /<game>/servers/           the game's servers (worker/servers.mjs): named, lasting room pools with their own
  *                              policy (open, humans-only, hybrid, beginner) and door; /<game>/api/servers as JSON
@@ -83,6 +84,7 @@
  * it when a server uses it), or the owner's own key (secret HOMIE_BRAIN_KEY).
  */
 import { NetRoom, WATCH_POLICIES, departure, errorLine, versionOf } from './room.mjs';
+import { appCors, isAppOrigin } from './standalone.mjs';
 import { ROOM_ID, badRoomPage, frameAncestors, noWatchPage, playPage, watchPage } from './pages.mjs';
 import {
   PUBLIC_SERVER, SERVER_ID, homeOf, memberCounts, memberOf, noteMember, policyOf, pooledRoom, roomCode, roomServer, serverAccess, serverPassOf, serverView, serversOf,
@@ -576,7 +578,16 @@ function finish(res, path) {
 export default {
   async fetch(request, env, ctx) {
     const url = new URL(request.url);
-    const res = finish(await route(request, env, ctx), url.pathname);
+    // A standalone copy's Lobby call (worker/standalone.mjs): every answer to it can be read by the app's page, an
+    // unknown game's 404 and a failure included, so the app can say why it plays offline. No other address is opened.
+    const appLobby = isAppOrigin(request) && /^\/[^/]+\/api\/lobby\/?$/.test(url.pathname);
+    let res;
+    try { res = finish(await route(request, env, ctx), url.pathname); } catch (error) {
+      if (!appLobby) throw error;
+      try { console.error(JSON.stringify({ at: new Date().toISOString(), ev: 'lobby-route-failed', path: url.pathname, error: errorLine(error) })); } catch { /* no console */ }
+      res = json({ ok: false, error: 'failed' }, 500);
+    }
+    if (appLobby) return appCors(request, res);
     // A referral's arrival (worker/referrals.mjs): only a person's page load with ?via= of another site, on a studio
     // that pays referrals. The page is answered first; a cookie is added to it only then.
     if (url.searchParams.has('via') && res && res.status === 200 && /text\/html/i.test(res.headers.get('content-type') ?? '')) {
@@ -998,9 +1009,14 @@ async function route(request, env, ctx) {
       return json({ ok: true, game, room: best?.room ?? null, players: best?.players ?? 0, max }, 200, { 'cache-control': 'no-store' });
     }
     if (sub === 'api/lobby') {
+      // A standalone copy's page reads this answer from another origin: the Worker's own `fetch` adds its header to
+      // every answer of this address (worker/standalone.mjs), whichever line here made it.
+      const app = isAppOrigin(request);
       if (!door.ok) return json({ ok: false, error: 'not-found' }, 404);
       // ?server=<id>: a room of that server's pool (its door first); none: public. Strangers never meet across servers.
       const sid = url.searchParams.get('server') ?? 'public';
+      // An app plays on the public server only: it has no account and no invite to show a server's door.
+      if (app && sid !== 'public') return json({ ok: false, error: 'app-public', message: 'A standalone copy plays on the public server.' }, 403);
       const srv = SERVER_ID.test(sid) || sid === 'public' ? serverById(sid) : null;
       if (!srv) return json({ ok: false, error: 'no-server', message: `${meta.name} has no server called ${String(sid).slice(0, 24)}.` }, 404);
       if (srv.id === 'public' && publicHidden() && !(await pageDoor(srv)).owner) return json({ ok: false, error: 'closed', message: 'Pick a server to play on.' }, 403);
@@ -1010,8 +1026,11 @@ async function route(request, env, ctx) {
       const not = String(url.searchParams.get('not') ?? '').split(',').filter((r) => ROOM_ID.test(r)).slice(0, 4).join(',');
       const pol = policyFor(srv);
       // Strangers on different builds of the game never meet (section 23): the Lobby matches within the live build.
-      const ver = versionOf(meta?.netplay?.version);
-      return lobby().fetch(`https://lobby/join?max=${humanSeats(pol)}&server=${srv.id}&rooms=${srv.roomsMax}${not ? `&not=${encodeURIComponent(not)}` : ''}${ver ? `&ver=${encodeURIComponent(ver)}` : ''}`, { method: 'POST' });
+      // A standalone copy is the build it was made from, whatever is live now: it says its own (`gv`, or none for a
+      // game that named none then) and is matched with copies of that build. What it says is its own word, so the
+      // Lobby is told it came from an app (`app=1`) and keeps only a few such builds' rooms (LOBBY_APP_VERSIONS).
+      const ver = app ? versionOf(url.searchParams.get('gv')) : versionOf(meta?.netplay?.version);
+      return lobby().fetch(`https://lobby/join?max=${humanSeats(pol)}&server=${srv.id}&rooms=${srv.roomsMax}${not ? `&not=${encodeURIComponent(not)}` : ''}${ver ? `&ver=${encodeURIComponent(ver)}` : ''}${app ? '&app=1' : ''}`, { method: 'POST' });
     }
     if (sub === 'api/agent') {
       // An AI's seat (worker/agents.mjs): its pass, the server's policy, a room with people in it, a ticket.
@@ -1700,6 +1719,11 @@ export class Table {
  * room, where it waits as a spectator and is seated when a seat frees (`full: true`). An AI (`agent=1`) is only ever
  * sent to a room with people in it; it never opens one. Players are people: agents are reported apart.
  */
+/** How many builds of a game besides the live one may have Lobby rooms on one server at once (standalone copies name their own). */
+export const LOBBY_APP_VERSIONS = 8;
+/** How many rooms a game's Lobby keeps in all. Its list is one stored value: 512 rooms is about a third of what one may hold. */
+export const LOBBY_ROOMS_MAX = 512;
+
 export class Lobby {
   constructor(ctx, env) {
     this.ctx = ctx;
@@ -1779,8 +1803,15 @@ export class Lobby {
       const not = new Set(String(url.searchParams.get('not') ?? '').split(',').filter(Boolean));
       for (const [name, until] of this.closed) if (until <= now) this.closed.delete(name);
       // Every room of the server counts toward its `rooms_max` and its numbering; only this build's rooms are matched.
-      const ofServer = [...this.rooms.values()].filter((r) => (r.server ?? 'public') === server && !not.has(r.name) && !this.closed.has(r.name));
+      const everyRoom = [...this.rooms.values()].filter((r) => (r.server ?? 'public') === server);
+      const ofServer = everyRoom.filter((r) => !not.has(r.name) && !this.closed.has(r.name));
       const pool = ofServer.filter((r) => (r.ver ?? '') === ver);
+      // A standalone copy names its own build (the Worker says `app=1`), and anybody can claim to be one: only a few
+      // builds besides the live one ever have rooms here, so a caller that invents a build a request makes no pool.
+      const app = url.searchParams.get('app') === '1';
+      if (app && !everyRoom.some((r) => (r.ver ?? '') === ver) && new Set(everyRoom.map((r) => r.ver ?? '')).size > LOBBY_APP_VERSIONS) {
+        return json({ ok: false, room: null, error: 'versions', message: 'Too many versions of this game are being played at once: play offline for now.' }, 503);
+      }
       if (url.searchParams.get('agent') === '1') {
         // An AI: a room of this pool with people in it and an AI seat free (the most people first). Never a new room.
         const reserve = Math.max(0, Math.floor(Number(url.searchParams.get('ai'))) || 0);
@@ -1802,11 +1833,27 @@ export class Lobby {
       }
       let room = best?.r;
       let full = false;
-      if (!room && server !== 'public' && pool.length >= roomsMax) {
-        // Every room this server may have is full: the fullest one, where the visitor waits for a seat.
-        room = pool.reduce((a, b) => (b.players + b.pending.length > a.players + a.pending.length ? b : a), pool[0]);
+      const fullest = (list) => list.reduce((a, b) => (b.players + b.pending.length > a.players + a.pending.length ? b : a), list[0]);
+      if (!room && server !== 'public' && everyRoom.length >= roomsMax) {
+        // Every room this server may have exists, whatever build each runs: the fullest one of this build, where the
+        // visitor waits for a seat; with none of this build, the fullest of the server (its players are told a newer
+        // build is live, and the visitor is let in when they have it). Never a room past the server's own number.
+        const from = pool.length ? pool : ofServer;
+        if (!from.length) return json({ ok: false, room: null, error: 'full', message: 'Every room of this server is taken.' }, 503);
+        room = fullest(from);
         full = true;
       }
+      if (!room && this.rooms.size >= LOBBY_ROOMS_MAX) {
+        // The Lobby keeps a bounded list (it is one stored value): rooms nobody is seated in go first, the oldest
+        // first. When every room has people in it, nobody gets a new one: this build's fullest, or no room at all.
+        const empty = [...this.rooms.values()].filter((r) => r.players === 0).sort((a, b) => a.at - b.at);
+        for (const r of empty) { if (this.rooms.size < LOBBY_ROOMS_MAX) break; this.rooms.delete(r.name); }
+        if (this.rooms.size >= LOBBY_ROOMS_MAX) {
+          if (!pool.length) return json({ ok: false, room: null, error: 'busy', message: 'Every room is taken right now.' }, 503);
+          room = fullest(pool);
+          full = true;
+        }
+      }
       if (!room) {
         let n = this.next[server] ?? 1;
         while (not.has(roomCode(server, n)) || this.closed.has(roomCode(server, n)) || this.rooms.has(roomCode(server, n))) n += 1;

package/worker/pages.mjs

@@ -455,6 +455,9 @@ const SHELL_JS = String.raw`(function () {
       if (m.what === 'attached') { state.attached = true; lastRects = ''; tellRects(); }
       // The link (section 22): in the room, knocking again, or playing alone because the room never answered.
       if (m.what === 'link' && typeof m.state === 'string') state.link = { state: m.state, why: String(m.why || ''), hosting: m.hosting === true, at: Date.now() };
+      // Every seat is taken and this browser asked to play (the room's own word, in its welcome): it watches until one
+      // frees up, and the chip says so. Not full any more once it has been seated, or plays by itself.
+      if (m.what === 'full') state.full = m.full === true;
       // The game's own word that it was playable (section 21), beside who lifted the card: a late one is a game whose
       // arrival should be 'game'. A performance probe reads both here.
       if (m.what === 'ready') {
@@ -469,11 +472,13 @@ const SHELL_JS = String.raw`(function () {
         if (m.final === true || screenMode) reloadGame();
         else flash('A new version of ' + boot.name + ' is ready: it loads after this round.');
       }
-      if (m.what === 'token' && typeof m.token === 'string') { state.seat = m.seat; try { sessionStorage.setItem(KEY, m.token); } catch (e) {} if (window.__homieChat) window.__homieChat.seat(); }
+      if (m.what === 'token' && typeof m.token === 'string') { state.seat = m.seat; if (typeof m.seat === 'number') state.full = false; try { sessionStorage.setItem(KEY, m.token); } catch (e) {} if (window.__homieChat) window.__homieChat.seat(); }
       if (m.what === 'stats') state.stats = m.stats;
       if (m.what === 'round') { onRound(m.round); if (state.stale && m.round && m.round.phase === 'over') reloadGame(); }
       if (m.what === 'roster') state.roster = m.slots;
-      if (m.what === 'closed') { state.closed = m.why; if (m.why === 'kicked' || m.why === 'room-closed' || m.why === 'agents-off') notice(m.why === 'kicked' ? 'kicked' : 'closed', m); }
+      // Stopped for good. Removed, or the room closed: the notice. A room with no place left at all: the same notice
+      // with its own words, because "try another room" is the only thing a player can do about it.
+      if (m.what === 'closed') { state.closed = m.why; if (m.why === 'kicked' || m.why === 'room-closed' || m.why === 'agents-off') notice(m.why === 'kicked' ? 'kicked' : 'closed', m); else if (m.why === 'room-full' || m.why === 'too-many') notice('full', m); }
       // A game's net.pickPlayer(seat): only an owner's page listens (its overlay opens that player's card).
       if (m.what === 'pick' && (m.seat === null || typeof m.seat === 'number')) { try { window.dispatchEvent(new CustomEvent('homie-pick', { detail: { seat: m.seat } })); } catch (e) {} }
       paint();
@@ -520,8 +525,10 @@ const SHELL_JS = String.raw`(function () {
         var next = {};
         Object.keys(all).forEach(function (x) { if (x !== k) next[x] = all[x]; });
         if (m.op === 'set' && m.v !== null && m.v !== undefined) next[k] = m.v;
-        var how = prefsWrite(next);
-        if (how === 'too-large') out.why = how; else { out.ok = true; out.kept = how; }
+        // A NaN or an Infinity would be written as null and read back as a setting (a volume of null plays as 0):
+        // refused, whatever helper sent it.
+        var how = m.op === 'set' && typeof m.v === 'number' && !isFinite(m.v) ? 'value' : prefsWrite(next);
+        if (how === 'too-large' || how === 'value') out.why = how; else { out.ok = true; out.kept = how; }
       } else out.why = 'op';
     } catch (e) { out.why = 'error'; }
     state.prefs = { op: m.op, ok: out.ok, why: out.why || null };
@@ -656,8 +663,8 @@ const SHELL_JS = String.raw`(function () {
     var label = labelOf(state.room || '');
     var box = document.createElement('div'); box.className = 'notice'; box.setAttribute('data-notice', kind); box.setAttribute('role', 'alertdialog'); box.setAttribute('data-keep-focus', '');
     var inner = document.createElement('div'); inner.className = 'box';
-    var h = document.createElement('h1'); h.textContent = kind === 'kicked' ? 'You were removed from this room' : 'This room is closed';
-    var p = document.createElement('p'); p.textContent = state.notice.message || (kind === 'kicked' ? 'The studio removed you from this room.' : 'The studio closed this room. Thanks for playing!');
+    var h = document.createElement('h1'); h.textContent = kind === 'kicked' ? 'You were removed from this room' : kind === 'full' ? 'This room is full' : 'This room is closed';
+    var p = document.createElement('p'); p.textContent = kind === 'full' ? label + ' has no place left, to play or to watch. Another room is one tap away.' : state.notice.message || (kind === 'kicked' ? 'The studio removed you from this room.' : 'The studio closed this room. Thanks for playing!');
     var w = document.createElement('p'); w.className = 'when';
     w.textContent = mins ? (kind === 'kicked' ? 'You can come back to ' + label + ' in ' + mins + ' min.' : label + ' opens again in ' + mins + ' min.') : '';
     var acts = document.createElement('div'); acts.className = 'acts';
@@ -666,7 +673,7 @@ const SHELL_JS = String.raw`(function () {
     acts.append(other, back);
     inner.append(h, p, w, acts); box.appendChild(inner);
     document.body.appendChild(box);
-    say(kind === 'kicked' ? 'removed from this room' : 'room closed');
+    say(kind === 'kicked' ? 'removed from this room' : kind === 'full' ? 'room full' : 'room closed');
   }
 
   function paint() {
@@ -680,10 +687,12 @@ const SHELL_JS = String.raw`(function () {
     if (aiN) bits.push(aiN + ' AI');
     if (f && f.counts && f.counts.watchers) bits.push(f.counts.watchers + ' watching');
     if (state.full) bits.push('waiting for a seat');
-    if (state.closed) bits.push(state.closed === 'replaced' ? 'opened in another tab' : 'reconnecting');
-    // The link (section 22): cut off from the room and knocking again, or playing alone because it never answered.
+    // Stopped for good: nothing is knocking any more, so it never says "reconnecting". What is true, in a word.
+    if (state.closed) bits.push({ replaced: 'opened in another tab', 'room-full': 'room full', 'too-many': 'room full', stale: 'updating…', kicked: 'removed from this room', 'room-closed': 'room closed', 'agents-off': 'room closed' }[state.closed] || 'disconnected: reload to play');
+    // The link (section 22): cut off from a room it was in and knocking again ("reconnecting" is true only then), or
+    // playing by itself because the room never answered, or did not come back in time.
     else if (state.link && state.link.state === 'reconnecting') bits.push('reconnecting');
-    else if (state.link && state.link.state === 'alone') bits.push('offline, reconnecting');
+    else if (state.link && state.link.state === 'alone') bits.push(state.link.why === 'reconnect-timeout' ? 'playing on your own: the room dropped' : 'playing on your own: looking for the room');
     // The arrival card's line: the room and who is in it ("Room 2 · 3 playing · 2 AI").
     if (!A.done && state.room) A.facts([labelOf(state.room), n ? n + ' playing' : '', aiN ? aiN + ' AI' : ''].filter(Boolean).join(' · '));
     say(bits.join(' · ') || 'joining…');

package/worker/parts.mjs

@@ -112,7 +112,13 @@ const CSS = `<style>
 .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{width:100%;aspect-ratio:16/9;border:1px solid color-mix(in srgb,var(--fg) 14%,transparent);border-radius:16px;background:#000}
+.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)}
@@ -165,10 +171,45 @@ function costLine(c) {
   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
-    ? `<iframe class="pframe" title="${esc(p.name)}: try it" src="${esc(`${p.url}${p.preview.page}`)}" sandbox="allow-scripts allow-pointer-lock" loading="lazy" referrerpolicy="no-referrer"></iframe>`
+    ? 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))],

package/worker/standalone.mjs

@@ -0,0 +1,34 @@
+/**
+ * STANDALONE COPIES OF A GAME (standalone/STANDALONE.md): the same built game in a desktop or phone app
+ * (`homie-studio standalone build`). The app's page is not served by this site, so it is another origin to this
+ * Worker: `app://game` in the desktop app (Electron), `capacitor://localhost` on iOS and `https://localhost` on
+ * Android (Capacitor). Those three are fixed by the shells, never by a game.
+ *
+ * What an app origin may do here is ONE thing: ask the Lobby which public room to join (`POST /<game>/api/lobby`),
+ * and read the answer. The room's socket (`/<game>/__net`) never asked where a page came from, so it needs nothing.
+ * Everything else a page of this site does stays this site's own: no credentials are allowed across (there is no
+ * `access-control-allow-credentials` anywhere here), the lobby is never opened to `*`, and the POSTs that check
+ * `sameOrigin` (players, saves, the shop, chat reports, the office) still refuse an app, as they refuse any other
+ * site. So an app has no account, no cloud saves and no shop, and says so.
+ */
+
+/** The origins of the app shells' own page. */
+export const APP_ORIGINS = ['app://game', 'capacitor://localhost', 'https://localhost'];
+
+/** The app origin this request came from, or null (this site's own pages, another site, a tool with no Origin). */
+export function appOriginOf(request) {
+  const origin = request.headers.get('origin');
+  return origin && APP_ORIGINS.includes(origin) ? origin : null;
+}
+
+export const isAppOrigin = (request) => appOriginOf(request) !== null;
+
+/** The answer as an app's page may read it: its own origin named, and nothing else. Any other request: unchanged. */
+export function appCors(request, response) {
+  const origin = appOriginOf(request);
+  if (!origin) return response;
+  const out = new Response(response.body, response);
+  out.headers.set('access-control-allow-origin', origin);
+  out.headers.append('vary', 'origin');
+  return out;
+}

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