@homie-rocks/studio 0.46.2 → 0.46.5

package/CHANGELOG.md

@@ -17,6 +17,112 @@ 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.5] - 2026-10-11
+
+**Plugin 0.46.5**
+
+A page left open across a deploy is brought up to date with its game, and a check never opens the live site
+unless it is asked to.
+
+### Added
+
+- `room.bots: { keep, names: [...] }`: a rules game names its own bots, by seat. The roster, the results and
+  `world.label` all use it. Opt-in: without `names` the toolkit's own list is used, as before.
+
+- A predictor can judge its own shot as the server will: `ctx.judgedTick(aimTick)` (the tick the server will
+  pose the others at for this seat; the snapshot's control row now carries the seat's own rewind allowance in a
+  game that declares `room.historySeconds`), `ctx.ray/rays(..., { atTick })` and `room.poseAt(id, tick)` (the pose
+  at a tick from the snapshots the browser holds), and `ctx.math` (the rules' own `math`).
+
+### Fixed
+
+Each of these changes what happened before; none needs a change to a game.
+
+- A play page open during a deploy kept hosting the newer game inside the older page: only the frame was loaded
+  again. When the newer game needed something the old page did not have (a player ticket, for a game that had
+  just started keeping results with `room.records`), the player saw an empty history and finished rounds were not
+  recorded until they reloaded the page themselves. The page now says what it was made for, the Worker answers
+  the frame with a stand-in when a page made now would differ, and the page does one full reload to the same room
+  and seat. A page from before this handshake is sent to a fresh page, by the one way it has, only when the game
+  cannot keep its results inside it. A deploy that changes only a game's code or art still reloads the frame alone.
+- A finished round that had no player to be written for was dropped without a word. The log now says
+  `record-unsaved`, and the player is told on their screen that the round was not saved and to reload.
+- The player's own body was drawn sinking for the whole tick it landed in, and standing only at the tick's end
+  (up to 33 ms late at 20 ticks a second). It is drawn down to the ground by the moment it met it.
+- `homie-studio check` with no `--url` opened the studio's **live** site, and with no game the first game by name:
+  `npm run check` could seat two check browsers in a live public room of a game nobody was working on. With no
+  `--url` a check now runs against this studio's own build: its running dev server, or one it starts on a free
+  port and stops afterwards. With no game it covers the games this checkout changed (against the default branch,
+  committed or not), else every game. The live site is checked only when asked: `--live`, or its address in
+  `--url`. `port check` and `perf` follow the same rule (the running dev server, `--url`, or `--live`).
+
+### Upgrade notes
+
+- Nothing to do. A script that relied on `homie-studio check` reaching the live site says `--live` now.
+- The first deploy of this version reloads open play pages whole, once (their pages are older than it).
+- Version 0.46.5 is provisional. No deploy or merge is part of this PR.
+
+## [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.

package/bin/homie-studio.mjs

@@ -785,6 +785,8 @@ function print(result) {
         `Written: ${result.file}`);
       break;
     case 'check':
+      if (result.results) { for (const r of result.results) lines.push(`${r.game}: PASS at ${r.site}: room ${r.room}, round ${r.round?.n} (${r.round?.humans} humans, ${r.round?.bots} bots), connection ${r.uninterrupted === true ? 'uninterrupted' : r.uninterrupted === false ? 'INTERRUPTED' : 'unknown'}`); break; }
+      if (result.site) lines.push(`Checked ${result.local ? 'this studio\'s own build' : 'the site'} at ${result.site}.`);
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`),
         ...(result.frames ?? []).map((f) => `  ${f.browser} drew ${f.fps ?? '?'} fps${f.renderer ? ` on ${f.renderer}` : ''}`),
@@ -933,8 +935,9 @@ async function main() {
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
     const game = positional[2] ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address or the live site)' };
+    // Never the live site unless asked (--live, or its address): this studio's running dev server, else say so.
+    const url = flags.get('url') ?? (flags.has('live') ? siteUrl(root) : (await import('../lib/dev.mjs')).runningDev(root)?.url);
+    if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address), start npm run dev, or say --live for the live site' };
     return tracked(root, 'checks', (report) => portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'port check');
   }
   if (cmd === 'app' && sub === 'role') {
@@ -955,8 +958,8 @@ async function main() {
   if (cmd === 'lab') return labCommand(root, sub);
   if (cmd === 'perf') {
     const game = sub ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'perf', why: 'give --url (the local dev address or the live site)' };
+    const url = flags.get('url') ?? (flags.has('live') ? siteUrl(root) : (await import('../lib/dev.mjs')).runningDev(root)?.url);
+    if (!url) return { ok: false, command: 'perf', why: 'give --url (the local dev address), start npm run dev, or say --live for the live site' };
     const devices = String(flags.get('device') ?? 'computer,phone').split(',').map((d) => d.trim()).filter(Boolean);
     const num = (k, d, lo, hi) => Math.max(lo, Math.min(hi, Number(flags.get(k) ?? d) || d));
     return perfRun({ root, url, game, devices, runs: num('runs', 1, 1, 50), seconds: num('seconds', 15, 3, 300), warm: num('warm', 3, 0, 60), profile: flags.has('profile'), out: flags.get('out') ? resolve(String(flags.get('out'))) : null, maxLoad: num('max-load', 0.8, 0.05, 50), cpu: num('cpu', 4, 1, 20), pair: flags.get('pair') ? String(flags.get('pair')) : null, log });
@@ -973,14 +976,30 @@ async function main() {
   if (cmd === 'dev' && flags.has('stop')) return stopDev(root);
   if (cmd === 'dev') return dev(root, { lan: flags.has('lan'), port: flags.get('port') ?? 8787, remoteAi: flags.has('remote-ai'), localAi: !flags.has('no-local-ai'), timestamps: flags.has('timestamps'), log });
   if (cmd === 'check') {
-    const game = positional[1] ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'check', why: 'give --url (the local dev address or the live site)' };
+    // lib/check-site.mjs: with no --url a check runs against this studio's own build, never the live site (--live asks
+    // for that); with no game it covers the games this checkout changed.
+    const { checkSite, gamesToCheck } = await import('../lib/check-site.mjs');
+    const { games, why } = gamesToCheck(root, positional[1]);
+    if (!games.length) return { ok: false, command: 'check', why: 'this studio has no game to check' };
     // A big binary committed under games/ fails the check before any browser starts: it belongs in R2, never in git.
     const { bigCommittedFiles } = await import('../lib/asset-check.mjs');
-    const big = bigCommittedFiles(root).filter((f) => f.path.startsWith(`games/${game}/`));
-    if (big.length) return { ok: false, command: 'check', why: `committed files over 5 MB under games/${game}: ${big.map((f) => `${f.path} (${(f.bytes / 1024 / 1024).toFixed(1)} MB)`).join(', ')}. Big media goes to the studio's R2 (homie-studio storage add, then media move); raw models stay in art/<slug>/raw/ (git-ignored); a shipped model is made phone-sized with homie-studio assets optimise. Take it out of git (git rm --cached), then check again.` };
-    return tracked(root, 'checks', (report) => check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'check');
+    for (const game of games) {
+      const big = bigCommittedFiles(root).filter((f) => f.path.startsWith(`games/${game}/`));
+      if (big.length) return { ok: false, command: 'check', why: `committed files over 5 MB under games/${game}: ${big.map((f) => `${f.path} (${(f.bytes / 1024 / 1024).toFixed(1)} MB)`).join(', ')}. Big media goes to the studio's R2 (homie-studio storage add, then media move); raw models stay in art/<slug>/raw/ (git-ignored); a shipped model is made phone-sized with homie-studio assets optimise. Take it out of git (git rm --cached <file>) and check again.` };
+    }
+    const site = await checkSite(root, { url: flags.get('url') ?? null, live: flags.has('live'), log });
+    if (!site.ok) return { ok: false, command: 'check', why: site.why };
+    try {
+      if (!positional[1]) log(`check: ${games.join(', ')} (${why}) at ${site.url}`);
+      const results = [];
+      for (const game of games) {
+        const shots = flags.get('shots') ? resolve(flags.get('shots'), ...(games.length > 1 ? [game] : [])) : null;
+        const r = await tracked(root, 'checks', (report) => check({ url: site.url, game, shots, log, report }), 'check');
+        results.push({ ...r, game, site: site.url, local: site.local });
+        if (!r.ok) break;
+      }
+      return results.length === 1 ? results[0] : { ok: results.every((r) => r.ok), command: 'check', site: site.url, local: site.local, why: results.find((r) => !r.ok)?.why, results };
+    } finally { await site.stop(); }
   }
   if (cmd === 'shoot') {
     const game = positional[1] ?? listGames(root)[0]?.id;

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
@@ -941,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
@@ -986,6 +1004,112 @@ 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`.
+
+To guess a shot the server will judge with rewind, ask for what the server
+will use (0.46.5). `ctx.judgedTick(aimTick)` is the tick it will pose the others
+at: the `aimTick` the input carries, held to how far back this seat may look
+right now (the server says so in every snapshot) and to this tick. Pass it on:
+`ctx.ray(from, dir, max, { atTick: ctx.judgedTick(input.aimTick), ...filters })`
+poses the other bodies as the server will, from the snapshots this browser
+holds (between two of them, or carried on from the newest along its velocity).
+Inside the allowance that is the drawn target; past the game's cap it is a newer
+pose, and the predictor then shows no hit where the server will see none.
+`room.poseAt(id, tick)` gives `{pos, vel, known}` for the game's own tests
+(`known: false` is a guess past the newest snapshot). `ctx.math` is the rules'
+own `math`, and the context is accepted by guarded rules code as a world is for
+what the two share (`tick`, `dt`, `math`, `ray`, `rays`, `rayAll`, and a scene's
+`ray`, `rayAll`, `sweep`, `support`), so an aiming helper written for the rules
+can be called with `ctx` instead of being restated in the view. It has no
+`near`, `inBox`, `send` or `emit`: a helper that needs those is the server's.
+
+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.
+
+### Naming the bots (0.46.5)
+
+`room.bots: { keep: 4, names: ['Vex', 'Moth', 'Kilo'] }` gives the game's bots its own names, by seat (the list
+wraps). The roster, the round's results and `world.label(id)` all say the same name, and a restore keeps it.
+Without `names` the toolkit's own list is used. A name is 1 to 24 characters on one line.
+
 ### Discrete actions with a value
 
 Use `select: f.pulse()` for a weapon slot or other byte-valued action. Call

package/guides/game/SKILL.md

@@ -243,6 +243,11 @@ world or inventory, use Lasting worlds above. Ordinary match rooms expire after
   handle. Draw the character's name over its body and in the ranking (a declared command requests it; rules validate and keep it in the player entity), except on a kids server, where the others stay handles. Ember Vale does it.
 - Show who is playing (`saves.player.name`, guest or signed in) and a small "Keep my progress" button that calls
   `saves.signIn()`; the play page shows its passkey sheet. Pressing Play never needs an account.
+- A guest who signs in to an account that already has the same key: say how the two combine, once, in
+  `site/src/worker.mjs`: `mergeSaves({ '<id>': { saves: { coins: 'sum', 'best-level': 'larger', settings: 'newer' },
+  stats: { kills: 'sum' } } })` from `@homie-rocks/studio/worker` (or a function for an inventory). Server records
+  are joined without a rule; any other key with no rule reaches the game's `onConflict` (SAVES.md, "When a guest
+  signs in to their account").
 - Prove it: build, `npm run dev`, open `http://localhost:8787/<id>/play` (passkeys need `localhost`, not
   `127.0.0.1`), play, reload: the progress is still there. The whole guide is
   `node_modules/@homie-rocks/studio/saves/SAVES.md` (the limits, offline and conflicts, what is stored, privacy).
