@homie-rocks/studio 0.32.0 → 0.33.0

package/lib/build.mjs

@@ -30,6 +30,10 @@
  *                                          fits, for `dev` (whose R2 is empty). Workers Builds (WORKERS_CI=1) builds
  *                                          as a deploy.
  *
+ *   site/src/rules/<id>.mjs, index.mjs     for a game written as rules plus view (games/<id>/src/rules.ts): its rules as
+ *                                          one checked, guarded module for the Worker (lib/rules-build.mjs,
+ *                                          lib/rules-guard.mjs). The Table runs them: the server is the room's host.
+ *
  * game.json "build" picks how a game becomes files (a ported game keeps its own shape):
  *   (absent) / { "mode": "bundle" }   src/main.ts (or "entry") bundled by esbuild — new games and ES-module ports
  *   { "mode": "static" }              the folder copied as it is (plain <script> games), plus homie-port.js,
@@ -38,6 +42,8 @@
  *   { "mode": "command", "command": "npm run build", "out": "dist" }
  *                                     the game's own build (Vite, webpack…), then its output copied; base must be './'
  */
+import { playerImage } from './player-image.mjs';
+import { playerOrigins } from '../worker/embed.mjs';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -49,7 +55,12 @@ import { buildMedia } from './media.mjs';
 import { buildSiteFiles, isoDate, landingOf, readPosts, readTheme } from './site.mjs';
 import { checkJsonLd } from './schema-check.mjs';
 import { SCHEMA_REFUSED } from '../worker/schema.mjs';
-import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
+import { PACKAGE_ROOT, isRulesGame, listGames, readStudio } from './studio.mjs';
+
+// The rules build brings a JavaScript parser with it. It is loaded when a build first needs it, never when this
+// module is: Homie for Claude Desktop starts the toolkit with no node_modules beside it (scripts/desktop.mjs).
+let rulesBuildModule = null;
+const rulesBuild = () => (rulesBuildModule ??= import('./rules-build.mjs'));
 import { SEAT_MAX, netplayRow } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { basedOnRow, licenseOf, retiredKeys } from '../worker/license.mjs';
@@ -64,6 +75,7 @@ import { audienceOf } from '../worker/shop-rules.mjs';
 import { loungeConfig, loungeProblems } from '../worker/lounge-store.mjs';
 // GAME PARTS (parts/PARTS.md): the three call-outs below are all the build knows of them.
 import { buildParts, partsPlugin } from './parts-build.mjs';
+// RULES ON THE SERVER (NETPLAY.md section 29): a game with a src/rules.ts is built as a view bundle plus a rules module.
 
 /** Never copied into a static game's served folder. */
 const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md', 'lab.json', 'codex']);
@@ -356,7 +368,8 @@ function pointAtBundle(html, bundle) {
  * its public/ folder. What `build` serves at /games/<id>/, and what the Game Lab (lib/lab.mjs) builds New and Today
  * with. `sourcemap` is esbuild's (the lab keeps a linked map beside its builds); `maps` keeps the site build's map in
  * .studio/maps/<id>/. Returns { mode, warnings, metafile, bundle, chunks } (metafile: the bundle's inputs, null for
- * other modes; bundle: its path in `out`, null when the game has none; chunks: what it loads later).
+ * other modes; bundle: its path in `out`, null when the game has none; chunks: what it loads later; rules: for a game
+ * written as rules plus view, what lib/rules-build.mjs made of its rules, else null).
  *
  * The bundle is ES modules with code splitting: every `await import('./later')` in the game becomes a chunk of its
  * own (assets/chunk-<HASH>.js) that the browser fetches when the game asks, from beside the bundle, wherever the
@@ -372,18 +385,28 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
   let bundled = null;
   let chunks = [];
   const budgets = modelBudgetsOf(g, log);
