@homie-rocks/studio 0.46.0 → 0.46.3

package/CHANGELOG.md

@@ -17,6 +17,111 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.46.3] - 2026-10-11
+
+**Plugin 0.46.3**
+
+A guest who signs in keeps both histories; a rival's sounds reach the players who can hear them; a shooter's own
+actions answer at once; a tap moves as far as it was held; a client cannot stretch its own lag compensation.
+
+### Added
+
+Every item here is opt-in: a game that declares none of them plays, costs and saves exactly as on 0.46.2.
+
+- `mergeSaves({ '<game>': { saves: { '<key or prefix*>': rule }, stats: { … } } })` from
+  `@homie-rocks/studio/worker`: how a guest's saves combine with an account's when the guest signs in to an account
+  that already has the same key. Rules: `'account'`, `'guest'`, `'newer'`, `'larger'`, `'smaller'`, `'sum'`,
+  `'union'` (a list joined by id), or the game's own function, run on the server. It happens once, in the sign-in's
+  own transaction, guarded against a room writing a result at the same moment. The sign-in response says what
+  was merged, moved and kept (`adopted`), and a key no rule could combine reaches the game's `onConflict` with the
+  guest's value (saves/SAVES.md, "When a guest signs in to their account").
+- Effects with an audience: `world.emit(effect, at, data, { within: metres, to: id | [ids] })` sends an effect only
+  to the players whose own body is in range or who are named; a watcher receives the ones with a range. For a sound a rival
+  could hear or a number only the shooter may see, in place of drawing it from state the rival should not have.
+  An effect with no audience is public and is sent as before.
+- `f.held()`, an input type: the browser sends the average of the control over each tick, so a key held for part
+  of a tick moves the body for that part. Short taps no longer travel a whole tick or two by where the tick's
+  edges fell. An entry that reaches the server after its tick is settled on the next ticks, not counted twice.
+- `openRoom({ predict: { <kind>(me, input, ctx) { … } } })`: the player's own actions predicted like their own
+  movement (run each predicted tick and between ticks, put right by every snapshot and re-run). `ctx.ghost` shows a
+  provisional entity and `ctx.effect` a provisional effect that the server's own then confirms (`confirms: true`)
+  or the room retracts (`room.on('retract', …)`). A valued pulse (`f.pulse()`) now names the tick it was pressed
+  on and the server acts on it in that tick; the control row says the newest pulse acted on, so a prediction
+  holds when the pulse's own message is late (as it can be through a Gate).
+- `world.unitsLeft`: the budget units the running handler may still spend, so a handler that plans can stop early.
+- `room.rewindSeconds` in rules: the game's hard cap on how far a person's ray is rewound for latency (from 0 to
+  `historySeconds`). Without it the cap is `historySeconds`, as before; `0.25` is a sensible value for a shooter.
+
+### Fixed
+
+Each of these changes what happened before; none needs a change to a game.
+
+- A guest with verified results who signed in to an account that also had some kept only the account's: the
+  guest's `server:` record was dropped, and nothing could combine the two afterwards because a browser cannot
+  write a `server:` key. Two server records are now joined by id when the guest signs in, with no rule declared.
+- A result a room wrote for the guest a moment after they signed in was written under a player that no longer
+  existed. It now follows the guest to the account (`appendServerRecord`, at the same one read and one write).
+- Lag compensation could be stretched by a client: the round trip was timed on a separate answer the client could
+  hold back, and only the smallest value ever seen was kept. It is now timed on the input frames themselves (each
+  names the newest snapshot its browser had), as a low percentile over the last ten seconds, and the allowance
+  counts the whole ticks an input waited after it arrived instead of a fixed one. A client still cannot look
+  faster than it is; one that pretends to be slower is bounded by `room.rewindSeconds`.
+
+### Upgrade notes
+
+- Nothing to do for a studio that declares none of the above. To use `mergeSaves`, add it to
+  `site/src/worker.mjs` beside `hostRules`.
+- A page from before this version that is still open against the new Worker is timed the old way until it
+  reloads. Its rewind is bounded by the same cap.
+- All of the above works the same through Gates (a room of more than 64 seats) as in a small room; each has a
+  seeded test both ways. Through a Gate a held input that misses its tick can be drawn a few centimetres short for
+  a tick or two before it settles.
+- Version 0.46.3 is provisional. No deploy or merge is part of this PR.
+
+## [0.46.2] - 2026-10-11
+
+**Plugin 0.46.2** · Big rooms: the room runs the rules, its Gates do the rest.
+
+A room of hundreds has a new shape, a deploy the owner asked for is approved by the asking, and Homie paces no input of a server-hosted game.
+
+Measured on Cloudflare with a game where every player sees about 180 others: 300 players at 20 frames a second from a home connection; 600 at 20 frames a second measured from inside Cloudflare, marginal from one home connection carrying all 600; 1,000 are admitted and the room keeps its ticks, but delivery is not there yet. On the same game 0.45.0 delivered 13 frames a second at 300 and lost every player at 1,000.
+
+### Added
+
+- `room.rates` in game.json: a studio's own pace on what one player may send, in messages a second by kind (`{ "in": 60 }`). Leave it out and there is none.
+- `lib/crowd-probe/`: a Worker of its own that plays simulated players against a studio from inside Cloudflare, five a request, and `lib/crowd-cloud.mjs`, which adds the requests up into the report the home driver writes. A trial's tool: no studio's Worker imports it.
+- Each Gate measures the room's clock against its own, the room's ticks a second by its own clock, and the longest it went without a world. The room's own count of its ticks cannot see the room run late.
+- A big room's diagnostics come from an object that is neither the room nor a Gate with players. The room and each Gate post a second's facts to it (ticks a second, how long a player's input took to reach the rules, frames written to each player, how old the world was when a Gate sent it, how far behind players say they are), and `/_studio/api/room` answers from that copy with its age. Measuring a room costs it nothing, and a room too busy to answer still has its last word read.
+- A player's client says which tick it holds (`g` on its inputs and pings). A Gate that finds a player more than a second behind sends that player fewer, fresher frames, down to one a second, and restores the rate when they have caught up. Each frame is a change from the last one sent and carries the player's own body. A client that says nothing is sent every tick, as before.
+
+### Changed
+
+- In a room behind Gates the room object runs the rules and hands each Gate one world a tick. The Gate chooses what each of its players can see, encodes it and writes it. The room no longer selects, encodes or queues anything per player on its tick.
+- A Gate holds fifty players and Gates fill in order: the room tells the door which Gate has room, so fifty players in a 1,000-seat game are one Gate and a full room is twenty. A studio sets its room's size and nothing else. A room of 64 or fewer is still its Table alone.
+- The world crosses from the room to a Gate as one block of numbers, the same block for every Gate, plus whatever else about a body changed since that Gate last heard: about 33 KB a tick for 1,000 players where the JSON was 150 KB, and almost nothing for the Gate to parse.
+- A body that keeps its course is not sent again. A client built with 0.46.2 moves it along its last velocity, and a Gate sends it only when that has drifted past the game's `view.precisionM` (near bodies) or half the distance it covers between `view.farHz` refreshes (far ones). On the crowd-circuit game at 1,000 players a frame falls from 71 rows to 20, a player from 14.8 KB a second on the wire to 6.3, and a far body is drawn 3 cm from the truth on average where it was 35 cm. A game page built before 0.46.2 is sent every moving body, as before.
+- A Gate works out once for each world what does not depend on the player. Encoding a player's frame takes under a third of the time.
+- Each Gate has its own channel to the room. The relay between them (the Concentrator) is gone: it re-read and re-sent every world for eight Gates and was the first object to fall behind. A studio's `CONCENTRATOR` binding stays declared and unused, so an upgrade needs no migration.
+- A Gate sends the room what its players sent at once when the channel is quiet and never more than one frame in 50 ms, however many players it holds. Receipts ride that frame.
+- Far-view refreshes are spread across players, so a room's largest updates do not all leave on the same tick.
+- A deploy requested in the owner's prompt is approved for that task, including retries. Unrequested deployments remain held; explicit refusals revoke the task approval.
+- The crowd probe offers WebSocket compression, as every browser does, coasts, names the tick it holds, follows the room's word on how early its inputs arrive (as the toolkit's client does), and reports whether the server agreed to compress, what that saved, and the kilobytes a second a player cost.
+
+### Fixed
+
+- Homie no longer paces what a player sends a game whose rules run on the server. 0.45.3 dropped honest input at 60 a second when a slow network delivered a batch late. What players say to each other keeps its pace, and so does every room a player's own browser hosts.
+- A game with fields only their owner may see keeps each player's view in the room when the room is behind Gates. A Gate was handed the whole state.
+- Late callbacks that catch up at the requested tick rate no longer end a healthy room as an overrun; sustained slow ticks still stop.
+- Relay failures log their layer, close cause and queue counters. A link's receipt latency measures the link, not the cadence a receipt waited for. Frozen Cloudflare clocks are not reported as zero execution time.
+- Deployment summaries no longer assume Workers Free. A big room's estimate counts its Gates and its diagnostics object and says which request traffic it leaves out.
+
+### Upgrade notes
+
+- Rebuild and deploy a studio to get the new room shape; a game needs no change. A game page built before 0.46.2 still plays in a big room: it is sent every tick and every moving body, because it says neither which tick it holds nor that it coasts.
+- A room of 64 seats or fewer, and every room a player's browser hosts, is as it was: none of this is on its path. The one change that reaches a small server-hosted room is that Homie no longer paces what a player sends it.
+- To measure your own game on your own Cloudflare account: `lib/crowd-load.mjs` plays a crowd from your computer and `lib/crowd-probe/` from inside Cloudflare. `lib/crowd-probe/README.md` has the commands and how to delete the probe afterwards.
+- What four trials on Cloudflare measured, what is proven and what is not, is in `docs/crowd-transport-0462.md`.
+
 ## [0.46.0] - 2026-10-10
 
 **Plugin 0.46.0**

