@homie-rocks/studio 0.18.2 → 0.19.1

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,42 @@ 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.
+
+`perf sizes` reads each big script for whether it is minified from its code, not from how well it gzips: whitespace,
+comments and names outside its strings (a minifier leaves about 1 to 2% whitespace; indented source has 15 to 30%).
+Minified JavaScript gzips about as well as source text, and a bundle with three.js in it carries the shaders as GLSL
+source in strings, which no minifier touches; the line for such a file says `minified, 19% GLSL shader source in
+strings`, and the JSON's `code` has every measure.
+
 ## 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,27 @@
  *   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; each big script read for whether it
+ *                                          is minified, from its code, and how much of it is GLSL shader source in strings)
+ *   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 +166,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 +188,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 +469,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)` : ''}${f.code ? `  ${f.code.minified ? `minified${f.code.shaderPct >= 5 ? `, ${f.code.shaderPct}% GLSL shader source in strings` : ''}` : 'NOT minified'}` : ''}`),
+        ...(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 +528,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 +548,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 +920,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-code.mjs

@@ -0,0 +1,255 @@
+/**
+ * Is a JavaScript file minified, and how much of it is strings and GLSL shader source? Read from the code itself,
+ * never from how well the whole file gzips.
+ *
+ * How well a file compresses says nothing about it: minified JavaScript gzips to a quarter or a third of its bytes
+ * (three.core.min.js 26%, three.module.min.js 24%), more than its indented source does (20%: whitespace is the easiest
+ * thing to compress). And a bundle with three.js in it carries the shaders as GLSL source in strings, line by line, with
+ * their indentation and their long names, which no minifier touches: a game's minified three.js bundle can be thousands
+ * of lines, nearly all of them inside shader strings.
+ *
+ * So the file is read the way a JavaScript parser reads it, just far enough to tell code from strings, template
+ * literals, regular expressions and comments, and only the code is judged:
+ *   - whitespace: the share of the code's characters that are spaces, tabs and line breaks. A minifier leaves the
+ *     few a keyword needs (about 1 to 2%); indented source is 15 to 30%;
+ *   - comments: the share of the file in comments, licence comments (`/*!`, `@license`, `@preserve`) apart, since a
+ *     minifier keeps those;
+ *   - lines: the code's characters per line (string contents not counted);
+ *   - names: the identifiers that are not a property (after `.`) or an object's key, which a minifier renames: their
+ *     mean length and the share one or two characters long (`mangled`). A minifier that keeps names (whitespace and
+ *     syntax only) is still a minifier.
+ * And the strings: the share of the file inside string and template literals, and the share of those that are GLSL
+ * shader source (#ifdef, uniform vec3, gl_FragColor, texture2D( ...).
+ *
+ * It is a reader, not a parser: a `/` after `)` or `}` is division unless the `(` followed if/while/for/with or the
+ * `{` opened a block, and a regular expression never spans a line (when it seems to, it was division). That is what a
+ * minifier's output and ordinary source need; a file it cannot read cleanly is judged on what it read.
+ */
+
+const KEYWORDS = new Set(['break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'export', 'extends', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'let', 'new', 'return', 'super', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'await', 'of', 'null', 'true', 'false', 'static', 'async', 'get', 'set', 'enum', 'implements', 'interface', 'package', 'private', 'protected', 'public', 'undefined', 'arguments', 'eval']);
+/** After these a `/` starts a regular expression; after any other keyword (this, null, true ...) it is division. */
+const REGEX_AFTER_KEYWORD = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await', 'extends']);
+/** A `{` after one of these opens a block (a `/` after its `}` starts a statement); anywhere else, an object. */
+const BLOCK_AFTER_PUNCT = new Set([')', ';', '{', '}', '=>']);
+const BLOCK_AFTER_KEYWORD = new Set(['else', 'do', 'try', 'finally']);
+
+/** GLSL in a string: one of these marks a shader line; a literal with two different ones (or a long one with one) is shader source. */
+const GLSL = [
+  /#\s*(?:ifdef|ifndef|endif|elif|define|undef|include\s*<|pragma|extension|version)\b/,
+  /\b(?:uniform|varying|attribute)\s+(?:(?:lowp|mediump|highp)\s+)?(?:float|int|uint|bool|[biu]?vec[234]|mat[234](?:x[234])?|sampler\w*)\b/,
+  /\bprecision\s+(?:lowp|mediump|highp)\s+(?:float|int|sampler\w*)\b/,
+  /\bgl_(?:Position|FragColor|FragCoord|FragData|PointSize|PointCoord|InstanceID|VertexID|FrontFacing)\b/,
+  /\bvoid\s+main\s*\(/,
+  /\b(?:texture2D|textureCube|texture2DLodEXT|textureLod|texelFetch)\s*\(/,
+  /\b(?:[biu]?vec[234]|mat[234])\s+\w+\s*[=;,)]/,
+  /\b(?:[biu]?vec[234]|mat[234])\s*\(/,
+  /\b(?:smoothstep|inversesqrt|fract|clamp|saturate|dot|normalize|mix)\s*\([^)]*\)\s*;/,
+];
+function glslScore(text) {
+  // A shader says what it is in its first lines; a huge literal (a base64 blob) is read only that far.
+  const head = text.length > 65_536 ? text.slice(0, 65_536) : text;
+  let n = 0;
+  for (const re of GLSL) if (re.test(head)) n++;
+  return n;
+}
+const isShader = (text) => { const s = glslScore(text); return s >= 2 || (s >= 1 && text.length >= 400); };
+
+const isIdStart = (c) => (c >= 97 && c <= 122) || (c >= 65 && c <= 90) || c === 36 || c === 95 || c >= 0x80 || c === 92;
+const isIdPart = (c) => isIdStart(c) || (c >= 48 && c <= 57);
+const isDigit = (c) => c >= 48 && c <= 57;
+const isWs = (c) => c === 32 || c === 9 || c === 10 || c === 13 || c === 11 || c === 12 || c === 0xa0 || c === 0xfeff || c === 0x2028 || c === 0x2029;
+
+/**
+ * Read `text` (a JavaScript file). Returns the measures above, rounded, and the verdict:
+ *   { minified, mangled, whitespacePct, commentPct, licencePct, codeCharsPerLine, nameLength, shortNamesPct, names,
+ *     stringPct, shaderPct, bytes, why }
+ */
+export function readCode(text) {
+  const src = String(text);
+  const n = src.length;
+  let i = 0;
+  let codeChars = 0; // characters read as code (not in a string, template, comment or regular expression's body)
+  let codeWs = 0;
+  let codeBreaks = 0;
+  let commentChars = 0;
+  let licenceChars = 0;
+  let stringChars = 0;
+  let shaderChars = 0;
+  const names = { count: 0, short: 0, chars: 0 };
+  /** The last significant token: { t: 'name'|'kw'|'num'|'str'|'regex'|'punct', v } */
+  let prev = null;
+  const braces = []; // '{b' a block, '{o' an object or other expression, '${' a template's substitution
+  const parens = []; // true when the ( followed if/while/for/with
+  const templates = []; // the text of each open template literal (one may hold ${ } with another inside)
+
+  const literal = (body) => {
+    stringChars += body.length;
+    if (body.length >= 12 && isShader(body)) shaderChars += body.length;
+  };
+
+  const regexAllowed = () => {
+    if (!prev) return true;
+    if (prev.t === 'name' || prev.t === 'num' || prev.t === 'str' || prev.t === 'regex') return false;
+    if (prev.t === 'kw') return REGEX_AFTER_KEYWORD.has(prev.v);
+    if (prev.v === ')' || prev.v === ']' || prev.v === '}') return false;
+    return true;
+  };
+
+  /** Scan a template literal's text from i up to its closing backtick (done) or a `${` (back to code). */
+  const templateText = () => {
+    const start = i;
+    while (i < n) {
+      const c = src.charCodeAt(i);
+      if (c === 92) { i += 2; continue; }
+      if (c === 96) { templates[templates.length - 1] += src.slice(start, i); i++; literal(templates.pop()); prev = { t: 'str' }; return; }
+      if (c === 36 && src.charCodeAt(i + 1) === 123) { templates[templates.length - 1] += src.slice(start, i); i += 2; braces.push('${'); prev = { t: 'punct', v: '${' }; return; }
+      i++;
+    }
+    templates[templates.length - 1] += src.slice(start, n);
+    literal(templates.pop());
+  };
+
+  while (i < n) {
+    const c = src.charCodeAt(i);
+    if (isWs(c)) {
+      codeChars++; codeWs++;
+      if (c === 10) codeBreaks++;
+      i++;
+      continue;
+    }
+    // Comments.
+    if (c === 47 && src.charCodeAt(i + 1) === 47) {
+      const end = src.indexOf('\n', i);
+      const stop = end < 0 ? n : end;
+      commentChars += stop - i;
+      i = stop;
+      continue;
+    }
+    if (c === 47 && src.charCodeAt(i + 1) === 42) {
+      const end = src.indexOf('*/', i + 2);
+      const stop = end < 0 ? n : end + 2;
+      const body = src.slice(i, stop);
+      if (body.startsWith('/*!') || /@license|@preserve|@copyright/i.test(body)) licenceChars += stop - i; else commentChars += stop - i;
+      i = stop;
+      continue;
+    }
+    // Strings.
+    if (c === 39 || c === 34) {
+      const start = i + 1;
+      let j = start;
+      while (j < n) {
+        const d = src.charCodeAt(j);
+        if (d === 92) { j += 2; continue; }
+        if (d === c || d === 10) break;
+        j++;
+      }
+      literal(src.slice(start, j));
+      i = Math.min(n, j + 1);
+      prev = { t: 'str' };
+      continue;
+    }
+    if (c === 96) { i++; templates.push(''); templateText(); continue; }
+    // Regular expressions (only where an expression can start, and never across a line).
+    if (c === 47 && regexAllowed()) {
+      let j = i + 1;
+      let inClass = false;
+      let ok = false;
+      while (j < n) {
+        const d = src.charCodeAt(j);
+        if (d === 10 || d === 13) break;
+        if (d === 92) { j += 2; continue; }
+        if (d === 91) inClass = true;
+        else if (d === 93) inClass = false;
+        else if (d === 47 && !inClass) { ok = true; break; }
+        j++;
+      }
+      if (ok) {
+        j++;
+        while (j < n && isIdPart(src.charCodeAt(j))) j++;
+        codeChars += j - i;
+        i = j;
+        prev = { t: 'regex' };
+        continue;
+      }
+    }
+    // Names and keywords.
+    if (isIdStart(c)) {
+      let j = i + 1;
+      while (j < n && isIdPart(src.charCodeAt(j))) j++;
+      const word = src.slice(i, j);
+      codeChars += j - i;
+      const afterDot = prev && prev.t === 'punct' && prev.v === '.';
+      if (!afterDot && KEYWORDS.has(word)) prev = { t: 'kw', v: word };
+      else {
+        // A property (after `.`) and an object's key (`{a:` or `,a:`) keep their names in any minifier: not counted.
+        let k = j;
+        while (k < n && isWs(src.charCodeAt(k))) k++;
+        const key = prev && prev.t === 'punct' && (prev.v === '{' || prev.v === ',') && src.charCodeAt(k) === 58 && braces[braces.length - 1] === '{o';
+        if (!afterDot && !key) {
+          names.count++;
+          names.chars += word.length;
+          if (word.length <= 2) names.short++;
+        }
+        prev = { t: 'name', v: word };
+      }
+      i = j;
+      continue;
+    }
+    // Numbers.
+    if (isDigit(c) || (c === 46 && isDigit(src.charCodeAt(i + 1)))) {
+      let j = i + 1;
+      while (j < n) {
+        const d = src.charCodeAt(j);
+        if (isIdPart(d) || d === 46) { j++; continue; }
+        if ((d === 43 || d === 45) && /[eE]/.test(src[j - 1]) && !/^0[xX]/.test(src.slice(i, j))) { j++; continue; }
+        break;
+      }
+      codeChars += j - i;
+      i = j;
+      prev = { t: 'num' };
+      continue;
+    }
+    // Punctuation.
+    codeChars++;
+    if (c === 123) { // {
+      const block = !prev || (prev.t === 'punct' && BLOCK_AFTER_PUNCT.has(prev.v)) || (prev.t === 'kw' && BLOCK_AFTER_KEYWORD.has(prev.v));
+      braces.push(block ? '{b' : '{o');
+      prev = { t: 'punct', v: '{' };
+      i++;
+      continue;
+    }
+    if (c === 125) { // }
+      const open = braces.pop();
+      i++;
+      if (open === '${') { templateText(); continue; }
+      // After a block a statement starts (a `/` there is a regular expression); after an object it is division.
+      prev = { t: 'punct', v: open === '{b' ? ';' : '}' };
+      continue;
+    }
+    if (c === 40) { parens.push(Boolean(prev && prev.t === 'kw' && ['if', 'while', 'for', 'with'].includes(prev.v))); prev = { t: 'punct', v: '(' }; i++; continue; }
+    if (c === 41) { const cond = parens.pop(); prev = { t: 'punct', v: cond ? ';' : ')' }; i++; continue; }
+    if (c === 61 && src.charCodeAt(i + 1) === 62) { codeChars++; prev = { t: 'punct', v: '=>' }; i += 2; continue; }
+    if (c === 46 && src.charCodeAt(i + 1) === 46 && src.charCodeAt(i + 2) === 46) { codeChars += 2; prev = { t: 'punct', v: '...' }; i += 3; continue; }
+    prev = { t: 'punct', v: src[i] };
+    i++;
+  }
+
+  const pct = (a, b) => (b ? Math.round((a / b) * 1000) / 10 : 0);
+  const whitespacePct = pct(codeWs, codeChars);
+  const commentPct = pct(commentChars, n);
+  const licencePct = pct(licenceChars, n);
+  const codeCharsPerLine = Math.round((codeChars - codeWs) / (codeBreaks + 1));
+  const nameLength = names.count ? Math.round((names.chars / names.count) * 10) / 10 : null;
+  const shortNamesPct = pct(names.short, names.count);
+  const stringPct = pct(stringChars, n);
+  const shaderPct = pct(shaderChars, n);
+  // Minified: the code carries almost no whitespace, and almost no comments but its licence. Mangled: most names
+  // one or two characters. (Indented source: 15-30% whitespace; esbuild's or terser's output: 1-2%.)
+  const minified = codeChars > 0 && whitespacePct < 6 && commentPct < 2;
+  const mangled = names.count >= 20 && shortNamesPct >= 70;
+  const said = `whitespace ${whitespacePct}% of the code, comments ${commentPct}%, ${codeCharsPerLine} characters a line of code, names ${nameLength ?? '-'} characters on average (${shortNamesPct}% one or two)`;
+  const why = minified
+    ? `minified${mangled ? ', names shortened' : ', names kept'} (${said})${stringPct >= 15 ? `; ${stringPct}% of its bytes are strings${shaderPct >= 5 ? `, ${shaderPct}% GLSL shader source` : ''}` : ''}`
+    : `not minified (${said})`;
+  return { minified, mangled, whitespacePct, commentPct, licencePct, codeCharsPerLine, nameLength, shortNamesPct, names: names.count, stringPct, shaderPct, bytes: n, why };
+}

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); }
+}