@homie-rocks/studio 0.5.0 → 0.6.0

package/lib/stats.mjs

@@ -0,0 +1,125 @@
+/**
+ * `homie-studio stats` — the studio's own numbers, for its owner (worker/stats.mjs says what is counted).
+ *
+ *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>]
+ *                                  the numbers, read with a key that lives ten minutes and is dropped after
+ *   homie-studio stats key [--hours 1]    a read key for the Homie MCP tool `studio_stats` (up to 30 days)
+ *   homie-studio stats link               a one-time link that opens /_studio/stats in the owner's browser
+ *   homie-studio stats revoke             every key and page session ends now
+ *   homie-studio stats share on|off       tell the homie.rocks directory "played this week" (two numbers), or stop
+ *
+ * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN. A key is minted here, on this computer, and only
+ * its SHA-256 goes into the studio's D1 (through Wrangler, which only the studio's owner is signed in to). The key
+ * itself is never sent to Cloudflare, never written to a file, and lives for its hours only. A studio running
+ * locally (`npm run dev`, a loopback --url) uses the local D1.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { runner } from './cloudflare.mjs';
+import { readStudio, siteUrl, writeStudio } from './studio.mjs';
+
+const HOUR = 3600_000;
+const RANGES = new Set(['1d', '7d', '30d', '90d']);
+const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
+
+function siteOf(root, url) {
+  const studio = readStudio(root);
+  const site = String(url || siteUrl(root, studio) || '').replace(/\/+$/, '');
+  if (!/^https?:\/\//.test(site)) return { studio, site: null };
+  return { studio, site };
+}
+
+/** Put a key's hash into the studio's D1 (remote, or local for a loopback site). The key never leaves this machine. */
+function mint(root, studio, kind, ttlMs, { local }) {
+  const key = `hsk_${randomBytes(24).toString('hex')}`;
+  const hash = createHash('sha256').update(key).digest('hex');
+  const now = Date.now();
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const sql = `DELETE FROM stats_keys WHERE expires_at < ${now}; INSERT INTO stats_keys (hash, kind, expires_at) VALUES ('${hash}', '${kind}', ${now + ttlMs});`;
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', sql]);
+  if (res.code !== 0) {
+    const why = /no such table: stats_keys/i.test(res.out)
+      ? 'this studio\'s D1 has no stats tables yet: run `npm run deploy` (it applies migration 0002_studio_stats.sql), or `npm run dev` for a local site'
+      : /not logged in|login|authenticat/i.test(res.out) ? 'Wrangler is not signed in to this studio\'s Cloudflare: run `npx wrangler login` (the person approves once)'
+        : `could not write the key's hash to D1: ${res.out.trim().split('\n').slice(-3).join(' ')}`;
+    return { ok: false, why };
+  }
+  return { ok: true, key, hash, expiresAt: new Date(now + ttlMs).toISOString() };
+}
+
+function drop(root, studio, hash, { local }) {
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `DELETE FROM stats_keys WHERE hash = '${hash}';`]);
+}
+
+export function statsQuery({ range, game, song, video } = {}) {
+  const q = new URLSearchParams();
+  q.set('range', RANGES.has(range) ? range : '7d');
+  if (game && SLUG.test(game)) q.set('game', game);
+  else if (song && SLUG.test(song)) q.set('song', song);
+  else if (video && SLUG.test(video)) q.set('video', video);
+  return q;
+}
+
+/** The numbers, read with a ten-minute key that is dropped as soon as they are in. */
+export async function statsShow(root, { url, range, game, song, video } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats', 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, 'read', 10 * 60_000, { local });
+  if (!k.ok) return { ok: false, command: 'stats', why: k.why };
+  try {
+    const res = await fetch(`${site}/api/stats?${statsQuery({ range, game, song, video })}`, { headers: { authorization: `Bearer ${k.key}` }, signal: AbortSignal.timeout(20_000) });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok || !body.ok) return { ok: false, command: 'stats', why: body.message ?? `${site}/api/stats answered ${res.status}` };
+    return { command: 'stats', ...body, ok: true };
+  } catch (error) {
+    return { ok: false, command: 'stats', why: `could not read ${site}/api/stats: ${error.message}` };
+  } finally { drop(root, studio, k.hash, { local }); }
+}
+
+/** A read key for `studio_stats` (the Homie MCP): 1 hour by default, 30 days at most. */
+export function statsKey(root, { url, hours } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats key', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const h = Math.max(1, Math.min(24 * 30, Math.floor(Number(hours) || 1)));
+  const k = mint(root, studio, 'read', h * HOUR, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'stats key', why: k.why };
+  return {
+    ok: true, command: 'stats key', site, key: k.key, expiresAt: k.expiresAt, hours: h,
+    use: `Call the Homie MCP tool studio_stats with { "site": "${site}", "key": "<this key>" } (and range, game, song or video). The key only reads this studio's numbers, ends at ${k.expiresAt}, and \`homie-studio stats revoke\` ends it sooner. Never paste it anywhere else.`,
+  };
+}
+
+/** A one-time sign-in link (30 minutes) that opens the private stats page in the owner's own browser. */
+export function statsLink(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats link', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const k = mint(root, studio, 'signin', 30 * 60_000, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'stats link', why: k.why };
+  return {
+    ok: true, command: 'stats link', site, link: `${site}/_studio/signin?k=${k.key}`, expiresAt: k.expiresAt,
+    use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, and keeps that browser signed in to the stats page for 30 days. It is theirs alone; do not post it anywhere.',
+  };
+}
+
+export function statsRevoke(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  const local = site ? loopback(site) : false;
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', 'DELETE FROM stats_keys;']);
+  return res.code === 0 ? { ok: true, command: 'stats revoke', site, message: 'Every stats key and page session has ended.' } : { ok: false, command: 'stats revoke', why: res.out.trim().split('\n').slice(-3).join(' ') };
+}
+
+export function statsShare(root, on) {
+  const studio = readStudio(root);
+  const share = on === 'on' || on === true || on === 'true';
+  writeStudio(root, { ...studio, stats: { ...(studio.stats ?? {}), share } });
+  return {
+    ok: true, command: 'stats share', share,
+    message: share
+      ? 'studio.json stats.share is on. After `npm run deploy`, the site tells the homie.rocks directory two numbers for the whole studio: Play presses and rounds with people in them, over the last 7 days. Nothing else leaves the studio.'
+      : 'studio.json stats.share is off. After `npm run deploy`, the site tells the directory nothing.',
+  };
+}

