@homie-rocks/studio 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -17,9 +17,31 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.26.0] - 2026-10-03
+
+**Plugin 0.27.0** · [#40](https://github.com/homie-rocks/homie/pull/40)
+
+A game's first minute: Play never opens on a blank screen, a bright game gets a bright landing in its own palette, and in Hero Rush 3D a new player's first round is a race they are in.
+
+### Added
+
+- The arrival card. From the play page's first paint (and the big screen's), the game's own look covers its frame while the room connects and the game loads: its title and pitch, its key art (the landing's hero still, a trailer's poster or its cover, drifting slowly), a progress line that says what is happening ("Finding a room…", "Room 4 · 3 playing · 2 AI", "Loading the game…", "Joining Room 4…", the game's own "Loading the heroes… 60%"), and the controls for this device from `landing.controls`. It is drawn in the game's palette (style.json), else its landing's colours, else the studio's, and it fades the moment the game is playable. `?arrive=0` leaves it out.
+- The netplay helper tells the play page when the game is playable (NETPLAY.md section 21): by itself once the browser is seated and has the room's state, or, for a game that keeps loading after that (models, textures, a baked world), at the game's own `net.playable()` (`createNetplay({ arrival: 'game' })`), with `net.loading(fraction, 'the heroes')` for the progress line. Nothing crosses the relay; the wire stays revision 8.
+- `homie-studio perf` measures the time to the first meaningful frame (`load.look`: the arrival card on the screen), and its time to playable waits for the card to lift. The perf skill's goals include it ("it opens on a blank screen").
+
+### Changed
+
+- A game with its own palette (style.json) and no `landing.scheme` or `landing.theme` of its own gets its landing in that palette: its paper as the page, its ink as the words, its accents, light or dark as its paper is, when the ink reads on the paper (4.5:1). Its footage keeps its colour, and the words sit on a soft panel of its paper. A bright game is no longer shown on the studio's dark page. A scheme or colours the owner set, a page of the studio's own and `site/theme.css` still win; a game without a style.json keeps the studio's look.
+- Hero Rush 3D: the bots never swamp a new player. In somebody's first round in the room, when nobody set the AI dial, the bots play a level easier. A bot far ahead of the best person in the room eases off (it walks, reacts later, swings less, then races for the coins near that person, or keeps near them, up their screen, without taking coins) and plays at its dial again once it is within its lead: Rookie −1, Steady 1, Fair 2, Strong 5, Maxed none. Scores stay honest (no score is ever changed, no coin given, taken or faked), and every bot is labelled, the phone's compact board too ("bot" or "AI" after the name). A casual player's first round at the default dial ended 61 coins behind the best bot before, and about 4 behind now; a player who chases the coins still wins clearly, and Maxed bots still beat a casual player.
+- Hero Rush 3D on a phone held upright: the camera follows lower and closer (30 degrees, about 5.5 m across), so every hero reads as a character (a mage was the top of its hat), and your name chip says what you are ("You · Mage"). The game passes `arrival: 'game'`: the card lifts on your own hero in its real model, never a stand-in. Your own hero is asked for first, the moment your seat is known, then the other heroes, then the skeletons (on an emulated slow phone your real hero is drawn at about 1.4 s instead of 2.1 s, the same bytes), the in-game title card is gone (the arrival card has the title), the "×2" mark moves off your hero and the controls hint sits above the touch buttons.
+
+### Upgrade notes
+
+- Nothing to do: `homie-studio upgrade` brings the arrival card to every game, and a game built before 0.26.0 lifts it once it has a seat. A game whose world keeps loading after its first state can say when it is ready: `createNetplay({ …, arrival: 'game' })`, `net.loading(p, 'what')` while it loads, and `net.playable()` once its world and the player's own body are drawn. A game made from Hero Rush 3D before 0.26.0 keeps its own code: tell Claude "bring the starter's first-round bots and phone camera into my game" if you want them.
+
 ## [0.25.0] - 2026-10-03
 
