@homie-rocks/studio 0.46.0 → 0.46.2

package/lib/crowd-probe/README.md

@@ -0,0 +1,61 @@
+# Measuring a big room
+
+Two tools, both for a trial on your own Cloudflare account. Neither is part of a studio: nothing in a studio's
+Worker imports them.
+
+- **From your computer** (`lib/crowd-load.mjs`): simulated players and two real Chrome players over your own
+  connection. What a player at home sees, up to what one connection and one computer can carry.
+
+  ```sh
+  CHROME_PATH=/path/to/chrome node node_modules/@homie-rocks/studio/lib/crowd-load.mjs \
+    --url https://<studio> --n 300 --seconds 150 --room home-300 --out reports/home-300
+  ```
+
+- **From inside Cloudflare** (this folder): what the room and its Gates can do, with no home connection in it.
+
+`lib/crowd-diagnostics.mjs` records the room's own figures beside either (a row a second), and
+`lib/crowd-summary.mjs <folder>` puts a run's steps in one table. Both players steer as the crowd-circuit
+fixture does; for another game, change the input they send.
+
+# The in-Cloudflare crowd probe
+
+A Worker that plays simulated players against a studio from inside Cloudflare's network. It separates what a
+studio's room and Gates can do from what one home connection and one busy computer can carry. It is a trial's
+tool: no studio's Worker imports it, and it is deleted when the trial is over.
+
+It proves the servers at a given number of players. It does not prove the last hop to a real player: its sockets
+never leave Cloudflare, and they are not compressed.
+
+## Deploy (in the account the studio is in, on a paid Workers plan)
+
+```sh
+cd node_modules/@homie-rocks/studio/lib/crowd-probe
+KEY=$(openssl rand -hex 24)
+npx wrangler deploy --var PROBE_KEY:$KEY
+```
+
+`wrangler` prints the probe's address (`https://homie-crowd-probe.<account>.workers.dev`). The probe answers
+nothing without the key.
+
+## Run one step
+
+```sh
+node node_modules/@homie-rocks/studio/lib/crowd-cloud.mjs \
+  --probe https://homie-crowd-probe.<account>.workers.dev --key $KEY \
+  --url https://<studio> --n 300 --seconds 150 --room cloud-300 --out reports/cloud-300
+```
+
+It opens one request to the probe for every five players, each held open for the step, adds up what they
+measured, and writes `report.json` in the shape `crowd-load.mjs` writes, so `crowd-summary.mjs` reads both.
+
+## Remove
+
+```sh
+npx wrangler delete --name homie-crowd-probe
+```
+
+## What it needs of Cloudflare
+
+- A paid plan: a request plays five players for minutes (the free plan's 10 ms of CPU a request is not enough).
+- Six connections open at once per request, which is why a request plays five players.
+- `global_fetch_strictly_public`, so its sockets reach the studio by its public address as a player's do.

package/lib/crowd-probe/client.mjs

@@ -0,0 +1,96 @@
+/**
+ * One simulated player, as the load probe plays it: says hello as the toolkit's client does (rules, coasting),
+ * decodes every snapshot, steers across the arena with a slow weave at ten inputs a second stamped a few ticks
+ * ahead, follows the room's word on how early those arrive, and names the tick it holds. No socket and no clock of
+ * its own: whoever runs it (the in-Cloudflare probe, a test) hands it messages and the time.
+ */
+import { snapshotDecoder } from '../../rules/interest.mjs';
+
+/** Counts by whole milliseconds, mergeable across players and across the Workers that ran them. */
+export class Tally {
+  constructor(bins = {}) { this.bins = bins; }
+  add(ms) { if (Number.isFinite(ms) && ms >= 0) { const k = Math.min(60000, Math.round(ms)); this.bins[k] = (this.bins[k] ?? 0) + 1; } }
+  merge(other) { for (const [k, n] of Object.entries(other?.bins ?? other ?? {})) this.bins[k] = (this.bins[k] ?? 0) + n; return this; }
+  json() {
+    const keys = Object.keys(this.bins).map(Number).sort((a, b) => a - b), count = keys.reduce((a, k) => a + this.bins[k], 0);
+    const at = (q) => { let n = 0; for (const k of keys) { n += this.bins[k]; if (n >= Math.ceil(count * q)) return k; } return null; };
+    return { count, p50: count ? at(0.5) : null, p95: count ? at(0.95) : null, p99: count ? at(0.99) : null, max: keys.at(-1) ?? 0 };
+  }
+}
+
+export function crowdClient({ index, game, send, tallies, period = 50, lead = 3 }) {
+  const decoder = snapshotDecoder(), pending = new Map();
+  const c = { index, seat: null, epoch: null, k: 0, at: 0, r: 0, own: null, lead, lastSent: 0, nextInput: 0, nextPing: 0, early: [], leadAt: 0,
+    measuring: false, frames: 0, firstTick: null, firstAt: null, lastTick: null, lastAt: null, down: 0, up: 0, inputs: 0, reports: 0, late: 0,
+    undecodable: 0, ownMissing: 0, maxGap: 0, welcomed: null, first: null, began: null, errors: [], closed: null, rawTick: undefined };
+  const say = (m, now) => { const text = JSON.stringify(m); if (c.measuring) c.up += text.length; send(text, now); };
+  return {
+    c,
+    open(now) {
+      c.began = now; c.nextPing = now + (index % 20) * 100; c.nextInput = now + (index % 10) * 10;
+      say({ t: 'hello', rules: true, v: 1, rev: 12, token: null, name: `Probe ${index}`, device: 'desk', want: 'play', canHost: false, coast: 1, game, max: 1000 }, now);
+    },
+    measure() { c.measuring = true; pending.clear(); c.firstTick = c.firstAt = null; c.frames = 0; c.down = c.up = c.inputs = c.reports = c.late = 0; c.maxGap = 0; },
+    message(text, now) {
+      if (c.measuring) c.down += text.length;
+      let m; try { m = JSON.parse(text); } catch { c.errors.push('decode'); return; }
+      if (m.t === 'welcome') { c.seat = m.seat; c.welcomed = now - c.began; if (m.full || c.seat === null) c.errors.push('unseated'); if (m.snap) this.snapshot(m.snap, now); }
+      else if (m.t === 'snap') this.snapshot(m, now);
+      else if (m.t === 'seat') c.seat = m.seat;
+      else if (m.t === 'err' || m.t === 'error') c.errors.push(`${m.code ?? m.t}: ${String(m.message ?? '').slice(0, 80)}`);
+    },
+    snapshot(raw, now) {
+      c.rawTick = raw.k;
+      const snap = decoder.decode(raw);
+      if (!snap) { c.undecodable += 1; return; }
+      const own = snap.d[1].find((e) => e[9] === c.seat && e[10] !== 1);
+      if (!own) { c.ownMissing += 1; return; }
+      if (c.first === null) c.first = now - c.began;
+      if (c.epoch !== snap.e) { pending.clear(); c.lastSent = 0; c.epoch = snap.e; }
+      const gap = c.at ? now - c.at : 0;
+      c.k = snap.k; c.at = now; c.own = own; c.r = own[2];
+      if (c.measuring) { c.firstTick ??= snap.k; c.firstAt ??= now; c.lastTick = snap.k; c.lastAt = now; c.frames += 1; c.maxGap = Math.max(c.maxGap, gap); tallies.gaps.add(gap); }
+      const control = snap.c?.find((row) => row[0] === c.seat);
+      if (!control) return;
+      if (control[3] !== -128 && control[3] !== undefined) {
+        const early = control[3] / 16;
+        if (c.measuring) {
+          c.reports += 1; if (early <= 0) c.late += 1;
+          // From the tick this player held when it stamped an input to the tick that input reached the rules:
+          // what the room, the Gate and both ways of the connection took, whatever lead the player keeps.
+          tallies.loops.add((c.lead - early) * period);
+        }
+        c.early.push(early); if (c.early.length > 40) c.early.shift();
+        if (c.early.length >= 20 && now - c.leadAt > 2000) {
+          const low = c.early.slice().sort((a, b) => a - b)[Math.floor(c.early.length / 20)];
+          if (low < 0.5 && c.lead < 12) c.lead += 1; else if (low > 1.5 && c.lead > 1) c.lead -= 1;
+          c.leadAt = now; c.early.length = 0;
+        }
+      }
+      for (const [tick, at] of pending) {
+        if (tick > control[2]) break;
+        pending.delete(tick);
+        if (c.measuring && tick === control[2]) tallies.ack.add(now - at);
+      }
+    },
+    /** Call every ten milliseconds or so. */
+    tick(now) {
+      if (c.closed) return;
+      if (now >= c.nextPing) { say({ t: 'ping', c: Math.round(now), hid: false, ...(c.rawTick !== undefined ? { g: c.rawTick } : {}) }, now); c.nextPing = now + 2000; }
+      if (!c.own || now - c.at > 2000 || now < c.nextInput) return;
+      c.nextInput += 100; if (c.nextInput <= now) c.nextInput = now + 100;
+      const k = Math.max(c.lastSent + 1, c.k + Math.min(10, Math.floor((now - c.at) / period)) + c.lead), y = c.own[3][1], east = Boolean(c.own[7][1]);
+      say({ t: 'in', e: c.epoch, k, s: [[0, east ? 127 : -127, y > 55 ? -35 : y < -55 ? 35 : Math.round(Math.sin(now / 3100 + index) * 35)]], r: c.r, g: c.rawTick }, now);
+      if (c.measuring) c.inputs += 1;
+      pending.set(k, now); c.lastSent = k;
+      for (const [tick, at] of pending) { if (now - at <= 5000) break; pending.delete(tick); }
+    },
+    close(code, reason) { c.closed = [code, String(reason ?? '')]; },
+    facts() {
+      const span = c.lastAt > c.firstAt ? c.lastAt - c.firstAt : 0;
+      return { i: index, seat: c.seat, firstStateMs: c.first, welcomeMs: c.welcomed, closed: c.closed, lead: c.lead, frames: c.frames, maxStateGapMs: c.maxGap,
+        tickHz: span ? (c.lastTick - c.firstTick) * 1000 / span : null, deliveredHz: span ? (c.frames - 1) * 1000 / span : null,
+        downBytes: c.down, upBytes: c.up, inputs: c.inputs, reports: c.reports, late: c.late, undecodable: c.undecodable, ownMissing: c.ownMissing, errors: c.errors.slice(0, 8), fresh: c.at ? true : false };
+    },
+  };
+}

package/lib/crowd-probe/worker.mjs

@@ -0,0 +1,72 @@
+/**
+ * The in-Cloudflare crowd probe: a Worker of its own that plays a few simulated players against a studio from
+ * inside Cloudflare's network, so a trial can tell what the studio's servers can do from what one home connection
+ * and one busy computer can carry. NOT part of a studio: nothing in a studio's Worker imports it. Deploy it beside
+ * the studio only for a trial (`lib/crowd-probe/README.md`), and delete it after.
+ *
+ * One request plays up to FIVE players (a Worker may hold six connections open at once) for as long as the caller
+ * keeps reading, and answers with a line of JSON every five seconds and a last one with everything it measured.
+ * `lib/crowd-cloud.mjs` opens as many requests as the step needs and adds them up.
+ *
+ * It proves the room and its Gates at that many players. It says nothing of the last hop to a real player.
+ */
+import { Tally, crowdClient } from './client.mjs';
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    if (!env.PROBE_KEY || request.headers.get('x-probe-key') !== env.PROBE_KEY) return new Response('not found', { status: 404 });
+    if (url.pathname === '/hello') return Response.json({ ok: true, probe: 1 });
+    const origin = url.searchParams.get('origin'), game = url.searchParams.get('game') ?? 'crowd-circuit', room = url.searchParams.get('room');
+    const from = Number(url.searchParams.get('from') ?? 0), count = Math.min(5, Math.max(1, Number(url.searchParams.get('count') ?? 5)));
+    const joinAt = Number(url.searchParams.get('joinAt')), rampMs = Number(url.searchParams.get('rampMs') ?? 50);
+    const measureAt = Number(url.searchParams.get('measureAt')), endAt = Number(url.searchParams.get('endAt'));
+    if (!/^https:\/\/[a-z0-9.-]+$/.test(origin ?? '') || !/^[A-Za-z0-9_-]{1,40}$/.test(room ?? '') || ![joinAt, measureAt, endAt].every(Number.isFinite) || endAt - joinAt > 900_000) return new Response('bad request', { status: 400 });
+    const { readable, writable } = new TransformStream(), writer = writable.getWriter(), encoder = new TextEncoder();
+    const line = (o) => writer.write(encoder.encode(JSON.stringify(o) + '\n')).catch(() => {});
+    const tallies = { ack: new Tally(), gaps: new Tally(), loops: new Tally() }, players = [];
+    const run = async () => {
+      const join = async (i) => {
+        const key = crypto.randomUUID().replaceAll('-', '');
+        const player = { socket: null, client: null };
+        player.client = crowdClient({ index: i, game, tallies, send: (text) => { try { player.socket?.send(text); } catch { /* closing */ } } });
+        players.push(player);
+        try {
+          await sleep(Math.max(0, joinAt + i * rampMs - Date.now()));
+          // As a browser arrives: the game's page says where its socket is.
+          const page = await fetch(`${origin}/${game}/__game/?room=${encodeURIComponent(room)}&device=desk&want=play&b=${key}`);
+          const match = (await page.text()).match(/window\.HOMIE_NET=(\{[^<]+\})<\/script>/);
+          if (!page.ok || !match) throw new Error(`bootstrap HTTP ${page.status}`);
+          const cfg = JSON.parse(match[1]);
+          const answer = await fetch(cfg.url.replace(/^ws/, 'http'), { headers: { Upgrade: 'websocket', Origin: 'null' } });
+          const socket = answer.webSocket;
+          if (!socket) throw new Error(`upgrade HTTP ${answer.status}`);
+          socket.accept(); player.socket = socket;
+          socket.addEventListener('message', (event) => { if (typeof event.data === 'string') player.client.message(event.data, Date.now()); });
+          socket.addEventListener('close', (event) => player.client.close(event.code, event.reason));
+          socket.addEventListener('error', () => player.client.close(1006, 'error'));
+          player.client.open(Date.now());
+        } catch (error) { player.client.c.errors.push(String(error?.message ?? error).slice(0, 120)); player.client.close(0, 'never connected'); }
+      };
+      const joins = Promise.all(Array.from({ length: count }, (_, n) => join(from + n)));
+      let measuring = false, lastLine = 0, lastTick = Date.now(), worstLag = 0;
+      while (Date.now() < endAt) {
+        const now = Date.now();
+        // This Worker's own lateness: how long past ten milliseconds its timer came back.
+        worstLag = Math.max(worstLag, now - lastTick - 10); lastTick = now;
+        if (!measuring && now >= measureAt) { measuring = true; for (const p of players) p.client.measure(); }
+        for (const p of players) p.client.tick(now);
+        if (now - lastLine >= 5000) { lastLine = now; await line({ t: 'sample', at: now, from, joined: players.filter((p) => p.client.c.first !== null).length, open: players.filter((p) => p.socket && !p.client.c.closed).length, measuring }); }
+        await sleep(10);
+      }
+      await joins;
+      const facts = players.map((p) => p.client.facts());
+      for (const p of players) { try { p.socket?.close(1000, 'probe step complete'); } catch { /* gone */ } }
+      await line({ t: 'final', from, count, colo: request.cf?.colo ?? null, measuredMs: Math.max(0, endAt - measureAt), worstTimerLagMs: worstLag, players: facts, tallies: { ack: tallies.ack.bins, gaps: tallies.gaps.bins, loops: tallies.loops.bins } });
+    };
+    ctx.waitUntil(run().catch((error) => line({ t: 'failed', from, error: String(error?.stack ?? error).slice(0, 400) })).finally(() => writer.close().catch(() => {})));
+    return new Response(readable, { headers: { 'content-type': 'application/x-ndjson', 'cache-control': 'no-store' } });
+  },
+};