+  // RULES PLUS VIEW (rooms on the server). A game with a src/rules.ts has its rules checked, guarded and loaded first:
+  // a rule the wall refuses stops the build here, with the line named. A game without one is hosted by a player's
+  // browser exactly as before, and cannot ask for the server.
+  const ruled = isRulesGame(g);
+  if (!ruled && g.room?.host === 'server') {
+    throw new Error(`games/${g.id}/game.json asks for "room": { "host": "server" }, but ${mode === 'bundle' ? 'this game has no src/rules.ts: its rules are inside its own code and run in a player\'s browser. Ask for it to be rewritten as rules plus view' : 'a ported game is someone else\'s browser code, which the server cannot run. It stays hosted by a player\'s browser'}.`);
+  }
+  if (ruled && mode !== 'bundle') throw new Error(`games/${g.id} has a src/rules.ts and game.json "build": { "mode": "${mode}" }. A game written as rules plus view is built by Homie itself: take the "build" setting out.`);
+  const { prepareRules, viewPlugin } = ruled ? await rulesBuild() : {};
+  const rules = ruled ? await prepareRules(esbuild, root, g, { log }) : null;
   const bundle = async (entryRel) => {
     const entry = join(g.dir, entryRel);
     if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
     const options = {
-      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: sourcemap ?? false,
+      entryPoints: [rules ? 'homie:view' : entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: sourcemap ?? false,
       outdir: join(out, 'assets'), splitting: true, entryNames: hashed ? 'main-[hash]' : 'main', chunkNames: 'chunk-[hash]',
       absWorkingDir: root, logLevel: 'silent', metafile: true,
       loader: LOADERS, assetNames: '[name]-[hash]',
       // game.json assets.budgets, read by createModels() (assets/assets.ts): a constant in the bundle, never a fetch.
       define: { __HOMIE_MODEL_BUDGETS__: JSON.stringify(budgets ?? {}) },
       // GAME PARTS: `@parts/<host>/<id>` and `@parts/<id>` resolve to the part's entry, and the game is credited.
-      plugins: [partsPlugin(root, g.id)],
+      plugins: [partsPlugin(root, g.id), ...(rules ? [viewPlugin(g, rules, entry)] : [])],
     };
     const failed = (error) => {
       const first = error.errors?.[0];
@@ -429,7 +452,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     cpSync(built, out, { recursive: true });
     writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
   } else {
-    await bundle(g.entry ?? 'src/main.ts');
+    await bundle(g.entry ?? (rules ? 'src/view.ts' : 'src/main.ts'));
     const html = join(g.dir, 'index.html');
     if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
     const text = readFileSync(html, 'utf8');
@@ -437,7 +460,15 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
   }
   if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
   if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
-  return { mode, warnings, metafile, bundle: bundled, chunks };
+  if (rules) {
+    // Only this game's executable view and rules data: buildInfo, the site and other games cannot reload its players.
+    const digest = createHash('sha256').update(rules.build);
+    for (const file of [bundled, ...chunks].filter(Boolean)) digest.update(readFileSync(join(out, file)));
+    digest.update(readFileSync(join(out, 'index.html')));
+    rules.build = digest.digest('hex').slice(0, 32);
+    if (g.netplay?.version !== undefined) log(`  ${g.id}: rules games use their build hash as the revision; netplay.version is not read`);
+  }
+  return { mode, warnings, metafile, bundle: bundled, chunks, rules };
 }
 
 /**
@@ -483,10 +514,13 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   const built = [];
   const retired = [];
   const cache = {};
+  const ruled = [];
+  const browserHosted = [];
   for (const g of games) {
     const out = join(dist, 'games', g.id);
     const started = Date.now();
-    const { mode, warnings, bundle, chunks } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true });
+    const { mode, warnings, bundle, chunks, rules } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true });
+    if (rules) ruled.push({ id: g.id, ...rules }); else browserHosted.push(g.id);
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
     // Room chat (NETPLAY.md section 19): game.json "chat", checked here (its quick lines pass the chat floor too).
@@ -509,7 +543,10 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       ...(bundle ? { bundle } : {}), ...(chunks.length ? { chunks: chunks.length, chunkBytes: later } : {}),
     });
     log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} ${chunks.length === 1 ? 'chunk' : 'chunks'} loaded later, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);
+    if (rules) log(`  ${g.id}: its rules run on the server (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; three seconds with bots: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler)`);
   }
+  // A game written before rules (its own code is the host) builds and runs exactly as it did. Said in one line.
+  if (browserHosted.length) log(`hosted by a player's browser, as before (no src/rules.ts; nothing to do): ${browserHosted.join(', ')}`);
   const all = listGames(root);
   // No game is handed over whole any more (remix was retired; worker/license.mjs). A one-game build starts from the
   // site as it is, which an older toolkit may have built: what that wrote for remixers (a game's whole source, and
@@ -533,6 +570,9 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
   // studio.json site.order: the catalogue's order is every listing's order.
   const shown = orderGames(all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))), s.order, log);
+  // Server-hosted games: what this build made, and for a one-game build what the catalogue before it said of the others.
+  const rulesOf = new Map(ruled.map((r) => [r.id, { host: 'server', tickHz: r.settings.tickHz, inputHz: r.settings.inputHz, contract: r.schema.contract, build: r.build, stateHash: r.stateHash, rounds: r.rounds }]));
+  if (only) for (const row of readJson(join(dist, 'games.json'))?.games ?? []) if (row?.room?.host === 'server' && row.id !== only && !rulesOf.has(row.id)) rulesOf.set(row.id, row.room);
   // What each game's build is (its landing's own pictures are not part of it): the digest the manifest names.
   const builds = {};
   const rows = shown.map((g) => {
@@ -540,6 +580,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     const net = netplayOf(g, join(dist, 'games', g.id));
     const { min, max } = seatsFor(g, net);
     const netRow = netplayRow(net);
+    if (rulesOf.has(g.id)) netRow.row = { ...netRow.row, version: rulesOf.get(g.id).build };
     for (const p of netRow.problems) log(`warning: games/${g.id}/game.json: ${p}`);
     const seeds = serverSeeds(g, log);
     // The game's own palette (style.json, its art direction): the play page's buttons wear its paper and ink, so the
@@ -558,11 +599,15 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     return {
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       ...(ui ? { ui } : {}),
-      roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
+      // A rules game's round is its rules' own (`room.rounds`), and its movement a per-kind choice there: game.json's
+      // `roundSeconds` and `netplay.movement` are not read for it. `room` says where its rules run, to the Worker.
+      roundSeconds: rulesOf.has(g.id) ? rulesOf.get(g.id).rounds?.seconds ?? null : g.roundSeconds ?? net.roundSeconds ?? null, movement: rulesOf.has(g.id) ? null : net.movement ?? null, cover: g.cover ?? null,
+      ...(rulesOf.has(g.id) ? { room: rulesOf.get(g.id) } : {}),
       // game.json "netplay": { "version", "stallMs", "params" } (NETPLAY.md sections 22 to 24): the game's revision (a
       // room runs one build at a time), its own host stall time, and the address's switches its frame is handed.
       ...(netRow.row ? { netplay: netRow.row } : {}),
       ...(g.screen ? { screen: g.screen } : {}),
+      ...(g.playerCard === false ? { playerCard: false } : {}),
       // game.json "saves": true — player accounts and cloud saves (saves/SAVES.md): the play shell answers the game's
       // saves calls, and the site's nav and the game's landing offer a player account.
       ...(g.saves === true || (g.saves && typeof g.saves === 'object') ? { saves: true } : {}),
@@ -616,6 +661,9 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       // studio.json "site": { "schema": { … } }: the owner's own schema.org properties on the studio (sameAs, …).
       ...(studioExtras ? { schema: studioExtras } : {}),
       site: {
+        ...(/^@[A-Za-z0-9_]{1,15}$/.test(s.twitterSite || '') ? { twitterSite: s.twitterSite } : {}),
+        ...(s.playerCard === false ? { playerCard: false } : {}),
+        ...(Array.isArray(s.playerCardOrigins) ? { playerCardOrigins: playerOrigins(s.playerCardOrigins) } : {}),
         ...(rows.some((g) => g.id === s.featured) ? { featured: s.featured } : {}),
         ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),
       },
@@ -645,6 +693,10 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     // shop.json, checked (nothing secret is ever in it): the Worker sells from this and checks it again.
     ...(shop ? { shop } : {}),
   };
+  for (const game of rows) {
+    const image = await playerImage(catalogue, game, dist, log);
+    if (image) game.playerImage = image;
+  }
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   // What this build made, for whatever runs next (a deploy says which games it changes; a script checks the live
   // site against it): per game its digest, its bundle and chunks, and whether it differs from the build before.
@@ -660,11 +712,14 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // A deploy builds first and prints its own result, not the build's: so the build a deploy is about to ship says
   // here which games it changes and which build each is (`homie-studio build` prints the same from its result).
   if (deploy) for (const b of built) log(`  ${b.id}: ${b.changed}${b.changed === 'new' ? '' : ' since the last build here'}, build ${b.hash}`);
+  // The rules of the server-hosted games, where the studio's Worker imports them (site/src/rules/). Written with the
+  // site, never before: a game that did not build has left both as they were.
+  const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.has(g.id)).map((g) => g.id));
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);
   return {
     ok: true, command: 'build', dist: live, games: built, catalogue: catalogue.games.map((g) => g.id),
-    builds: report, swapped, ...(typed ? { types: typed } : {}),
+    builds: report, swapped, ...(typed ? { types: typed } : {}), ...(hosted.length ? { hosted } : {}),
     // One plain note for the whole build, however many games and keys it is about (never one a key).
     ...(retired.length ? { retired: `Remix was retired, and games now build on each other through parts (pieces a studio shares; ask for a part, or see parts/PARTS.md). These settings no longer do anything and can be deleted: ${retired.join('; ')}. No game's source is served whole; a game made from another keeps its credit.` } : {}),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped, mediaNotes: media.notes ?? [],

package/lib/cf-usage.mjs

@@ -0,0 +1,76 @@
+/**
+ * Cloudflare's own figures for a studio's rooms, read from its GraphQL Analytics API: what the rooms of one Worker
+ * (or one room object) were billed for over a stretch of time. It is how the real-Cloudflare measurement of a
+ * server-hosted room (T1 in rooms-milestone-1-design.md, section 12) is checked against the arithmetic the deploy
+ * plan states (lib/cloudflare.mjs `hostedUse`), and how "a room everyone has left stops being billed" is seen on
+ * Cloudflare's side and not only in the room's own log.
+ *
+ * It reads; it changes nothing. It needs an API token that may read Account Analytics, which the caller supplies
+ * (never stored, never logged, never in a result).
+ *
+ * NOT YET RUN AGAINST CLOUDFLARE. The two datasets and their fields are Cloudflare's published ones
+ * (`durableObjectsInvocationsAdaptiveGroups`, `durableObjectsPeriodicGroups`), but this file has only been run
+ * against a stand-in for the API (test/rules-usage.test.mjs). Its first real run must confirm the field names and
+ * the units before any number from it is quoted.
+ */
+import { hostedUse } from './cloudflare.mjs';
+
+const ENDPOINT = 'https://api.cloudflare.com/client/v4/graphql';
+const QUERY = `query RoomUsage($account: String!, $filter: AccountDurableObjectsInvocationsAdaptiveGroupsFilter_InputObject!, $periodic: AccountDurableObjectsPeriodicGroupsFilter_InputObject!) {
+  viewer { accounts(filter: { accountTag: $account }) {
+    invocations: durableObjectsInvocationsAdaptiveGroups(limit: 10000, filter: $filter) { sum { requests errors responseBodySize wallTime } }
+    periodic: durableObjectsPeriodicGroups(limit: 10000, filter: $periodic) { sum { activeTime cpuTime duration inboundWebsocketMsgCount outboundWebsocketMsgCount rowsRead rowsWritten subrequests exceededCpuErrors exceededMemoryErrors fatalInternalErrors } }
+  } }
+}`;
+
+/** Cloudflare bills twenty incoming socket messages as one request. */
+export const SOCKET_MESSAGES_PER_REQUEST = 20;
+
+const total = (groups, key) => (Array.isArray(groups) ? groups : []).reduce((n, g) => n + (Number(g?.sum?.[key]) || 0), 0);
+
+/**
+ * What Cloudflare counted between `since` and `until` (ISO times) for the Durable Objects of one Worker script,
+ * or for one object of it (`objectId`).
+ * Returns { ok, requests, socketMessagesIn, socketMessagesOut, billedRequests, gbSeconds, cpuMs, activeMs, rowsWritten,
+ * rowsRead, errors, exceeded } or { ok: false, why }.
+ */
+export async function cfUsage({ accountId, token, script, since, until, objectId = null, fetchFn = globalThis.fetch }) {
+  if (!accountId || !token || !script) return { ok: false, why: 'needs the account id, an API token that may read Account Analytics, and the Worker\'s name' };
+  if (Number.isNaN(Date.parse(since)) || Number.isNaN(Date.parse(until)) || Date.parse(until) <= Date.parse(since)) return { ok: false, why: 'needs a stretch of time: since and until, as ISO times' };
+  const filter = { datetime_geq: new Date(since).toISOString(), datetime_leq: new Date(until).toISOString(), scriptName: script, ...(objectId ? { objectId } : {}) };
+  let body;
+  try {
+    const res = await fetchFn(ENDPOINT, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify({ query: QUERY, variables: { account: accountId, filter, periodic: filter } }), signal: AbortSignal.timeout(30_000) });
+    body = await res.json();
+    if (!res.ok || body?.errors?.length) return { ok: false, why: `Cloudflare's analytics answered ${res.status}${body?.errors?.length ? `: ${String(body.errors[0]?.message ?? '').slice(0, 200)}` : ''}` };
+  } catch (error) {
+    return { ok: false, why: `Cloudflare's analytics could not be reached: ${String(error?.message ?? error).slice(0, 120)}` };
+  }
+  const acct = body?.data?.viewer?.accounts?.[0];
+  if (!acct) return { ok: false, why: 'Cloudflare\'s analytics has nothing for that account' };
+  const requests = total(acct.invocations, 'requests');
+  const messagesIn = total(acct.periodic, 'inboundWebsocketMsgCount');
+  return {
+    ok: true, script, ...(objectId ? { objectId } : {}), since: filter.datetime_geq, until: filter.datetime_leq, hours: (Date.parse(until) - Date.parse(since)) / 3_600_000,
+    requests, socketMessagesIn: messagesIn, socketMessagesOut: total(acct.periodic, 'outboundWebsocketMsgCount'),
+    billedRequests: requests + Math.ceil(messagesIn / SOCKET_MESSAGES_PER_REQUEST),
+    gbSeconds: total(acct.periodic, 'duration'),
+    // Cloudflare reports processor and active time in microseconds.
+    cpuMs: total(acct.periodic, 'cpuTime') / 1000, activeMs: total(acct.periodic, 'activeTime') / 1000,
+    rowsWritten: total(acct.periodic, 'rowsWritten'), rowsRead: total(acct.periodic, 'rowsRead'),
+    errors: total(acct.invocations, 'errors'),
+    exceeded: { cpu: total(acct.periodic, 'exceededCpuErrors'), memory: total(acct.periodic, 'exceededMemoryErrors'), internal: total(acct.periodic, 'fatalInternalErrors') },
+  };
+}
+
+/**
+ * Cloudflare's figures for one room beside what the deploy plan says such a room uses: per room-hour, with how far
+ * each is from the estimate. T1's line is 10% for requests and GB-seconds.
+ */
+export function compareUse(use, { seats = 8, inputHz = 20, roomHours = use?.hours ?? 1 } = {}) {
+  if (!use?.ok || !(roomHours > 0)) return null;
+  const plan = hostedUse({ seats, inputHz });
+  const row = (measured, estimate) => ({ measured: Math.round(measured * 10) / 10, estimate, off: estimate ? Math.round(((measured - estimate) / estimate) * 1000) / 10 : null });
+  const out = { roomHours, requests: row(use.billedRequests / roomHours, plan.requests), gbSeconds: row(use.gbSeconds / roomHours, plan.gbSeconds), rowsWritten: row(use.rowsWritten / roomHours, plan.rows) };
+  return { ...out, within10: Math.abs(out.requests.off) <= 10 && Math.abs(out.gbSeconds.off) <= 10 };
+}