-**Plugin 0.26.0** · [#38](https://github.com/homie-rocks/homie/pull/38)
+**Plugin 0.26.0** · [#38](https://github.com/homie-rocks/homie/pull/38) · [release-2026-10-03-studio-0.25.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.25.0)
 
 Animated characters for 3D games: free CC0 heroes or one generated and auto-rigged on your fal account, on one skeleton standard with the library's clips retargeted onto it, and a shared player that runs, jumps and swings with IK feet and springs.
 

package/README.md

@@ -96,11 +96,14 @@ licence its owner picked in game.json `"license"`: `"remix-with-credit"` (the de
 `"no-remix"`, which `game remix` refuses. Every page ends with "Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
 files. `site/SITE.md` says all of it.
 
-The play page writes its room into the address, and a small room button at the edge shares it: Invite, Big
-screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
+The play page never opens blank (0.26.0): from its first paint an arrival card shows the game's own look (its title,
+pitch and key art in its palette, a progress line that says what is happening, and the controls for the device) until
+the game says it is playable (`NETPLAY.md` section 21; `worker/arrival.mjs`). It writes its room into the address, and
+a small room button at the edge shares it: Invite, Big screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
 the top's middle, moved in by `x` / `y`, or kept a small icon), so it never covers a scoreboard. A game whose
 picture is white or cream gets a light landing (`landing.scheme: "light"`). Every card and the directory show a
-game's landing still. Every HTML answer is `no-transform`, and the site's pages are never framed by another
+game's landing still. A game with its own palette (style.json) and no landing colours of its own gets its landing
+in that palette, light or dark as its paper is (0.26.0). Every HTML answer is `no-transform`, and the site's pages are never framed by another
 site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
 `not-a-homie`, at the site's root as under the game.
 
@@ -519,7 +522,8 @@ rules, the bots, the snapshots) and a replica, both a computer (1280x800 at 2x)
 on a fast computer is less than its rate). They play the same seeded presses through a warm-up and a measured
 window, and each run's JSON says, per browser: the time between animation frames (median, p95, p99, the share over 33
 and 50 ms), the game's JavaScript per frame (every requestAnimationFrame callback timed), the main thread per frame
