@homie-rocks/studio 0.14.3 → 0.15.0

package/README.md

@@ -80,11 +80,13 @@ its D1; nothing is stored by hand. studio.json `homie.directory: false` keeps a
 
 Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
 featured game, live rooms, the latest posts), Games, Music, Videos, Rooms (every public room playing now,
-joinable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
+joinable and watchable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
 page answers 404. Every game gets a landing at `/<game>/`: a full-bleed hero from its own footage or art, the
 pitch, a big Play button into a public room, how to play on a phone, a computer and a TV (with the join code),
-live rooms, credits (the original and its licence for a port), and "Make a game like this". Every page ends with
-"Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
+live rooms, credits (the original and its licence for a port; "Remix of <game> by <studio>", linked, for a
+remix), and "Make a game like this". A game's shared source (`/games/<id>/source.json`) says who made it and the
+licence its owner picked in game.json `"license"`: `"remix-with-credit"` (the default), `"remix-freely"` or
+`"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
@@ -95,13 +97,20 @@ game's landing still. Every HTML answer is `no-transform`, and the site's pages
 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.
 
+Anyone can **watch** a live room from any player's view at `/<game>/watch?room=<room>` (a Watch button sits beside
+Join on every room): the game itself, drawn by the watcher's own browser as a watcher that never takes a seat,
+with a strip of the players to switch between (a tap, keys 1-9, Auto, the whole room). A game draws the followed
+player's camera and HUD from `net.viewSeat` (Gem Rush and Ember Vale do; a game that does not is watched as its
+overview), and game.json `"watch": "overview"` or `false` keeps hidden hands hidden. Private and invite-only games
+are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
+
 ## Upgrading a studio
 
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.14.3 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.14.3 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.15.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.15.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -232,7 +241,7 @@ device; the owner's own passkey account (`homie-studio players owner`) counts as
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.14.3 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.15.0 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 
@@ -409,7 +418,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
-| `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`); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
+| `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 or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
 | `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |
 | `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 storage, or a link). `media list` shows it; `media put` uploads a file to storage and records its key. |

package/bin/homie-studio.mjs

