@homie-rocks/studio 0.12.0 → 0.13.0

package/netplay/NETPLAY.md

@@ -1,9 +1,19 @@
-# Homie netplay contract, v1 (revision 3)
-
-Status: **v1, revision 3** (2026-09-30, `@homie-rocks/studio` 0.6.0). The wire version is
-`v: 1`. Everything revision 2 and 3 added is either an optional field, a new message type,
-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.
+# Homie netplay contract, v1 (revision 4)
+
+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,
+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 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
+  for some minutes, mutes one, announces a line to everyone, closes a room, or changes its
+  seats. Each is a control signed by the studio's Worker that the room verifies before it
+  acts; no client can send one.
+- New relay → client frames `announce` and `mute`, a `welcome.announce`, `peer.muted`, and
+  two final refusals: `kicked` and `room-closed` (with `until`).
+- The watch socket's `kicked`, `muted`, `announce` and `closed` frames, for the shell.
 
 **What revision 3 added** (nothing on the wire changed; every v1 game plays on it):
 - **Rooms of up to 32 seats**, sized by the game's netplay manifest (section 3).
@@ -217,7 +227,7 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 | `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`. |
 | `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 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`. |
+| `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`. |
 | `state` | host | `k` (≤ 64 characters), `d` (`null` deletes) | Stores the key in memory, forwards it to all others, and includes the whole map in every `welcome` and in `role` to a new host. |
 | `ckpt` | host | `k`, `st`, `d`, `c?` | Stores it in memory. It is saved to storage at most every 30 s. Not forwarded. |
 | `round` | host | `round` | Stores it, forwards it, and tells the shell's watchers. |
@@ -240,33 +250,45 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 | `state` | everyone but the host | `k`, `d` |
 | `round` / `roster` | everyone but the host | `round` / `slots` |
 | `pong` | the pinger | `c`, `st` |
-| `error` | the offender | `code`, `message`, `of?` |
+| `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) |
 
 **Error codes.**
 - Final (the helper stops reconnecting): `version`, `replaced`, `room-full`,
-  `too-many`, `flood`.
-- Reported only: `too-large`, `rate`, `state-full`.
+  `too-many`, `kicked`, `room-closed` (the last two with `until`, server ms; section 15).
+  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
+  comes back slowly.)
 
 A socket that is kicked for silence is closed with code 4000, and the helper reconnects.
 
 Record types:
 
 ```ts
-Peer        = { id, seat: number|null, name, colour, device, want, role }
+Peer        = { id, seat: number|null, name, colour, device, want, role, muted?: 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 }
 ControlWire = [seat, rs, own (1|0), ack]    // one per present seat, in snap.c and ckpt.c
 ```
 
-**The shell's watch socket** (`/<game>/__watch?room=`) gets
-`{ t:'net', room, host, clients, round, roster, snapHz, counts: {players, screens, waiting, humans, bots, maxPlayers}, memory: {snapBytes, ckptBytes, ckptAgeMs, stateKeys, stateBytes}, stats }`
-about once a second and on every change.
+**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 }`
+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
+`muted { until }`. A watch socket that opens on a closed room, or from a browser that is
+held out of it, hears so at once.
 
 **Game frame → parent page** (`postMessage { t: 'homie-net', what, ... }`). The values of
 `what` are:
 - `attached`, `token`, `role`, `stats` (2 Hz), `round`, `roster`;