@@ -299,6 +304,8 @@ npm run build                                          # fix every error it name
 npx --no-install homie-studio build --types            # the same, with the TypeScript checked first: run it before a deploy
 npm run dev                                            # in the background: http://127.0.0.1:8787/<id>/play
 npx --no-install homie-studio check <id> --url http://127.0.0.1:8787 --shots ./.checks
+# With no --url the check runs against this studio's own build (its running dev server, or one it starts and
+# stops); with no <id>, on the games this checkout changed. The live site only with --live or its address.
 npx --no-install homie-studio shoot <id> --preview     # pictures of the built game on a stepped clock, no site needed (a 3D game where there is no GPU)
 npx --no-install homie-studio preview <id>             # only that game's built files at an address (alone, offline): for a capture script
 ```

package/lib/check-site.mjs

@@ -0,0 +1,85 @@
+/**
+ * WHERE A CHECK RUNS, AND ON WHICH GAMES, WHEN NOBODY SAYS (0.46.5).
+ *
+ * A check puts real browsers in a real room. With no `--url` it used to open the studio's LIVE site, and with no game
+ * the first game by name: `npm run check` in a studio working on one game sat two check browsers in a live public
+ * room of another. A check is a gate on what is in this folder, so:
+ *
+ *   where   `--url <site>` as given; else this studio's own dev server: the one already running (lib/dev.mjs keeps
+ *           its record), or one started for the check on a free port and stopped when the check ends. The live site
+ *           only when asked by name: `--live`, or its address in `--url`.
+ *   which   the game named; else every game this checkout changed (files under games/<id>/ that differ from the
+ *           default branch, committed or not); else, when nothing changed or this is not a git checkout, every game.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { once } from 'node:events';
+import { createServer } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { runningDev } from './dev.mjs';
+import { listGames, siteUrl } from './studio.mjs';
+
+const CLI = fileURLToPath(new URL('../bin/homie-studio.mjs', import.meta.url));
+
+async function freePort() {
+  const s = createServer(); s.listen(0, '127.0.0.1'); await once(s, 'listening');
+  const port = s.address().port; await new Promise((r) => s.close(r)); return port;
+}
+
+/**
+ * The site a check opens: { ok, url, local, live, started, stop() }. `stop` ends only a server this call started.
+ * `spawnFn` and `fetchFn` are for tests.
+ */
+export async function checkSite(root, { url = null, live = false, log = () => {}, spawnFn = spawn, fetchFn = globalThis.fetch, waitMs = 240_000 } = {}) {
+  const none = async () => {};
+  if (url) return { ok: true, url: String(url), local: /^https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::|\/|$)/.test(String(url)), live: false, started: false, stop: none };
+  if (live) {
+    const site = siteUrl(root);
+    return site ? { ok: true, url: site, local: false, live: true, started: false, stop: none } : { ok: false, why: 'this studio has no live site yet (deploy it first), so there is nothing for --live to check' };
+  }
+  const running = runningDev(root);
+  if (running) return { ok: true, url: running.url, local: true, live: false, started: false, stop: none };
+  const port = await freePort(), origin = `http://127.0.0.1:${port}`;
+  log(`check: no --url, so this studio's own build is checked: starting its dev server on ${origin} (stopped when the check ends; --live checks the live site)`);
+  const child = spawnFn(process.execPath, [CLI, 'dev', '--port', String(port), '--no-local-ai'], { cwd: root, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  let tail = '';
+  for (const stream of [child.stdout, child.stderr]) stream?.on('data', (chunk) => { tail = (tail + chunk).slice(-4000); });
+  const stop = async () => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    const ended = once(child, 'exit');
+    try { process.kill(-child.pid, 'SIGTERM'); } catch { try { child.kill('SIGTERM'); } catch { /* gone */ } }
+    const force = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, 8000);
+    try { await ended; } finally { clearTimeout(force); }
+  };
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline && child.exitCode === null && child.signalCode === null) {
+    const up = await fetchFn(`${origin}/games.json`, { signal: AbortSignal.timeout(1500) }).then((r) => r.ok).catch(() => false);
+    if (up) return { ok: true, url: origin, local: true, live: false, started: true, stop };
+    await new Promise((r) => setTimeout(r, 400));
+  }
+  await stop();
+  return { ok: false, why: `this studio's dev server did not start for the check${tail ? `:\n${tail.trim().split('\n').slice(-12).join('\n')}` : ''}\nStart it yourself (npm run dev) and give its address with --url, or fix the build.` };
+}
+
+/** The ids of the games this checkout changed against its default branch (committed or not), in the studio's order; [] when it cannot be told. */
+export function changedGames(root, { run = spawnSync } = {}) {
+  const git = (...args) => { const r = run('git', args, { cwd: root, encoding: 'utf8' }); return r.status === 0 ? String(r.stdout) : null; };
+  if (git('rev-parse', '--is-inside-work-tree') === null) return [];
+  const files = new Set((git('status', '--porcelain', '--', 'games') ?? '').split('\n').map((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> ').pop()).filter(Boolean));
+  const head = (git('symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD') ?? '').trim();
+  for (const base of [head, 'origin/main', 'main', 'origin/master', 'master'].filter(Boolean)) {
+    const fork = (git('merge-base', 'HEAD', base) ?? '').trim();
+    if (!fork) continue;
+    for (const f of (git('diff', '--name-only', `${fork}..HEAD`, '--', 'games') ?? '').split('\n')) if (f) files.add(f);
+    break;
+  }
+  const touched = new Set([...files].map((f) => /^games\/([^/]+)\//.exec(f)?.[1]).filter(Boolean));
+  return listGames(root).map((g) => g.id).filter((id) => touched.has(id));
+}
+
+/** The games a check covers: the one named, else what changed, else all of them. */
+export function gamesToCheck(root, named, options) {
+  if (named) return { games: [named], why: 'named' };
+  const changed = changedGames(root, options);
+  if (changed.length) return { games: changed, why: 'changed in this checkout' };
+  return { games: listGames(root).map((g) => g.id), why: 'nothing changed against the default branch: every game' };
+}

package/lib/check.mjs

@@ -1,5 +1,6 @@
 /**
- * `homie-studio check <game> --url <site>` — the promise, measured: two fresh
+ * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
+ * when nobody says: lib/check-site.mjs; never the live site unless asked): two fresh
  * browsers (separate Chrome processes and profiles, one a computer and one a
  * phone) press Play, land in the SAME public room, play, and both see the round
  * finish. Exit 0 only when all of that happened. Uses this Mac's Chrome through

package/lib/rules-check-worker.mjs

@@ -233,7 +233,7 @@ function play(c, companions, allow) {
   }
 
   /* ---- what the people press. Each plays one of three ways, changing every 20 s; seat 1 never sends anything. */
-  const ends = (fd) => (fd.t === 'bit' || fd.t === 'press' ? [false, true] : fd.t === 'fix' ? [-1, 1] : [L.P.coerce(fd, -Infinity, c.dims), L.P.coerce(fd, Infinity, c.dims)]);
+  const ends = (fd) => (fd.t === 'bit' || fd.t === 'press' ? [false, true] : fd.t === 'fix' || fd.t === 'held' ? [-1, 1] : [L.P.coerce(fd, -Infinity, c.dims), L.P.coerce(fd, Infinity, c.dims)]);
   const steering = new Map();
   let moveTick = 0;
   let moveSelf;

package/lib/rules-check.mjs

@@ -28,10 +28,10 @@ export const LONG_ALLOWANCE = Object.freeze({ ...ALLOWANCE, ticks: 8 * ALLOWANCE
 
 /** The ordered declarations a save depends on. Functions contribute their presence, never their implementation. */
 export function stateHash(c) {
-  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save, historySeconds } = c;
+  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save, historySeconds, rewindSeconds, botNames } = c;
   // Keep existing 2D save compatibility hashes when the 3D map vocabulary grows.
   const map = dims === 2 ? { name: geometry.name, bounds: geometry.bounds, boxes: geometry.boxes, circles: geometry.circles, spots: geometry.spots } : geometry;
-  return createHash('sha256').update(JSON.stringify({ kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, ...(historySeconds?{historySeconds}:{}), tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
+  return createHash('sha256').update(JSON.stringify({ kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, ...(historySeconds?{historySeconds}:{}), ...(rewindSeconds!==undefined?{rewindSeconds}:{}), ...(botNames?{botNames}:{}), tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
 }
 
 /**

package/lib/rules-types.mjs

@@ -78,7 +78,7 @@ type W = World<${parameters}>;
 type RW = World<${parameters}, true>;
 type Definition = Omit<RulesDef, 'entities' | 'room' | 'move' | 'asks'> & {
   entities: ${entities}; move?: Moves;
-  room?: { records?: {key:string;identity:string;eligible?:string;fields:Readonly<Record<string,string>>}; rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number }; historySeconds?: number;
+  room?: { records?: {key:string;identity:string;eligible?:string;fields:Readonly<Record<string,string>>}; rounds?: { seconds: number; breakSeconds: number }; bots?: { keep: number; names?: readonly string[] }; historySeconds?: number; rewindSeconds?: number;
     start?: (world: RW) => void;
     join?: (ctx: Pick<W, 'map' | 'shared' | 'tune' | 'math' | 'round'>, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string; character?: (${joins}) | null }) => ${joins};
     on?: { [K in keyof (Omit<Events, keyof GameRoomEvents> & GameRoomEvents)]?: (world: RW, event: EventData<(Omit<Events, keyof GameRoomEvents> & GameRoomEvents)[K]>) => void };

package/lib/template-history.json

@@ -2775,6 +2775,90 @@
      }
     }
    }
+  },
+  "0.46.3": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "27881d11d3ff3803",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
+  },
+  "0.46.5": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "27881d11d3ff3803",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -1699,6 +1699,18 @@ reads the other's snapshot with the wrong code.
 - **An old tab that knocks at the live build's room is refused**: `error stale` (final; the helper
   shows "This game was updated. Tap to reload." and the play page reloads the frame, at most twice
   a minute).
+- **A page older than the game it would host is brought up to date too (0.46.5).** The frame alone
+  is reloaded only while the play page around it is still the page the Worker would write now. The
+  page says what it was made for (`sh` on the frame's address: the toolkit's version and the parts
+  of the manifest a page is built around, `shellKey` in worker/pages.mjs; not the game's code or
+  words). When that differs, the Worker answers the frame with a stand-in that says so, and the
+  page does **one full reload**, to the same room (it is in the address) and the same seat (its
+  token is in the tab). A page from before this handshake has only one way to load a whole new
+  page, the one for leaving a finished room; it is used only when the game cannot work inside the
+  old page at all: the game keeps results for a player (`room.records`) and the old page holds no
+  player ticket. Such a player lands in a fresh page and a room the lobby gives them. A result
+  that still has no player to be written for is never dropped in silence: the log says
+  `record-unsaved`, and the player's screen says the round was not saved and to reload.
 - **A tab of the live build that knocks at a room still on the old build waits**: `error
   room-stale` (not final). The room's players are told to reload; when the last of them has left,
   the next knock is let in, and the room **starts fresh**: its checkpoint, snapshot, round, roster