package/lib/crowd-probe/wrangler.jsonc

@@ -0,0 +1,12 @@
+{
+  // The in-Cloudflare crowd probe (see README.md here). A trial's tool: deploy it for the trial, delete it after.
+  "name": "homie-crowd-probe",
+  "main": "worker.mjs",
+  "compatibility_date": "2026-06-01",
+  // Its sockets go to the studio by its public address, as a player's do, even when both are in one account.
+  "compatibility_flags": ["global_fetch_strictly_public"],
+  "workers_dev": true,
+  // A step holds each request open for minutes and decodes every frame five players are sent.
+  "limits": { "cpu_ms": 300000 },
+  "observability": { "enabled": false }
+}

package/lib/crowd-summary.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * One line a step for a crowd run: what the players saw (the driver's report) beside what the server did (the
+ * room's diagnostics, a row a second) and what this computer's connection could carry (the link probe).
+ *
+ *   node lib/crowd-summary.mjs <run-dir>     reads n<N>/report.json, n<N>/diagnostics.jsonl, n<N>/link.json;
+ *                                            writes summary.json and summary.md there and prints the table
+ *
+ * A step is LINK-LIMITED when the bytes the driver's sockets read reached four fifths of what the probe measured
+ * the connection carrying: its client-side latency then measures the connection, and the server's own columns
+ * (ticks a second, input transit, frames a Gate wrote per player) are the ones to read.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const sorted = (xs) => xs.filter(Number.isFinite).sort((a, b) => a - b);
+const pick = (xs, p) => { const a = sorted(xs); return a.length ? a[Math.min(a.length - 1, Math.floor(a.length * p))] : null; };
+const round = (n, d = 2) => (Number.isFinite(n) ? Math.round(n * 10 ** d) / 10 ** d : null);
+
+/** `report`: the driver's report.json. `rows`: diagnostics.jsonl, parsed. `link`: { downMBps } or null. */
+export function summarize(report, rows = [], link = null) {
+  const from = Date.parse(report.measurementStarted ?? ''), to = Date.parse(report.ended ?? '');
+  const during = rows.filter((r) => r.ok && r.ticks && (!Number.isFinite(from) || r.at >= from) && (!Number.isFinite(to) || r.at <= to));
+  const gates = during.flatMap((r) => (r.gates ?? []).filter((g) => g.subscribed > 0));
+  const seconds = report.measuredSeconds || 0;
+  const wire = report.payload?.wireDownBytes || report.payload?.downBytes || 0;
+  const wireMBps = seconds ? wire / seconds / 1e6 : null;
+  const linkMBps = link?.downMBps ?? null;
+  return {
+    // Where the players were: this computer and its connection ('home'), or inside Cloudflare's network.
+    from: report.generator === 'cloudflare' ? 'cloudflare' : 'home',
+    n: report.n, total: report.total, room: report.room, toolkit: report.toolkit ?? null, stopReason: report.stopReason ?? null,
+    joined: report.joined, connectedAtEnd: report.connectedAtEnd, disconnects: report.disconnects,
+    client: {
+      inputAckMs: { p50: report.inputAckMs?.p50 ?? null, p95: report.inputAckMs?.p95 ?? null, p99: report.inputAckMs?.p99 ?? null },
+      // A player's tick progression and the frames they received, a second: the median player, and the worst.
+      tickHz: { median: round(report.tickHz?.median), min: round(report.tickHz?.min) },
+      deliveredHz: { median: round(report.deliveredHz?.median), min: round(report.deliveredHz?.min) },
+      receiveGapMs: { p95: report.receiveGapMs?.p95 ?? null, p99: report.receiveGapMs?.p99 ?? null },
+      ackExpired: report.ackExpired ?? null,
+      compressedSockets: report.payload?.compressedSockets ?? null,
+      // Did the server agree to compress these sockets, and what it saved (decoded bytes over wire bytes).
+      compression: report.compression ?? null,
+      // Whole ticks ahead the median player stamped its input, and the share of the room's reports that said late.
+      inputLead: report.inputLead ?? null,
+      // From the tick a player held when it stamped an input to the tick that input reached the rules: the room,
+      // the Gate and the connection both ways, whatever lead the player keeps.
+      inputLoopMs: report.inputLoopMs ? { p50: report.inputLoopMs.p50, p95: report.inputLoopMs.p95, p99: report.inputLoopMs.p99 } : null,
+      // The driver's own health: a number above this is the driver's, not the server's.
+      driverLoopP99Ms: Math.max(0, ...(report.driver?.workerLoopP99Ms ?? [])) || null, driverPeakLagMs: Math.max(0, ...(report.driver?.peakTimerLagMs ?? []).filter(Number.isFinite)) || null,
+      driverLimited: Math.max(0, ...(report.driver?.peakTimerLagMs ?? []).filter(Number.isFinite)) > 250 || Math.max(0, ...(report.driver?.workerLoopP99Ms ?? [])) > 30,
+      wireKBsPerPlayer: round(seconds && report.joined && wire ? wire / seconds / report.joined / 1000 : null),
+      wireMBps: round(wireMBps || null), decodedMBps: round(seconds ? (report.payload?.downBytes ?? 0) / seconds / 1e6 : null),
+      errors: (report.errors ?? []).reduce((a, e) => a + (e.count ?? 1), 0),
+    },
+    link: { downMBps: round(linkMBps), limited: report.generator !== 'cloudflare' && linkMBps && wireMBps ? wireMBps >= linkMBps * 0.8 : null },
+    server: {
+      samples: during.length, failedPolls: rows.filter((r) => !r.ok).length,
+      maxAgeMs: pick(during.map((r) => r.diagnostics?.ageMs), 1),
+      // Ticks the rules ran a second, by the room's own clock.
+      tickRate: { median: round(pick(during.map((r) => r.tickRate), 0.5)), min: round(pick(during.map((r) => r.tickRate), 0)) },
+      // A Gate's stamp on a player's message to the room handling it.
+      inputTransitMs: { p50: pick(during.map((r) => r.inputTransitMs?.p50), 0.5), p95: pick(during.map((r) => r.inputTransitMs?.p95), 0.5), max: pick(during.map((r) => r.inputTransitMs?.max), 1) },
+      // Inputs that reached the rules after the tick they were stamped for (they apply on the next one).
+      lateInputs: (() => { const ins = during.reduce((a, r) => a + (r.ticks.ins ?? 0), 0), late = during.reduce((a, r) => a + (r.ticks.lateEntries ?? 0), 0); return ins ? round(late / ins, 3) : null; })(),
+      // Frames a Gate wrote to each of its players a second: the median Gate-second, and the worst.
+      gateDeliveredHz: { median: round(pick(gates.map((g) => g.deliveredHz), 0.5)), p05: round(pick(gates.map((g) => g.deliveredHz), 0.05)), min: round(pick(gates.map((g) => g.deliveredHz), 0)) },
+      gateWorldHz: { median: round(pick(gates.map((g) => g.worldHz), 0.5)), min: round(pick(gates.map((g) => g.worldHz), 0)) },
+      worldAgeMs: { p50: pick(gates.map((g) => g.worldAgeMs?.p50), 0.5), p95: pick(gates.map((g) => g.worldAgeMs?.p95), 0.95), max: pick(gates.map((g) => g.worldAgeMs?.max), 1) },
+      roomLinkAckMs: { median: pick(gates.map((g) => g.ackMs), 0.5), max: pick(gates.map((g) => g.maxAckMs), 1) },
+      gates: Math.max(0, ...during.map((r) => (r.gates ?? []).length)),
+      playersPerGate: (() => { const last = during.at(-1)?.gates ?? []; const c = sorted(last.map((g) => g.subscribed)); return c.length ? { min: c[0], max: c.at(-1) } : null; })(),
+      pacedPlayers: pick(during.map((r) => (r.gates ?? []).reduce((a, g) => a + (g.paced ?? 0), 0)), 1),
+      coastingPlayers: pick(during.map((r) => (r.gates ?? []).reduce((a, g) => a + (g.coasting ?? 0), 0)), 1),
+      // A Gate's own round trip to the room (its event loop's wait is in it): the median Gate-second and the worst.
+      // Ticks the room's worlds advanced a second by each Gate's own clock, and the longest a Gate went without one.
+      roomTickHzAtGates: { median: round(pick(gates.map((g) => g.roomTickHz), 0.5)), p05: round(pick(gates.map((g) => g.roomTickHz), 0.05)) }, worldGapMsMax: pick(gates.map((g) => g.worldGapMs), 1),
+      // The room's clock less a Gate's (median Gate), and how long the room says it held a Gate's frame.
+      roomClockOffsetMs: pick(gates.map((g) => g.roomClock?.offsetMs), 0.5), channelDelayMs: pick(gates.map((g) => g.roomClock?.delayMs), 0.5),
+      gateRttMs: { median: round(pick(gates.map((g) => g.rttMs), 0.5), 0), p95: round(pick(gates.map((g) => g.rttMs), 0.95), 0) },
+      inputOffsetMs: pick(gates.map((g) => g.inputOffsetMs), 0.5),
+      clientLagTicks: { p95: pick(gates.map((g) => g.clientLagTicks?.p95), 0.95), max: pick(gates.map((g) => g.clientLagTicks?.max), 1) },
+    },
+  };
+}
+
+/**
+ * The columns, in order. Some are easy to misread:
+ *   - "from": where the players were. `home` is this computer and its connection, what a real player at home
+ *     sees. `cloudflare` is the in-Cloudflare probe: what the servers can do, with no home connection in it.
+ *   - "ack": from sending an input to the snapshot that acknowledges its tick. It is never less than the lead.
+ *   - "loop": from the tick a player held when it stamped an input to the tick it reached the rules: the room, the
+ *     Gate and the connection both ways. This is the latency the system adds, whatever lead the player keeps.
+ *   - "lead (late)": whole ticks ahead the median player stamps its input, and the share the room called late.
+ *   - "room Hz at Gates": ticks the room's worlds advanced a second by the GATES' clocks. The room's own count of
+ *     its ticks cannot see the room run late.
+ *   - "world age": a Gate's clock when it wrote a world, less the room's stamp, corrected by the offset between
+ *     the two clocks that the Gate measures on its channel.
+ *   - "driver": the load driver's worst timer lag. Marked DRIVER when it was over a quarter of a second: that
+ *     step's client-side numbers are then the driver's.
+ */
+export function table(steps) {
+  const cell = (v) => (v === null || v === undefined ? '—' : String(v));
+  const head = ['N', 'from', 'joined/end/drops', 'ack p50/p95/p99 ms', 'loop p50/p95 ms', 'lead (late)', 'client tick Hz', 'client delivered Hz', 'wire MB/s (link)', 'KB/s a player', 'compressed (ratio)', 'driver lag ms', 'server late', 'Gates', 'room Hz at Gates med/p05', 'Gate delivered Hz med/p05', 'Gate rtt med/p95 ms', 'world age p50/p95 ms', 'paced', 'diag ok/failed'];
+  const lines = [`| ${head.join(' | ')} |`, `| ${head.map(() => '---').join(' | ')} |`];
+  for (const s of steps) lines.push(`| ${[
+    s.n, s.from, `${cell(s.joined)}/${cell(s.connectedAtEnd)}/${cell(s.disconnects)}`,
+    `${cell(s.client.inputAckMs.p50)}/${cell(s.client.inputAckMs.p95)}/${cell(s.client.inputAckMs.p99)}`,
+    `${cell(s.client.inputLoopMs?.p50)}/${cell(s.client.inputLoopMs?.p95)}`,
+    `${cell(s.client.inputLead?.ticksMedian)} (${cell(s.client.inputLead?.lateShare)})`,
+    cell(s.client.tickHz.median), cell(s.client.deliveredHz.median),
+    `${cell(s.client.wireMBps)} (${cell(s.link.downMBps)}${s.link.limited ? ', LINK-LIMITED' : ''})`,
+    cell(s.client.wireKBsPerPlayer),
+    s.client.compression ? `${s.client.compression.sockets}/${s.client.compression.of} (${cell(s.client.compression.ratio)})` : cell(s.client.compressedSockets),
+    `${cell(s.client.driverPeakLagMs === null ? null : Math.round(s.client.driverPeakLagMs))}${s.client.driverLimited ? ' DRIVER' : ''}`,
+    cell(s.server.lateInputs), cell(s.server.gates || null),
+    `${cell(s.server.roomTickHzAtGates.median)}/${cell(s.server.roomTickHzAtGates.p05)}`,
+    `${cell(s.server.gateDeliveredHz.median)}/${cell(s.server.gateDeliveredHz.p05)}`, `${cell(s.server.gateRttMs.median)}/${cell(s.server.gateRttMs.p95)}`,
+    `${cell(s.server.worldAgeMs.p50)}/${cell(s.server.worldAgeMs.p95)}`, cell(s.server.pacedPlayers),
+    `${s.server.samples}/${s.server.failedPolls}`,
+  ].join(' | ')} |`);
+  return lines.join('\n');
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const dir = resolve(process.argv[2] ?? '.');
+  const read = (file) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null);
+  const steps = [];
+  for (const name of readdirSync(dir).filter((n) => /^n\d+(-cloud)?$/.test(n)).sort((a, b) => parseInt(a.slice(1), 10) - parseInt(b.slice(1), 10) || a.length - b.length)) {
+    const report = read(join(dir, name, 'report.json'));
+    if (!report) continue;
+    const file = join(dir, name, 'diagnostics.jsonl');
+    const rows = existsSync(file) ? readFileSync(file, 'utf8').split('\n').filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } }) : [];
+    steps.push(summarize(report, rows, read(join(dir, name, 'link.json'))));
+  }
+  writeFileSync(join(dir, 'summary.json'), JSON.stringify(steps, null, 2));
+  writeFileSync(join(dir, 'summary.md'), `${table(steps)}\n`);
+  console.log(table(steps));
+}