package/lib/studio.mjs

@@ -29,6 +29,48 @@ export function requireStudio(from) {
 export function readStudio(root) { return JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')); }
 export function writeStudio(root, studio) { writeFileSync(join(root, 'studio.json'), `${JSON.stringify(studio, null, 2)}\n`); }
 
+/*
+ * WHERE THE SITE'S ADDRESS LIVES. studio.json is committed, and a workers.dev address carries the Cloudflare
+ * account's subdomain, which is often the person's own name. So studio.json keeps only a CUSTOM domain
+ * (`cloudflare.domain`, e.g. "night-owls.example"); the workers.dev address `deploy` gets back stays on this
+ * computer in .studio/local.json, which the studio's .gitignore leaves out.
+ */
+export const LOCAL_STATE = '.studio/local.json';
+export const isWorkersDev = (url) => { try { return /\.workers\.dev$/i.test(new URL(url).hostname); } catch { return false; } };
+
+/** `cloudflare.domain` as an origin: "example.com" or "https://example.com/" become "https://example.com"; else null. */
+export function domainOrigin(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return null;
+  try {
+    const u = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+    if (u.protocol !== 'https:' || !u.hostname.includes('.') || isWorkersDev(u.origin)) return null;
+    return u.origin;
+  } catch { return null; }
+}
+
+export function readLocal(root) {
+  try { return JSON.parse(readFileSync(join(root, LOCAL_STATE), 'utf8')); } catch { return {}; }
+}
+export function writeLocal(root, patch) {
+  const path = join(root, LOCAL_STATE);
+  mkdirSync(dirname(path), { recursive: true });
+  const next = { ...readLocal(root), ...patch };
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * The studio site's public address: its custom domain (studio.json `cloudflare.domain`, or a non-workers.dev
+ * `cloudflare.url` an older studio wrote by hand), else the workers.dev address this computer's deploy got back,
+ * else an older studio.json's workers.dev `url` (until the next deploy moves it out).
+ */
+export function siteUrl(root, studio = readStudio(root)) {
+  const cf = studio.cloudflare ?? {};
+  const custom = domainOrigin(cf.domain) ?? (cf.url && !isWorkersDev(cf.url) ? domainOrigin(cf.url) : null);
+  return custom ?? readLocal(root).url ?? cf.url ?? null;
+}
+
 export function listGames(root) {
   const dir = join(root, 'games');
   if (!existsSync(dir)) return [];

package/netplay/NETPLAY.md

@@ -1,8 +1,19 @@
-# Homie netplay contract, v1 (revision 2)
-
-Status: **v1, revision 2** (2026-09-26). The wire version is `v: 1`. Everything revision
-2 added is either an optional field or a new message type, and both sides ignore types
-they do not know. A change to the contract bumps `v` and keeps v1 working.
+# Homie netplay contract, v1 (revision 3)
+
+Status: **v1, revision 3** (2026-09-30, `@homie-rocks/studio` 0.6.0). The wire version is
+`v: 1`. Everything revision 2 and 3 added is either an optional field, a new message type,
+or a change of pace inside the old caps, and both sides ignore types they do not know. A
+change to the contract bumps `v` and keeps v1 working.
+
+**What revision 3 added** (nothing on the wire changed; every v1 game plays on it):
+- **Rooms of up to 32 seats**, sized by the game's netplay manifest (section 3).
+- **One address may hold every seat plus four sockets** (section 6), so a party on one
+  Wi-Fi fills a 32-seat room with a TV beside it.
+- **The checkpoint, round and roster caps double for 17–32 seats** (section 6): a
+  32-seat courier game's checkpoint measured 56 KB against the 64 KB cap.
+- **Idle input keepalive** in the helper: an unchanged input frame goes out at most four
+  times a second (section 11).
+- Measured cost and free-plan headroom of a 32-seat room (section 11).
 
 **What revision 2 added:**
 - Interpolation measures transit time.
@@ -95,8 +106,12 @@ code.
 | `colour` | `seat % 12` | An index into a 12-colour palette. |
 
 - **Every visitor gets a seat at once**, phone or desktop. There is no gathering.
-- **Room size.** `maxPlayers` comes from the manifest. On the site the Table reads it.
-  Locally, the first visitor of an empty room sends it in `hello.max`.
+- **Room size.** `maxPlayers` comes from the game's netplay manifest: game.json's
+  `netplay.maxPlayers`, or a `netplay.json` beside game.json or in the game's build
+  (`maxPlayers` or `players.max`), else game.json's `players.max`, else 8. **A room holds
+  at most 32** (`SEAT_MAX`). `homie-studio build` writes the number into the catalogue and
+  the site's Table takes it from there; the first visitor of an empty room may lower it
+  (`hello.max`), never raise it.
 - **A dropped seat is held 60 s** for its token, which covers a reload or a network blip.
   **A visitor who is present beats one who left:** when no seat is free, the relay
   reclaims the seat that has been absent longest. Visitors who leave can never lock a
@@ -259,13 +274,15 @@ so `ev.origin` is `"null"`.
 | `in` | < 256 B | 2 KB | 20 Hz, plus an immediate flush (≤ 60 Hz) on a press edge | 60 |
 | `ev` | < 1 KB | 4 KB (512 B from a screen) | as needed | host 30, replica 10, screen 2 |
 | `state` | < 2 KB per key | 8 KB per key; **64 keys and 64 KB per room** → `state-full` | only on change | 64 |
-| `ckpt` | < 32 KB | 64 KB | 1 Hz | 4 |
-| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB | on change | 4 / 8 |
+| `ckpt` | < 32 KB | 64 KB (128 KB for 17–32 seats) | 1 Hz | 4 |
+| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB (16 / 8 KB for 17–32 seats) | on change | 4 / 8 |
 | `ping` | — | 256 B | every 2 s | 8 |
 
 **Sockets.**
-- At most `maxPlayers + 16` per room, and **12 per client address per room**. The Worker
-  passes `CF-Connecting-IP` as `conn.ip`.
+- At most `maxPlayers + 16` per room, and per client address per room **12, or every seat
+  plus four when that is more** (`perAddress`: 12 for 8 seats, 20 for 16, 36 for 32). The
+  Worker passes `CF-Connecting-IP` as `conn.ip`. Measured before revision 3: 32 visitors on
+  one address got 12 seats and 20 `too-many` refusals.
 - A client dropping more than 100 messages over the caps within 5 s is closed (`flood`).
 
 **Keep it small.**
@@ -494,6 +511,31 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
   writes/h ≈ $0.07/h, 9× everything else), or rewriting a whole log per event.
 - Re-check Cloudflare's published prices before quoting.
 
+**A 32-seat room (measured 2026-09-30, `@homie-rocks/studio` 0.6.0).** Every incoming
+socket message is a Durable Object request (billed 20:1; outgoing messages are free), and
+in a full room the replicas' inputs are nearly all of them:
+
+| 32 seats, one host | Incoming msgs/s at the relay | Requests/hour (20:1) | Free plan (100,000 a day) |
+|---|---|---|---|
+| every replica moving, input 20 Hz | ≈ 630 | ≈ 114 k | ≈ 53 room-minutes a day |
+| a game's own vendored helper, input 30 Hz | ≈ 860 | ≈ 155 k | ≈ 39 room-minutes a day |
+| half the replicas standing still, 0.6.0 helper | ≈ 415 | ≈ 75 k | ≈ 80 room-minutes a day |
+
+  - Put another way, the free plan carries roughly **28 player-hours a day** at 20 Hz input
+    (each seated player costs about one request a second). A studio that plays more than
+    that a day needs Workers Paid ($5 a month), where a full 32-seat room-hour costs about
+    $0.02 in requests plus $0.006 in duration.
+  - **Idle keepalive (helper, 0.6.0):** an input frame identical to the last one sent (same
+    avatar or intent, same held keys, no press, same reset epoch) is re-sent at most every
+    250 ms. The host already holds that frame, so nothing it reads changes. A player standing
+    still costs 4 messages a second instead of 20. A game that vendors its own copy of the
+    helper gets this by updating that copy.
+  - Keep `inputHz` at 20 unless the game needs more: 30 Hz costs 1.5× the requests.
+  - Snapshots of a real 32-seat courier game (32 bodies plus the control table) were 1.1–1.7 KB at
+    20 Hz: about 32 KB/s down per replica, 2 KB/s up. No snapshot delta or compression was
+    needed; the 2 KB target and 16 KB cap hold at 32 seats. Duration (13,000 GB-s a day free)
+    covers one busy room all day.
+
 ## 12. Trust and safety
 
 - **The host is a visitor's browser.** A modified host could fake scores. That is
@@ -569,7 +611,8 @@ npx --no-install homie-studio check my-game --url http://127.0.0.1:8787
     candidate for v2, not in v1.
 - **No lag compensation for hits.** A game can rewind a victim by the attacker's
   `rtt/2 + delay` itself.
-- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B).
+- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B;
+  a 32-body courier game's snapshot: 1.1–1.7 KB).
 - **A reload shows a bot in the player's body for about 1–2 s**, and then the player
   takes the same body back.
 - **The host is a visitor's browser** (section 12).

package/netplay/netplay.ts

@@ -161,6 +161,8 @@ export interface NetStats {
   snapHzOut: number;
   inputHzIn: number;
   inputHzOut: number;
+  /** Idle input frames not sent (identical to the last one, inside the keepalive interval). */
+  idleInputsSkipped?: number;
   lastSnapBytes: number;
   maxSnapBytes: number;
   bytesInPerS: number;
@@ -507,6 +509,13 @@ const IN_SLOW_CAP_PER_S = 15;
 const IN_SLOW_MS = 8000;
 /** A socket with this much still unsent does not queue another input frame (the newest one waits instead). */
 const IN_BACKLOG_BYTES = 2048;
+/**
+ * An input frame identical to the last one sent (same avatar or intent, same held keys, no press, same reset epoch)
+ * goes out at most this often: a player standing still says so four times a second, not twenty. The host already
+ * holds that frame, so nothing it reads changes; every incoming socket message is a Durable Object request
+ * (billed 20:1), and in a 32-seat room the replicas' inputs are nearly all of them (NETPLAY.md §11).
+ */
+const IDLE_INPUT_MS = 250;
 
 function heldList(held: Iterable<string> | Record<string, boolean> | undefined): string[] {
   if (!held) return [];
@@ -635,9 +644,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let prevHeld = new Set<string>();
   let pendingPresses: Record<string, number> = {};
   let inputTimer: ReturnType<typeof setTimeout> | null = null;
+  /** The last input frame sent, as text (idle frames repeat it at most every IDLE_INPUT_MS). */
+  let lastInputSig = '';
   /** Wall times of the input frames sent in the last second, and until when the slow cap holds. */
   const inSent: number[] = [];
   let inSlowUntil = 0;
+  let idleSkipped = 0;
   /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
   let closedWhy: string | null = null;
   /** Wall time the socket went down (0 while connected): how long a reconnect has taken. */
@@ -1071,12 +1083,17 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     const budget = inputBudgetWait();
     const backlog = (ws?.bufferedAmount ?? 0) > IN_BACKLOG_BYTES;
     if (budget > 0 || backlog) { inputTimer = setTimeout(flushInput, backlog ? Math.max(budget, 30) : budget); return; }
+    // Standing still: the host has this exact frame already. Say it again only as a keepalive.
+    const pressed = Object.keys(pendingPresses).length > 0;
+    let sig = '';
+    try { sig = JSON.stringify([pendingA, pendingHeld, mine.rs]); } catch { sig = ''; }
+    if (!pressed && sig && sig === lastInputSig && wall() - lastInputSentAt < IDLE_INPUT_MS) { idleSkipped += 1; return; }
     inSent.push(wall());
     inSeq += 1;
     const msg: Record<string, unknown> = { t: 'in', q: inSeq, a: pendingA, h: pendingHeld, r: mine.rs };
     if (Object.keys(pendingPresses).length) msg['p'] = pendingPresses;
     if (raw(msg)) {
-      inputOut.hit(wall()); pendingPresses = {};
+      inputOut.hit(wall()); pendingPresses = {}; lastInputSig = sig;
       sentHist.push({ q: inSeq, a: pendingA, h: pendingHeld, at: wall(), r: mine.rs });
       if (sentHist.length > 64) sentHist.shift();
     }
@@ -1095,7 +1112,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     const t = wall();
     return {
       role, seat, host, connected, offline, rtt, offset: Math.round(offset),
-      snapHzIn: snapIn.hz(t), snapHzOut: snapOut.hz(t), inputHzIn: inputIn.hz(t), inputHzOut: inputOut.hz(t),
+      snapHzIn: snapIn.hz(t), snapHzOut: snapOut.hz(t), inputHzIn: inputIn.hz(t), inputHzOut: inputOut.hz(t), idleInputsSkipped: idleSkipped,
       lastSnapBytes, maxSnapBytes, bytesInPerS: perSecond(bytesIn), bytesOutPerS: perSecond(bytesOut),
       interpDelay: Math.round(interpDelay()), snapAgeP90: Math.round(ageP90), starvedPct: +starvedPct.toFixed(3), rejectedSnaps,
       owned: api.owned, pending: sentHist.length, stateKeys: stateMap.size,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), song and video pages from the music/ and videos/ manifests, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",