-(Chrome's TaskDuration), time to the first frame, to a seat and to playable, the game's files on the wire, the heap
+(Chrome's TaskDuration), time to the first meaningful frame (`load.look`: the play page's arrival card), to the
+game's first frame, to a seat and to playable, the game's files on the wire, the heap
 after a garbage collection, and netplay messages and kilobytes a second each way. `--profile` adds a CPU profile per
 browser in a window of its own (a `.cpuprofile` for Chrome DevTools) and its hottest functions, read through the
 game's source map when the build kept one (`homie-studio build --maps` keeps it in `.studio/maps/<id>/`, never in
@@ -758,7 +762,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `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`; `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/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/arrival.mjs`: its arrival card. |
 | `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`. |
 | `lib/media.mjs`, `media/MEDIA.md` | The `music/` and `videos/` manifests: which entries get a page, and where each file's bytes come from (the site itself up to 25 MiB a file, the studio's R2, or a link). `media list` shows it; `media move` puts the big ones in R2 and records each one's SHA-256; `media put` uploads a loose file to `/media/<key>`. |
 | `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |

package/lib/perf.mjs

@@ -15,9 +15,11 @@
  * Each browser plays (the same seeded presses every run) through a warm-up and then a measured window, and the run
  * writes, per browser (host and replica):
  *
- *   load     ms from opening the page to the game's first animation frame, to a seat, and to playable (seated with a
- *            body that the game's port probe reports, or seated and drawing when it has none); what the game's own
- *            files weighed on the wire, the biggest first
+ *   load     ms from opening the page to the first meaningful frame (`look`: the play page's arrival card on the
+ *            screen, the game's title and art; a page without one, the game's first animation frame), to the game's
+ *            first animation frame, to a seat, and to playable (seated with a body that the game's port probe reports,
+ *            or seated and drawing when it has none, and the arrival card lifted); what the game's own files weighed on
+ *            the wire, the biggest first
  *   frames   the time between animation frames: median, 95th and 99th percentile, the worst, and the share of frames
  *            over 33 ms (a dropped frame at 60 Hz, twice) and over 50 ms (a hitch anyone sees)
  *   work     the game's JavaScript inside each animation frame (every requestAnimationFrame callback, timed)
@@ -197,7 +199,7 @@ async function openPlayer(puppeteer, chrome, device, playUrl, label, log, cpu) {
     let seatedAt = null; let playableAt = null; let shell = null; let body = null;
     const deadline = Date.now() + 90_000;
     while (Date.now() < deadline && playableAt === null) {
-      shell = await T(page.evaluate(() => { const s = window.__shell; return s ? { room: s.room, seat: s.seat, role: s.stats?.role ?? null } : null; }), 5000);
+      shell = await T(page.evaluate(() => { const s = window.__shell; const a = s?.arrival; return s ? { room: s.room, seat: s.seat, role: s.stats?.role ?? null, arrival: a ? { phase: a.phase, lookMs: a.lookMs, liftedMs: a.liftedMs, by: a.by } : null } : null; }), 5000);
       const now = Date.now();
       if (seatedAt === null && shell?.room && Number.isInteger(shell.seat) && shell.role) seatedAt = now;
       const g = await inGame(h, () => {
@@ -206,7 +208,9 @@ async function openPlayer(puppeteer, chrome, device, playUrl, label, log, cpu) {
         if (p && p.view !== 'board') { const r = p.rows(p.now() - 400); const last = r[r.length - 1]; self = last ? Number.isFinite(last[1]) : false; }
         return { first: window.__perf?.first?.() ?? null, port: Boolean(p), view: p?.view ?? null, self };
       });
-      if (seatedAt !== null && g?.first !== null && g?.first !== undefined) {
+      // The play page's arrival card (0.26.0) covers the game until the game says it is playable: not playable before.
+      const lifted = !shell?.arrival || shell.arrival.phase === 'done';
+      if (seatedAt !== null && g?.first !== null && g?.first !== undefined && lifted) {
         // A body the game reports (its port probe), or no body to wait for (a board, or a game with no probe).
         if (!g.port || g.view === 'board' || g.self) { playableAt = now; body = g.port && g.view !== 'board' ? 'reported' : 'none to report'; }
         else if (now - seatedAt > 10_000) { playableAt = null; body = 'never reported by the port probe in 10 s'; break; }
@@ -223,7 +227,11 @@ async function openPlayer(puppeteer, chrome, device, playUrl, label, log, cpu) {
     const at = (epoch) => (epoch && origin ? Math.round(epoch - origin) : null);
     const files = [...h.requests.values()].filter((r) => r.done);
     const gameFiles = files.filter((r) => /\/__game\//.test(r.url));
+    // The first meaningful frame: the arrival card's first frame (the page's own clock), else the game's first frame.
+    const look = Number.isFinite(shell?.arrival?.lookMs) ? shell.arrival.lookMs : at(g?.first);
     h.loadInfo = {
+      lookMs: look,
+      arrival: shell?.arrival ? { by: shell.arrival.by ?? null, liftedMs: shell.arrival.liftedMs ?? null } : null,
       firstFrameMs: at(g?.first),
       seatedMs: at(seatedAt),
       playableMs: at(playableAt),
@@ -518,7 +526,7 @@ export function metricsOfRun(run) {
     put('work.p50', b.work?.p50); put('work.p95', b.work?.p95); put('work.mean', b.work?.mean);
     put('busy', b.main?.busyPerFrame); put('script', b.main?.scriptMsPerS);
     put('heap', b.heap?.afterGcMb); put('heap.growth', b.heap?.gcGrowthMbPerMin);
-    put('load.firstFrame', b.load?.firstFrameMs); put('load.seated', b.load?.seatedMs); put('load.playable', b.load?.playableMs); put('load.gameKb', b.load?.gameKb);
+    put('load.look', b.load?.lookMs); put('load.firstFrame', b.load?.firstFrameMs); put('load.seated', b.load?.seatedMs); put('load.playable', b.load?.playableMs); put('load.gameKb', b.load?.gameKb);
     put('net.msgsOut', b.net?.msgsOut); put('net.msgsIn', b.net?.msgsIn); put('net.kbOut', b.net?.kbOut); put('net.kbIn', b.net?.kbIn);
   }
   return out;
@@ -541,7 +549,7 @@ function headlineOf(summary) {
     for (const role of ['host', 'replica']) {
       const m = (k) => summary.metrics[`${device}.${role}.${k}`]?.median;
       if (m('frame.p50') === undefined) continue;
-      out.push(`${device} ${role}: frames ${m('frame.p50')} ms median, ${m('frame.p95')} ms p95, ${m('frame.over50') ?? 0}% over 50 ms; game JS ${m('work.p50')} ms a frame (p95 ${m('work.p95')}); main thread ${m('busy')} ms a frame; playable at ${m('load.playable') ?? '?'} ms; netplay ${m('net.msgsOut')} out / ${m('net.msgsIn')} in a second; heap ${m('heap')} MB`);
+      out.push(`${device} ${role}: frames ${m('frame.p50')} ms median, ${m('frame.p95')} ms p95, ${m('frame.over50') ?? 0}% over 50 ms; game JS ${m('work.p50')} ms a frame (p95 ${m('work.p95')}); main thread ${m('busy')} ms a frame; first look at ${m('load.look') ?? '?'} ms, playable at ${m('load.playable') ?? '?'} ms; netplay ${m('net.msgsOut')} out / ${m('net.msgsIn')} in a second; heap ${m('heap')} MB`);
     }
   }
   return out;

package/lib/site.mjs

@@ -419,8 +419,19 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
   // The landing's own colours (landing.theme): only colours, and the ink on its own accent worked out like the studio's.
   // Else the game's own palette (games/<id>/style.json, its art-direction decisions): one look from the game to its page.
   const style = !L.theme ? readJson(join(g.dir, 'style.json'))?.palette : null;
-  // Its accents only: the page keeps the studio's light or dark scheme, so its text always reads.
-  const fromStyle = style && typeof style === 'object' ? { accent: style.accent, glow: style.accent2 } : null;
+  // 0.26.0: the whole landing in that palette (its paper as the page, its ink as the words, its accents) when the game
+  // sets no landing colours or scheme of its own and its ink reads on its paper (4.5:1): a bright game is no longer
+  // shown on the studio's dark page. The scheme follows the paper. Anything less readable: its accents only, on the
+  // studio's scheme, as before.
+  let fromStyle = style && typeof style === 'object' ? { accent: style.accent, glow: style.accent2 } : null;
+  let ownScheme = null;
+  if (fromStyle && L.scheme === undefined) {
+    const paper = luminance(style.bg); const ink = luminance(style.ink);
+    if (paper !== null && ink !== null && (Math.max(paper, ink) + 0.05) / (Math.min(paper, ink) + 0.05) >= 4.5) {
+      fromStyle = { ...fromStyle, bg: style.bg, fg: style.ink };
+      ownScheme = paper > ink ? 'light' : 'dark';
+    }
+  }
   const raw = L.theme && typeof L.theme === 'object' ? L.theme : fromStyle;
   const theme = raw ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(raw[k] ?? ''))).map((k) => [k, raw[k]])) : null;
   if (theme?.accent) { const l = luminance(theme.accent); if (l !== null) theme.accentInk = l > 0.4 ? '#0b0b10' : '#ffffff'; }
@@ -443,7 +454,7 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
     source: g.share?.source !== false,
     tv: g.screen?.tv !== false && L.tv !== false,
     theme: theme && Object.keys(theme).length ? theme : null,
-    ...(L.scheme === 'light' || L.scheme === 'dark' ? { scheme: L.scheme } : {}),
+    ...(L.scheme === 'light' || L.scheme === 'dark' ? { scheme: L.scheme } : ownScheme ? { scheme: ownScheme, schemeFrom: 'style' } : {}),
   };
 }
 

package/lib/template-history.json

@@ -1234,6 +1234,45 @@
      }
     }
    }
+  },
+  "0.26.0": {
+   "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": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "abf2f0d59341512d",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "aaea65236db52126",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -583,13 +583,16 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
    overrides). `?screen=1` makes a spectator that shows a QR code to the game URL.
    `/<game>/watch?room=` makes a watcher, with a strip of the players (section 16).
 8. **Show room facts** from the watch feed or the frame's messages: the lobby line,
-   results, and with `?debug=1` the debug strip.
+   results, and with `?debug=1` the debug strip. Until the game is playable, show them on
+   the arrival card, in the game's own look (section 21), never a blank screen.
 9. **One matcher:** every Play door for a game lands in the same rooms (the `Lobby`).
 
 ### The game (a vendored `netplay.ts`)
 
 1. **Call `createNetplay({ game, maxPlayers, movement, checkpoint })` once** and render
-   from the first frame. Never wait for `ready`.
+   from the first frame. Never wait for `ready`. A game that loads for seconds after its
+   first state passes `arrival: 'game'` and calls `net.playable()` once its world and the
+   player's own body are drawn (section 21): the play page's arrival card covers the wait.
 2. **Handle `role` at any time.**
    - Promoted: restore (section 9).
    - Host but not promoted: start a fresh round.
@@ -1422,3 +1425,36 @@ account or typed text.
 the host asks how the slimes hunt (chase, surround, gang up on the most hurt, regroup at the King),
 whether a wave comes, and how hard to push; every screen shows what the slimes are up to when a model
 chose it. The floor is the vale as it always played.
+
+## 21. The arrival (0.26.0)
+
+The play page and the big screen never open on a blank screen. From the page's first paint until
+the game says it is playable, an **arrival card** covers the game's frame in the game's own look:
+its title and pitch, its key art (the landing's hero still, a trailer's poster or its cover,
+drifting slowly), a progress line that says what is happening ("Finding a room…", "Room 4 · 3
+playing · 2 AI", "Loading the game…", "Joining Room 4…", the game's own "Loading the heroes…
+60%") and the controls for this device (game.json `landing.controls`). Then it fades and the
+game has the screen. Its colours are the game's palette (style.json), else its landing's, else
+the studio's (`worker/arrival.mjs`). Nothing here crosses the relay: it is between the game's frame
+and its page, so the wire stays revision 8.
+
+| From the helper to its page | When |
+|---|---|
+| `{ what: 'attached', …, arrival: 'auto' \| 'game' }` | the helper starts (a helper older than 0.26.0 sends no `arrival`) |
+| `{ what: 'loading', p, label? }` | the game's `net.loading(p, label)`: 0 to 1, at most ten a second, never after `playable` |
+| `{ what: 'playable', by: 'game' \| 'auto' }` | once: the game's `net.playable()`, or (`arrival: 'auto'`) the helper's own |
+
+- **`arrival: 'auto'`** (the default, so every game gets the card with no code): the helper says
+  `playable` once this browser has its role and the room's state (a host at once, anyone else at
+  its first snapshot), two animation frames later, so the game has drawn with it.
+- **`arrival: 'game'`**: the game says when, with `net.playable()` once its world and the player's
+  own body are drawn (Hero Rush 3D: its own hero with its real model, not the stand-in), and
+  `net.loading(p, 'the heroes')` while it loads. A game whose own loading takes seconds after the
+  first state (models, textures, a baked terrain) uses this, so the player never sees stand-ins.
+- **The page's fallbacks**, so a game is never hidden behind the card: a helper older than 0.26.0
+  lifts it 0.6 s after the browser has a seat; a frame with no helper, 8 s after it loaded; any game,
+  15 s after its helper attached; and 30 s after the page opened, whatever happens. A kick or a
+  closed room lifts it for its notice. `?arrive=0` leaves it out.
+- **Measured** by `homie-studio perf` (`load.look`: the card's first frame, the first meaningful
+  frame; `load.playable`: seated, the body drawn and the card lifted), from the page's own marks
+  `homie:look` and `homie:playable` and `window.__shell.arrival`.

package/netplay/netplay.ts

@@ -50,6 +50,11 @@
  *     them), messages taken down (`on('unchat')`), and the game's own chat UI
  *     (`net.say(text)`, `net.sayLine(id)`, `net.react(kind)`); the room's rules
  *     are `net.chatRules`. The play page's chat panel needs none of it.
+ *   - The arrival (0.26.0, NETPLAY.md section 21): tells its page when the game
+ *     is playable, so the play page's arrival card (the game's title, art and a
+ *     progress line) gives it the screen: by itself once seated with the room's
+ *     state, or the game's own `net.playable()` (`arrival: 'game'`), with
+ *     `net.loading(p, what)` while it loads. Nothing crosses the relay.
  *
  * WHAT IT DOES NOT DO: rendering, physics, input devices, bots. `Roster` below
  * is the bot-yield bookkeeping a host needs; the bots themselves are the game's.
@@ -451,6 +456,14 @@ export interface NetplayOptions<C = unknown> {
    * moves an AI's body with its own bot code (a Roster that passes `p.agent`). Reading the dial declares 'skill' too.
    */
   caps?: ('skill' | 'agents')[];
+  /**
+   * THE ARRIVAL (NETPLAY.md section 21): who says when the play page's arrival card (the game's title, art and a
+   * progress line while the room connects and the game loads) gives the screen to the game. 'auto' (the default): this
+   * helper, once this browser has its role and the room's state (a host at once, anyone else at its first snapshot),
+   * two animation frames later. 'game': the game itself, with `net.playable()` once its world and the player's own body
+   * are drawn (the page lifts the card anyway 12 s after the helper attached, so a game that never says is never hidden).
+   */
+  arrival?: 'auto' | 'game';
 }
 
 type WebSocketCtor = new (url: string) => WebSocketLike;
@@ -609,6 +622,17 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   hushed: boolean;
   /** This browser plays as an AI (the frame of an agent pass). */
   readonly asAgent: boolean;
+  /**
+   * THE ARRIVAL (section 21): the world and the player's own body are drawn, so the play page's arrival card gives the
+   * screen to the game. Once; later calls do nothing. Needed only with `arrival: 'game'` (an 'auto' game may call it
+   * earlier than the helper would).
+   */
+  playable(): void;
+  /**
+   * While it loads: how far along the game is (0 to 1) and what it is loading ("the heroes"), for the arrival card's
+   * progress line. At most ten a second reach the page; nothing after `playable()`.
+   */
+  loading(fraction: number, what?: string): void;
   /** Resolves with the first role (welcome, or offline fallback). */
   readonly ready: Promise<RoleChange<S, C>>;
   on<K extends keyof NetHandlers<S, A, C>>(kind: K, fn: NetHandlers<S, A, C>[K]): () => void;
@@ -1110,6 +1134,26 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let idleSkipped = 0;
   /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
   let closedWhy: string | null = null;
+  // The arrival (section 21): the play page's card lifts at `playable` (the game's word, or this helper's).
+  const arrival: 'auto' | 'game' = opts.arrival === 'game' ? 'game' : 'auto';
+  let playableSent = false;
+  let autoArmed = false;
+  let snapSeen = false;
+  let loadingAt = 0;
+  function sayPlayable(by: 'game' | 'auto'): void {
+    if (playableSent) return;
+    playableSent = true;
+    post?.({ what: 'playable', by });
+  }
+  /** 'auto': a host at once, anyone else at its first snapshot, then two animation frames (the game drew with it). */
+  function autoPlayable(): void {
+    if (arrival !== 'auto' || playableSent || autoArmed || !roleKnown) return;
+    if (role !== 'host' && !snapSeen) return;
+    autoArmed = true;
+    const raf = (globalThis as { requestAnimationFrame?: (cb: () => void) => number }).requestAnimationFrame;
+    const later = (fn: () => void): void => { if (typeof raf === 'function') raf(fn); else setTimeout(fn, 16); };
+    later(() => later(() => sayPlayable('auto')));
+  }
   /** The studio's announcement now showing, and the seats the studio muted (until when, server ms). */
   let announcement: Announcement | null = null;
   const muted = new Map<number, number>();
@@ -1354,6 +1398,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     emit('role', e);
     resolveView('seat');
     notifyStats(true);
+    autoPlayable();
   }
 
   /** The newest snapshot this browser holds, if recent: a promoted host's restore when the relay has none. */
@@ -1584,7 +1629,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       replaceState(m['state']);
     }
     rebase = true;
-    if (snap && next !== 'host') acceptSnap(snap, JSON.stringify(snap).length, false);
+    // The relay's last snapshot comes with the welcome: the room's state is in (the arrival, section 21).
+    if (snap && next !== 'host' && acceptSnap(snap, JSON.stringify(snap).length, false)) snapSeen = true;
     if (next === 'host' && !snap && !continuing) snap = localSnap();
     offline = false;
     connected = true;
@@ -1685,7 +1731,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (role === 'host') return; // a stale frame from a previous host
     const s: Snapshot<S> = { k: Number(m['k']) || 0, st: Number(m['st']), d: m['d'] as S, from: typeof m['from'] === 'number' ? m['from'] : null };
     if (Array.isArray(m['c'])) s.c = m['c'] as ControlWire[];
-    if (acceptSnap(s, bytes, true)) emit('snapshot', s);
+    if (acceptSnap(s, bytes, true)) { emit('snapshot', s); if (!snapSeen) { snapSeen = true; autoPlayable(); } }
   }
 
   function onInput(m: Record<string, unknown>): void {
@@ -1877,7 +1923,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     // No shell (a plain file, a dev server): the game is its own host, offline.
     queueMicrotask(() => goOfflineHost('offline'));
   } else {
-    post?.({ what: 'attached', v: NETPLAY_VERSION, rev: NETPLAY_REVISION, mark: NETPLAY_MARK });
+    post?.({ what: 'attached', v: NETPLAY_VERSION, rev: NETPLAY_REVISION, mark: NETPLAY_MARK, arrival });
     open();
     // A relay that never answers must not leave a game on a black screen. But the wait is counted only while
     // this page is able to listen: a phone compiling shaders under load is blocked for seconds at a time, and
@@ -2050,6 +2096,15 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     get announcement() { return announcement && (announcement.until === undefined || announcement.until > now()) ? announcement : null; },
     isMuted(s: number | null): boolean { return s !== null && (muted.get(s) ?? 0) > now(); },
     pickPlayer(s: number | null): void { post?.({ what: 'pick', seat: typeof s === 'number' ? s : null }); },
+    playable(): void { sayPlayable('game'); },
+    loading(fraction: number, what?: string): void {
+      if (playableSent) return;
+      const t = wall();
+      const p = Math.max(0, Math.min(1, Number(fraction) || 0));
+      if (t - loadingAt < 100 && p < 1) return;
+      loadingAt = t;
+      post?.({ what: 'loading', p: Math.round(p * 100) / 100, ...(typeof what === 'string' && what ? { label: what.slice(0, 40) } : {}) });
+    },
     get watching() { return watching; },
     get viewSeat() { markFollows(); return watching ? viewNow : (offline ? null : seat); },
     get following() { return watching ? following : seat; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "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/site/SITE.md

@@ -47,7 +47,13 @@ site's pages only); the owner's tools are `/_studio/api/chat`, `/_studio/api/cha
 Made from the game's own files, nothing invented:
 
 - **The hero**, full-bleed: the game's footage when it has some, else its cover (or key art) moving slowly, tinted
