@homie-rocks/studio 0.35.1 → 0.37.0

package/lib/typecheck.mjs

@@ -1,3 +1,4 @@
+import { runRulesCompiler } from './rules-compiler.mjs';
 /**
  * `homie-studio build --types` — the games' TypeScript, checked before anything is built.
  *
@@ -6,15 +7,15 @@
  * of its own to run `npx tsc` with.
  *
  *   - The compiler is the STUDIO'S OWN (`typescript` in its node_modules, which a new studio's package.json asks
- *     for). @homie-rocks/studio does not depend on it: the check is something a studio opts into, and a studio that
- *     never does pays nothing for it. Without it the command stops and says the one line that installs it.
+ *     for). This optional check for legacy games keeps using that compiler. Rules games use the toolkit's own
+ *     pinned compiler through typecheckRules below, on every build.
  *   - A game with a tsconfig.json of its own is checked with it. Any other game is checked the way esbuild reads
  *     it: its entry and whatever that imports, as ES2022 for a browser, strictly, with the pictures, sounds and
  *     models it imports as addresses (the build's own loaders).
  *   - Only errors in the game's own files stop the build. A game imports the toolkit's helpers as TypeScript
  *     source, and a creator can do nothing about a line in node_modules; those are counted and said, never fatal.
  *
- * Never run unasked: a plain `build` is exactly as fast as it was.
+ * The legacy check runs only when asked with --types. The rules check is mandatory.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
@@ -105,3 +106,51 @@ export function typecheck(root, games, { log = () => {} } = {}) {
   }
   return { typescript: ts.version, games: rows };
 }
+
+/** Every rules build uses the toolkit's pinned compiler, its own strict settings and declaration-derived faces. */
+export async function typecheckRules(root, g, checked, tune, { log = () => {} } = {}) {
+  const [{ PACKAGE_ROOT }, { rulesTypes, rulesViewTypes, rulesAnswerScopes }] = await Promise.all([import('./studio.mjs'), import('./rules-types.mjs')]);
+  const compiler = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+  const dir = join(root, '.studio', 'types', g.id);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'rules.d.ts'), rulesTypes({ ...checked, answerScopes: await rulesAnswerScopes(join(g.dir, 'src/rules.ts')) }, tune));
+  writeFileSync(join(dir, 'view.d.ts'), rulesViewTypes(checked));
+  writeFileSync(join(dir, 'files.d.ts'), AMBIENT);
+  const project = join(dir, 'tsconfig.json');
+  writeFileSync(project, `${JSON.stringify({ compilerOptions: { ...OPTIONS, checkJs: true, paths: {
+    ...Object.fromEntries(Object.entries(JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).exports)
+      .filter(([, entry]) => entry?.types).map(([name, entry]) => [`@homie-rocks/studio/${name.slice(2)}`, [join(PACKAGE_ROOT, entry.types)]])),
+    '@homie-rocks/studio/rules': [join(dir, 'rules.d.ts')],
+    '@homie-rocks/studio/rules/view': [join(dir, 'view.d.ts')],
+    '@homie-rocks/studio/*': [join(PACKAGE_ROOT, '*')],
+  } }, files: [join(g.dir, 'src/rules.ts'), join(g.dir, g.entry ?? 'src/view.ts'), join(dir, 'files.d.ts')] }, null, 2)}\n`);
+  const res = await runRulesCompiler(compiler, ['-p', project, '--pretty', 'false']);
+  if (res.error) throw new Error(`games/${g.id}: the rules type check could not finish: ${res.error.message}`);
+  const messages = [];
+  for (const line of `${res.stdout ?? ''}\n${res.stderr ?? ''}`.split(/\r?\n/)) {
+    const at = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
+    if (at) {
+      const file = resolve(at[1]);
+      // Imported game helpers count too. Only the toolkit's own implementation is outside the author's remit.
+      if (!file.startsWith(`${PACKAGE_ROOT}${sep}`) && !file.includes(`${sep}node_modules${sep}`) || file.startsWith(`${g.dir}${sep}`)) {
+        const sourceLine = readFileSync(file,'utf8').split(/\r?\n/)[Number(at[2])-1] ?? '';
+        const advice = /Property 'ask'.*type 'never'/.test(at[5]) ? 'This handler scope never calls world.ask, so no answer can arrive here. Handle the answer in the scope that asks.'
+          : /world\.round\.end/.test(sourceLine) && at[4] === 'TS2339' ? 'Only room handlers end a round. Send a declared event to a room handler that calls world.round.end().'
+          : /'check'.*does not exist/.test(at[5]) ? 'Remove the obsolete check key. Generated observations require no exemption.'
+          : /=> (?:GameDecision|GuideDecision)'/.test(at[5]) ? 'A floor returns goal and say names from agents.json with exactly the args and sayArgs each declares, or {} to decline. Forward a request as { goal: ask.k, args: ask.args }.'
+          : /\.args\./.test(sourceLine) ? 'Use the argument names and types declared in agents.json and shapes.view; for a union, narrow its goal or request name before reading variant-specific arguments.'
+          : /unknown/.test(at[5]) ? 'Validate this external value with a type check before reading it.'
+          : /e\.picks/.test(sourceLine) ? 'Check e.ask before reading a question specific to one ask. Picks use the declared choice names, booleans and numbers.'
+          : at[4] === 'TS2339' && /self\./.test(sourceLine) ? 'Declare the field on this entity kind, or use an existing declared name.'
+          : at[4] === 'TS2322' && /join|kind:/.test(sourceLine) ? `room.join returns a player kind: ${checked.schema.kinds.filter(k => k.player).map(k => k.name).join(', ')}.`
+          : at[4] === 'TS2345' && /world\.despawn\s*\(/.test(sourceLine) ? 'world.despawn takes self, the non-player entity running this handler. Send an event to ask another entity to remove itself.'
+          : at[4] === 'TS2345' && /world\.send\s*\(/.test(sourceLine) && /Argument of type.*(?:readonly|pos:)/.test(at[5]) ? 'world.send takes an entity ID. Pass entity.id rather than the entity record.' : '';
+        messages.push(`${relative(root, file)}:${at[2]}:${at[3]} ${at[4]} ${at[5].length > 360 ? at[5].slice(0, 220) + ' … ' + at[5].slice(-100) : at[5]}${advice ? `\n  Repair: ${advice}` : ''}`);
+      }
+    } else if (/^error TS/.test(line)) messages.push(line);
+    else if (/^\s+\S/.test(line) && messages.length) messages[messages.length - 1] += `\n${line.length > 360 ? line.slice(0, 220) + ' … ' + line.slice(-100) : line}`;
+  }
+  if (messages.length) throw new Error(`games/${g.id}: its rules have type errors:\n${messages.slice(0, 30).map((m) => `  ${m}`).join('\n')}`);
+  if (res.status !== 0 && !res.stdout) throw new Error(`games/${g.id}: TypeScript stopped without diagnostics (${res.signal ?? res.status})`);
+  log(`types: games/${g.id}: rules, move and view checked with the toolkit's strict compiler`);
+}

package/links/links.d.ts

@@ -0,0 +1,3 @@
+export function randomId(): string;
+export function appLink(address: string, params?: Record<string, string | number | boolean | null | undefined>, base?: string): string;
+export function qrSvg(text: string, options?: { quiet?: number; dark?: string; light?: string; title?: string; minLevel?: 'L' | 'M' | 'Q' | 'H' }): string;

package/links/links.mjs

@@ -0,0 +1,16 @@
+/** Public links, QR and HTTP-safe IDs; the encoder is shared with the wall shell. */
+export { qrSvg } from '../worker/qr.mjs';
+export function randomId() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export function appLink(address, params = {}, base = globalThis.location?.href) {
+  const url = new URL(address, base);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('links use an HTTP(S) address without credentials');
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null || value === undefined) url.searchParams.delete(key);
+    else url.searchParams.set(key, String(value));
+  }
+  return url.href;
+}