package/lib/cloudflare.mjs

@@ -40,7 +40,7 @@ import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
 import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, configPath, domainOrigin, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -161,9 +161,30 @@ export async function zonePlan(root, opts = {}) {
   return z ? zoneView(z) : null;
 }
 
+/**
+ * What an hour of play in one full room of a server-hosted game uses of the free plan's three daily allowances for
+ * Durable Objects (NETPLAY.md section 29; the arithmetic is Cloudflare's published pricing): incoming socket messages
+ * are billed 20 to 1 (at most `inputHz` input frames a second a player, and a ping every two seconds); an object in
+ * memory is billed as 128 MB; and until a room is saved (a later release) it writes only its alarm, twelve times an
+ * hour. Estimates, for the plan to say. Homie limits nothing because of them.
+ */
+export function hostedUse({ seats = 8, inputHz = 20 } = {}) {
+  const requests = Math.round((seats * (inputHz * 3600 + 1800)) / 20);
+  const gbSeconds = 0.128 * 3600;
+  const pct = (n, of) => (n / of < 0.001 ? 'under 0.1%' : `${Math.round((n / of) * 1000) / 10}%`);
+  return { seats, requests, gbSeconds, rows: 12, share: { requests: pct(requests, 100_000), gbSeconds: pct(gbSeconds, 13_000), rows: pct(12, 100_000) } };
+}
+
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
 export function deployPlan(root) {
   const studio = readStudio(root);
+  // Games whose rules run on the server (a src/rules.ts, and not "room": { "host": "browser" }): one line each.
+  const hosted = listGames(root).filter((g) => isRulesGame(g) && g.room?.host !== 'browser').map((g) => {
+    const seats = Math.max(1, Math.min(32, Math.floor(Number(g.players?.max)) || 8));
+    const tickHz = Math.max(1, Math.min(60, Math.floor(Number(g.room?.tickHz)) || 20));
+    const use = hostedUse({ seats, inputHz: Math.max(1, Math.min(tickHz, Math.floor(Number(g.room?.inputHz)) || tickHz)) });
+    return { id: g.id, name: g.name ?? g.id, ...use };
+  });
   const cf = { created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
   const storage = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
@@ -173,7 +194,8 @@ export function deployPlan(root) {
     cloudflare: [
       { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
       { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
-      { kind: 'Durable Object', name: 'Table', what: 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
+      { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
+      ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `the rules of ${h.name} run on Cloudflare, in each room's Table, not in a player's browser. An hour of play in one full room (${h.seats} players) uses about ${h.share.requests} of the free plan's 100,000 requests a day, ${h.share.gbSeconds} of its 13,000 GB-seconds of running time and ${h.share.rows} of its 100,000 rows written. A room with nobody in it uses nothing. Out of requests, every room of every game stops until 00:00 UTC; the Workers Paid plan removes the three allowances`, state: 'in the Worker', plan: 'Workers Free' })),
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       storage
         ? { kind: 'R2 bucket', name: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
@@ -189,6 +211,7 @@ export function deployPlan(root) {
       stores: 'the site\'s address and a claim token, the studio\'s name and slug, the @homie-rocks/studio version, and each game\'s id, name, blurb and Play/page links. Never code, media, keys or accounts.',
     },
     never: 'It never touches a Worker, database or bucket this studio did not create, and it never adds a payment method or buys anything.',
+    ...(hosted.length ? { hosted } : {}),
   };
 }
 

package/lib/dev.mjs

@@ -25,14 +25,14 @@
  * named and left alone.
  */
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join, sep } from 'node:path';
 import { detectLocalAi, localAiVars } from './local-ai.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 import { routesOf } from './routes.mjs';
 import { ensureMigrations, migrationWord } from './scaffold.mjs';
-import { listGames, workerDir } from './studio.mjs';
+import { isRulesGame, listGames, workerDir } from './studio.mjs';
 
 export const devFile = (root) => join(workerDir(root), '.wrangler', 'homie-dev.json');
 
@@ -281,6 +281,25 @@ function passLines(stream, to, opts) {
   stream.on('end', () => { if (rest) to.write(relayLines(rest, opts).join('\n')); });
 }
 
+/**
+ * RULES ON THE SERVER, WHILE DEV RUNS (NETPLAY.md section 29). A game whose rules run in the Table is in the Worker's
+ * own bundle (site/src/rules/), so a change to its rules, its movement, its tunables, its map or its settings is live
+ * only after a build: the build checks and guards the rules again and writes the module, and Wrangler, which watches
+ * the Worker's files, restarts the local Worker with it. dev does that build by itself when one of those files is
+ * saved. `rulesStamp` is what it compares: the newest change among them, and how many there are.
+ */
+export function rulesStamp(g) {
+  const files = [join(g.dir, 'game.json'), join(g.dir, 'tunables.json')];
+  for (const sub of ['src', 'map']) {
+    const dir = join(g.dir, sub);
+    if (existsSync(dir)) for (const name of readdirSync(dir, { recursive: true })) files.push(join(dir, String(name)));
+  }
+  let newest = 0;
+  let n = 0;
+  for (const f of files) { try { const st = statSync(f); if (st.isFile()) { n += 1; newest = Math.max(newest, st.mtimeMs); } } catch { /* gone */ } }
+  return `${n}:${Math.round(newest)}`;
+}
+
 const builtIds = (root) => { try { return JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { return null; } };
 
 /**
@@ -337,7 +356,7 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
   }
   // --remote-ai: Wrangler's --local turns every remote binding off ("not supported"), so a dev with the real Workers AI
   // (the guides' brains, room chat's review) runs without it; everything else stays local all the same.
-  const args = ['dev', ...(remoteAi ? [] : ['--local']), '--ip', '127.0.0.1', '--port', port, ...ai.args, ...localVars];
+  const args = ['dev', ...(remoteAi ? [] : ['--local']), '--ip', '127.0.0.1', '--port', port, '--var', 'HOMIE_EMBED_PREVIEW:1', ...ai.args, ...localVars];
   log(`Stop it with: ${stop}   (this studio's dev server only)`);
 
   let child = null;
@@ -391,7 +410,29 @@ export async function dev(root, { port: askedPort = 8787, remoteAi = false, loca
       }
     } finally { busy = false; }
   };
-  const timer = setInterval(() => { look().catch(() => {}); }, watchMs);
+  // A rules game saved while dev runs is built again (see rulesStamp), one game at a time.
+  const stamps = new Map(listGames(root).filter(isRulesGame).map((g) => [g.id, rulesStamp(g)]));
+  let rebuilding = false;
+  const rulesLook = async () => {
+    if (rebuilding || ending) return;
+    for (const g of listGames(root).filter(isRulesGame)) {
+      const now = rulesStamp(g);
+      if (stamps.get(g.id) === now) continue;
+      stamps.set(g.id, now);
+      rebuilding = true;
+      try {
+        log(`games/${g.id} changed: checking its rules and building it again…`);
+        const hash = () => { try { return JSON.parse(readFileSync(join(root, 'site/dist/games.json'), 'utf8')).games.find((x) => x.id === g.id)?.room?.stateHash; } catch { return null; } };
+        const before = hash();
+        await build(root, { only: g.id, log });
+        log(`games/${g.id} is rebuilt. ${before && before === hash() ? 'Local rooms resume their saved match; pages reconnect.' : 'The stored shape changed: local rooms reset to a fresh match; pages reconnect.'}`);
+      } catch (error) {
+        log(`games/${g.id} did not build, so the local site still runs what it had:\n${String(error?.message ?? error)}`);
+      } finally { rebuilding = false; }
+      return;
+    }
+  };
+  const timer = setInterval(() => { look().catch(() => {}); rulesLook().catch(() => {}); }, watchMs);
   timer.unref?.();
 
   /** Wait for the local site, then hold it to its own address (socketOriginProblem); a mismatch ends dev. */

package/lib/lab-check.mjs

@@ -111,10 +111,11 @@ export async function labCheck(root, id, { take = null, today = 'HEAD', device =
   const dir = out ?? join(labDir(root, game), `check-${stamp}`);
   mkdirSync(dir, { recursive: true });
   const server = await startLabServer(root, { port: 0, today, watchFiles: false, log: () => {} });
-  const browser = await puppeteer.launch({
+  let browser;
+  try { browser = await puppeteer.launch({
     executablePath: chrome, headless: true, timeout: 150_000, protocolTimeout: 240_000,
     args: [...chromeArgs(), '--mute-audio', '--window-size=1600,1000', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows', '--force-color-profile=srgb'],
-  });
+  }); } catch (error) { await server.close(); throw error; }
   const t0 = Date.now();
   try {
     const page = await browser.newPage();

package/lib/mcp-tools.mjs

@@ -1096,7 +1096,7 @@ export function toolDefs(ctx, avail = {}) {
           if (!r.ended) return stillRunning(r.job, 'The deploy plan');
           if (r.job.code !== 0) return fail(whyOf(r.job));
           const p = r.result;
-          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), ...(p.zone?.warning ? [`Warning (say this to the person as it is): ${p.zone.warning}`] : p.zone?.why ? [p.zone.why] : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
+          return ok([`What going online does for ${p.studio}:`, 'Rules rooms resume when their stored shape matches. Changes to fields, declaration order or maximum seats start a fresh match.', ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), ...(p.zone?.warning ? [`Warning (say this to the person as it is): ${p.zone.warning}`] : p.zone?.why ? [p.zone.why] : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
         }
         const studio = readStudio(root);
         return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy', ...(a.ownRoute === true ? ['--own-route'] : [])] }] });

package/lib/mcp.mjs

@@ -1,7 +1,7 @@
 /**
  * `homie-studio mcp` — the studio toolkit as a LOCAL MCP server (stdio), so the chat that shows Homie's cards also
  * does the building: in the Claude desktop app through the Homie extension (.mcpb, desktop/ in this repository), in
- * Claude Code, Codex or any MCP client. The remote Homie MCP (homie.rocks/mcp) coordinates (directory, grants, hub,
+ * Claude Code, Codex or any MCP client. The remote Homie MCP (homie.rocks/mcp) coordinates (directory, hub,
  * progress relay for phones); this one does the work on this computer: studios, games, builds, checks with real
  * browsers, deploys. Tools that overlap the remote ones keep their names and input shapes (lib/mcp-tools.mjs).
  *

package/lib/office.mjs

@@ -32,9 +32,16 @@ export async function withKey(root, url, fn) {
   if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
   const local = loopback(site);
   const k = mint(root, studio, 'office', 10 * 60_000, { local });
+  let expiresAt = Date.now() + 10 * 60_000;
   if (!k.ok) return { ok: false, why: /no such table: stats_keys/.test(k.why) ? k.why : k.why };
   try {
     const call = async (path, body = null) => {
+      if (Date.now() >= expiresAt - 60_000) {
+        expiresAt = Date.now() + 10 * 60_000;
+        const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+        const renewed = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `UPDATE stats_keys SET expires_at = ${expiresAt} WHERE hash = '${k.hash}';`]);
+        if (renewed.code !== 0) throw new Error('could not renew the office key; run again to resume statements');
+      }
       const res = await fetch(`${site}${path}`, {
         method: body ? 'POST' : 'GET',
         headers: { authorization: `Bearer ${k.key}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },

package/lib/perf.mjs

@@ -477,8 +477,10 @@ async function oneRun({ puppeteer, chrome, root, url, game, device, k, seconds,
       const win = await windowOf(h, a[i], b[i], seconds);
       win.heap.afterGcMb = round((after[i].m.JSHeapUsedSize ?? NaN) / 1048576, 2);
       win.heap.gcGrowthMbPerMin = round((((after[i].m.JSHeapUsedSize ?? NaN) - (a[i].m.JSHeapUsedSize ?? NaN)) / 1048576) / (win.seconds / 60), 2);
-      const shell = await T(h.page.evaluate(() => { const s = window.__shell; if (!s) return null; const t = s.stats ?? {}; return { role: t.role ?? null, seat: s.seat ?? null, peers: t.peers ?? null, snapHzOut: t.snapHzOut ?? null, snapHzIn: t.snapHzIn ?? null, inputHzOut: t.inputHzOut ?? null, inputHzIn: t.inputHzIn ?? null, lastSnapBytes: t.lastSnapBytes ?? null, maxSnapBytes: t.maxSnapBytes ?? null, bytesOutPerS: t.bytesOutPerS ?? null, bytesInPerS: t.bytesInPerS ?? null, rtt: t.rtt ?? null, interpDelay: t.interpDelay ?? null, starvedPct: t.starvedPct ?? null, reconnects: t.reconnects ?? null, link: s.link && typeof s.link === 'object' ? s.link.state ?? null : null, stale: s.stale ? s.stale.ver ?? true : null, reloaded: s.reloaded ?? 0 }; }), 5000);
-      const role = shell?.role === 'host' ? 'host' : 'replica';
+      const shell = await T(h.page.evaluate(() => { const s = window.__shell; if (!s) return null; const t = s.stats ?? {}; return { role: t.role ?? null, seat: s.seat ?? null, peers: t.peers ?? null, snapHzOut: t.snapHzOut ?? null, snapHzIn: t.snapHzIn ?? null, inputHzOut: t.inputHzOut ?? null, inputHzIn: t.inputHzIn ?? null, lastSnapBytes: t.lastSnapBytes ?? null, maxSnapBytes: t.maxSnapBytes ?? null, bytesOutPerS: t.bytesOutPerS ?? null, bytesInPerS: t.bytesInPerS ?? null, rtt: t.rtt ?? null, interpDelay: t.interpDelay ?? null, starvedPct: t.starvedPct ?? null, reconnects: t.reconnects ?? null, link: s.link && typeof s.link === 'object' ? s.link.state ?? null : null, stale: s.stale ? s.stale.ver ?? true : null, reloaded: s.reloaded ?? 0, hosted: s.facts?.hosted ?? null, ticks: s.facts?.ticks ?? null }; }), 5000);
+      // A room whose rules run on the server (NETPLAY.md section 29) has no browser host: both browsers are replicas,
+      // and the second is named apart so its numbers and pictures do not land on the first's.
+      const role = shell?.role === 'host' ? 'host' : run.browsers.some((b) => b.role === 'replica') ? 'replica-2' : 'replica';
       // A browser that ended the window cut off from its room (the helper's link: reconnecting, alone, offline,
       // closed) was not measured playing with the other one: the run is labelled and left out, never judged.
       if (shell) shell.link = linkOf(shell.link);
@@ -492,7 +494,10 @@ async function oneRun({ puppeteer, chrome, root, url, game, device, k, seconds,
       await T(h.page.screenshot({ path: shot, type: 'png', clip: { x: 0, y: 0, width: vp.width, height: vp.height, scale } }), 15_000);
       run.browsers.push({ role, seat: shell?.seat ?? null, load: h.loadInfo, ...win, render: renderCostOf(cost[i]) ?? { samples: 0, drawCalls: null, triangles: null, note: 'not exposed by the game (exposePort extra: drawCalls, triangles): runtime scene cost was not measured' }, netplay: shell, errors: h.errors.slice(0, 10), screenshot: existsSync(shot) ? relative(out, shot) : null });
     }
-    if (!run.browsers.some((x) => x.role === 'host')) run.blocked ??= 'neither browser became the room\'s host';
+    // The server is such a room's host, and that is a valid room: its tick figures come from the room's watch feed.
+    const hosted = run.browsers.find((x) => x.netplay?.hosted === 'server');
+    if (hosted) run.room = { hosted: 'server', ticks: hosted.netplay.ticks ?? null };
+    else if (!run.browsers.some((x) => x.role === 'host')) run.blocked ??= 'neither browser became the room\'s host';
     if (profile) {
       // A window of its own, still playing: a profiler slows what it watches, so the measured window above never has one.
       const maps = mapsFor(root, game);

package/lib/player-image.mjs

@@ -0,0 +1,40 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { PLAYER_IMAGE, playerEnabled, playerImageRule } from '../worker/embed.mjs';
+
+/**
+ * The picture a game's player card shows, measured by the build: the first of the wide landing still, the landing
+ * cover, the game's cover and the studio's social picture that X's reference says will render (worker/embed.mjs
+ * PLAYER_IMAGE: format, pixel count, size) and that this build can read whole. A refused picture is a warning
+ * naming the file and the rule, and the page keeps the picture card it had. A picture whose shape is not the
+ * player's still gets the card: the reference only says the two "should" match, so that is a warning too.
+ * Only built local files are measured; a remote picture can change without this build knowing.
+ */
+export async function playerImage(cat, game, dist, log) {
+  if (!playerEnabled(cat, game)) return null;
+  const sources = [...new Set([game.landing?.hero?.wideImage, game.landing?.cover,
+    game.cover ? `/games/${game.id}/${game.cover}` : null, cat.studio.theme?.social].filter(Boolean))];
+  const warn = (file, rule) => log(`warning: ${file}: player card needs ${rule}; keeping the picture card unless another image qualifies.`);
+  if (!sources.length) warn(`games/${game.id}/game.json`, 'a cover or a studio social picture in the built site (starters do not include one)');
+  const root = realpathSync(dist);
+  for (const src of sources) {
+    if (!src.startsWith('/') || src.startsWith('//')) { warn(src, 'a local image the build can measure'); continue; }
+    if (!/\.(jpe?g|png|webp|gif)$/i.test(src)) { warn(src, 'JPG, PNG, WEBP or GIF; SVG and AVIF are unsupported'); continue; }
+    try {
+      const file = realpathSync(resolve(dist, '.' + src));
+      if (!file.startsWith(root + sep)) throw new Error('outside built assets');
+      const bytes = statSync(file).size;
+      if (!(bytes < PLAYER_IMAGE.maxBytes)) { warn(src, 'an image under 5 MB'); continue; }
+      const sharp = (await import('sharp')).default;
+      const data = readFileSync(file);
+      const { width, height, format } = await sharp(data).metadata();
+      const rule = playerImageRule({ width, height, format, bytes });
+      if (rule === 'format') { warn(src, 'JPG, PNG, WEBP or GIF image contents'); continue; }
+      if (rule) { warn(src, `at least 68,600 pixels; found ${width}×${height}`); continue; }
+      // Decode as well as reading headers: a truncated/corrupt file is not a usable card picture.
+      await sharp(data).resize(1, 1).raw().toBuffer();
+      return { src, width, height, format, bytes };
+    } catch { warn(src, 'a readable, complete image in the built assets'); }
+  }
+  return null;
+}