package/README.md

@@ -206,8 +206,9 @@ game its studio chooses to share, each with its own licence ("Game parts", below
 
 `players.max` in game.json is the room's chosen positive integer capacity; omitted means 8.
 There is no 32-player ceiling or default per-address admission limit. Public games use
-rules plus view with `room.host: "server"`. Gates carry the browser connections and
-concentrators combine Gate links for larger rooms. Server rules survive browser departures.
+rules plus view with `room.host: "server"`. Gates carry the browser connections, each on
+its own channel to the room: the room runs the rules and hands every Gate one world a tick;
+the Gate selects, encodes and paces each player's view. Server rules survive browser departures.
 New browser/offline games use the same rules contract. Existing netplay games and their
 port host helpers remain supported for upgrades, with their original 32-seat limit.
 For larger rooms, follow `guides/game/REWRITE.md`.

package/docs/rooms-milestone-2-notes.md

@@ -0,0 +1,345 @@
+# Rooms milestone 2: releasable slices
+
+The opening sections preserve the released slice-1 record. The 0.45.0 slice-2
+implementation, local measurements and remaining work follow below.
+
+0.44.0 is slice 1, **spatial state delivery**. It is useful independently in an
+existing server-hosted room: the studio chooses `room.view.radiusM` in game.json,
+and a player's view receives nearby entities and its own body. Unchanged state
+is compressed as deltas. No change to rules or movement is needed. `room.each`,
+`enter` and `leave` describe the visible set, so a view must dispose of departed
+meshes and recreate returning ones. Leaving view does not mean despawning.
+
+This first PR does not claim that the public join/build path admits hundreds.
+That path retains milestone 1's 32-seat restriction until slice 2 supplies Gates
+and removes it. The simulation and relay now handle a 300-seat test directly,
+without a simulation seat clamp or truncated rosters/control rows. This is the
+foundation for the next slice, not a substitute for its admission and transport
+proof. No deployment or merge was made.
+
+## What ships first
+
+- `room.view.radiusM`: a studio-selected radius in metres, including z in 3D.
+  Omitted or null means the whole room, with the existing small-room path and
+  no extra per-client encoding. Zero means only colocated entities. No default
+  radius, downstream budget, spend limit, or crowd admission policy is imposed.
+- The real relay filters both ongoing snapshots and join/rejoin welcome state.
+  A player with no body yet sees no entities. Watchers retain the whole-room
+  overview in this slice; following a camera does not restrict their feed.
+- Each connection retains one keyframe. Deltas carry changed entity components,
+  new entities and explicit removals, against that keyframe. They carry the
+  current round and only the receiving player's input acknowledgment/control row.
+- A keyframe at least once per simulation second, and a fresh one at every
+  connection or epoch change. Backpressure skips snapshots without advancing the
+  encoder. A missing intermediate delta cannot corrupt later updates. A lost
+  keyframe causes deltas to be ignored until the next keyframe, at most one
+  simulation second later. WebSocket itself is ordered and reliable.
+- Saving and host recovery still use complete authoritative state. Filtering
+  never changes simulation, collision, queries, scoreboards or shared state.
+- Seeded, virtual-time correctness in `npm test`; the long 300-client run is in
+  `test:rules:extended`. The pre-existing 12-scenario real-time traffic matrix and
+  27 handover repetitions move there too, with all assertions retained. The gate
+  keeps two actual-browser cases (tab hiding and socket closing); virtual time
+  covers the rate/seed/handover matrix. No wall-clock throughput threshold is a
+  release gate.
+
+Interest is a bandwidth feature, **not hidden information**. Shared state,
+effects, roster and watcher overview are still public. Private fields and tells
+arrive together in slice 3. Browser hosting continues to send complete state;
+requesting a radius there produces a build diagnostic. The existing starters
+need no contract rewrite for slice 1 and keep their whole-room views.
+
+## Design decisions and departures
+
+The roadmap's sections 5, 6, 7, 10 and 23 are the starting point. Milestone 1
+already separates the host, core, transport-free relay and view. We reuse those
+roles instead of first splitting Table into new abstractions or declaring empty
+Durable Object classes. Gate and concentrator classes arrive together in slice 2,
+when they can actually carry connections and their deploy can be tested.
+
+Interest/deltas precede Gates: doing this work in the existing relay gives a
+shippable feature and a measurable role to move. The codec is independent of
+Cloudflare and does not introduce a second runtime or contract profile. A small
+game continues to see the match contract without `uses` or `profile` boilerplate.
+
+Deltas name periodic keyframes rather than retaining an acknowledged history
+per player. One baseline bounds memory, intermediates may be skipped safely, and
+reconnect always starts fresh. This trades retransmitted changes and up to one
+simulation second of recovery after a lost keyframe for a much smaller protocol.
+It is not the roadmap's final bandwidth scheduler; near/far tiers, priorities,
+short IDs, watcher follow feeds and shared far encodings remain slice 3 work.
+
+The roadmap's default 96-metre visibility radius, default crowd cap from S6,
+per-client bandwidth budget and guest-address cap are not defaults we will
+adopt. They contradict the owner's no-imposed-limits rule. Studios may choose
+limits explicitly. Cloudflare limits and measured capacity are reported as
+information, never turned into a Homie admission ceiling.
+
+## Local proof
+
+The workload uses the checked and guarded rules loader, real host runtime and
+NetRoom relay, with 300 simulated WebSocket clients, one actual player body per
+seat, 20 Hz seeded inputs, a 20-by-15 grid at four-metre spacing and a chosen
+12-metre radius. Each player moves at up to 2 m/s and increments a field each
+tick. All 300 input acknowledgments, own bodies and roster entries are checked;
+there are no rules errors or cut ticks. The fixture explicitly chooses a
+5,000,000-unit tick budget; this is not a new default or a general game capacity
+claim. Warmup is 20 ticks. Clients keep one baseline and latest state, not a log
+of every received frame.
+
+Measurement includes input dispatch, rules, encoding, serialization and all 300
+clients parsing and decoding in the same Node process. Memory is peak sampled
+whole-process heap/RSS, including the harness and rules loader, not isolated
+server memory. Bytes count all downstream frames during the measurement window,
+including snapshot JSON and pings; WebSocket/TLS framing is not included. These
+are **local numbers, not Cloudflare measurements**, not Internet latency, and
+not a rendering or physical-phone capacity result.
+
+Measurement command:
+
+```sh
+node --input-type=module -e 'import {interestWorkload} from "./packages/studio/test/rules-interest-workload.mjs"; console.log(JSON.stringify(await interestWorkload({ticks:1200,measure:true}),null,2))'
+```
+
+Observed on macOS arm64, Node 22.23.3, 1,200 measured ticks (60 seconds of
+virtual play), plus 20 warmup ticks. Other local verification was running; CPU
+timings are observations, not a throughput guarantee.
+
+| Measurement | Local result |
+| --- | ---: |
+| Clients / tick rate | 300 / 20 Hz |
+| Peak visible bodies for one client | 33 |
+| Tick including relay and all client decoding, p50 / p95 / p99 | 14.88 / 21.04 / 25.41 ms |
+| Largest measured tick | 31.98 ms |
+| Downstream per player, mean / highest | 23,171 / 29,117 bytes/s |
+| Peak sampled whole-process heap / RSS | 133,426,952 / 238,764,032 bytes |
+
+This does **not** meet the roadmap's eventual 16 KB/s target. Tiers, priority and
+shared encodings in slice 3 have work to do; no target was weakened or represented
+as passed. All 300 clients are simulated, not 300 browser tabs or Cloudflare
+connections.
+
+## Release verification
+
+- Focused codec, relay and rules tests: 20 passed, no skips.
+- Real view client on virtual time: 189 passed, including the new spatial
+  delivery/lost-keyframe/reconnect case. Existing Chrome rendering smoke tests
+  run in the root gate; this slice adds no rendering-specific browser case.
+- Plugin: 123 passed, one optional live-URL fixture skipped.
+- Plugin validation, packed Desktop server and release preflight passed;
+  preflight lists studio 0.44.0 as the sole new npm version.
+- Template and history generation, changelog sync/check completed.
+- Root `npm test` runs with `CHROME_PATH` pointing to local Chrome. Final root
+  results and all six CI checks are tracked on [PR #83](https://github.com/homie-rocks/homie/pull/83).
+- A same-role reconnect now delivers its welcome snapshot to the rules view,
+  even though no role-change event fires. The regression blocks later periodic
+  keyframes and verifies that welcome-based deltas advance the view immediately.
+
+## Remaining slices, in order
+
+Each is a separate releasable commit series/PR after its predecessor is released.
+Slices 1 and 2 are implemented. Slice 1 shipped in 0.44.0; this PR prepares
+slice 2 as 0.45.0 on the released 0.44.1 base.
+
+1. **0.44.0 — spatial state delivery**, above. Proof: codec oracle, real views
+   on virtual time, loss/reconnect, and 300-client host/relay workload.
+2. **0.45.0 — Gates and bigger public rooms (implemented below).** Gate/concentrator classes together,
+   reuse the delivery role, batch input and preserve commands, authenticated binding-only admission,
+   resume/revocation, and automatic layout from `players.max`. Remove public seat
+   caps, make guest policy studio-selected, report tested size in build/deploy
+   plans. Prove 300 clients through the actual join path, Gate restart/resend,
+   20 Gates through concentrators, and small rooms without extra objects. Preserve
+   existing netplay builds, checks, deploys and host/port helpers at their original
+   32-seat limit. New games, starters and authoring guides use rules plus view,
+   including browser/offline mode.
+3. **Private and scheduled delivery.** Field `see`, reliable one-player `tell`,
+   optional studio-chosen downstream budget and priorities (near/far visual
+   scheduling shipped in slice 2),
+   watcher follow/region and overview feeds, crowd rendering guidance/helpers.
+   Update starters where these capabilities apply. Prove no owner/server field
+   reaches another player's bytes, tells survive reconnect once, boundary
+   enter/leave and fairness under a chosen budget; measure a dense crowd and
+   rendering in real browsers. A view leaving interest is not evidence of privacy.
+4. **Crowd policies and vehicles.** Studio-selected `crowd.cap` with queue/hold,
+   soft event work scheduling without dropping work, `uses`, solid bodies,
+   attach/control/detach and driver prediction. Prove cap absent means no imposed
+   cap; explicit queues/holds release correctly; four-person vehicle prediction,
+   seat contention, disconnect and restore. Ship one vehicle example and update
+   the skill in the same slice.
+5. **Large worlds' files.** Extend existing studio-owned R2 asset serving to game
+   files over 25 MiB and multipart upload; streamed map chunks, zones, compiled
+   triangle meshes and navigation. Reuse the existing upload/build machinery.
+   Prove large asset integrity, interrupted/resumed multipart upload and map
+   streaming with the same collision data on server and client.
+6. **Milestone proofs and authoring tools.** Single-machine swarm CLI, match kit,
+   cross-browser-engine movement hashing, S6 at 20/60 Hz and multiple regions,
+   S11 transport assessment, dense crowd tuning and remaining authoring trials.
+   Local correctness stays seeded/virtual; long runs stay extended. The roadmap's
+   300-bot, 30-minute Cloudflare exit test, Gate recovery latency, physical phone
+   rendering and actual billing need a separately authorized deployment/device
+   session. No local receipt here is represented as those results.
+
+## Slice 2 (0.45.0): public rooms in the hundreds
+
+Implemented:
+
+- `players.max` is the single build size, read by public admission, compilation
+  and deploy planning without the 32-seat clamp. Shared carrier addresses have
+  no automatic player ceiling.
+- Gate and Concentrator classes carry ordered, batched logical connections over
+  binding-only links. Public authentication remains in the Worker. Small rooms
+  embed the delivery role in the Table; larger layouts use one logical Gate per
+  64 seats and concentrators above eight Gates. These are routing partitions,
+  not admission limits. The template generates both bindings and migrations.
+- Link loss closes downstream sockets for normal token-based seat resumption.
+  Gates do not persist simulation or become a second authority. Gate passes are
+  internal binding requests, not independently client-supplied authorizations.
+- Ordered snapshot deltas, shared spatial indexing and cached wire rows reduce
+  repeated work. Optional `precisionM`, `nearM`, and `farHz` schedule remote
+  visual state; controlled bodies remain exact and independently recoverable in
+  every frame. A lost remote delta cannot stall the local body or collider
+  revisions. Snapshot exits remain immediate.
+- Revision 12 carries roster patches after a full welcome roster. A reconnect
+  storm previously repeated full rosters to every player. The patch baseline is
+  the last transmitted roster, separately from policy relabelling.
+
+A 300-player manifest (the game still needs appropriate arena,
+spawning, rule cost and rendering):
+
+```json
+{
+  "players": { "min": 1, "max": 300 },
+  "room": {
+    "host": "server",
+    "view": { "radiusM": 12, "precisionM": 0.01, "nearM": 4, "farHz": 5 }
+  }
+}
+```
+
+The visual settings are examples, not imposed defaults or information privacy.
+The workload explicitly chooses a 5,000,000-unit tick budget as in slice 1.
+
+### Local measurements
+
+All results below are **local**, not Cloudflare, billing, Internet latency or
+physical-phone results. Bytes exclude WebSocket/TLS framing. Heap/RSS include
+clients and the test harness in the same Node process. Other work on this
+machine affects CPU timing; bytes are deterministic for the virtual workload.
+
+| Workload | Players | Mean bytes/player/s | Tick p50 / p95 ms | Peak heap / RSS bytes |
+| --- | ---: | ---: | ---: | ---: |
+| Unmodified 0.44.0, 1,200 virtual ticks | 300 | 23,171 | 12.23 / 16.72 | 134,431,008 / 238,534,656 |
+| Final scheduled/delta delivery, 1,200 virtual ticks | 300 | 9,937 | 10.57 / 15.59 | 129,070,360 / 232,275,968 |
+| Final scheduled/delta delivery, 120 virtual ticks | 1,000 | 10,258 | 33.88 / 52.12 | 190,297,048 / 328,974,336 |
+| Gate links, 4 Chrome pages, reconnect churn and host restore, before roster patches | 300 | 88,444 | 15.79 / 73.47 | 142,211,400 / 375,734,272 |
+| Same mixed transport workload, with roster patches | 300 | 13,623 | 13.52 / 25.33 | 154,397,384 / 274,808,832 |
+
+Steady-state downstream falls about **57%** at 300. The two preliminary mixed
+runs include recovery traffic and measured a host wake (potentially several
+ticks); they are not directly comparable to the steady-state pair or the final
+single-tick measurements below. They did not declare rounds. The final harness
+declares a ten-minute round and verifies that failures preserve it.
+
+The mixed harness uses the real Gate/Concentrator classes, rules loader,
+host and NetRoom, external local WebSockets and four Chrome pages rendering
+received bodies, with in-memory links standing in for Durable Object bindings.
+Actual public Worker routing and workerd eviction are checked separately below.
+
+Commands:
+
+```sh
+node packages/studio/test/rules-crowd-local.mjs 300 60
+node packages/studio/test/rules-crowd-local.mjs 1000 60
+node --test packages/studio/test/rules-gates.test.mjs packages/studio/test/rules-interest.test.mjs
+```
+
+The sustained, real-time 300/1,000 mixed runs live in `test:rules:extended`,
+which runs files sequentially so load experiments do not compete with each other.
+Virtual-time tests cover batching/order, 1,000 logical admissions, link cleanup,
+spatial boundaries, quantisation, far scheduling and keyframe recovery.
+
+### Admission, compatibility and recovery proofs
+
+Existing browser-hosted netplay games retain the build and runtime path from
+0.44.1, including host helpers, HUD and port import. Their manifest precedence
+and 32-seat limit remain; larger requests print the limit and rewrite guide.
+The generated Worker supplies Gate/Concentrator exports for pre-Gate studio
+entries without rewriting custom Worker source. The release gate uses unchanged Ember Vale files from released 0.32.1, packs and
+installs the current package, builds it and runs the real two-browser check
+through a completed round. Starters/docs teach rules plus view only.
+Migrating the rules fixtures exposed missing TypeScript resolution for shared parts;
+the guarded checker now resolves those same declared parts as the bundler.
+
+The public Worker test verifies its actual authorization and capacity selection
+for 300 and 1,000 against Gate bindings, including a private-door refusal and
+ignoring caller-supplied capacity/hosting. Real local workerd tests additionally
+prove 20 Gate binding links through concentrators and a Gate abort, and the full
+public Worker → Gate → Table/SQLite route: 40 seats in a declared 300-player room,
+then Gate death and Table death, with every token resuming its original seat.
+The extended Workerd case also passed all **1,000 actual public admissions**
+across 16 Gates/two concentrators, then a Gate abort (59 returning clients) and
+a Table abort (all 1,000 returning clients), retaining every seat. That fixture
+runs at 1 Hz and is a storage/admission proof, not a 20 Hz capacity benchmark.
+These are functional proofs; the measured full crowds below use in-memory
+internal binding links as described above, not a Cloudflare deployment.
+
+Both declared-round mixed receipts now pass:
+
+| Local mixed run | Bytes/player/s, all measured traffic | Tick p50 / p95 / max ms | Peak Node heap / RSS bytes | Churn |
+| --- | ---: | ---: | ---: | ---: |
+| 300 players, 4 Chrome pages, 62.93 s | 10,463 | 10.21 / 31.54 / 142.32 | 206,609,760 / 313,114,624 | 15 |
+| 1,000 players, 4 Chrome pages, 101.02 s | 9,203 | 32.97 / 59.29 / 188.74 | 314,542,056 / 573,784,064 | 50 |
+
+Each run recovered all players after both failures within the same live round;
+simulated clients retained their seats, and all four real pages delivered live
+snapshot receipts after recovery. The final runs also verify each simulated and
+real client's own body after recovery. The 300 run's initial steady 20-second window
+was 9,274 bytes/player/s; the 1,000 run measured 7,931 over its first 20.19 seconds.
+Recovery-window averages include disconnected intervals,
+so the seeded virtual comparison above is the fair before/after bandwidth pair.
+Mixed tick timing is now one host tick through snapshot enqueue; earlier mixed
+numbers measured a host wake, potentially several ticks. Browser process memory
+is excluded from Node heap/RSS. The 300 run averaged 19.05 simulation ticks/s
+including failures; the 1,000 run averaged 16.27. CPU timings vary with other
+machine activity; 1,000 p95 exceeds a
+50-ms tick period, so this is not a claim of guaranteed 20 Hz on Cloudflare.
+
+The earlier failed 1,000 run is superseded. Fixes isolated a single failed
+client send from its entire Gate, compacted identical fanout rows on internal
+links, and made the restart harness reconstruct both saved relay seats and the
+host (as a Table restart does) instead of rejoining every old connection just
+before disconnecting it. Final root and six-check CI results are tracked in
+[PR #85](https://github.com/homie-rocks/homie/pull/85). No deployment or merge
+was performed.
+
+Competing full-suite and load runs triggered the real Workerd overrun guard
+and a mixed-run recovery timeout. They are failed stress attempts, not capacity
+receipts. The successful full Workerd rerun kept that guard enabled and ran
+without our other load runs. No Cloudflare CPU, memory or network guarantee is
+inferred from these local results.
+
+The scripted recovery checks include deliberate observation waits. All clients
+were back when checked at 20.08 s (Gate) / 20.74 s (rules) at 300, and
+20.10 s / 60.00 s at 1,000. These are upper bounds, not minimum recovery latency.
+The 1,000-client full restart is visibly expensive; faster crowd reconnection
+and deployed latency measurements remain work for the milestone proof slice.
+
+## Later step: retire browser-hosted netplay
+
+Retirement is not part of 0.45.0. Its preconditions are that every game in
+Homie's own three live studios has moved to server rules, and a release has
+already shipped a one-command assisted rewrite for other studios. Until both
+are met, existing games must continue to build, pass check, run and deploy,
+with the legacy release gate protecting that promise. New games remain rules
+games only.
+
+### Upgrade proof on the real studio copy
+
+Copied `/Users/ryan/Studios/homie-arcade` to
+`/tmp/homie-arcade-045-0Vaqlp/studio`, packed and installed 0.45.0 there.
+`npm run build` passed for all five existing netplay games.
+`npm run check -- --url http://127.0.0.1:8898` passed for its default game,
+2048 Race: desktop and phone finished round 1 in 123 seconds, with both
+connections uninterrupted. The original studio was not changed; nothing was
+deployed. The released 0.32.1 Ember Vale gate also passed with an older Worker
+entry: one host and one replica finished round 1 in 92 seconds.

package/guides/game/RULES.md

@@ -207,6 +207,7 @@ State belongs only in `fields`, `motion`, or `shared`; never a changing module v
 | `f.fix()` | Multiples of 1/4096, ±2147483648; `fuel: f.fix({ init: 1 })` |
 | `f.bit()` | Boolean; `alive: f.bit({ init: true })` |
 | `f.press()` | Input-only one-shot boolean button; `fire: f.press()` |
+| `f.held()` | Input-only number averaged over the tick (0.46.3); `ax: f.held()` |
 | `f.tick()` | Absolute tick, 0–4294967295; `until: f.tick()` |
 | `f.ticks()` | Tick duration, same range; `cooldown: f.ticks()` |
 | `f.vec3()` | Float32 vector `{x,y,z}`; `target: f.vec3()` |
@@ -220,7 +221,7 @@ State belongs only in `fields`, `motion`, or `shared`; never a changing module v
 Vector writes may omit z (it becomes zero); reads contain all three coordinates.
 Integer writes round and clamp, not wrap. Guard against underflow explicitly:
 `self.hp = Math.max(0, self.hp - damage)`. Inputs may contain only integer types,
-fix, bit and press. Each field may hold at most 16,384 cells and a kind 65,536.
+fix, held, bit and press. Each field may hold at most 16,384 cells and a kind 65,536.
 A scalar is one cell; a vector four; a text is `1 + ceil(max/64)`;
 a list is `1 + max * itemCells`; a map is `1 + max * (1 + itemCells)`;
 a struct is one plus the cells of its fields. Map keys are at most 32 characters.
@@ -344,6 +345,7 @@ These costs bound work, not elapsed wall time.
 | `sendArea(area,event,data?)` | Entity/room; 20 + 2N + 6C; 64 areas/tick, reach 64m | `world.sendArea({sphere:{at:self.pos,r:2}}, 'hit', {damage:1})` |
 | `after(ticks,event,data?)` | Entity/room; 16 + 6C; wait clamped 1–2147483647; targets caller | `world.after(20, 'ready', {})` |
 | `emit(effect,at,data?)` | Declared effect; 10 + 6C; at is position or ID; 256 effects a tick, and the next one throws | `world.emit('spark', self.pos, {})` |
+| `emit(effect,at,data,audience)` | The same, plus 8, for who may perceive it (0.46.3): `{within: metres}`, `{to: id}` or `{to: [ids]}` (32 at most), or both | `world.emit('grunt', self.id, {}, {within: 45})` |
 | `spawn(kind,at,fields?)` | Entity/room; 10 + copy cost; 2048 entities, non-player kinds only | `world.spawn('coin', self.pos, { value: 2 })` |
 | `despawn(self)` | Own non-player entity; constant guard cost | `world.despawn(self)` |
 | `place(self,at,options?)` | Own entity; 82; options vel/heading; clamps to bounds, changes movement revision | `world.place(self, world.map.spots('start')[0])` |
@@ -369,7 +371,8 @@ Queries return readonly views; send events to make recipients change themselves.
 Math vectors are readonly too: replace `d.x += n` with
 `d = { ...d, x: d.x + n }`, or use `world.math.add`/`scale`.
 
-World properties: `tick`, `dt`, `tune`, `shared`, `map`, `math`, `stage`, `level`,
+World properties: `tick`, `dt`, `unitsLeft` (0.46.3: budget units the running
+handler may still spend, so a planner can stop early), `tune`, `shared`, `map`, `math`, `stage`, `level`,
 `levelMax`, `round: {n,phase,endsAt}`. Phase is `live` or `over`.
 `rounds.seconds: 0` means no automatic deadline: your room must call round.end.
 A positive duration ends automatically. Round results arrive two ticks after the
@@ -780,8 +783,17 @@ Rules, collision, saves and shared state stay authoritative and unchanged.
 Views must interpolate distant motion and dispose/recreate entities on view exit
 and entry. Omit the settings for full precision and the room's normal tick rate.
 
-A small room embeds delivery in its Table. Larger rooms open Gate connections;
-more than eight Gates use concentrators. The studio template supplies their exports, bindings and
+A small room embeds delivery in its Table. Larger rooms open Gate connections, one channel
+from each Gate to the room: the room runs the rules and hands each Gate one world a tick, and
+the Gate selects, encodes and paces each player's view. A player on a slow connection is sent
+fewer, fresher frames, never a growing backlog; draw from the newest snapshot and interpolate.
+A body that keeps its course is not sent every tick: the view library moves it along its last
+velocity, and it is sent again when that has drifted past `view.precisionM` (near bodies) or half
+the distance it covers between `view.farHz` refreshes (far ones). `precisionM` is what a crowd
+costs a player's connection: 0.01 is a centimetre; 0.05 sends about a sixth fewer bytes.
+Homie sets no pace on what a player sends a server-hosted game. To set your own, add
+`"rates": { "in": 60 }` to `room` in game.json: messages a second per player, by frame kind.
+The studio template supplies the Gate exports, bindings and
 migration; upgrade the template before deploying an existing studio. No infrastructure naming or studio admission ceiling is required.
 Read the local measurements and their limitations in
 `docs/rooms-milestone-2-notes.md` before making a capacity claim.
@@ -932,7 +944,22 @@ Declare `room.historySeconds: 1` (maximum two seconds). The server retains and
 saves non-collider body positions and placement revisions on its virtual clock.
 The view's `room.viewTick` is the tick used to interpolate remote bodies. Send it
 with an action, then use `world.ray(..., {atTick, ...filters})`. Fractional ticks
-interpolate saved poses. Player requests clamp to the smaller of the configured window and the server-measured round-trip latency plus 150 ms presentation delay and one simulation tick. Without a measurement only that small margin is allowed. The relay measures a nonce challenge; client-supplied latency figures are ignored.
+interpolate saved poses. A player's request is clamped to: the relay's own
+measurement of that connection's round trip, plus 150 ms of presentation delay,
+plus the whole ticks the input waited between arriving and running (at least one,
+at most a quarter of a second). Without a measurement only that margin is allowed.
+
+The measurement (0.46.3) is a low percentile of the last ten seconds of round
+trips timed on the input frames themselves: each frame names the newest snapshot
+its browser had, and the relay knows when that snapshot left. A client cannot
+make it shorter than its real latency, and holding back a separate answer no
+longer raises it. A modified client can still pretend to be further away than it
+is, as it could by really being so; what that buys is bounded by the game's cap.
+Set `room.rewindSeconds` (from 0 to `historySeconds`): the most any shot is
+rewound, whatever the connection reports. `0.25` suits a shooter: a round trip
+up to about 100 ms is compensated in full and a slower player leads the target a
+little. Without it the cap is `historySeconds`, as before. Client-supplied
+latency figures are ignored.
 A placement or new round prevents rewinding through a teleport or reset.
 
 Rewind changes actor poses only. Eligibility filters use current fields, so a
@@ -977,6 +1004,89 @@ skips the intermission. Use it for an authorized retry; validate eligibility in
 your room handler. Pending restart intent survives save/restore.
 
 
+### Held input: a tap moves for the time it was down (0.46.3)
+
+An ordinary input field is read once a tick, at the tick's edge. A key held for
+60 ms of a 50 ms tick therefore moves the body for one tick or for two, by where
+the edges happened to fall: short taps travel too far and vary. Declare a
+movement axis `ax: f.held()` instead. The browser then sends the average of what
+the control read over each tick (a key down for a third of the tick reads a
+third of its value; an analogue stick reads its mean), prediction uses the same
+number, and `move` multiplies speed by it as before, so the body moves for the
+part of the tick the key was down. `room.input({ax: 1})` is called as usual,
+every frame or on change; a boolean counts as 1. `think` returns a plain number.
+Use it for movement axes, not for buttons: a button is `f.press()` or `f.pulse()`.
+Keep its values in -1 to 1. An entry that reaches the server after its tick is
+not counted twice: the tick it missed ran on the value before it, and the server
+settles the difference on the next ticks, so the body ends where the browser
+predicted.
+
+### Effects with an audience: what a player may perceive (0.46.3)
+
+Everything in a snapshot's public fields and every plain `world.emit` reaches
+every player. A sound or a flash must not be drawn from state a rival should not
+have (another player's exact health), and need not be sent to someone who could
+not perceive it. Emit the event instead, and say who perceives it:
+
+```ts
+world.emit('grunt', self.id, {}, { within: 45 });            // earshot of where self stands
+world.emit('hitConfirm', target.id, { damage }, { to: shooter.id }); // the shooter alone
+world.emit('alarm', self.pos, {}, { within: 30, to: allies }); // either is enough
+```
+
+`within` is metres from the effect's place (the named entity's position at that
+moment) to the listener's own body; `to` names entities, and the people driving
+them receive it. A watcher, and a seat with no body yet, perceive the room: they
+receive every effect with a `within`, and never one addressed only `to` somebody.
+An effect with no audience is public, exactly as before. Delivery costs one
+frame a listener on ticks that have such effects and nothing on ticks that do
+not. Send what is perceivable (a hit landed, roughly how hard); send exact
+numbers only `to` the player entitled to them.
+
+### Predicting the player's own actions (0.46.3)
+
+The own position is predicted by `move`. Other own actions (a weapon swap, a
+build, a reload, a hit marker) otherwise wait for the server's round trip. Give
+the view a predictor for the kind:
+
+```ts
+const room = openRoom<typeof rules>({ predict: { runner(me, input, ctx) {
+  if (input.select) swap(me, input.select, ctx.tick * ctx.dt);        // the rules' own pure helper
+  if (input.build && me.builds > 0) { me.builds--; ctx.ghost('cover', spot(me), { size }); }
+  if (input.fire && aimHits(ctx, me)) ctx.effect('hit', me.id, {});
+} } });
+```
+
+The room runs it for the own body once a predicted tick, after `move`, with that
+tick's input, and on a copy between ticks, so a press answers on the next drawn
+frame. `me` holds the body's declared fields (and readonly `id`, `pos`, `vel`,
+`heading`, `grounded`, `motion`); what it writes is held to the declared types
+and read back through `room.me`. Every snapshot puts the server's values back
+and runs the still-pending inputs again, exactly as it does for the position, so
+a wrong guess corrects itself. Share pure helpers with the rules (no `world`):
+the server's handler remains the authority and the only place a result counts.
+
+`ctx.ghost(kind, at, fields?, {match?, seconds?})` draws a provisional entity:
+`room.each` yields it with `provisional: true` until an entity of that kind that
+`match(entity)` accepts (default: within a metre) arrives, and then until that
+one is drawn, so there is never a gap or a double. `ctx.effect(name, at, data?,
+{match?})` fires the effect's listeners now with `predicted: true`; the server's
+own effect of that name then arrives with `confirms: true` (use its exact data,
+do not replay the sound). If the server ran the tick without confirming, the
+room emits `retract` (`{ghost, kind}` or `{effect, ...data}`) and the ghost
+leaves: take the marker down quietly. `ctx.ray/rays/rayAll` query what the
+player sees (`ctx.viewTick`); `ctx.preview` says the run is between ticks. A
+predictor runs often: keep it cheap, and keep per-entity state in `me`.
+
+A tick's prediction runs more than once (between ticks, again when the input
+changes, then the tick itself) and shows each thing once. Things are told apart
+by their name and `key`: give two effects of one name that mean different things
+(`ctx.effect('audio', me.id, {name: 'jump'}, {key: 'jump'})` beside a `reload`)
+a `key` each, and the same for two ghosts of a kind. Read `me.id` into a constant
+before using it in a `match` closure: `me` is reused. A valued pulse
+(`f.pulse()`) carries the tick it was predicted on, and the server acts on it in
+that tick, so a predicted swap is in the snapshot of the tick it was drawn for.
+
 ### Discrete actions with a value
 
 Use `select: f.pulse()` for a weapon slot or other byte-valued action. Call