-  with the studio's colour so the words read. A game whose picture is white or cream (a light arena) takes
+  with the studio's colour so the words read. **In the game's own palette (0.26.0):** a game with a style.json (its
+  art direction) and no `landing.scheme` or `landing.theme` of its own gets its whole landing in that palette, its
+  paper as the page, its ink as the words, its accents, light or dark as its paper is, when the ink reads on the paper
+  (4.5:1); its footage then keeps its colour (a third of the tint) and the words sit on a soft panel of its paper. A
+  bright game is no longer shown on the studio's dark page. `landing.scheme`, `landing.theme`, a `site/pages/<id>/`
+  page and `site/theme.css` are the owner's and always win; a palette whose ink does not read keeps its accents only,
+  on the studio's scheme, as before. A game whose picture is white or cream (a light arena) takes
   `"scheme": "light"` in its `landing` block: its landing is drawn light, the hero tinted and shaded with a light
   background and the words dark, where a dark studio's tint would turn it grey (`"dark"` is the other way round,
   for a dark game in a light studio). `landing.theme` colours still win, and the rest of the site keeps its look. Footage is looked for in this order: `landing.hero` in game.json;
@@ -143,6 +149,18 @@ A studio with its own landing in `site/` keeps it: the template never replaces w
 
 ## The play page
 
