@homie-rocks/studio 0.18.2 → 0.19.0

package/README.md

@@ -15,6 +15,7 @@ cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
 npx homie-studio check crown-thief --url http://127.0.0.1:8787
+npx homie-studio perf crown-thief --url http://127.0.0.1:8787   # how fast it runs: a computer and an emulated phone, host and replica
 npx homie-studio deploy --plan                         # what deploy will create, and what it costs; changes nothing
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
@@ -409,6 +410,36 @@ feed every command behaves exactly as before. `lib/progress.mjs` has the whole f
 names the Cloudflare account, often after its owner. A custom domain goes in studio.json
 as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `stats` use.
 
+## How fast it runs: `homie-studio perf`
+
+```sh
+npx homie-studio perf crown-thief --url http://127.0.0.1:8787 [--device computer,phone] [--runs 3] [--profile]
+npx homie-studio perf sizes crown-thief                     # every built file, raw and gzipped; with build --maps, the bundle's modules
+npx homie-studio perf compare .perf/crown-thief/<before> .perf/crown-thief/<after> --goal phone.host.frame.p95
+```
+
+One run is two headless Chromes on this computer's GPU in a fresh room of their own (`?room=perf-…`): the host (the
+rules, the bots, the snapshots) and a replica, both a computer (1280x800 at 2x) or both an emulated phone (390x844 at
+3x, touch, Chrome's CPU throttle at 4x with `--cpu`, 4G; each run records the slow-down the throttle really gave, which
+on a fast computer is less than its rate). They play the same seeded presses through a warm-up and a measured
+window, and each run's JSON says, per browser: the time between animation frames (median, p95, p99, the share over 33
+and 50 ms), the game's JavaScript per frame (every requestAnimationFrame callback timed), the main thread per frame
+(Chrome's TaskDuration), time to the first frame, to a seat and to playable, the game's files on the wire, the heap
+after a garbage collection, and netplay messages and kilobytes a second each way. `--profile` adds a CPU profile per
+browser in a window of its own (a `.cpuprofile` for Chrome DevTools) and its hottest functions, read through the
+game's source map when the build kept one (`homie-studio build --maps` keeps it in `.studio/maps/<id>/`, never in
+`site/dist`).
+
+The computer is shared, so every run waits for the 1-minute load to fall under 0.8 per core (`--max-load`) and
+records the load before and after; a run that started busy says `loaded` and `compare` leaves it out. A software
+renderer (SwiftShader) makes the run `blocked`: nothing on it is judged. `compare` calls a metric better only when a
+rank test says it is unlikely to be chance (p < 0.05), the 95% bootstrap interval of the change stays below zero, and
+it is at least 3% better; runs taken side by side with the same `--pair` label are judged as pairs (a signed-rank
+test on their ratios), so a computer that drifted busier cancels. Guards (frame time, main thread per frame, time to
+playable, heap, the host's upload) must not get worse. Results are files under `.perf/<id>/` (git-ignored); the
+command prints paths and medians. The Homie plugin's `perf` skill runs the whole loop: baseline, one change at a time,
+keep or revert, and a report in the studio's `perf/` folder.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud

package/bin/homie-studio.mjs

@@ -16,10 +16,26 @@
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio game remix <source.json url> --id <new id>
  *   homie-studio games
- *   homie-studio build [<id>]
+ *   homie-studio build [<id>] [--maps]   (--maps: also keep each bundle's source map and module sizes in .studio/maps/<id>/,
+ *                                          never in site/dist: what `perf` reads a CPU profile through)
  *   homie-studio dev [--port 8787] [--remote-ai]   (--stop: stop exactly this studio's dev server, nothing else;
  *                                         AI guides think scripted here unless --remote-ai: real Workers AI, billed)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio perf <id> [--url <site>] [--device computer,phone] [--runs 1] [--seconds 15] [--warm 3] [--profile]
+ *                     [--cpu 4] [--out <dir>] [--max-load 0.8] [--pair <label>]
+ *                                         (how fast it runs: per device, two browsers in a fresh room, the host and a replica,
+ *                                          playing: frame times (median, p95, p99, long frames), the game's JavaScript per frame,
+ *                                          the main thread per frame, time to playable and what it downloaded, the heap, netplay
+ *                                          messages a second; the computer's load with every run. --profile: a CPU profile of
+ *                                          each browser and its hottest functions. Files under .perf/<id>/<time>/; the phone is
+ *                                          emulated (a --cpu times slower CPU, 4G) on this computer's GPU. The plugin's perf
+ *                                          skill runs the whole measure, change, compare, keep-or-revert loop)
+ *   homie-studio perf sizes <id>          (what a player downloads: every built file, raw and gzipped, the biggest first; with
+ *                                          build --maps, which modules make up the bundle)
+ *   homie-studio perf compare <before dir> <after dir> [--goal phone.host.frame.p95] [--min 3] [--guards a,b] [--also c,d]
+ *                                         (better, worse or the same within the noise: medians, a 95% interval, a rank test,
+ *                                          and the guards that must not get worse; runs taken side by side with the same
+ *                                          --pair label on both sides are judged as pairs, so a computer's drift cancels)
  *   homie-studio chrome [install] [--fresh]  (which Chrome the checks use; on Linux, `install` fetches Chrome for Testing;
  *                                          --fresh fetches it even when the machine has a Chrome)
  *   homie-studio look [<path>...] [--url <site>] [--shots <dir>] [--only computer,phone,sideways]
@@ -149,6 +165,7 @@ import { publish } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
+import { DEFAULT_GOAL, perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
 import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
@@ -170,7 +187,7 @@ import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -451,6 +468,26 @@ function print(result) {
     case 'chrome install':
       lines.push(result.already || result.command === 'chrome' ? `Chrome: ${result.chrome}` : `Installed Chrome for Testing ${result.buildId}: ${result.chrome}`);
       break;
+    case 'perf':
+      lines.push(`Measured ${result.game}: ${result.runs.length} run(s), in ${result.out}`, ...result.headline.map((l) => `  ${l}`),
+        ...(result.blocked ? [`  ${result.blocked}`] : []), ...(result.loaded ? [`  ${result.loaded}`] : []),
+        `Each run: ${result.out}/<device>-<n>.json (and its screenshots); medians: ${result.summary}${result.sizes ? `; sizes: ${result.sizes}` : ''}`,
+        ...(result.profiles?.length ? [`CPU profiles (Chrome DevTools opens them; the hottest functions are in each run's JSON): ${result.profiles.join(', ')}`] : []));
+      break;
+    case 'perf sizes': {
+      const kb = (b) => `${(b / 1024).toFixed(1)} KB`;
+      lines.push(`${result.game}: ${result.total.files} files, ${kb(result.total.bytes)} (${kb(result.total.gzip)} gzipped); JavaScript ${kb(result.js.bytes)} (${kb(result.js.gzip)} gzipped)`,
+        'Biggest:', ...result.biggest.slice(0, 8).map((f) => `  ${kb(f.bytes).padStart(10)}  ${f.path}${f.gzip !== f.bytes ? `  (${kb(f.gzip)} gzipped)` : ''}`),
+        ...(result.modules ? ['Bundle modules:', ...result.modules.top.slice(0, 8).map((m) => `  ${kb(m.bytes).padStart(10)}  ${m.module}`)] : []),
+        ...(result.apart ? [`Not loaded by the game: ${result.apart.files} file(s), ${kb(result.apart.bytes)} (${result.apart.note})`] : []));
+      break;
+    }
+    case 'perf compare':
+      lines.push(`${result.verdict.toUpperCase()}: ${result.why}`,
+        ...result.guards.filter((g) => g.verdict !== 'same').map((g) => `  ${g.verdict} ${g.metric}: ${g.why}`),
+        ...(result.left.before + result.left.after ? [`  left out: ${result.left.before} run(s) before, ${result.left.after} after (blocked or started on a busy computer)`] : []),
+        `Written: ${result.file}`);
+      break;
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`),
@@ -490,6 +527,10 @@ async function main() {
     if (line) process.stdout.write(`${line}\n`);
     return { ok: true, command: 'help' };
   }
+  if (cmd === 'perf' && sub === 'compare') {
+    if (!positional[2] || !positional[3]) return { ok: false, command: 'perf compare', why: 'usage: homie-studio perf compare <before dir> <after dir> [--goal <metric>] [--min 3]' };
+    return perfCompare(positional[2], positional[3], { goal: String(flags.get('goal') ?? DEFAULT_GOAL), min: flags.has('min') ? Number(flags.get('min')) / 100 : 0.03, guards: flags.get('guards') ? String(flags.get('guards')).split(',').map((x) => x.trim()).filter(Boolean) : null, also: flags.get('also') ? String(flags.get('also')).split(',').map((x) => x.trim()).filter(Boolean) : [] });
+  }
   const root = requireStudio();
   if (cmd === 'statusline') return installStatusLine(root, { remove: flags.has('remove'), replace: flags.has('replace'), project: flags.get('project') ?? null });
   if (cmd === 'codex') return codexCommand(root, sub);
@@ -506,7 +547,16 @@ async function main() {
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
   if (cmd === 'game' && sub === 'remix') return remixGame(root, positional[2], flags.get('id'), { name: flags.get('name') });
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
-  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log }), 'build');
+  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps') }), 'build');
+  if (cmd === 'perf' && sub === 'sizes') return perfSizes(root, positional[2] ?? listGames(root)[0]?.id);
+  if (cmd === 'perf') {
+    const game = sub ?? listGames(root)[0]?.id;
+    const url = flags.get('url') ?? siteUrl(root);
+    if (!url) return { ok: false, command: 'perf', why: 'give --url (the local dev address or the live site)' };
+    const devices = String(flags.get('device') ?? 'computer,phone').split(',').map((d) => d.trim()).filter(Boolean);
+    const num = (k, d, lo, hi) => Math.max(lo, Math.min(hi, Number(flags.get(k) ?? d) || d));
+    return perfRun({ root, url, game, devices, runs: num('runs', 1, 1, 50), seconds: num('seconds', 15, 3, 300), warm: num('warm', 3, 0, 60), profile: flags.has('profile'), out: flags.get('out') ? resolve(String(flags.get('out'))) : null, maxLoad: num('max-load', 0.8, 0.05, 50), cpu: num('cpu', 4, 1, 20), pair: flags.get('pair') ? String(flags.get('pair')) : null, log });
+  }
   if (cmd === 'status') {
     const studio = readStudio(root);
     return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
@@ -869,7 +919,7 @@ try {
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
-  if (result?.command === 'check' || result?.command === 'port check' || result?.command === 'look') process.exit(process.exitCode ?? 0);
+  if (['check', 'port check', 'look', 'perf'].includes(result?.command)) process.exit(process.exitCode ?? 0);
 } catch (error) {
   await flushProgress().catch(() => {});
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });

package/lib/build.mjs

@@ -30,6 +30,7 @@
  *                                     the game's own build (Vite, webpack…), then its output copied; base must be './'
  */
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
@@ -205,7 +206,23 @@ export function seatsFor(g, net = netplayOf(g)) {
   return { min: Math.min(max, minNamed ?? 1), max, asked };
 }
 
-export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1' } = {}) {
+/**
+ * `build --maps` (what `homie-studio perf` reads a CPU profile through): the bundle's source map and esbuild's metafile
+ * go to .studio/maps/<id>/ (git-ignored, this computer's own), never into site/dist, so a deploy never ships them. The
+ * bundle itself is byte for byte the one a plain build makes (an external map adds no comment to it); main.js.sha256
+ * says which bundle the map belongs to, so a map left over from an older build is never used.
+ */
+function keepMap(root, id, out, metafile) {
+  const dir = join(root, '.studio', 'maps', id);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const map = join(out, 'assets', 'main.js.map');
+  if (existsSync(map)) { cpSync(map, join(dir, 'main.js.map')); rmSync(map, { force: true }); }
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify(metafile ?? {}));
+  writeFileSync(join(dir, 'main.js.sha256'), `${createHash('sha256').update(readFileSync(join(out, 'assets', 'main.js'))).digest('hex')}\n`);
+}
+
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
   const require = createRequire(join(root, 'package.json'));
   let esbuild;
   try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
@@ -228,7 +245,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
       const entry = join(g.dir, entryRel);
       if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
       const result = await esbuild.build({
-        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
+        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: maps ? 'external' : false,
         outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
         loader: LOADERS, assetNames: '[name]-[hash]',
       }).catch((error) => {
@@ -236,6 +253,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
         throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
       });
       warnings += result.warnings.length;
+      if (maps) keepMap(root, g.id, out, result.metafile);
     };
     if (mode === 'static') {
       copyStatic(g.dir, out);

package/lib/perf-profile.mjs

@@ -0,0 +1,171 @@
+/**
+ * WHERE A GAME'S TIME GOES: a Chrome CPU profile (`homie-studio perf --profile`, the .cpuprofile DevTools opens)
+ * summed per function, and the game's minified bundle read back through its source map, so the summary names
+ * `draw (src/main.ts:620)` rather than `Xe (main.js:1:48213)`.
+ *
+ * Self time is the time a function itself was on the stack's top (what to make cheaper); total time includes what it
+ * called (where a frame's time is spent overall). Idle, the garbage collector and Chrome's own work ("(program)") are
+ * kept apart, so a game that is mostly idle reads as idle, not as a list of tiny hot spots.
+ */
+
+const B64 = new Map([...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'].map((c, i) => [c, i]));
+
+/** A source map's `mappings` as one array of segments per generated line: [column, source, line, column, name?]. */
+export function decodeMappings(mappings) {
+  const lines = [];
+  let src = 0;
+  let line = 0;
+  let col = 0;
+  let name = 0;
+  for (const text of String(mappings ?? '').split(';')) {
+    const segs = [];
+    let gen = 0;
+    for (const seg of text.split(',')) {
+      if (!seg) continue;
+      const v = [];
+      let value = 0;
+      let shift = 0;
+      for (const ch of seg) {
+        const d = B64.get(ch);
+        if (d === undefined) break;
+        value += (d & 31) << shift;
+        if (d & 32) { shift += 5; continue; }
+        v.push(value & 1 ? -(value >>> 1) : value >>> 1);
+        value = 0;
+        shift = 0;
+      }
+      gen += v[0] ?? 0;
+      if (v.length >= 4) {
+        src += v[1]; line += v[2]; col += v[3];
+        if (v.length >= 5) { name += v[4]; segs.push([gen, src, line, col, name]); } else segs.push([gen, src, line, col]);
+      }
+    }
+    lines.push(segs);
+  }
+  return lines;
+}
+
+/**
+ * A lookup for one source map: (0-based line, column) in the generated file → { source, line (1-based), column, name },
+ * the nearest mapping at or before that column on that line; null outside the map.
+ */
+export function sourceMapLookup(map) {
+  const lines = decodeMappings(map?.mappings);
+  const sources = (map?.sources ?? []).map((s) => String(s).replace(/^(\.\.\/)+/, '').replace(/^webpack:\/\/\//, ''));
+  const names = map?.names ?? [];
+  const content = map?.sourcesContent ?? [];
+  return (line, column) => {
+    const segs = lines[line];
+    if (!segs?.length) return null;
+    let lo = 0;
+    let hi = segs.length - 1;
+    let best = -1;
+    while (lo <= hi) { const mid = (lo + hi) >> 1; if (segs[mid][0] <= column) { best = mid; lo = mid + 1; } else hi = mid - 1; }
+    if (best < 0) return null;
+    // A function's own position often lands on its name token; prefer a named segment within a few columns.
+    let seg = segs[best];
+    for (let k = best; k >= 0 && column - segs[k][0] <= 12; k--) if (segs[k][4] !== undefined) { seg = segs[k]; break; }
+    const source = sources[seg[1]] ?? null;
+    const named = seg[4] !== undefined ? names[seg[4]] ?? null : null;
+    const text = typeof content[seg[1]] === 'string' ? content[seg[1]].split('\n')[seg[2]] ?? '' : '';
+    // What the line defines wins over a segment's name: at an arrow function V8 points at its first parameter, whose
+    // segment names the parameter, not the function.
+    return { source, line: seg[2] + 1, column: seg[3], name: nameFromLine(text, seg[3]) ?? named };
+  };
+}
+
+/**
+ * The function a line of source defines, when the line says: `function draw(`, `const step = (`, `draw(…) {` (a method),
+ * `step: (dt) =>`. The whole line first (a line usually defines one function), then from the mapped column on.
+ */
+function nameFromLine(text, column) {
+  const tries = [
+    /function\s*\*?\s*([A-Za-z_$][\w$]*)\s*[(<]/,
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:function\b|\([^)]*\)\s*(?::[^=]+)?=>|[A-Za-z_$][\w$]*\s*=>)/,
+    /^\s*(?:(?:public|private|protected|static|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::[^{]+)?\{/,
+    /([A-Za-z_$][\w$]*)\s*:\s*(?:async\s*)?(?:function\b|\([^)]*\)\s*(?::[^=]+)?=>)/,
+  ];
+  for (const re of tries) { const m = re.exec(text); if (m && !['if', 'for', 'while', 'switch', 'catch', 'return'].includes(m[1])) return m[1]; }
+  void column;
+  return null;
+}
+
+const SPECIAL = new Set(['(root)', '(program)', '(idle)', '(garbage collector)']);
+
+/**
+ * A CPU profile summed per function. `maps`: [{ match: (url) => boolean, lookup }] (sourceMapLookup), for scripts
+ * shipped minified. `game`: (url) => boolean, the game's own scripts (the rest is the play page and the browser).
+ * Returns milliseconds and shares of the busy (not idle) time, the hottest functions first.
+ */
+export function summarizeProfile(profile, { maps = [], game = () => true, top = 15 } = {}) {
+  const nodes = new Map((profile?.nodes ?? []).map((n) => [n.id, n]));
+  const parent = new Map();
+  for (const n of nodes.values()) for (const c of n.children ?? []) parent.set(c, n.id);
+  const samples = profile?.samples ?? [];
+  const deltas = profile?.timeDeltas ?? [];
+  // Each sample stands for the time until the next one (the last: the average step).
+  const span = (i) => (i + 1 < deltas.length ? deltas[i + 1] : (deltas.length ? deltas.reduce((s, x) => s + x, 0) / deltas.length : 0));
+  const keyOf = (cf) => `${cf.functionName || '(anonymous)'}|${cf.url}|${cf.lineNumber}|${cf.columnNumber}`;
+  const fns = new Map();
+  const fnOf = (n) => {
+    const cf = n.callFrame;
+    const k = keyOf(cf);
+    let f = fns.get(k);
+    if (!f) { f = { key: k, cf, self: 0, total: 0 }; fns.set(k, f); }
+    return f;
+  };
+  let all = 0;
+  let idle = 0;
+  let gc = 0;
+  let program = 0;
+  const scripts = new Map();
+  for (let i = 0; i < samples.length; i++) {
+    const n = nodes.get(samples[i]);
+    if (!n) continue;
+    const us = span(i);
+    all += us;
+    const name = n.callFrame.functionName;
+    if (name === '(idle)') { idle += us; continue; }
+    if (name === '(garbage collector)') gc += us;
+    if (name === '(program)') program += us;
+    fnOf(n).self += us;
+    const script = n.callFrame.url ? scriptName(n.callFrame.url) : SPECIAL.has(name) ? name : '(native)';
+    scripts.set(script, (scripts.get(script) ?? 0) + us);
+    // Total: once per function per sample, however deep the recursion.
+    const seen = new Set();
+    for (let id = n.id; id !== undefined; id = parent.get(id)) {
+      const p = nodes.get(id);
+      if (!p || p.callFrame.functionName === '(root)') break;
+      const f = fnOf(p);
+      if (seen.has(f)) continue;
+      seen.add(f);
+      f.total += us;
+    }
+  }
+  const busy = all - idle;
+  const ms = (us) => Math.round(us / 100) / 10;
+  const pct = (us) => (busy ? Math.round((us / busy) * 1000) / 10 : 0);
+  const place = (cf) => {
+    if (!cf.url) return null;
+    const map = maps.find((m) => m.match(cf.url));
+    const hit = map ? map.lookup(cf.lineNumber, cf.columnNumber) : null;
+    if (hit?.source) return { name: hit.name ?? null, where: `${hit.source}:${hit.line}`, mapped: true };
+    return { name: null, where: `${scriptName(cf.url)}:${cf.lineNumber + 1}:${cf.columnNumber + 1}`, mapped: false };
+  };
+  const rows = [...fns.values()].filter((f) => !SPECIAL.has(f.cf.functionName)).sort((a, b) => b.self - a.self).slice(0, top).map((f) => {
+    const at = place(f.cf);
+    const minified = f.cf.functionName || '(anonymous)';
+    // V8 names a function from where it was declared or assigned; one it calls anonymous (a callback) stays so, and
+    // `where` says which line it is on.
+    return { name: f.cf.functionName ? at?.name ?? minified : '(anonymous)', ...(at?.mapped && at.name && at.name !== minified ? { minified } : {}), where: at?.where ?? '(native)', game: Boolean(f.cf.url && game(f.cf.url)), selfMs: ms(f.self), selfPct: pct(f.self), totalPct: pct(f.total) };
+  });
+  const byScript = [...scripts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([script, us]) => ({ script, ms: ms(us), pct: pct(us) }));
+  let gameUs = 0;
+  for (const f of fns.values()) if (f.cf.url && game(f.cf.url)) gameUs += f.self;
+  return { ms: ms(all), busyMs: ms(busy), idlePct: all ? Math.round((idle / all) * 1000) / 10 : 0, gcPct: pct(gc), programPct: pct(program), gamePct: pct(gameUs), top: rows, scripts: byScript };
+}
+
+/** A script's address without the site: `/gem-rush/__game/assets/main.js`, `/_homie/site.js`. */
+export function scriptName(url) {
+  try { const u = new URL(url); return u.pathname || url; } catch { return String(url).slice(0, 120); }
+}

package/lib/perf-stats.mjs

@@ -0,0 +1,249 @@
+/**
+ * WHETHER A CHANGE MADE A GAME FASTER, OR ONLY LOOKS LIKE IT (`homie-studio perf compare`).
+ *
+ * Two builds are measured in turns (before, after, after, before, ...), several runs each, and every run gives one
+ * number per metric (a run's 95th-percentile frame time, say). A browser's numbers move from run to run on their own:
+ * another app wakes up, a garbage collection lands in the window, the bots wander somewhere busier. So a difference
+ * between two medians means nothing by itself. A change counts as better only when all three hold:
+ *
+ *   - it is unlikely to be chance: a permutation test on the runs' ranks (Mann-Whitney U, exact for the small run
+ *     counts used here), one-sided, p < 0.05;
+ *   - the 95% bootstrap interval of the change in medians stays on the better side of zero;
+ *   - it is big enough to matter: at least `min` (3%) better at the median.
+ *
+ * A guard (another metric that must not get worse) is judged the same way, stricter (p < 0.01, at least 5% worse),
+ * because a handful of guards checked at 0.05 would flag a regression by chance on most changes. A metric that never
+ * varies (bytes of a build) has no noise to test: any change of at least 1% counts.
+ *
+ * PAIRS. A shared computer drifts: measured on an Apple M4 while other work ran, the main thread per frame rose from
+ * 0.88 to 1.25 ms over five runs of the SAME build as the load average went from 4 to 7.6, host and replica together.
+ * When the runs were taken side by side (`try` measures before, after, after, before, … and labels each neighbouring
+ * pair), the test is on the pairs instead: each after-run against the before-run next to it, as a ratio, so a drift
+ * that hits both cancels. Wilcoxon signed-rank, exact: with 6 pairs, p < 0.05 needs the after-run to win at least 5
+ * of the 6 pairs (and lose only the closest one). The change is the median ratio; its interval a bootstrap over pairs.
+ *
+ * Everything here is lower-is-better (milliseconds, bytes, messages); nothing reads a clock or the network.
+ */
+
+/** The q-quantile (0..1) of numbers, by linear interpolation between order statistics. null for none. */
+export function quantile(values, q) {
+  const xs = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!xs.length) return null;
+  const at = (xs.length - 1) * q;
+  const lo = Math.floor(at);
+  const hi = Math.ceil(at);
+  return xs[lo] + (xs[hi] - xs[lo]) * (at - lo);
+}
+
+export const median = (values) => quantile(values, 0.5);
+
+/** A small summary of numbers: n, median, the middle half, min, max, and the spread as a share of the median. */
+export function summarize(values) {
+  const xs = values.filter(Number.isFinite);
+  if (!xs.length) return { n: 0, median: null, q1: null, q3: null, min: null, max: null, spread: null };
+  const m = median(xs);
+  const q1 = quantile(xs, 0.25);
+  const q3 = quantile(xs, 0.75);
+  return { n: xs.length, median: round(m), q1: round(q1), q3: round(q3), min: round(Math.min(...xs)), max: round(Math.max(...xs)), spread: m ? round((q3 - q1) / Math.abs(m), 4) : null };
+}
+
+export const round = (x, digits = 3) => (Number.isFinite(x) ? Number(x.toFixed(digits)) : null);
+
+/** Midranks of a joined list (ties share the average of their ranks), 1-based. */
+function ranks(values) {
+  const order = values.map((v, i) => [v, i]).sort((a, b) => a[0] - b[0]);
+  const r = new Array(values.length);
+  for (let i = 0; i < order.length;) {
+    let j = i;
+    while (j + 1 < order.length && order[j + 1][0] === order[i][0]) j++;
+    const mid = (i + j) / 2 + 1;
+    for (let k = i; k <= j; k++) r[order[k][1]] = mid;
+    i = j + 1;
+  }
+  return r;
+}
+
+/**
+ * Mann-Whitney U as an exact permutation test on rank sums: every way of choosing which runs were "after" is equally
+ * likely when the change did nothing, so p is the share of those choices whose "after" ranks are as low (`less`) or as
+ * high (`greater`) as the ones measured. Exact up to 200,000 choices (10 + 10 runs is 184,756), the normal
+ * approximation with a tie correction past that.
+ */
+export function rankTest(before, after) {
+  const a = before.filter(Number.isFinite);
+  const b = after.filter(Number.isFinite);
+  const n1 = a.length;
+  const n2 = b.length;
+  if (!n1 || !n2) return { n1, n2, u: null, less: null, greater: null, twoSided: null, exact: false };
+  const r = ranks([...a, ...b]);
+  const observed = r.slice(n1).reduce((s, x) => s + x, 0);
+  const u = observed - (n2 * (n2 + 1)) / 2;
+  const total = binom(n1 + n2, n2);
+  const eps = 1e-9;
+  if (total <= 200_000) {
+    let le = 0;
+    let ge = 0;
+    let all = 0;
+    const pick = (start, left, sum) => {
+      if (left === 0) { all++; if (sum <= observed + eps) le++; if (sum >= observed - eps) ge++; return; }
+      for (let i = start; i <= r.length - left; i++) pick(i + 1, left - 1, sum + r[i]);
+    };
+    pick(0, n2, 0);
+    const less = le / all;
+    const greater = ge / all;
+    return { n1, n2, u, less: round(less, 5), greater: round(greater, 5), twoSided: round(Math.min(1, 2 * Math.min(less, greater)), 5), exact: true };
+  }
+  const n = n1 + n2;
+  const mean = (n2 * (n + 1)) / 2;
+  const counts = new Map();
+  for (const x of r) counts.set(x, (counts.get(x) ?? 0) + 1);
+  const ties = [...counts.values()].reduce((s, t) => s + (t ** 3 - t), 0);
+  const sd = Math.sqrt(((n1 * n2) / 12) * ((n + 1) - ties / (n * (n - 1))));
+  const z = sd ? (observed - mean) / sd : 0;
+  const less = normalCdf(z + 0.5 / (sd || 1));
+  const greater = 1 - normalCdf(z - 0.5 / (sd || 1));
+  return { n1, n2, u, less: round(less, 5), greater: round(greater, 5), twoSided: round(Math.min(1, 2 * Math.min(less, greater)), 5), exact: false };
+}
+
+function binom(n, k) {
+  let c = 1;
+  for (let i = 1; i <= k; i++) c = (c * (n - k + i)) / i;
+  return Math.round(c);
+}
+
+function normalCdf(z) {
+  // Abramowitz and Stegun 7.1.26, |error| < 1.5e-7.
+  const t = 1 / (1 + 0.3275911 * Math.abs(z) / Math.SQRT2);
+  const y = 1 - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-(z * z) / 2);
+  return z >= 0 ? (1 + y) / 2 : (1 - y) / 2;
+}
+
+/** A seeded random number generator (mulberry32): the same runs always give the same interval. */
+export function seeded(seed = 1) {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * The 95% percentile-bootstrap interval of the relative change in medians, (after - before) / before: resample each
+ * side's runs with replacement 4,000 times. Seeded, so the same numbers give the same interval.
+ */
+export function bootstrapChange(before, after, { iterations = 4000, seed = 7 } = {}) {
+  const a = before.filter(Number.isFinite);
+  const b = after.filter(Number.isFinite);
+  if (!a.length || !b.length) return null;
+  const rnd = seeded(seed);
+  const draw = (xs) => { const out = new Array(xs.length); for (let i = 0; i < xs.length; i++) out[i] = xs[Math.floor(rnd() * xs.length)]; return out; };
+  const changes = [];
+  for (let i = 0; i < iterations; i++) {
+    const ma = median(draw(a));
+    const mb = median(draw(b));
+    if (ma) changes.push((mb - ma) / Math.abs(ma));
+  }
+  if (!changes.length) return null;
+  return [round(quantile(changes, 0.025), 4), round(quantile(changes, 0.975), 4)];
+}
+
+/**
+ * One metric, before against after (lower is better). Returns the medians, the change, p, the interval and a verdict:
+ * `better`, `worse` or `same` (within the noise), with `why` in words. `min` is the smallest change that counts as
+ * better (0.03 = 3%); `worseMin` and `worseAlpha` the stricter bar for calling it worse.
+ */
+export function judge(before, after, { min = 0.03, alpha = 0.05, worseMin = 0.05, worseAlpha = 0.01, unit = '' } = {}) {
+  const a = before.filter(Number.isFinite);
+  const b = after.filter(Number.isFinite);
+  const sa = summarize(a);
+  const sb = summarize(b);
+  const base = { before: sa, after: sb, change: null, p: null, pWorse: null, ci: null, verdict: 'unknown', why: null };
+  if (!a.length || !b.length) return { ...base, why: `not measured on both sides (${a.length} before, ${b.length} after)` };
+  const change = sa.median ? (sb.median - sa.median) / Math.abs(sa.median) : (sb.median === sa.median ? 0 : null);
+  const fixed = sa.min === sa.max && sb.min === sb.max;
+  const pct = (x) => `${x > 0 ? '+' : ''}${(x * 100).toFixed(1)}%`;
+  const say = (x) => `${round(x, 2)}${unit}`;
+  if (change === null) return { ...base, change: null, why: 'the before median is 0, so a relative change has no meaning' };
+  if (fixed) {
+    // Nothing to test: the same number every run (a build's bytes). Any real difference is the change itself.
+    const verdict = change <= -0.01 ? 'better' : change >= 0.01 ? 'worse' : 'same';
+    return { ...base, change: round(change, 4), verdict, exact: true, why: `${say(sa.median)} → ${say(sb.median)} (${pct(change)}, the same every run)` };
+  }
+  const t = rankTest(a, b);
+  const ci = bootstrapChange(a, b);
+  const res = { ...base, change: round(change, 4), p: t.less, pWorse: t.greater, ci, n: [t.n1, t.n2] };
+  const head = `${say(sa.median)} → ${say(sb.median)} (${pct(change)}; 95% interval ${ci ? `${pct(ci[0])} to ${pct(ci[1])}` : 'n/a'}; p = ${t.less} better, ${t.greater} worse; ${t.n1} + ${t.n2} runs)`;
+  if (t.less < alpha && ci && ci[1] < 0 && change <= -min) return { ...res, verdict: 'better', why: head };
+  if (t.greater < worseAlpha && ci && ci[0] > 0 && change >= worseMin) return { ...res, verdict: 'worse', why: head };
+  const reasons = [];
+  if (change > -min) reasons.push(`smaller than the ${Math.round(min * 100)}% that counts`);
+  if (t.less >= alpha) reasons.push(`p ${t.less} is not under ${alpha}`);
+  if (ci && ci[1] >= 0) reasons.push('the interval reaches zero');
+  return { ...res, verdict: 'same', why: `${head}: within the noise (${reasons.join('; ') || 'not clearly either way'})` };
+}
+
+/**
+ * Wilcoxon signed-rank test on paired differences (after - before, or their log ratios), exact for up to 20 pairs
+ * (every sign assignment), the normal approximation past that. Zeros are dropped. `less`: p that the after side is
+ * lower by chance; `greater`: higher.
+ */
+export function signedRankTest(diffs) {
+  const d = diffs.filter((x) => Number.isFinite(x) && x !== 0);
+  const n = d.length;
+  if (!n) return { n: 0, wins: 0, less: 1, greater: 1, exact: true };
+  const r = ranks(d.map(Math.abs));
+  const wPlus = d.reduce((s, x, i) => s + (x > 0 ? r[i] : 0), 0);
+  const wins = d.filter((x) => x < 0).length;
+  const eps = 1e-9;
+  if (n <= 20) {
+    let le = 0;
+    let ge = 0;
+    const total = 2 ** n;
+    for (let mask = 0; mask < total; mask++) {
+      let w = 0;
+      for (let i = 0; i < n; i++) if (mask & (1 << i)) w += r[i];
+      if (w <= wPlus + eps) le++;
+      if (w >= wPlus - eps) ge++;
+    }
+    return { n, wins, less: round(le / total, 5), greater: round(ge / total, 5), exact: true };
+  }
+  const mean = (n * (n + 1)) / 4;
+  const sd = Math.sqrt((n * (n + 1) * (2 * n + 1)) / 24);
+  return { n, wins, less: round(normalCdf((wPlus + 0.5 - mean) / sd), 5), greater: round(1 - normalCdf((wPlus - 0.5 - mean) / sd), 5), exact: false };
+}
+
+/**
+ * One metric from runs taken in pairs (before[k] beside after[k]); lower is better. The same verdicts and bars as
+ * judge(), on the pairs' ratios.
+ */
+export function judgePaired(before, after, { min = 0.03, alpha = 0.05, worseMin = 0.05, worseAlpha = 0.01, unit = '' } = {}) {
+  const pairs = before.map((a, i) => [a, after[i]]).filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b) && a > 0 && b > 0);
+  const sa = summarize(pairs.map(([a]) => a));
+  const sb = summarize(pairs.map(([, b]) => b));
+  const base = { before: sa, after: sb, change: null, p: null, pWorse: null, ci: null, verdict: 'unknown', why: null, paired: true };
+  if (pairs.length < 3) return { ...base, why: `too few pairs measured on both sides (${pairs.length})` };
+  const logs = pairs.map(([a, b]) => Math.log(b / a));
+  const pct = (x) => `${x > 0 ? '+' : ''}${(x * 100).toFixed(1)}%`;
+  const say = (x) => `${round(x, 2)}${unit}`;
+  if (logs.every((x) => x === 0)) return { ...base, change: 0, p: 1, pWorse: 1, verdict: 'same', why: `${say(sa.median)} → ${say(sb.median)}: identical in every pair` };
+  const change = Math.exp(median(logs)) - 1;
+  const t = signedRankTest(logs);
+  const rnd = seeded(11);
+  const boots = [];
+  for (let i = 0; i < 4000; i++) { const draw = logs.map(() => logs[Math.floor(rnd() * logs.length)]); boots.push(Math.exp(median(draw)) - 1); }
+  const ci = [round(quantile(boots, 0.025), 4), round(quantile(boots, 0.975), 4)];
+  const res = { ...base, change: round(change, 4), p: t.less, pWorse: t.greater, ci, n: [pairs.length, pairs.length], wins: t.wins };
+  const head = `${say(sa.median)} → ${say(sb.median)} (${pct(change)} in the median pair; after was lower in ${t.wins} of ${pairs.length} pairs run side by side; 95% interval ${pct(ci[0])} to ${pct(ci[1])}; p = ${t.less} better, ${t.greater} worse)`;
+  if (t.less < alpha && ci[1] < 0 && change <= -min) return { ...res, verdict: 'better', why: head };
+  // Few pairs cannot reach p < 0.01 (6 pairs: 1/64 at best), so the guard's bar is then "worse in every pair".
+  const wa = Math.max(worseAlpha, 1.5 / 2 ** pairs.length);
+  if (t.greater < wa && ci[0] > 0 && change >= worseMin) return { ...res, verdict: 'worse', why: head };
+  const reasons = [];
+  if (change > -min) reasons.push(`smaller than the ${Math.round(min * 100)}% that counts`);
+  if (t.less >= alpha) reasons.push(`p ${t.less} is not under ${alpha}`);
+  if (ci[1] >= 0) reasons.push('the interval reaches zero');
+  return { ...res, verdict: 'same', why: `${head}: within the noise (${reasons.join('; ') || 'not clearly either way'})` };
+}