package/netplay/NETPLAY.md

@@ -1,10 +1,17 @@
-# Homie netplay contract, v1 (revision 10)
+# Homie netplay contract, v1 (revision 11)
 
-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,
+Status: **v1, revision 11** (2026-10-08, `@homie-rocks/studio` 0.33.1). The wire
+version is `v: 1`. Everything revisions 2 to 11 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.
 
+**Revision 11** adds browser rules hosting and offline play (29.7): `held` occupants on
+welcome/promotion, explicit `rules: true` on runtime output, `hosted` relay events,
+`view` player events, `retime` clock-only round frames, terminal `rules-end`, and
+`host` with `why: 'host-kept'` to a rules host whose yield elected nobody.
+The hosting page's unmarked frames have ordinary player allowances. Old-style games
+keep revision 10's character counts and rates.
+
 **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`,
@@ -295,7 +302,7 @@ it.
 | The host closes or says `bye` | Sends `leave`, then elects a replacement. |
 | **Stall:** the host has sent no snapshot for **1.5 s** (the game's own `netplay.stallMs`, 1.5 to 10 s; section 22) while others are present | Demotes it (`role replica, why host-stalled`) and elects another. A host whose frames hitch sends a heartbeat meanwhile, for 4 s. |
 | **Frozen host at a newcomer's hello:** the host is hidden, or has sent nothing for 2.5 s | Makes the newcomer host at once. The old host gets `role replica`. |
-| **Hidden tab** | The helper sends a checkpoint, then `yield`. `ping {hid: true}` has the same effect. |
+| **Hidden tab** | The helper sends a checkpoint, then `yield`. `ping {hid: true}` has the same effect. A rules host is answered when nobody could take the role (section 29.7). |
 | **Silent socket:** nothing received for **10 s** | Closes it (a slept phone, a half-open link). The seat's body turns into a bot. The helper pings every 2 s. |
 
 - **Ranking candidates:**
@@ -2247,8 +2254,8 @@ The state hash includes ordered declarations and handler names/presence, body/pl
 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.
+`netplay.version` for rules games in either hosting mode. Browser-hosted games use the
+checkpoint handover described below. 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
@@ -2259,3 +2266,113 @@ After sixty seconds paused without a returning person, the room ends even if wat
 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.
+### 29.7 The same runtime in a browser and offline
+
+`room.host: 'browser'` bundles the guarded host runtime and announces `rules: true` in
+`hello`. The relay elects a browser using the existing election and visibility yield.
+Only an elected host that announced rules receives step `in` frames (`e`, `k`, `s`, `r`);
+an older host receives the original input format. The relay supplies `from` from the socket's
+seat. It preserves `e` on a rules host's snapshots, and seat expiry sends `{ t: 'free', seat }`
+to a rules host. An old-style host is sent neither, and its `welcome` and `role` carry no
+`held`: nothing an old-style game sends or receives differs from revision 9. A page that
+announces rules with a revision below 11 is never elected (its output would be unmarked).
+Joins, AI identity and policy are the relay's facts, never fields copied from a player's input.
+
+A rules checkpoint holds `{ rules: build, data: runtimeSave }`. Promotion validates it and
+restores one complete state through `createHost` and the single `createCore` save validator, with a fresh input epoch. `restoreEpoch` is the single replacement epoch option; `startPaused: false` lets browser promotion resume with the relay’s current occupants, while server recovery starts paused. A malformed or incompatible checkpoint
+starts a fresh round, says so, and immediately replaces the relay checkpoint. Abrupt loss
+can rewind to the last checkpoint; the replacement host republishes the round's wall-clock
+deadline from its restored tick. No newer display snapshot is mixed into the save.
+
+An elected rules host may send `{ t: 'rules-end', rules: true, why }` when its runtime ends. The relay
+accepts this only from that host in a game the server catalogue identifies as rules, sends terminal `room-over` to everyone, closes sockets,
+and forgets the room and checkpoint. A later visitor starts fresh. Replicas cannot end it.
+`host-failed` and `room-over` are terminal helper errors; neither starts offline play or
+restores the failed state automatically.
+
+Browser simulation uses `performance.now()`. The helper converts outgoing timestamps to
+the room's wall clock with rising snapshot stamps. Clock corrections republish the round deadline. A callback up to a tenth of a second late (two tick periods, if that is longer) is caught up, as on the server; a later one rebases the simulation clock without blaming rules, so a browser whose timers are that late runs slow and yields to a faster one.
+Hidden local hosts pause; visible hosts resume at the same tick. With another player present,
+the hidden host checkpoints and yields as before. Server isolate overrun enforcement is
+explicitly enabled only by the server adapter.
+
+Server-hosted games with offline enabled fetch a separate rules entry after playable.
+Private games (`offline: false`) have no local rules import. Local play sends no snapshots,
+checkpoints, results or state to the relay. A dropped connection tries for five seconds
+before local play starts when rules are available; reconnecting announces the switch to
+the online round. Production bundles do not read Lab stage or tuning globals.
+
+The browser relay and rules build share `worker/limits.mjs`. The rules view receives the
+same table without adding imports to vendored connection helpers. Rules sizes are UTF-8
+JSON bytes, including the runtime marker. Old-style games count characters, as before.
+For tick rate H and seat count S, the shared allowances are:
+
+| Frame | Bytes through 16 seats | Bytes above 16 seats | Tokens/second |
+| --- | --- | --- | --- |
+| Snapshot | 16,384 | 16,384 | max(30, ceil(1.25 H)) |
+| Checkpoint | 65,536 | 131,072 | 4 |
+| Shared state | 8,192 | 8,192 | H + 64 |
+| Event, including effects | 4,096 | 4,096 | ceil((H + 10S + 32) / 0.8) |
+| Round | 8,192 | 16,384 | 8 |
+| Roster | 4,096 | 8,192 | 2S + 8 |
+| Decision | 6,144 | 6,144 | ceil((H + 5S + 8) / 0.8) |
+| Caps / rules-end | 512 | 512 | 4 |
+
+The relay's token bucket holds two seconds of each allowance. For every kind but the
+snapshot the sender refills at 80% of that rate and holds one second of tokens, which
+leaves headroom for transport batching and late timers. A snapshot spends the relay's
+whole rate with two tokens in hand: a tick that runs on time sends its snapshot at once,
+so a browser host sends a snapshot a tick at any tick rate, as the server does, and the
+quarter above the tick rate absorbs the ticks a late timer runs together. Only snapshots
+coalesce. All other runtime output, including checkpoints and decisions, shares one
+ordered FIFO, and each frame leaves as soon as its own kind has a token: nothing reliable
+waits for a snapshot's.
+A snapshot over the relay allowance drops. Reliable output over it moves the rules to
+another player with `host-fault` explaining the change; that socket is not elected again
+(a page that reconnects is a newcomer, behind every other candidate). The
+room ends only if no eligible host remains. Player rate errors never end the room.
+
+**Giving the role up is one ordered act.** A rules host that yields (its tab is hidden, it
+runs slow, the game calls `handOff()`) saves a checkpoint and puts `yield` behind it in the
+same FIFO, so the relay elects with the tick the room is on. From the yield on, the sender
+holds what the rules make until the relay answers: a `role` to somebody else discards it
+(the next host makes those ticks itself), and `{ t: 'host', host, why: 'host-kept' }`, sent
+to everyone in a rules room whose host's yield elected nobody, releases it in order. Two seconds without an answer
+release it too. `ping` does not report `hid: true` while a yield is still queued. A page
+that closes (`pagehide`, `close()`) sends what its allowances permit, in order, then its
+last checkpoint whatever the checkpoint allowance says (the relay's bucket holds twice the
+sender's), then `bye`; a frame it could not send is covered by that checkpoint.
+
+**Everything the rules say goes one way.** The helper sends no `round`, `roster`, `state`,
+`caps`, `snap`, `ckpt` or `decide` of its own in a rules game. A host that reconnects and
+is still the host (the relay may have restarted with an old save or none) asks its runtime
+to announce: the round with its results, the roster, the shared state and the capabilities
+leave as marked output, then a checkpoint. A promoted host that restored a checkpoint says
+its shared state with its round, since the checkpoint may be older than what the relay kept.
+A modified host can already fabricate rules output; its marker adds no authority.
+
+Effects share one frame per tick. Shared state also has a room total of 64 keys and
+65,536 bytes. Build smoke checks measure every runtime kind; browser size excesses
+fail with a measured explanation, and server builds warn. These samples are not a
+proof of every future round. Oversized runtime frames remain terminal with the
+measurement on every page. Clock-only round retimings carry no results and do not
+fire another round event. Offline players retry at most 2.5 seconds apart, and the
+browser's `online` event retries immediately.
+
+The view's guide helper never owns guides. Online commands, asks, inputs and speech go
+through the relay even on the page running the runtime. Runtime events return through the
+relay with a `hosted` mark (which a player's event cannot supply), and rosters and results
+return with the same AI labels all other views receive. A rules host's relayed speech keeps
+a live person's seat or null; older hosts retain the original sender stamping. Offline
+play uses the same runtime boundary locally and has bots, without online guides or AI.
+
+A slow host reports its achieved speed. A replacement needs a recent event-loop measurement
+at least fifty percent faster plus ten percentage points, and any measured hosting speed
+must also pass that threshold. Two equally slow hosts keep one authority. Hidden tabs and
+lost hosts still use the existing election path. Welcome and promotion frames include held
+seat identities, without tokens, so an absent person's body stays theirs after handover.
+
+A missing offline module leaves the connection helper alive and says the game needs a
+connection. A failed offline runtime stops locally while reconnection continues. An online
+runtime failure ends the room. Snapshots never grow above 16,384 bytes, including above
+sixteen seats.