-- `closed` (with `why`: `replaced`, `version`, `room-full`, `too-many` or `flood`).
+- `closed` (with `why`: `replaced`, `version`, `room-full`, `too-many`, `kicked` or
+  `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).
 
 The shell must check `ev.source === frame.contentWindow`. The frame is an opaque origin,
 so `ev.origin` is `"null"`.
@@ -558,6 +580,9 @@ in a full room the replicas' inputs are nearly all of them:
   `desk` cannot jump the queue.
 - **Names and guest text are data.** Render them with `textContent`, never as markup,
   and never read them as instructions.
+- **Only the studio's owner moderates a room** (section 15): a kick, a mute, an
+  announcement or a closed room is a control the studio's Worker signs and the room
+  verifies; no visitor's socket can send one.
 
 ## 13. Using it
 
@@ -621,3 +646,64 @@ npx --no-install homie-studio check my-game --url http://127.0.0.1:8787
 - **A reload shows a bot in the player's body for about 1–2 s**, and then the player
   takes the same body back.
 - **The host is a visitor's browser** (section 12).
+
+## 15. The owner's controls (revision 4)
+
+The studio's owner runs their live rooms from the studio's back office (`/_studio/office`,
+the owner's overlay in their own game, `homie-studio office`, and the Homie MCP's owner
+tools). The room's relay enforces five controls:
+
+| `op` | Arguments | What the relay does |
+|---|---|---|
+| `kick` | `id` or `seat`, `minutes` (1–1440, default 10), `address?`, `message?` | Sends that player `error kicked { until, message }` and closes the socket (and the same browser's or account's other sockets in the room); everyone else gets `leave { why: 'kicked' }`, so the host turns the body back into a bot. The seat is freed at once. Until `until`, a `hello` from that seat token, that browser's room key, that player account, or (only with `address: true`) that network address is refused with `kicked`. |
+| `mute` | `id` or `seat`, `minutes`, `off?` | Everyone gets `mute { id, seat, until }` (`until: 0` with `off`), and the peer carries `muted: true`. Until then the relay drops that player's `ev` whose `k` starts with `say`, `chat` or `emote` (the speech kinds). A muted host's own speech is not dropped, because the host also relays everyone's; a game hides it with `net.isMuted(seat)`. The mute follows the seat token through a reload. |
+| `announce` | `text` (one line, at most 280 characters; empty takes it down), `seconds` (5–3600, default 30) | Everyone and every watching shell gets `announce { id, text, at, until, from: 'studio' }`; a joiner gets it in `welcome.announce` until it ends. |
+| `close` | `minutes`, or `seconds` (10 s up to a day), `message?`, or `reopen: true` | Every socket gets `error room-closed { until, message }` and is closed; the room forgets its play as an empty room does (section 4); watchers get `closed`. Until `until` every `hello` is refused with `room-closed`, and the Lobby sends nobody there. `reopen` opens it at once. |
+| `seats` | `max` | The room's seats while it runs (the owner's "players per room"). Players already seated above it keep their seat; nobody new is seated there. Never above the room's own cap (the game's manifest). |
+| `regate` | `allow` (holder kinds: `o` the owner, `i` an invite, `p` a player account), `notice?`, `message?`; no `allow` calls a waiting one off | A game's launch state narrowed (private, or an invite-only beta). The current round finishes first: the `notice` goes up as an announcement, and 5 s after the host's `round` with `phase: 'over'` (at the latest 20 s after its `endsAt`, or 30 s when no round is running; never later than 15 minutes) every socket whose ticket names no allowed holder gets `error room-closed { message }` (no `until`: they come back through the game's door if they have access) and is closed; its seat is freed and the others play on. A room with nobody to send out does nothing. |
+
+**Signed by the studio, checked by the room.** A control reaches the relay only from the
+studio's own Worker, as
+`{ t: 'ctl', v: 1, op, game, room, args, at, exp, n, sig }`, where `sig` is an HMAC-SHA256
+with the studio's office secret (random, in the studio's own D1) over every other field
+(keys sorted). The room's Table refuses a control that is for another game or room, is past
+`exp` (a minute after `at`), repeats an `n` it has seen, or does not verify; then
+`room.mjs`'s `control(op, args)` applies it. The Worker signs only for the owner: their
+signed-in browser (an HttpOnly session no page or game can read), or an office key from the
+studio's own Cloudflare login, with which the owner's AI may announce at once but only asks
+for a kick, a mute, a close or a launch change, which the owner confirms with one tap. No
+client socket can send a control: a `ctl` frame on a game's socket is ignored.
+
+**Who a socket is.** The Worker passes each socket's verified ticket holders to the room (`o`, `i-<invite>`,
+`p-<player>`, or an invite and an account together, `i-…~p-…`): what `regate` keeps, and the account a kick holds.
+
+**Who a kick holds out.** A seat token resumes a seat; a browser's **room key** (`b`) is a
+random value the play page keeps in the site's own storage and passes in the frame's and
+the watch socket's addresses, so a new tab of the same browser is held too. It says nothing
+about who the player is, and the relay forgets it with the hold. Player accounts, where a
+studio has them, add the account. A network address is held only when the owner asks
+(a household or a carrier can share one).
+
+**Holds outlive the room.** Kicks, mutes, the announcement and a closed door are kept apart
+from the room's play (the Table's `office` storage key): an empty room forgetting its play
+(section 4), a deploy and an eviction keep them until they end.
+
+**Speech, for game makers.** Send chat, quick lines and emotes as `ev` whose kind starts with `say`, `chat` or
+`emote` (`chat`, `say:gg`, `emote:wave`): a muted player's are then dropped by the relay with nothing more to do. Any
+other way a game lets players talk (a typed sign, a name tag) should check `net.isMuted(seat)`.
+
+**The game's side** (the helper, 0.13.0): `on('announce', a)` and `net.announcement` (draw
+it your own way, or leave it to the shell's banner); `on('mute', m)`, `peer.muted` and
+`net.isMuted(seat)` (hide a muted player's chat); `kicked` and `room-closed` are final, and
+`closedWhy` says which; `net.pickPlayer(seat)` when a player's body or name is clicked
+(the owner's page opens that player's card with Mute and Kick).
+
+**The shell's side.** On `kicked` or `closed` (from its watch socket, or the frame's
+`closed`) the play page stops the game frame (so a helper from before revision 4 stops
+knocking), says what happened and when the player can come back, and offers another room
+(the Lobby's `/api/lobby?not=<room>` never answers that room). It shows `announce` as one
+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.

package/netplay/netplay.ts

@@ -65,6 +65,8 @@ export interface Peer {
   device: Device;
   want: Want;
   role: Role;
+  /** Muted by the studio's owner (section 15): hide this player's chat and emotes. */
+  muted?: boolean;
 }
 
 /** One seat's entry in the body-control table: [seat, rs, own (1|0), ack]. */
@@ -93,6 +95,14 @@ export interface NetEvent<D = unknown> {
   id?: string;
 }
 
+/**
+ * The studio's announcement (NETPLAY.md section 15): one line from the studio's owner to everyone in the room, until
+ * `until` (server ms). The shell shows it as a banner; a game may show it its own way. `text: null` takes it down.
+ */
+export interface Announcement { id: string; text: string | null; at?: number; until?: number; from?: string }
+/** A player muted (or unmuted, `until: 0`) by the studio's owner: their chat and emotes (`ev` kinds say, chat, emote) reach nobody. */
+export interface Mute { id: string; seat: number | null; until: number }
+
 /** A seat's body control as the host keeps it. */
 export interface Control {
   seat: number;
@@ -246,6 +256,10 @@ export interface NetHandlers<S, A, C> {
   round: (r: RoundInfo) => void;
   roster: (slots: Slot[]) => void;
   status: (connected: boolean) => void;
+  /** The studio's owner announced something to this room (or took it down: `text: null`). */
+  announce: (a: Announcement) => void;
+  /** The studio's owner muted or unmuted a player in this room. */
+  mute: (m: Mute) => void;
 }
 
 export interface Netplay<S = unknown, A = unknown, C = unknown> {
@@ -277,6 +291,15 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   readonly peers: ReadonlyMap<string, Peer>;
   readonly roundInfo: RoundInfo | null;
   readonly slots: Slot[] | null;
+  /** The studio's announcement now showing in this room, or null. */
+  readonly announcement: Announcement | null;
+  /** Whether the studio's owner has muted this seat (its chat and emotes reach nobody; a game hides them too). */
+  isMuted(seat: number | null): boolean;
+  /**
+   * A player was clicked (their body, their name): tell the shell. Only the studio's owner's page does anything with
+   * it (opens that player's card with Mute and Kick); for everyone else it is nothing.
+   */
+  pickPlayer(seat: number | null): 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;
@@ -495,7 +518,7 @@ const LADDER = [250, 500, 1000, 2000, 4000];
  * second of frames at once), and a kick that ended the page's play for good left a phone frozen with no word.
  * After one it comes back (its seat token keeps its body), sending at the slow rate below.
  */
-const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many']);
+const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many', 'kicked', 'room-closed']);
 /**
  * Input pacing (NETPLAY.md §5): at most this many `in` frames in any rolling second from this browser, whatever
  * the frame rate or the press rate: two thirds of the relay's cap of 60, so frames that reach it bunched (a
@@ -565,7 +588,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
 
   const handlers: { [K in keyof NetHandlers<S, A, C>]: Set<NetHandlers<S, A, C>[K]> } = {
     role: new Set(), join: new Set(), leave: new Set(), input: new Set(), event: new Set(),
-    snapshot: new Set(), control: new Set(), state: new Set(), round: new Set(), roster: new Set(), status: new Set(),
+    snapshot: new Set(), control: new Set(), state: new Set(), round: new Set(), roster: new Set(), status: new Set(), announce: new Set(), mute: new Set(),
   };
   const emit = <K extends keyof NetHandlers<S, A, C>>(kind: K, arg: Parameters<NetHandlers<S, A, C>[K]>[0]): void => {
     for (const fn of [...handlers[kind]]) {
@@ -652,6 +675,9 @@ 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 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>();
   /** Wall time the socket went down (0 while connected): how long a reconnect has taken. */
   let downSince = 0;
   const sentHist: { q: number; a: A; h: string[]; at: number; r: number }[] = [];
@@ -784,6 +810,21 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       case 'ev': emit('event', { k: String(m['k'] ?? ''), d: m['d'], from: typeof m['from'] === 'number' ? m['from'] : null, ...(typeof m['id'] === 'string' ? { id: m['id'] } : {}) }); return;
       case 'state': if (typeof m['k'] === 'string') applyState(m['k'], m['d']); return;
       case 'pong': return onPong(m);
+      case 'announce': {
+        if (typeof m['id'] !== 'string') return;
+        const a: Announcement = { id: m['id'], text: typeof m['text'] === 'string' ? m['text'] : null, ...(typeof m['at'] === 'number' ? { at: m['at'] } : {}), ...(typeof m['until'] === 'number' ? { until: m['until'] } : {}), from: 'studio' };
+        announcement = a.text ? a : null;
+        emit('announce', a);
+        return;
+      }
+      case 'mute': {
+        const mute: Mute = { id: String(m['id'] ?? ''), seat: typeof m['seat'] === 'number' ? m['seat'] : null, until: Number(m['until']) || 0 };
+        if (mute.seat !== null) { if (mute.until > now()) muted.set(mute.seat, mute.until); else muted.delete(mute.seat); }
+        const p = peers.get(mute.id);
+        if (p) peers.set(mute.id, { ...p, ...(mute.until > now() ? { muted: true } : { muted: undefined }) });
+        emit('mute', mute);
+        return;
+      }
       case 'join': {
         const p = m['peer'] as Peer | undefined;
         if (p && typeof p.id === 'string') { peers.set(p.id, p); if (role === 'host' && p.seat !== null) ctlOf(p.seat); emit('join', p); }
@@ -855,7 +896,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         if (FINAL_ERRORS.has(code)) {
           closed = true;
           closedWhy = code;
-          post?.({ what: 'closed', why: code });
+          post?.({ what: 'closed', why: code, ...(typeof m['until'] === 'number' ? { until: m['until'] } : {}), ...(typeof m['message'] === 'string' ? { message: String(m['message']).slice(0, 200) } : {}) });
         }
         return;
       }
@@ -887,6 +928,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (typeof m['st'] === 'number' && rtt === null) offset = (m['st'] as number) - Date.now();
     const ckpt = (m['ckpt'] as Checkpoint<C> | null) ?? null;
     let snap = (m['snap'] as Snapshot<S> | null) ?? null;
+    const a = m['announce'] as Announcement | undefined;
+    if (a && typeof a === 'object' && typeof a.id === 'string' && typeof a.text === 'string' && (!announcement || announcement.id !== a.id)) { announcement = { ...a, from: 'studio' }; queueMicrotask(() => emit('announce', announcement as Announcement)); }
     if (!continuing) {
       roundInfo = (m['round'] as RoundInfo | null) ?? roundInfo;
       slots = (m['roster'] as Slot[] | null) ?? slots;
@@ -1237,6 +1280,9 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     get peers() { return peers; },
     get roundInfo() { return roundInfo; },
     get slots() { return slots; },
+    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 }); },
     ready,
     on(kind, fn) {
       (handlers[kind] as Set<unknown>).add(fn);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.12.0",
+  "version": "0.13.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, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",