+**The arrival (0.26.0).** The play page and the big screen never open blank. From the first paint, an arrival
+card covers the game's frame in the game's own look (worker/arrival.mjs): its title, its pitch (`landing.pitch`, else
+the blurb's first sentence), its key art (the landing's hero still, a trailer's poster or its cover, drifting slowly;
+`landing.hero.tallImage` on an upright phone when there is one), a progress line that says what is happening
+("Finding a room…", "Room 4 · 3 playing · 2 AI", "Loading the game…", "Joining Room 4…", and the game's own
+"Loading the heroes… 60%"), and the controls for this device (`landing.controls.phone`, `.computer`, `.tv`). Its
+colours are the game's palette (style.json), else the landing's (`landing.theme`, `landing.scheme`), else the
+studio's. It lifts when the game says it is playable (NETPLAY.md section 21): by itself once seated with the room's
+state, or at the game's own `net.playable()`; a game built before 0.26.0 lifts it once it has a seat, and nothing
+keeps a game behind it longer than 15 s after the game started (30 s after the page opened). `?arrive=0` leaves it
+out. `homie-studio perf` reads its first frame as the time to the first meaningful frame (`load.look`).
+
 `/<id>/play` puts the visitor in a public room at once and writes the room into the address, so a reload comes
 back to it and a copied address brings a friend into it. A small room button at the edge (top right by default)
 opens: **Invite** (the phone's share sheet, or the link copied), **Big screen** (`/<id>/tv` of this room, on

package/starters/gem-rush/game.json

@@ -5,5 +5,6 @@
   "players": { "min": 1, "max": 8 },
   "roundSeconds": 60,
   "entry": "src/main.ts",
-  "netplay": { "v": 1, "public": true, "movement": "owner" }
+  "netplay": { "v": 1, "public": true, "movement": "owner" },
+  "landing": { "pitch": "Grab the gems. Bump your rivals away.", "controls": { "phone": "Drag to move; a second finger bumps.", "computer": "WASD or arrows to move, Space to bump." } }
 }

package/starters/gem-rush-3d/game.json

@@ -7,5 +7,6 @@
   "entry": "src/main.ts",
   "netplay": { "v": 1, "public": true, "movement": "owner" },
   "needs": { "three": "0.185.1" },
-  "assets": "library"
+  "assets": "library",
+  "landing": { "pitch": "Grab the gems. Bump your rivals away.", "controls": { "phone": "Drag to move; a second finger bumps.", "computer": "WASD or arrows to move, Space to bump." } }
 }

package/starters/hero-rush-3d/game.json

@@ -7,5 +7,6 @@
   "entry": "src/main.ts",
   "netplay": { "v": 1, "public": true, "movement": "owner" },
   "needs": { "three": "0.185.1" },
-  "assets": "library"
+  "assets": "library",
+  "landing": { "pitch": "Grab the coins. Jump their swings. Knock the loot loose.", "controls": { "phone": "Drag anywhere to run; Jump and Swing at the bottom right.", "computer": "WASD or arrows to run, Space to jump, F or a click to swing." } }
 }