@homie-rocks/studio 0.32.0 → 0.33.0

package/netplay/NETPLAY.md

@@ -1,10 +1,30 @@
-# Homie netplay contract, v1 (revision 9)
+# Homie netplay contract, v1 (revision 10)
 
-Status: **v1, revision 9** (2026-10-06, `@homie-rocks/studio` 0.31.0). The wire
-version is `v: 1`. Everything revisions 2 to 9 added is either an optional field, a new message type,
+Status: **v1, revision 10** (2026-10-07, `@homie-rocks/studio` 0.33.0). The wire
+version is `v: 1`. Everything revisions 2 to 10 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 10 added** (a game that knows none of it plays exactly as before, hosted by a player's
+browser; nothing here changes a frame such a game sends or receives):
+- **The server as host** (section 29): a game written as rules plus view (`src/rules.ts`, `src/move.ts`,
+  `src/view.ts`) has no browser host. Its rules run in the room's `Table`, in a host runtime
+  (`rules/host.ts`) that plays the host's part on this wire. The relay gains one kind of host, the
+  server: it is not a client, it is never elected away, and stall detection, yield and the caps
+  written for a host that is somebody's phone do not apply to it.
+- **Input as steps** (section 29): for such a game `in` carries `e`, `k`, `s` and `r` (the room's epoch,
+  the first tick the frame covers, one or more entries `[o, ...fields]`, and the placement counter),
+  and `snap` carries `e` and one control row a seat, `[seat, r, ack, lead]`. There is no separate
+  sequence number: an entry is named by its tick.
+- **The life of a server-hosted room** (section 29): it pauses when the last person's socket closes,
+  resumes on the tick it paused on, and ends when nobody returns within a minute. The whole room is
+  saved once a second by default and restored after a restart, under a new epoch (section 29.6).
+- The refusal `host-failed` (the rules could not start: the room says why and lets nobody in) and
+  the error `room-over` (the room ended because its rules kept failing); `welcome.host` and the watch
+  feed's `host` are `{ id: 'server', seat: null }` for such a room, and the feed says `hosted: 'server'`
+  with the room's tick figures (`ticks`); `NETPLAY_REVISION` 10 and the build mark
+  `homie-netplay-rev:10`.
+
 **What revision 9 added** (a game that knows none of it plays as before; a revision-8 helper and a
 revision-8 relay ignore every new field and frame):
 - **The link, said out loud** (section 22): `net.link` and `on('link')` (`online`, `reconnecting`,
@@ -1172,11 +1192,16 @@ it at `/games/<id>/agents.json`, where the Table reads it once.
 | `k` | From → to | `d` | The relay |
 |---|---|---|---|
 | `agent:view` | host → one AI's seat (`to: seat`) | the game's view of that guide (below) | Only the host, only to an AI's seat, under 2 KB, at most one every 2 s per AI; kept as that AI's latest view. |
+| `agent:offer` | host → everyone | `{ slot, view }` | The bounded declared guide view, at most once every 2 s. Replicas accept it only from the current host. |
+| `agent:goal` | host → everyone | `{ slot, goal, prev, askAt }` | A goal change for UI listeners; `goal` and `prev` are helper goals or null, timestamps in milliseconds. Host only. |
+| `agent:ask` | host → everyone | `{ slot, k, args, from, at }` | A validated person's guide request for UI listeners; `at` is milliseconds. Host only. |
 | `agent:do` | AI → host | `{ goal, args }` | A goal of the vocabulary whose arguments fit the AI's latest view and the seats people hold; at most one every 3 s. |
 | `say:<lineId>` | AI → host | `{ args }` | A line of the vocabulary with fitting arguments, on a server whose AI may talk (`policy.brain` is `workers-ai` or `owner-key`), at most one every 4 s and 8 a minute. The host renders it and relays it to everyone as `say:<lineId>` `{ slot, seat, args, ai: true }`, which the relay checks again (a line of the vocabulary; a view argument from the speaking AI's latest view, or only an id for a guide no AI holds): a host cannot put its own words in an AI's line. |
 | `ask:<askId>` | a person → host | `{ slot, seat, args }` | Copied to the AI in `seat` (an ask id of the vocabulary). |
 | anything else from an AI with no game client, `chat`, `emote`, `agent:view` | | | Dropped and counted (`stats.agentDrops`). An AI never types. |
 
+Only the host emits `ai: true`. A server host removes `ai`, `slot` and `seat` from relayed person or watcher speech. Replicas accept guide lines only from the current host (whose seat is null for a server host). Vocabulary membership uses own keys, never inherited properties.
+
 The lite feed (hands `host`) carries `join`/`leave`, `roster`, `round`, `policy`, `vote`, events
 addressed to its seat, the party's `say:`/`emote:` lines (`chat` only on a `speech: game`
 server), and the asks made of it; never `snap`, `ckpt` or `state`.
@@ -1204,7 +1229,7 @@ agents.ask(slot, 'ask_help', { quest: 'king-slime' });     // a person's button
 | Call | Meaning |
 |---|---|
 | `useAgents(net, vocab, { view, decide, roles?, holdMs?, askWaitMs? })` | Every browser. On the host: sends each AI-held guide its view every 2 s, runs the floor for the rest (once a second), takes `agent:do` and AI lines, answers asks. |
-| `goalOf(slot)` | `{ goal, args, from: 'brain' \| 'floor', at, state, asked? }` or null (the game's own bot code drives). An AI's decision holds for `holdMs` (45 s) or until it is done; a goal that answered a person's ask (`asked`) is carried through until done (or 60 s), whatever a brain says. A brain's decision that does not answer an open ask leaves it open, and the floor answers it after `askWaitMs`. |
+| `goalOf(slot)` | `{ goal, args, from: 'brain' \| 'floor', at, state, asked? }` or null (the game's own bot code drives). An AI's decision holds for `holdMs` (45 s) or until it is done; a goal that answered a person's ask (`asked`) is carried through until done (or 60 s), whatever a brain says. A brain's decision that does not answer an open ask leaves it open, and the floor attempts it once after `askWaitMs`. That attempt closes the ask even if it declines, returns nothing, or throws. Ordinary browser helpers keep their one-second floor cadence, including after an accepted ask. The rules host sets `carryFloor: true` to carry an accepted ask through its scripted floor for 60 s or until done; that is the rules contract in section 29. |
 | `done(slot, ok?)` | The goal finished (or failed): the next view says so (a brain thinks again); a guide no AI holds decides at once. |
 | `ask(slot, k, args)`, `askButtons(slot, offer)`, `asksFor(slot)` | A person's ask (a button); the buttons to draw (one per value its argument may take); the asks made of a guide in the last 30 s. An ask of a held guide waits `askWaitMs` (4 s) for its brain, then the floor answers it. |
 | `on('say' \| 'goal' \| 'ask', fn)` | A guide's line (text from the vocabulary; never on a browser with Quiet AI on), a goal change (with `askAt`, the ask that led to it), an ask. |
@@ -1213,6 +1238,16 @@ agents.ask(slot, 'ask_help', { quest: 'king-slime' });     // a person's button
 A view adds `goal` (`{ goal, args, state }`) and `asks` itself. The brain also thinks again when
 the view's `zone` or `danger` changes.
 
+The helper compares both the goal and its arguments when answering an ask. A carried goal also
+blocks a brain from substituting other arguments to that same goal. Without a `decide` callback,
+the helper closes an ask on its next floor beat. A floor that declines an ask does not mark its
+standing goal as `asked`. These rules also apply to browser-hosted games.
+
+Reopening a verified agent pass resumes its existing seat and replaces the previous socket,
+in both browser-hosted and server-hosted rooms. After one replacement, the same stay can reopen
+at most once every four seconds and eight times a minute. Earlier retries receive `agent-pace` with `retryMs` and leave
+the current socket, body and goal intact.
+
 ### House guides and their brains
 
 On a beginner server whose AI may talk, with a vocabulary, a person seated and a host whose game
@@ -2014,3 +2049,213 @@ room.standing;   // { state: 'joining' | 'playing' | 'solo' | 'watching' | 'wait
   again on `leave` and at a round's rollover (`seatWaiting()`). Everyone: test
   `net.link === 'reconnecting'` for your own "Reconnecting…", read `net.full`, and say where the
   player stands with `net.line('…')`.
+
+## 29. The server as host (revision 10)
+
+Until revision 10 a room's host was always a player's browser. A game **written as rules plus
+view** moves its rules onto the server: what is true in the game (who took which coin, every score,
+when a round ends) is decided in the room's `Table` on the studio's own Cloudflare, and a browser
+sends what its player presses and draws what it is told. `@homie-rocks/studio/rules` is the format
+(`defineRules`, `defineMove`, `f`), `rules/host.ts` the runtime, and the starter `coin-dash` the
+example. This section is what the wire and the relay do for such a game. Everything else in this
+document (seats and tokens, chat, votes, watchers, the owner's controls, the arrival, the link)
+applies to it unchanged.
+
+**A game written the old way is not touched by any of this.** A game with no `src/rules.ts` builds
+and runs exactly as before, hosted by a player's browser, with the election, the yield and the
+checkpoint of sections 2 and 9. It cannot ask for the server: `"room": { "host": "server" }` on
+such a game fails the build with the reason. So does a ported game.
+
+### 29.1 Who is the host
+
+- game.json `"room": { "host": "server" }` (the default for a game that has a `src/rules.ts`). The
+  build checks the rules, guards them (section 29.5) and puts them into the studio's Worker
+  (`site/src/rules/`, imported by `site/src/worker.mjs` and handed over with `hostRules`).
+- When a room of such a game opens, its `Table` starts the host runtime **before the first socket
+  is attached**. The relay (`worker/room.mjs`) is told `setServerHost(runtime)`.
+- **The server host is not a client.** It is not in the room's clients and has no socket. The relay
+  calls it with parsed frames (`runtime.frame(m)`) and fans out each frame it hands back
+  (`room.hostFrame(m, text)`), once, already encoded. An empty room is therefore still empty.
+- **A browser never becomes host in such a room.** Every `welcome` says `role: 'replica'` (or
+  `'screen'`) and `host: { id: 'server', seat: null }`. Nobody is elected, nobody is deposed, no
+  `role` or `host` frame is sent, and `yield` does nothing. A `snap`, `state`, `round`, `roster`,
+  `caps` or `ckpt` frame from a client is dropped, as it is from any client that is not the host:
+  a changed browser cannot say what a host says.
+- Stall detection does not apply (there is no host socket to go quiet), and neither do `LIMITS` and
+  `RATES`, which were written for a host that is somebody's phone. A client's own frames are capped
+  as ever (`in`: 2 KB and 60 a second).
+- **If the rules cannot start** (this build of the site does not hold them, or they do not fit the
+  contract) the room refuses every hello with the final error `host-failed` and the reason in
+  `message`. It does not fall back to a browser by itself.
+
+### 29.2 Frames, for a rules game
+
+The frames are section 5's. For a rules game two of them carry different fields.
+
+| Frame or field | For a rules game |
+|---|---|
+| `in` (a seat to the host) | `e`, `k`, `s`, `r` |
+| `e` | The room epoch the sender has adopted (32 bits). A frame with another epoch is dropped |
+| `k` | The first room tick the frame covers (32 bits) |
+| `s` | One or more entries `[o, ...fields]`, at most 64. `o` is a tick offset from `k`, rising; the entry is stamped `k + o`. The fields are the kind's declared `input` fields in order, each a number (a `press` is 1 or 0). For an owner-moved body an entry also carries its claimed position, velocity and heading: nine numbers, `x y z` each |
+| `r` | The placement counter the sender has adopted (16 bits). A claim made with an older one is ignored |
+| `snap` (the host to everyone) | `from: null`, `e`, `k` (the tick just run), `st`, `d` (the packed state), `c` |
+| `d` | `[[round n, phase (1 live, 0 over), endsAt (a tick)], entities]`. An entity is `[id, kind, r, pos, vel, heading, grounded, fields, motion]`, and for a player's body `seat, driver (0 person, 1 bot, 2 ai), away, owner` after. `kind` is the kind's index in the rules, `fields` and `motion` its declared fields in order. A room and its players share one build, so the declarations are not on the wire |
+| `c` | One row a person's seat: `[seat, r, ack, lead]` |
+| `ack` | The stamp of the newest entry from that seat the server had when it ran tick `k`, among entries stamped `k` or earlier |
+| `lead` | How early that seat's frames arrived, in sixteenths of a tick, signed. For one frame: the time from its arrival to the moment tick `k` of that frame was due. The row carries the smallest value since the last snapshot. Negative is late. -128: no frame arrived |
+| `ev`, kind `fx` (the host to everyone) | `d: [tick, [[effect, at, data]…]]`: the effects the rules emitted on that tick. `effect` is its index in the rules' `shapes.effects`, `at` a position or an entity id, `data` its declared fields in order. Reliable, as every `ev` is; a view plays each when it draws that tick |
+| `ev`, kind `cmd` (a seat to the host) | `d: [command, data]`: a reliable one-shot request to the sender's own body, run on the next tick |
+| `state`, key `shared` (the host) | The rules' `shared` fields, in order, sent when they change |
+| `round`, `roster`, `caps` | As today. The roster's `slot` is the body's seat; a bot's `seat` is null. Results are read from the `score: true` field of every player's body, two ticks after a round's time is up; ties share a place |
+
+The optional final player field `goal` is null or `{ goal, args, from, at, asked }`, with `at` in ticks. Older snapshots without it read as null.
+
+The relay also sends two internal frames to its rules host; no client may send either:
+
+| Frame | Fields | Meaning |
+|---|---|---|
+| `vocabulary` | `vocab` | The build's validated `agents.json`, or null. Installed before joins. |
+| `decided` | `n, ok, by?, picks?, why?` | The answer to a host's `decide`. Only a matching pending request is settled, once, on a tick. Picks are validated against the declaration; `why` is a word of at most 32 characters. |
+
+A failed game-decision floor still settles once: `by: 'floor'`, `why: 'floor-error'`, and declared picks (false for yes/no, zero for score, the first declared choice). Its failure is counted once. Late replies are ignored. Reserved companions occupy the relay's top `aiSeats + guides` seats; guides take the highest seats. Plain practice bots and away people have no agent goal, floor or ask buttons. An AI's role comes from its admitted peer facts or the reservation policy.
+
+**One step a tick, on both sides.** A seat's input is a value that holds from one entry to the
+next. The step for tick `t` is the values of the newest entry stamped `t` or earlier, plus the
+presses of an entry stamped exactly `t`. A tick with no entry repeats the held values with every
+press cleared. What the server does with an entry stamped `j`, when the last tick it ran is `K`:
+
+| Case | Test | What happens |
+|---|---|---|
+| Other epoch | The frame's `e` is not the room's | The frame is dropped |
+| Duplicate | `j` is not above the newest stamp it has from that seat | Ignored. It still counts as the player being there |
+| On time, or early | `K < j`, and `j` is at most one second ahead | Kept, and applied on tick `j` |
+| Too early | `j` is more than one second ahead | This entry and the rest of the frame are dropped |
+| Late | `j <= K` | Its values hold from tick `K + 1`. Its presses fire on tick `K + 1` if that is at most a quarter of a second after `j`. Otherwise they are dropped. Nothing is applied in the past |
+| Missing | No entry for a tick | The held step |
+| Silence | No frame from the seat for one second | Its input is neutral until the next entry |
+
+The server runs one step for each body each tick, whatever arrives: more frames, or frames stamped
+ahead, buy no extra step. Every input value is held to its declared type.
+
+**What a browser sends** (`net.steps(e, k, entries, r)`; a view calls `room.input(sample)` and the
+view library does this). It steps on its own copy of the room's clock, a little ahead of the server,
+and holds that lead from `lead`. A step whose sample (or claim) changed, or that holds a press,
+makes an entry. A period with no entry sends nothing; after 250 ms without a frame the held values
+are sent again as an ordinary entry. A hidden tab sends one neutral entry and stops stepping.
+
+**In this release a person's body is owner-moved** (`body: { move: 'owner' }` in the rules): its
+browser runs the game's `move` code and claims a position, as `netplay.movement: 'owner'` does
+today, and the server holds each claim to the body's `maxSpeed` (a tick of it every tick, a quarter
+of a second banked at most). It does not stop a changed browser walking through a wall. Bots, and a
+body whose player is away, are moved by the server with the same `move` code. Scores, pickups,
+rounds and placements are the server's in either case.
+
+### 29.3 The life of a server-hosted room
+
+| Moment | What happens |
+|---|---|
+| The first person joins | The `Table` has made the relay room and the host runtime. The epoch is a fresh random number. `room.start` has run; the tick loop starts |
+| People are playing | A timer chain inside the object runs one tick at a time, each timed against the moment it is due. One snapshot a tick |
+| A player's socket closes | The seat is held 60 s (`holdMs`). The body stays and is `away`: its input is neutral, or its kind's `think` steers it |
+| The seat's hold runs out | The body is removed, or stays as a bot (`player: { leave: 'bot' }`) |
+| The last person's socket closes | **The room pauses.** The tick timer is cleared and the clock stops. Watchers and AI seats never keep it ticking |
+| A person returns within 60 s | The room resumes at the tick it paused on. No tick is skipped and none runs for the gap |
+| Nobody returns within 60 s | **The room ends.** The relay forgets it and its stored seats are deleted (`office` and `recorded` are kept). The next visitor gets a fresh room, with a new epoch |
+| A restart or a deploy | The whole room restores at its saved tick, under a new epoch. Seats keep their tokens. A deploy that changed the state shape ends the match instead (section 29.6) |
+| The rules fail again and again | Every tick failing for two seconds of the clock (a handler that used its whole share, or a fault in the runtime itself), or ticks that ran slow for five: the room ends, its players get the error `room-over`, and the log names the game, its build, the kind and the handler (`why`: `budget`, `fault`, `overrun`). Both are seconds on the clock, not a count of ticks |
+| Anything is thrown in a tick | It is caught where the tick began, written to the log as `host-fault` (game, build, tick, the part of the tick, at most once a second) and counted. The tick after it runs: a room that is running always has exactly one timer pending, and a room that is paused or ended has none |
+
+### 29.4 What the testing tools read
+
+A room with no browser host is a valid room. `window.__homieNet` and `window.__homiePort` are
+published by the view library with the same names a game written the old way publishes (own
+position, score, `busy`), so `check`, `shoot`, `perf` and the playtest judge read a rules game as
+they read today's; every browser's role is `replica`. The watch feed (`facts()`) says
+`hosted: 'server'` and carries the room's tick figures in `ticks`: the tick it is on, ticks run,
+late ticks, input frames and late entries, handler errors, budget stops, and the handler that used
+the most units. The relay's log has the same figures as one `ticks` line every ten seconds.
+
+### 29.5 What keeps a rules module inside its room
+
+The rules of a studio's own games run in the same isolate as its site, accounts and shop. The wall
+is made of language restrictions, checked and rewritten at build (`lib/rules-guard.mjs`), plus the
+fact that rules are handed a `world` object and nothing else. It is built against a careless module
+written by the studio's own AI; it is not a sandbox against code written to attack, and no rules
+from outside the studio run on its server.
+
+- **At build**, with the line named: globals, methods and syntax are allowlists (no `Date`, no
+  `Math.sin` or `**`, no `JSON`, `fetch`, timers, `class`, `this`, `try`, `async`, regular
+  expressions, `delete`, getters; no `constructor`, `prototype`, `__proto__`; no `==` or `!=` except
+  against `null`; no whole number of any size such as `10n`; no function under the name `valueOf`,
+  `toString` or `toJSON`); a rules module has no state of its own (no module-level `let` or `var`,
+  nothing module-level assigned to, nothing of the game's run at load); it imports only
+  `@homie-rocks/studio/rules` and the game's own files.
+- **Rewritten**: every loop and function counts a unit against the running handler's budget; every
+  computed key and method call goes through a guard that never reaches a prototype, a constructor
+  or a method read as a value; every value an operator would turn into a number or a text (an
+  operand of `-`, `<` or `+`, a part of a template, an argument of `Number`, `String` or `Math.max`)
+  is checked to be one already, so a list or an object there stops the handler instead of being
+  walked uncounted; a write to a property is checked not to land on a function, so nothing is kept
+  on one; text made by `+` or a template, a spread and the list methods are charged by their size,
+  and before they run; no list, text, `Map` or `Set` passes 65,536 entries.
+- **What comes back from rules is read as plain data.** What a handler returns, every argument of a
+  `world` call and everything written to a field, a list, `motion`, an event or an effect is read by
+  `typeof` and by its own data properties, inside the try that catches the handler and inside its
+  budget. The runtime never calls a `valueOf`, a `toString`, a getter or an iterator of the rules,
+  nothing in the reading can throw, and what is not a number, a text, true, false, a list or an
+  object of the declared shape becomes the zero of that shape. Stored state is frozen, so a query
+  (`world.near`) hands it out without copying it.
+- **At run time**: a handler that has used a quarter of `room.budget.tick` is stopped and abandoned,
+  as one that throws is. Rules cannot catch it, because rules cannot contain `try`. The default is
+  500,000 units a tick at 20 ticks a second or fewer, and 10,000,000 divided by the tick rate
+  above that. When a tick has used all of `budget.tick` it ends early: `move` has run for every
+  body (once the budget is gone with a small share each, and not at all once the tick has used half
+  its budget again), handlers not yet run are skipped, and
+  events not yet run stay queued in order. The tick pays first for the state it sends: 4 units for
+  every value in its snapshot.
+- **Bounds a game is written inside**: a room holds 2,048 entities, 16,384 events and timers
+  waiting, 64 area events a tick and 256 effects a tick; a declared field holds 16,384 values when
+  it is full and all the fields of one kind of entity 65,536 (a list of lists multiplies);
+  `world.sweep` reads the first 16 ids of `ignore`; a game's own answer to `world.ask` holds 256
+  values, four levels deep. `world.math` takes numbers and vectors of numbers.
+- The view's bundle holds the same guarded `move` code the server runs, and the rules'
+  declarations as data. It holds none of the rules' handlers.
+
+### 29.6 Saves, restarts and deploys
+
+The Table writes the whole room to its SQLite `save` table in one synchronous transaction:
+entities, motion, shared state, rounds, seats and their tokens, pending events, timers and
+inputs, RNG state, tick, epoch, state hash and build hash. Saves larger than 2 MB use several
+rows in that transaction. The default interval is `room.durability.movementSeconds: 1`;
+round end, `world.finish()` and pause save immediately. Both elapsed ticks and elapsed wall
+time bound the interval, including ticks that catch up after a delay. Cloudflare's output
+gate holds outgoing frames until preceding writes are confirmed.
+
+A restore starts paused at the saved tick. No ticks run for the outage. Its epoch is one
+more than the larger of the saved epoch and the separately stored `boots.epoch`; that epoch
+is stored before ticking. Clients reconnect with their seat tokens and jitter capped at two
+seconds. An unreconnected player's body is away when ticking resumes.
+
+| Deploy | Room | Page |
+|---|---|---|
+| This game's build hash is unchanged | Restore and resume | Reconnect without reloading |
+| Build changed, state hash unchanged | Restore under the new rules | Refuse the old build with `stale`, `immediate: true`; reload the game and reclaim the seat |
+| State hash changed | Delete the save and end the room | `room-over`, `rematch: true`; load a fresh game in another room |
+
+The state hash includes ordered declarations and handler names/presence, body/player settings,
+field options, shared state, shapes, bots, asks, map, dimensions, tick rate, rounds and contract.
+Handler implementations, tunables and view code do not change it. The build hash includes
+built rules, view, tunables and map, excluding build time, commit and other games. It replaces
+`netplay.version` for rules games. Browser-hosted games keep the existing version and checkpoint
+behaviour. An old standalone app must update before joining a rules game's live room.
+
+A restored run increments `boots.count` at its first tick and clears it after ten seconds of
+ticking. The second successive restored run waits a deterministic room-specific delay of up
+to thirty seconds. The third ends instead of restoring and logs `restore loop`, the game and
+build, and that another room sharing the isolate may have caused the resets.
+
+After sixty seconds paused without a returning person, the room ends even if watchers remain.
+Ending deletes `save`, `boots` and `net`, preserves `office` and `recorded`, and keeps an `ended`
+marker so a late reconnect cannot reopen that room. The Lobby forgets it. The stored alarm
+also cleans up a room whose object restarted with nobody returning.

package/netplay/netplay.ts

@@ -73,6 +73,13 @@
  *     with `net.prefs.number(key, fallback)`, never a `null` to multiply by), `net.params`
  *     (the address's switches the page passed in), `net.shell` (where the page's
  *     own buttons sit over the game), and `guardGestures()` for a touch game.
+ *   - Rules on the server (revision 10, NETPLAY.md section 29): a game written as
+ *     rules plus view has no browser host. `createNetplay({ rules: true })` is what
+ *     its view library (`@homie-rocks/studio/rules/view`) starts: this browser never
+ *     hosts, its input goes out as steps stamped with the room's tick
+ *     (`net.steps(e, k, entries, r)`), and each snapshot names the room's epoch
+ *     (`snapshot.e`) and carries one row a seat, `[seat, r, ack, lead]`. A game
+ *     written the old way uses none of it and runs exactly as before.
  *
  * 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.
@@ -81,9 +88,9 @@
 
 export const NETPLAY_VERSION = 1;
 /** The contract revision this helper speaks (NETPLAY.md): its hello says so (`rev`), and so does every build of it. */
-export const NETPLAY_REVISION = 9;
+export const NETPLAY_REVISION = 10;
 /** In every bundle that includes the helper: `homie-studio build` reads it to tell the office which revision a build speaks. */
-export const NETPLAY_MARK = 'homie-netplay-rev:9';
+export const NETPLAY_MARK = 'homie-netplay-rev:10';
 
 export type Role = 'host' | 'replica' | 'screen';
 export type Device = 'phone' | 'desk' | 'tv';
@@ -169,7 +176,7 @@ export interface LinkChange {
   downMs: number;
 }
 /** A newer build of the game is live (`on('stale')`): this tab still runs `mine`; `final`: it was kept out of a room for it. */
-export interface StaleNotice { ver: string | null; mine: string | null; final: boolean }
+export interface StaleNotice { ver: string | null; mine: string | null; final: boolean; immediate?: boolean }
 /** One of the play page's own controls drawn over the game, in CSS pixels of the game's own viewport. */
 export interface ShellRect {
   /** `room` (the room button), `server` (the server pill), `chip` (the "3 playing" line), `chat`, `join` (the big screen's QR card), `banner`, `results`. */
@@ -416,7 +423,13 @@ export interface Peer {
 
 /** One seat's entry in the body-control table: [seat, rs, own (1|0), ack]. */
 export type ControlWire = [seat: number, rs: number, own: number, ack: number];
-export interface Snapshot<D = unknown> { k: number; st: number; d: D; from?: number | null; c?: ControlWire[]; /** Revision 9: a heartbeat: the host's last state again, while its frames hitch. */ hb?: 1 }
+export interface Snapshot<D = unknown> {
+  k: number; st: number; d: D; from?: number | null; c?: ControlWire[]; /** Revision 9: a heartbeat: the host's last state again, while its frames hitch. */ hb?: 1;
+  /** Revision 10, a rules game: the room's epoch. Its `c` rows are `[seat, r, ack, lead]` (the placement counter, the newest input stamp the server had, and how early this seat's input arrived, in sixteenths of a tick; -128: none arrived). */
+  e?: number;
+}
+/** Revision 10: one input entry of a rules game, `[o, ...fields]`: a tick offset from the frame's first tick, then the kind's declared input fields in order (and, for an owner-moved body, its claimed position, velocity and heading: nine numbers). */
+export type StepEntry = number[];
 export interface Checkpoint<D = unknown> { k: number; st: number; d: D; c?: ControlWire[] }
 export interface InputFrame<A = unknown> {
   /** Sequence number per sender. */
@@ -568,6 +581,12 @@ export interface NetplayOptions<C = unknown> {
   watchKeys?: boolean;
   /** May this browser be elected host? Default true. */
   canHost?: boolean;
+  /**
+   * Revision 10: this game is written as rules plus view, and its room's host is the server (NETPLAY.md section 29).
+   * This browser is never elected host, sends its input with `net.steps`, and reads the control table as rows of
+   * `[seat, r, ack, lead]`. Set by the view library (`openRoom`), not by a game.
+   */
+  rules?: boolean;
   /** Game id, for the relay's logs. */
   game?: string;
   /** Seats in a room (the manifest's players.max). The relay takes it from the first visitor of an empty room. */
@@ -897,6 +916,12 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   input(a: A, held?: Iterable<string> | Record<string, boolean>): void;
   /** Player: an explicit press edge (for buttons you do not report as held). */
   press(id: string): void;
+  /**
+   * Revision 10, a rules game: one input frame. `e` is the room's epoch this browser has adopted, `k` the first room
+   * tick the frame covers, `entries` its steps (`[o, ...fields]`, offsets rising) and `r` the placement counter it has
+   * adopted. False when not sent (not seated, not connected). The view library calls it; a game calls `room.input`.
+   */
+  steps(e: number, k: number, entries: StepEntry[], r: number): boolean;
   /** Event. Host: to everyone, or to one seat (number) or one peer id (string, e.g. a screen). Others: to the host. */
   send(kind: string, data?: unknown, to?: number | string): void;
   /** Host: latest input frame from a seat (intents, buttons) whatever the body's control. */
@@ -1454,7 +1479,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   // A watcher (section 16) is a screen that never takes a seat, whatever else it is told.
   const watching = Boolean(opts.watch ?? cfg?.watch);
   const want: Want = watching ? 'screen' : (opts.want ?? cfg?.want ?? 'play');
-  const canHost = opts.canHost ?? true;
+  const rulesGame = opts.rules === true;
+  const canHost = rulesGame ? false : opts.canHost ?? true;
   const defaultOwn = (opts.movement ?? 'owner') === 'owner';
 
   // Where parent notifications go: the shell page around a framed game.
@@ -1767,14 +1793,14 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     emit('link', e);
   }
   /** A newer build is live (section 23): the relay's `stale` frame (still playing) or its `stale` refusal (kept out). */
-  function noteStale(ver: unknown, final: boolean): void {
+  function noteStale(ver: unknown, final: boolean, immediate = false): void {
     const next = cleanVersion(ver) ?? '';
     const first = staleVer === null;
     staleVer = next;
     if (!first && !final) return;
-    post?.({ what: 'stale', ver: next || null, mine: version, final });
+    post?.({ what: 'stale', ver: next || null, mine: version, final, ...(immediate ? { immediate: true } : {}) });
     if (!final) showOverlay('stale', inApp ? APP_STALE_LINE : 'A new version is ready. Tap to reload.', 10_000);
-    emit('stale', { ver: next || null, mine: version, final });
+    emit('stale', { ver: next || null, mine: version, final, ...(immediate ? { immediate: true } : {}) });
   }
 
   /* ------------------------------------------------------------ the page around the frame (revision 9, section 24) */
@@ -2266,7 +2292,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       }
       case 'stale': {
         // A newer build of the game is live (section 23): this tab keeps playing in its own room, and is told.
-        noteStale(m['ver'], false);
+        noteStale(m['ver'], false, m['immediate'] === true);
         return;
       }
       case 'watch': {
@@ -2301,6 +2327,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       }
       case 'error': {
         const code = String(m['code'] ?? '');
+        if (code === 'room-over' && m['rematch'] === true) {
+          closed = true; closedWhy = code;
+          post?.({ what: 'rematch', room: cfg?.room ?? null });
+          setLink('closed', code);
+          return;
+        }
         // Inputs over the relay's cap were dropped: send fewer for a while (the newest frame still goes out).
         if ((code === 'rate' && m['of'] === 'in') || code === 'flood') inSlowUntil = wall() + IN_SLOW_MS;
         // An AI alone in a room (nobody seated): it knocks again only after a while (section 17).
@@ -2309,7 +2341,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         if (code === 'rate' || code === 'state-full') { warnOnce(`${code}:${String(m['of'] ?? '')}`, m['message']); return; }
         // The room still runs another build of the game (section 23): not final. Its players were told to reload; this
         // browser keeps knocking and is let in when they have. Said once, not at every knock.
-        if (code === 'room-stale') { lastRefusal = code; warnOnce('room-stale', m['message']); if (link === 'alone') paintLink(); return; }
+        if (code === 'room-stale') { post?.({ what: 'wait', final: false }); lastRefusal = code; warnOnce('room-stale', m['message']); if (link === 'alone') paintLink(); return; }
         console.warn('[netplay] relay refused:', code, m['message']);
         // The same seat opened in another tab, a full room, a version the relay does not speak: reconnecting
         // would repeat the refusal (or, for 'replaced', make the two tabs evict each other for ever).
@@ -2318,7 +2350,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
           closedWhy = code;
           post?.({ what: 'closed', why: code, room: cfg?.room ?? null, ...(typeof m['until'] === 'number' ? { until: m['until'] } : {}), ...(typeof m['message'] === 'string' ? { message: String(m['message']).slice(0, 200) } : {}) });
           // Kept out of a room for running an older build (section 23): the page reloads the game; the game may too.
-          if (code === 'stale') noteStale(m['ver'], true);
+          if (code === 'stale') noteStale(m['ver'], true, m['immediate'] === true);
           setLink('closed', code);
         }
         return;
@@ -2335,6 +2367,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   }
 
   function onWelcome(m: Record<string, unknown>): void {
+    post?.({ what: 'build', ver: version });
     clearTimeout(connectTimer);
     const next = m['role'] as Role;
     const wasOffline = offline;
@@ -2453,6 +2486,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       rebase = false;
       lastArrival = 0;
     }
+    if (rulesGame && buf.length && buf[buf.length - 1].e !== s.e) { buf.length = 0; ages.length = 0; lastArrival = 0; }
     const newest = buf[buf.length - 1];
     if (newest && s.st <= newest.st) return false;
     const arrival = wall();
@@ -2498,7 +2532,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
 
   /** Seated replica: read my entry of the control table in the newest snapshot. */
   function controlFrom(s: Snapshot<S>): void {
-    if (seat === null || role === 'host' || !Array.isArray(s.c)) return;
+    // A rules game's rows are [seat, r, ack, lead], read by the view library from the snapshot itself.
+    if (seat === null || role === 'host' || rulesGame || !Array.isArray(s.c)) return;
     const e = s.c.find((x) => x[0] === seat);
     if (!e) return;
     const [, rs, own, ack] = e;
@@ -2516,6 +2551,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     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 (m['hb'] === 1) s.hb = 1;
+    if (typeof m['e'] === 'number') s.e = m['e'];
     if (acceptSnap(s, bytes, true)) { emit('snapshot', s); if (!snapSeen) { snapSeen = true; autoPlayable(); } }
   }
 
@@ -2769,7 +2805,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (closed) return;
     // A hidden tab does not play and its timers crawl: reconnect when it is looked at again.
     if (hidden()) { waitingVisible = true; return; }
-    const wait = Math.max(LADDER[Math.min(attempt, LADDER.length - 1)] as number, aloneUntil - wall());
+    const wait = Math.max(rulesGame ? (attempt < 3 ? Math.random() * Math.min(2000, 500 * 2 ** attempt) : (0.5 + Math.random() * 0.5) * Math.min(60_000, 2000 * 2 ** Math.min(attempt - 2, 5))) : LADDER[Math.min(attempt, LADDER.length - 1)] as number, aloneUntil - wall());
     attempt += 1;
     reconnects += 1;
     setTimeout(open, wait);
@@ -3137,6 +3173,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       if (role === 'host' || seat === null || offline || !connected) { pendingPresses = {}; return; }
       scheduleInput(edge);
     },
+    steps(e, k, entries, r) {
+      if (role === 'host' || seat === null || offline || !connected || !entries.length) return false;
+      if (!raw({ t: 'in', e, k, s: entries, r })) return false;
+      inputOut.hit(wall());
+      return true;
+    },
     press(idp) {
       if (role === 'host' || seat === null || offline || !connected) return;
       pendingPresses[idp] = (pendingPresses[idp] ?? 0) + 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.32.0",
+  "version": "0.33.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",
@@ -58,6 +58,22 @@
       "types": "./port/powerups.ts",
       "default": "./port/powerups.ts"
     },
+    "./rules": {
+      "types": "./rules/rules.ts",
+      "default": "./rules/rules.ts"
+    },
+    "./rules/view": {
+      "types": "./rules/view.ts",
+      "default": "./rules/view.ts"
+    },
+    "./rules/guard": {
+      "types": "./rules/guard.ts",
+      "default": "./rules/guard.ts"
+    },
+    "./rules/host": {
+      "types": "./rules/host.ts",
+      "default": "./rules/host.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -66,6 +82,7 @@
     "lib/",
     "netplay/",
     "port/",
+    "rules/",
     "worker/",
     "mcp/",
     "saves/",
@@ -89,9 +106,14 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.131.0",
+    "@babel/generator": "8.0.6",
+    "@babel/parser": "8.0.7",
+    "@babel/traverse": "8.0.7",
+    "@babel/types": "8.0.6",
     "@gltf-transform/core": "4.5.1",
     "@gltf-transform/extensions": "4.5.1",
     "@gltf-transform/functions": "4.5.1",
+    "@jridgewell/trace-mapping": "0.3.31",
     "esbuild": "0.28.1",
     "gltf-validator": "2.0.0-dev.3.10",
     "meshoptimizer": "1.3.0",