@@ -164,7 +164,7 @@ function print(result) {
       lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`), '', result.online);
       break;
     case 'game remix':
-      lines.push(`games/${result.id} is a remix of ${result.from} (${result.files.length} files). Make it yours in games/${result.id}/src/, then: npx homie-studio dev`);
+      lines.push(`games/${result.id} is a remix of ${result.from} (${result.files.length} files). Its game.json credits the original: "${result.credit}"${result.page ? ` (${result.page})` : ''}, on its landing and in its credits. Make it yours in games/${result.id}/src/, then: npx homie-studio dev`);
       break;
     case 'game new':
       lines.push(`games/${result.id} is a new game from the ${result.from} starter. Change it in games/${result.id}/src/, then: npx homie-studio dev`);

package/lib/build.mjs

@@ -33,6 +33,7 @@ import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
+import { licenseOf, remixRow } from '../worker/license.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
@@ -64,8 +65,12 @@ function dirBytes(dir) {
   return n;
 }
 const TEXT = /\.(ts|tsx|js|mjs|jsx|json|html|css|md|txt|svg|glsl|wgsl|frag|vert)$/i;
-/** Text files of a game folder, capped (2 MB total, 512 KB each): what `homie-studio game remix` takes. */
-export function sourceOf(dir, id) {
+/**
+ * Text files of a game folder, capped (2 MB total, 512 KB each): what `homie-studio game remix` takes; with who made
+ * it (`credit`: the studio and the game; the live site adds the page, worker/index.mjs) and its licence (game.json
+ * "license", worker/license.mjs).
+ */
+export function sourceOf(dir, id, { studio = null, game = null, license } = {}) {
   const files = {};
   let total = 0;
   const walk = (rel) => {
@@ -82,7 +87,7 @@ export function sourceOf(dir, id) {
     }
   };
   walk('');
-  return { v: 1, kind: 'homie-game-source', id, files };
+  return { v: 1, kind: 'homie-game-source', id, credit: { studio, game: game ?? id }, license: licenseOf(license), files };
 }
 
 /*
@@ -193,7 +198,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
     if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
-    if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id))}\n`);
+    if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id, { studio: studio.name ?? null, game: g.name ?? g.id, license: g.license }))}\n`);
     const main = join(out, 'assets', 'main.js');
     const bytes = existsSync(main) ? statSync(main).size : dirBytes(out);
     const seats = seatsFor(g, netplayOf(g, out));
@@ -225,6 +230,12 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       ...(g.saves === true || (g.saves && typeof g.saves === 'object') ? { saves: true } : {}),
       // game.json `"launch": "private" | "invite"`: the game's launch state until its owner sets one live (the office).
       ...(g.launch === 'private' || g.launch === 'invite' ? { launch: g.launch } : {}),
+      // game.json `"watch"` (NETPLAY.md section 16): watchers see any player's view (the default), only the whole room
+      // ("overview": hidden hands or roles), or nothing (false: no watch door).
+      ...(g.watch === 'overview' ? { watch: 'overview' } : g.watch === false || g.watch === 'off' ? { watch: 'off' } : {}),
+      // Its source licence (worker/license.mjs), and, for a remix, what it is a remix of (shown on its landing).
+      license: licenseOf(g.license),
+      ...(remixRow(g.remixOf) ? { remixOf: remixRow(g.remixOf) } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });

package/lib/mcp-tools.mjs

@@ -684,7 +684,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_remix', title: 'Remix a shared game',
-      description: 'Bring a game another studio shared in the Homie directory into this studio as a new game of its own (the original stays credited in game.json).',
+      description: 'Bring a game another studio shared in the Homie directory into this studio as a new game of its own. The original stays credited: game.json remixOf says "Remix of <game> by <studio>" with a link back, shown on the new game\'s landing and in its credits. A game whose owner\'s licence says no remix is refused.',
       inputSchema: { type: 'object', properties: { game: str('The directory game: "<studio site>/<game id>" or its play URL'), id: str('The new game id in this studio'), name: str('Optional: its new name'), ...STUDIO_ARG }, required: ['game', 'id'] },
       annotations: { title: 'Remix a game', ...RW, openWorldHint: true },
       run: async (a) => {
@@ -696,7 +696,8 @@ export function toolDefs(ctx, avail = {}) {
         const r = await cli(ctx, root, `game remix ${a.id}`, ['game', 'remix', source, '--id', a.id, ...(a.name ? ['--name', String(a.name).slice(0, 60)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'The remix');
         if (r.job.code !== 0) return fail(`Not remixed: ${whyOf(r.job)}`);
-        return ok(`games/${a.id} is a remix of ${site}/${gameId} (${(r.result?.files ?? []).length} files).`, { kind: 'game', ...r.result });
+        const credit = r.result?.credit ? ` Its game.json credits the original: "${r.result.credit}"${r.result.page ? ` (${r.result.page})` : ''}, on its landing and in its credits; keep it.` : '';
+        return ok(`games/${a.id} is a remix of ${site}/${gameId} (${(r.result?.files ?? []).length} files).${credit}`, { kind: 'game', ...r.result });
       },
     },
     {

package/lib/scaffold.mjs

@@ -169,7 +169,7 @@ studio's pinned copy, never a registry lookup of the bare name.
 (\`node_modules/@homie-rocks/studio/site/SITE.md\` says all of it):
 
 - **Sections, like homie.rocks:** Home (the featured game, live rooms, latest posts), Games, Music, Videos,
-  Rooms (every public room playing now, joinable) and Posts. A section with nothing in it has no tab, and its
+  Rooms (every public room playing now, joinable and watchable) and Posts. A section with nothing in it has no tab, and its
   page is not found.
 - **A new studio goes live with its Home only:** its name and "First game coming soon", with what is on the way
   (games, posts, music and videos), until its first game, song or video is published. A post shows there at once.
@@ -200,8 +200,22 @@ studio's pinned copy, never a registry lookup of the bare name.
   scoreboard or a bar is there, move it in game.json \`"screen": { "share": … }\`: a corner or \`top-center\`, per
   device (\`desk\`, \`phone\`, \`sideways\`), with an \`x\` / \`y\` offset in pixels, and \`"label": false\` to keep it
   a small icon (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Look at it on a phone and a computer.
+- **Watch any player.** Every live room can be watched at \`/<id>/watch?room=<room>\` (each room on the Rooms page
+  and the landing has a Watch button): the game itself, drawn by the watcher's own browser, which never takes a
+  seat, with a strip of the players to switch between (a tap, keys 1-9, A for Auto, O for the whole room). Point the
+  camera and the HUD at \`net.viewSeat\` (your own seat when playing; the followed player when watching; null: the
+  overview camera; \`room.viewBody()\` in a port), and call \`net.spotlight(seat)\` on a hit, a kill or a goal so
+  Auto cuts to it (\`NETPLAY.md\` section 16). A game that never reads \`viewSeat\` is watched as its overview. A
+  game with hidden hands or roles says game.json \`"watch": "overview"\` (the whole room only) or \`false\` (no
+  watch door); a private or invite-only game is watched only by those it lets in.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
+- **Remixing.** A public game shares its source at \`/games/<id>/source.json\`, with who made it (the studio, the
+  game, its page) and the licence its owner picks in game.json \`"license"\`: \`"remix-with-credit"\` (the
+  default), \`"remix-freely"\` or \`"no-remix"\`, and \`{ "kind": "…", "spdx": "MIT" }\` to name a licence too.
+  \`npx --no-install homie-studio game remix <source.json> --id <new id>\` brings another studio's game in as a new
+  game here: its game.json \`remixOf\` says "Remix of <game> by <studio>" with a link back, and its landing and
+  credits show it; keep that credit. A game whose licence says no remix is refused.
 - **Progress that lasts** (a character, unlocks, a collection, days of play) goes in **saves**, never in the room:
   a room forgets everything 60 s after its last player leaves. game.json \`"saves": true\` and
   \`createSaves\` from \`@homie-rocks/studio/saves\` (\`node_modules/@homie-rocks/studio/saves/SAVES.md\`): per

package/lib/studio.mjs

@@ -5,6 +5,7 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { httpsPage, licenseOf, pageOfSource, remixAllowed, remixCredit, remixRow } from '../worker/license.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -125,7 +126,11 @@ export function newGame(root, id, { from = 'gem-rush', name } = {}) {
   return { ok: true, command: 'game new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String) };
 }
 
-/** `homie-studio game remix <source.json url> --id <new id>`: a shared game brought in as this studio's own. */
+/**
+ * `homie-studio game remix <source.json url> --id <new id>`: a shared game brought in as this studio's own. Its
+ * game.json `remixOf` credits the original ("Remix of <game> by <studio>", with a link back to its page), and its
+ * landing and credits show it. A game whose owner's licence says no remix is refused (worker/license.mjs).
+ */
 export async function remixGame(root, source, id, { name } = {}) {
   if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error('give the new game an id: --id <lowercase-id>');
   const dest = join(root, 'games', id);
@@ -137,6 +142,14 @@ export async function remixGame(root, source, id, { name } = {}) {
   if (!res.ok) throw new Error(`${url} answered ${res.status}`);
   const body = await res.json();
   if (body?.kind !== 'homie-game-source' || !body.files || typeof body.files !== 'object') throw new Error('that address is not a shared Homie game source');
+  // Who made it and what they allow: the source's credit and licence (a studio before 0.14.4 sends neither, so the
+  // default licence, and the page from the address).
+  const credit = body.credit && typeof body.credit === 'object' ? body.credit : {};
+  const license = licenseOf(body.license);
+  if (!remixAllowed(license)) {
+    const who = remixRow({ name: credit.game ?? body.id, studio: credit.studio });
+    throw new Error(`${who?.name ?? 'That game'}${who?.studio ? ` by ${who.studio}` : ''} is not open to remixing: its owner's licence says no remix. Make a game of your own like it instead.`);
+  }
   const wrote = [];
   for (const [rel, text] of Object.entries(body.files)) {
     if (typeof text !== 'string' || rel.includes('..') || rel.startsWith('/') || !/^[A-Za-z0-9._/-]+$/.test(rel)) continue;
@@ -148,11 +161,18 @@ export async function remixGame(root, source, id, { name } = {}) {
   if (!existsSync(join(dest, 'game.json'))) throw new Error('the shared source has no game.json');
   const meta = JSON.parse(readFileSync(join(dest, 'game.json'), 'utf8'));
   const from = meta.id;
-  meta.remixOf = { source: String(url), id: from, name: meta.name };
+  // The credit, in the remix's own game.json: the original's name, studio, page and licence, the line its landing and
+  // credits show, and, when the original was itself a remix, what that was a remix of.
+  const row = remixRow({ name: credit.game ?? meta.name ?? from, studio: credit.studio, page: httpsPage(credit.page) ?? pageOfSource(url) });
+  const before = remixRow(meta.remixOf);
+  meta.remixOf = {
+    credit: remixCredit(row), name: row?.name ?? null, studio: row?.studio ?? null, page: row?.page ?? null,
+    source: String(url), id: from, license, ...(before ? { of: before } : {}),
+  };
   meta.id = id;
   if (name) meta.name = String(name).slice(0, 60);
   writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
   const main = join(dest, meta.entry ?? 'src/main.ts');
   if (existsSync(main) && from) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
-  return { ok: true, command: 'game remix', id, from: String(url), files: wrote };
+  return { ok: true, command: 'game remix', id, from: String(url), credit: meta.remixOf.credit, page: meta.remixOf.page, license, files: wrote };
 }

package/lib/template-history.json

@@ -380,6 +380,60 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.14.4": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "e579cd6ce3ce342a",
+     "## The site": "7c1618431bae6324",
+     "## Making games": "ce87c4dde1894c26",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.15.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "e579cd6ce3ce342a",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -1,10 +1,20 @@
-# Homie netplay contract, v1 (revision 4)
+# Homie netplay contract, v1 (revision 5)
 
-Status: **v1, revision 4** (2026-10-01, `@homie-rocks/studio` 0.13.0). The wire version is
-`v: 1`. Everything revisions 2 to 4 added is either an optional field, a new message type,
+Status: **v1, revision 5** (2026-10-01, `@homie-rocks/studio` 0.15.0). The wire version is
+`v: 1`. Everything revisions 2 to 5 added is either an optional field, a new message type,
 a new refusal, or a change of pace inside the old caps, and both sides ignore types they do
 not know. A change to the contract bumps `v` and keeps v1 working.
 
+**What revision 5 added** (a v1 game that knows none of it is watched as its overview):
+- **Watching** (section 16): a watcher is a screen that came to watch a live room from any
+  player's view. It never takes a seat, hosts only a room no player can, and the game draws
+  the followed player's camera and HUD from `net.viewSeat`. Auto follows the action
+  (`net.spotlight(seat)`, else the leader of the `scores` probe).
+- New optional fields `hello.watch`, `welcome.watch` and `peer.watch`, a relay → client
+  `watch` frame, the final refusal `watch-off`, and `counts.watchers` in the watch feed.
+- game.json `"watch"`: `"overview"` (hidden hands or roles: the whole room only) or `false`.
+- `PALETTE`: the contract's 12 player colours, which a peer's `colour` indexes.
+
 **What revision 4 added** (a v1 game that knows none of it keeps playing; its shell shows
 the notices and the banner):
 - **The owner's controls** (section 15): the studio's owner kicks a player out of a room
@@ -91,12 +101,15 @@ code.
 |---|---|---|---|---|---|
 | `host` | One browser per room | yes | if seated (a seatless host is possible) | `snap`, `state`, `ckpt`, `round`, `roster`, `ev` | `in`, `ev`, `join`, `leave` |
 | `replica` | Every other seated browser | no | yes | `in`, `ev` | `snap`, `state`, `ev`, `round`, `roster`, `join`, `leave`, `seat` |
-| `screen` | A spectator (a TV or laptop with `?screen=1`, or a visitor waiting for a seat) | no | no | `ev` (2/s, 512 B) | the same as a replica |
+| `screen` | A spectator (a TV or laptop with `?screen=1`, a watcher from the game's watch door, or a visitor waiting for a seat) | no | no | `ev` (2/s, 512 B) | the same as a replica |
 
 - **Role and seat are separate facts.**
   - `net.isHost` answers: do I run the rules?
   - `net.seat !== null` answers: do I have a body?
   - A screen can be elected host when nobody else can host.
+- **A watcher** (section 16) is a screen that never takes a seat: not at its hello, and not when
+  one frees up. A visitor who wanted to play and found the room full is the other kind of screen:
+  it takes the next free seat.
 - **Offline is not a fourth role.** With no shell (a plain file, a Vite dev server),
   the helper reports `role: 'host'`, `seat: null` and `offline: true`, and every send
   is a no-op.
@@ -113,7 +126,7 @@ code.
 | `token` | The capability that resumes a seat | Returned in `welcome` and never shown to others. The shell keeps it in `sessionStorage`. |
 | `id` | One socket | Used for routing, event addressing and the host reference. It changes on every reconnect. |
 | `name` | Display name | Typed by the guest, so untrusted: render it with `textContent` only. |
-| `colour` | `seat % 12` | An index into a 12-colour palette. |
+| `colour` | `seat % 12` | An index into the contract's 12 colours, `PALETTE` (the watch page's strip draws them; a game that colours its players by seat matches it). |
 
 - **Every visitor gets a seat at once**, phone or desktop. There is no gathering.
 - **Room size.** `maxPlayers` comes from the game's netplay manifest: game.json's
@@ -224,7 +237,7 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 
 | `t` | Sent by | Fields | What the relay does |
 |---|---|---|---|
-| `hello` | everyone, once | `v: 1`, `token?`, `name?`, `device`, `want: 'play'\|'screen'`, `canHost`, `game?`, `max?` | Seats the client (or queues it), picks a role, replies `welcome`, and sends `join` to the others. Refuses with `version`, `room-full` or `too-many`. |
+| `hello` | everyone, once | `v: 1`, `token?`, `name?`, `device`, `want: 'play'\|'screen'`, `canHost`, `game?`, `max?`, `watch?` (revision 5) | Seats the client (or queues it), picks a role, replies `welcome`, and sends `join` to the others. Refuses with `version`, `room-full`, `too-many` or `watch-off`. A `watch: true` hello is a watcher (section 16). |
 | `snap` | host | `k`, `st`, `d`, `c?` (control table) | Clamps `st` to [now − 2 s, now + 250 ms] (a snapshot stamped in the future would freeze replicas). Stores the snapshot and fans it out with `from`. Skips a socket with more than 256 KB buffered. |
 | `in` | seated non-host | `q`, `a`, `h`, `p?`, `r` (the reset epoch the sender has adopted) | Forwards to the host only, stamped `from: <seat>`. Presses are clamped to integers 0–8, at most 16 keys. |
 | `ev` | anyone | `k`, `d`, `to?` | **From a muted player** (section 15): a speech kind (`say…`, `chat…`, `emote…`) is dropped. **From the host:** to everyone else, to one seat (`to`: number) or to one peer (`to`: id string, such as a screen). **From anyone else:** to the host, with `from` and the sender's `id`. **Best-effort:** a drop over a cap is reported with `error rate`. |
@@ -239,7 +252,7 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 
 | `t` | To | Fields |
 |---|---|---|
-| `welcome` | the new client | `v`, `id`, `room`, `seat`, `token`, `name`, `colour`, `role`, `why: 'first'\|'resumed'\|'joined'\|'host-stalled'\|'host-hidden'`, `host`, `peers`, `st`, `max`, `round`, `roster`, `snap`, **`state`**, `ckpt` (host only), `full?` |
+| `welcome` | the new client | `v`, `id`, `room`, `seat`, `token`, `name`, `colour`, `role`, `why: 'first'\|'resumed'\|'joined'\|'host-stalled'\|'host-hidden'`, `host`, `peers`, `st`, `max`, `round`, `roster`, `snap`, **`state`**, `ckpt` (host only), `full?`, `watch?: { follow, why? }` (a watcher only) |
 | `role` | a client whose role changed | `role`, `why`, `host`, `peers`. For a new host, also `ckpt`, `snap`, `round`, `roster`, `state`. |
 | `seat` | a waiting spectator that just got a seat | `seat`, `token`, `name`, `colour`, `role` |
 | `host` | everyone else, on a change | `host`, `why` |
@@ -253,10 +266,12 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 | `error` | the offender | `code`, `message`, `of?`, `until?` |
 | `announce` | everyone (and in `welcome.announce`) | `id`, `text` (`null`: taken down), `at`, `until`, `from: 'studio'` (section 15) |
 | `mute` | everyone | `id`, `seat`, `until` (`0`: unmuted) (section 15) |
+| `watch` | one watcher | `follow`, `why?` (`overview`, `seated-here`): whether it may follow one player now (section 16) |
 
 **Error codes.**
 - Final (the helper stops reconnecting): `version`, `replaced`, `room-full`,
-  `too-many`, `kicked`, `room-closed` (the last two with `until`, server ms; section 15).
+  `too-many`, `kicked`, `room-closed` (the last two with `until`, server ms; section 15),
+  `watch-off` (a watcher of a game that cannot be watched; section 16).
   The helper before revision 4 does not know `kicked` and `room-closed` and keeps knocking;
   every knock is refused at `hello`, and the shell stops the frame (section 15).
 - Reported only: `too-large`, `rate`, `state-full`. (`flood` closes the socket; the helper
@@ -267,7 +282,7 @@ A socket that is kicked for silence is closed with code 4000, and the helper rec
 Record types:
 
 ```ts
-Peer        = { id, seat: number|null, name, colour, device, want, role, muted?: true }
+Peer        = { id, seat: number|null, name, colour, device, want, role, muted?: true, watch?: true }
 RoundInfo   = { n, phase: 'live'|'over', startedAt, endsAt, results?: RoundResult[] }   // server ms
 RoundResult = { slot, seat: number|null, name, score, bot, place }
 Slot        = { slot, seat: number|null, name, bot }
@@ -275,7 +290,7 @@ ControlWire = [seat, rs, own (1|0), ack]    // one per present seat, in snap.c a
 ```
 
 **The shell's watch socket** (`/<game>/__watch?room=&b=`) gets
-`{ t:'net', room, host, clients, round, roster, snapHz, openedAt, announce, closedUntil?, counts: {players, screens, waiting, humans, bots, maxPlayers}, memory: {snapBytes, ckptBytes, ckptAgeMs, stateKeys, stateBytes}, stats }`
+`{ t:'net', room, host, clients, round, roster, snapHz, openedAt, announce, closedUntil?, counts: {players, screens, waiting, watchers, humans, bots, maxPlayers}, memory: {snapBytes, ckptBytes, ckptAgeMs, stateKeys, stateBytes}, stats }`
 about once a second and on every change, and the owner's controls as they happen
 (section 15): `announce` (the same frame the game gets), `closed { until, message }`, and,
 only for the browser they are about (its room key `b`), `kicked { until, message }` and
@@ -289,6 +304,12 @@ held out of it, hears so at once.
   `room-closed`, and `until` and `message` for the last two);
 - `pick` (with `seat`): the game's `net.pickPlayer(seat)`, a player clicked. Only the studio
   owner's page does anything with it (section 15).
+- `view` (a watcher; section 16): `seat`, `following`, `follows` (the game draws the followed
+  player), `canFollow`, `whyNot`; and `scores` (`[{ seat, score }]`, once a second, from the
+  game's `scores` probe).
+
+**Parent page → game frame** (revision 5): `postMessage { t: 'homie-watch', follow: seat | 'auto' | null }`.
+The helper takes it only from its own parent window, and only as a watcher.
 
 The shell must check `ev.source === frame.contentWindow`. The frame is an opaque origin,
 so `ev.origin` is `"null"`.
@@ -486,6 +507,7 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
    - use separate storage keys, or a SQLite-backed object, if a save can pass 128 KiB.
 7. **Choose the device** with the short-edge rule (≤ 540 px is a phone; `?hand=`
    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.
 9. **One matcher:** every Play door for a game lands in the same rooms (the `Lobby`).
@@ -508,7 +530,9 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
 4. **When seated:** call `net.input([...avatar, ...intent], held)` every frame. Adopt
    your body on `control` with `reset`. While `!net.owned`, predict (section 8).
 5. **Render others** from `net.sample()` and your own body locally. A spectator gets an
-   overview camera.
+   overview camera. **Draw from `net.viewSeat`** (section 16): your own seat when you play,
+   the followed player's body, camera and HUD when you watch, the overview when it is `null`;
+   call `net.spotlight(seat)` on a hit or a goal, and expose `scores` for Auto and the strip.
 6. **Draw your own HUD**: clock (`round.endsAt − net.now()`), scores, results.
 7. **Touch controls on phones:** a drag in the lower-left moves you. On desktop,
    WASD and the arrow keys.
@@ -616,9 +640,9 @@ function frame(dt) {
     if (net.snapshotDue()) net.snapshot(fastState(), tick);
     net.state('world', slowWorld());                                                   // sent only when it changed
   } else net.input([q(me.x), q(me.y), q(me.vx), q(me.vy), stick.x, stick.y], heldButtons());
-  render(hosting ? authoritative : net.sample());
+  render(hosting ? authoritative : net.sample(), net.viewSeat);                         // camera + HUD: whose view (section 16)
 }
-net.expose({ self: () => me, peer: (seat) => positionOf(seat), frames: () => frameCount });
+net.expose({ self: () => me, peer: (seat) => positionOf(seat), frames: () => frameCount, scores: () => scoresBySeat() });
 ```
 
 ```sh
@@ -707,3 +731,85 @@ line across the top until it ends, and tells a muted player so.
 **Launch states** are the site's, not the relay's: a game that is private or an invite-only
 beta gives each browser it lets in a signed ticket (`t`) for its frame and sockets, and the
 Worker refuses a socket without one before it reaches the room.
+
+## 16. Watching (revision 5)
+
+A **watcher** watches a live room from any player's view. Nothing is streamed: the watcher's
+own browser loads the game and receives what a replica receives (snapshots, keyed state, events
+sent to everyone), and draws it with the followed player's camera and HUD. Every existing game
+is watchable on day one as its spectator overview; a game that draws `net.viewSeat` lets the
+watcher switch between the players.
+
+**Who a watcher is (the relay).**
+- The shell's watch door (`/<game>/watch?room=<room>&follow=<seat>|auto|overview`) boots the
+  game with `HOMIE_NET = { …, want: 'screen', watch: true, follow, watchPolicy }`, and the
+  socket's address carries `w=1`. A revision-5 helper also says `watch: true` in its `hello`.
+  Either one makes the socket a watcher:
+  - it **never takes a seat**, at its hello or later, whatever its hello asks for;
+  - it **hosts only a room no player can host**: election ranks every visible, responsive
+    player above it, and a watcher never deposes a frozen host at its hello;
+  - its peer record carries `watch: true`, and the watch feed counts it (`counts.watchers`);
+  - for every cap it is a screen: `ev` at 2/s and 512 B, one of the room's `+16` sockets.
+- `welcome.watch = { follow, why? }` says whether it may follow one player's view, and a
+  `watch { follow, why }` frame says so when that changes. `why` is `overview` (the game shows
+  watchers the whole room only) or `seated-here` (this browser holds a seat in this room).
+- A game whose game.json says `"watch": false` has no watch door: the Worker answers it with a
+  page that says so and refuses a `w=1` socket (403), and the relay refuses a watching hello
+  with `error watch-off` (final). The Worker passes the game's rule to the room with every
+  socket (`wp=follow|overview|off`).
+
+**What the game does (the helper).**
+
+| Call | Meaning |
+|---|---|
+| `net.watching` | This browser watches. |
+| `net.viewSeat` | Whose camera and HUD to draw: a player's own seat; the seat a watcher follows; `null` for the overview camera. Reading it (or listening for `view`) tells the watch page that this game draws the followed player. A game that never does is shown as its overview, and the page says so. |
+| `net.on('view', ({ seat, following, prev, why }) => …)` | Whose view changed. `why`: `start`, `seat`, `asked`, `auto`, `left` (the followed player left; Auto takes over, and returns to them if they are back within 30 s), `back`, `policy`. |
+| `net.follow(seat \| 'auto' \| null)` | Follow a seat, the action, or the whole room. The watch page's strip and keys call it through the frame; a game's own spectator UI may too. False when not allowed. |
+| `net.spotlight(seat)` | Something happened to this player (a hit, a kill, a goal). A no-op except on a watcher in Auto. |
+| `net.players()` | The seated players in seat order (key 1 is the first). |
+| `net.following`, `net.canFollow` | What was asked; whether this watcher may choose. |
+| `net.watchedSeat` | `viewSeat` without claiming the camera follows: for an overlay that only marks the followed player (the port's HUD). |
+
+- **Auto** shows a player for at least 3.5 s, then cuts to the newest spotlight. With no action,
+  every 12 s it looks at the leader of the game's `scores` probe
+  (`net.expose({ scores: () => [{ seat, score }] })`; a tie keeps who is shown), else the next
+  player in seat order. Nobody seated: the overview.
+- **Keys** inside the frame, for a watcher who clicked into the game: 1–9 the n-th player in
+  seat order, A Auto, O or 0 the whole room, ← → the previous or next player
+  (`createNetplay({ watchKeys: false })` turns them off). The watch page answers the same keys.
+- The helper tells its page `view` and `scores` (section 5) and takes `homie-watch` from its
+  own parent window only.
+- **Draw the followed player as that player's own browser frames them**: their body under the
+  camera, their score or health in the HUD, their row marked as "you" is (with their name, never
+  "You"). Their own body is interpolated like every other one; nothing of yours moves.
+
+**Hidden information.** A watcher receives what any replica receives. What is private goes to
+one seat (`net.send(kind, data, seat)`), so a watcher following that seat never has it. A game
+whose shared state itself shows a hand or a role (cards, a traitor game) says game.json
+`"watch": "overview"`: its watchers draw the whole room only and the strip only names the
+players. `"watch": false` removes the watch door. Neither is a wall a modified browser cannot
+climb, and neither needs to be: anyone may take a seat in a public room and receive the same
+stream as a player. The rule decides what is offered and drawn.
+
+**A second tab is not a peek.** A browser that holds a seat in a room watches that room in the
+overview only (`seated-here`), for as long as its seat is there: the relay compares the
+browser's room key (`b`, section 15), so a second tab cannot look over an opponent's shoulder
+with a click. Another device is another watcher, as it would be another player.
+
+**Launch states and the owner's controls.** The watch door is the play door: a private game or
+an invite-only beta is watched only by whoever may play it, and their ticket rides in the
+frame's and the sockets' addresses as it does for Play. A kick holds that browser out of
+watching the room too (the same room key), and a closed room closes for watchers.
+
+**Old games and old relays.**
+- A game with a helper from before revision 5 is booted as a screen: it draws its overview, the
+  Worker's `w=1` makes the relay treat it as a watcher, and the page lists the players without
+  letting the watcher choose.
+- A revision-5 helper on an older relay is a plain screen (no relay ever seated a screen); with
+  no `welcome.watch`, following is the page's to allow.
+
+**Cost.** A watcher is one more socket on the fan-out (outgoing messages are not billed) and one
+ping every 2 s (a request, billed 20:1). Like a big screen, a watcher alone keeps a room's object
+awake; the room's host of last resort is the watcher's browser, running the bots.
+