@homie-rocks/studio 0.2.0 → 0.3.0

package/lib/port.mjs

@@ -0,0 +1,277 @@
+/**
+ * `homie-studio port plan <folder>` and `homie-studio port import <folder> --id <id>`:
+ * the first two steps of making an existing single-player web game multiplayer.
+ *
+ * plan   reads the game without running it (loop, input, state, camera, physics,
+ *        storage, audio, network, size) and drafts a port plan: a difficulty
+ *        grade with its reasons, the netplay movement mode, the build mode, the
+ *        check view, and every risk the sandboxed play frame will hit. The agent
+ *        then READS the code and writes the final PORT.md; the draft is a start,
+ *        never the verdict.
+ * import copies the game into games/<id>/ untouched except for two lines (the
+ *        port toolkit first in <head>, a phone-safe viewport), writes game.json,
+ *        and keeps the licence beside it.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join, relative, resolve } from 'node:path';
+import { GAME_ID } from './studio.mjs';
+
+const SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', '.cache', '.parcel-cache', '.vite', 'coverage']);
+const CODE = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.svelte']);
+const TEXT = new Set([...CODE, '.html', '.htm', '.css', '.json', '.md', '.txt', '.glsl', '.frag', '.vert', '.tmx', '.xml', '.svg']);
+const MAX_READ = 2 * 1024 * 1024;
+
+function walk(dir, rel = '', out = []) {
+  for (const e of readdirSync(join(dir, rel), { withFileTypes: true })) {
+    if (SKIP.has(e.name)) continue;
+    const p = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) walk(dir, p, out);
+    else if (e.isFile()) out.push({ path: p, bytes: statSync(join(dir, p)).size, ext: extname(e.name).toLowerCase() });
+  }
+  return out;
+}
+
+const count = (text, re) => (text.match(re) ?? []).length;
+
+/** A licence file's SPDX-ish kind, from its words. */
+export function licenceOf(dir) {
+  const names = readdirSync(dir).filter((n) => /^(licen[cs]e|copying)(\.|$)/i.test(n));
+  if (!names.length) {
+    const pkg = existsSync(join(dir, 'package.json')) ? JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) : null;
+    return { file: null, kind: pkg?.license ? `${pkg.license} (package.json only)` : 'none', permissive: false };
+  }
+  const text = readFileSync(join(dir, names[0]), 'utf8');
+  let kind = 'unknown';
+  if (/Permission is hereby granted, free of charge/i.test(text)) kind = 'MIT';
+  else if (/Apache License[\s\S]{0,40}Version 2\.0/i.test(text)) kind = 'Apache-2.0';
+  else if (/Redistribution and use in source and binary forms/i.test(text)) kind = /Neither the name/i.test(text) ? 'BSD-3-Clause' : 'BSD-2-Clause';
+  else if (/Permission to use, copy, modify, and\/or distribute/i.test(text)) kind = 'ISC';
+  else if (/GNU AFFERO GENERAL PUBLIC LICENSE/i.test(text)) kind = 'AGPL';
+  else if (/GNU LESSER GENERAL PUBLIC LICENSE/i.test(text)) kind = 'LGPL';
+  else if (/GNU GENERAL PUBLIC LICENSE/i.test(text)) kind = 'GPL';
+  else if (/Mozilla Public License/i.test(text)) kind = 'MPL-2.0';
+  else if (/This is free and unencumbered software released into the public domain/i.test(text)) kind = 'Unlicense';
+  else if (/Creative Commons/i.test(text)) kind = 'Creative Commons';
+  return { file: names[0], kind, permissive: ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'BSD-2-Clause', 'ISC', 'Unlicense'].includes(kind) };
+}
+
+/** Read a game folder and draft its port plan. */
+export function planPort(folder) {
+  const dir = resolve(folder ?? '.');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`${dir} is not a folder`);
+  const files = walk(dir);
+  const texts = [];
+  let read = 0;
+  for (const f of files) {
+    if (!TEXT.has(f.ext) || f.bytes > 1024 * 1024 || read > MAX_READ) continue;
+    // Vendored libraries (three.module.js, jquery…) are not the game: counted, not analysed.
+    const vendored = /(^|\/)(vendor|libs?|third[-_]?party|build|jsm|addons|node_modules)\//i.test(f.path) || /(^|\/)(GLTFLoader|OBJLoader|FBXLoader|OrbitControls|PointerLockControls|BufferGeometryUtils|Octree|Capsule|OctreeHelper|EffectComposer|RenderPass|UnrealBloomPass)\.js$/.test(f.path) || /(\.min\.js|three(\.module)?\.js|three\.core\.js|jquery[-.\d]*\.js|phaser[.\w-]*\.js|pixi[.\w-]*\.js|matter[.\w-]*\.js|cannon[.\w-]*\.js|howler[.\w-]*\.js|lil-gui[.\w-]*\.js|stats[.\w-]*\.js|typeface\.js)$/i.test(f.path);
+    const text = readFileSync(join(dir, f.path), 'utf8');
+    read += text.length;
+    texts.push({ ...f, text, vendored });
+  }
+  const game = texts.filter((t) => !t.vendored && (CODE.has(t.ext) || t.ext === '.html' || t.ext === '.htm'));
+  const all = game.map((t) => t.text).join('\n');
+  const everything = texts.map((t) => t.text).join('\n');
+  const loc = game.filter((t) => CODE.has(t.ext)).reduce((n, t) => n + t.text.split('\n').length, 0)
+    + game.filter((t) => t.ext === '.html').reduce((n, t) => n + (t.text.match(/<script(?![^>]*src)[^>]*>[\s\S]*?<\/script>/gi) ?? []).join('\n').split('\n').length, 0);
+  const totalBytes = files.reduce((n, f) => n + f.bytes, 0);
+  const pkg = existsSync(join(dir, 'package.json')) ? JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) : null;
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const html = files.filter((f) => f.ext === '.html' || f.ext === '.htm').map((f) => f.path);
+  const index = html.find((p) => /(^|\/)index\.html?$/i.test(p) && !p.includes('/')) ?? html.find((p) => /index\.html?$/i.test(p)) ?? html[0] ?? null;
+  const indexText = index ? readFileSync(join(dir, index), 'utf8') : '';
+  const scripts = [...indexText.matchAll(/<script\b([^>]*)>/gi)].map((m) => ({ src: /src=["']([^"']+)["']/i.exec(m[1])?.[1] ?? null, module: /type=["']module["']/i.test(m[1]) }));
+  const has = (re) => re.test(all) || re.test(everything);
+
+  const engine = [];
+  if (has(/from ['"]three['"]|THREE\.|three\.module\.js|three\.core\.js/)) engine.push('three.js');
+  if (has(/BABYLON\.|@babylonjs/)) engine.push('babylon.js');
+  if (has(/new Phaser\.Game|from ['"]phaser['"]/)) engine.push('phaser');
+  if (has(/PIXI\.|from ['"]pixi\.js['"]/)) engine.push('pixi.js');
+  if (has(/\bkaboom\(|from ['"]kaboom['"]|from ['"]kaplay['"]/)) engine.push('kaboom');
+  if (has(/\bengineInit\(|LittleJS/)) engine.push('littlejs');
+  if (has(/\bme\.game\b|melonJS/)) engine.push('melonjs');
+  if (/function setup\s*\(|function draw\s*\(/.test(all) && /createCanvas\(/.test(all)) engine.push('p5');
+  if (!engine.length && /getContext\(\s*['"]2d['"]/.test(all)) engine.push('canvas-2d');
+  if (!engine.length && /getContext\(\s*['"](webgl2?|experimental-webgl)['"]/.test(all)) engine.push('webgl');
+  if (!engine.length) engine.push('dom');
+  const threeD = engine.some((e) => ['three.js', 'babylon.js', 'webgl'].includes(e));
+
+  const physics = [];
+  for (const [re, name] of [[/matter-js|Matter\.Engine/, 'matter.js'], [/cannon(-es)?|CANNON\./, 'cannon'], [/@dimforge\/rapier|RAPIER\./, 'rapier'], [/planck|Box2D|box2d/, 'box2d/planck'], [/ammo\.js|Ammo\(/, 'ammo.js'], [/oimo/i, 'oimo'], [/\bOctree\b.*capsule|Capsule\b/i, 'three octree collisions']]) {
+    if (has(re)) physics.push(name);
+  }
+  const customPhysics = /gravity/i.test(all) && /(dy|vy|velocity|\.vel)\b/i.test(all);
+
+  const loop = {
+    raf: count(all, /requestAnim(ation)?Frame|setAnimationLoop|\bticker\.add|scene\.registerBeforeRender|engine\.runRenderLoop/g),
+    interval: count(all, /setInterval\s*\(/g),
+    timeoutLoop: count(all, /setTimeout\s*\(/g),
+  };
+  const input = {
+    keys: count(all, /['"]key(down|up|press)['"]|onkey(down|up|press)|\.key(down|up)\s*\(/gi),
+    keyCode: count(all, /keyCode|\.which\b/g),
+    mouse: count(all, /['"](mouse(down|up|move)|click|dblclick|wheel|contextmenu)['"]|onclick|\.click\s*\(/gi),
+    pointer: count(all, /['"]pointer(down|up|move|cancel)['"]/g),
+    touch: count(all, /['"]touch(start|move|end|cancel)['"]|ontouch/g),
+    pointerLock: count(all, /requestPointerLock/g),
+    gamepad: count(all, /getGamepads/g),
+  };
+  const camera = {
+    perspective: count(all, /PerspectiveCamera/g),
+    orthographic: count(all, /OrthographicCamera/g),
+    followsHeading: /camera\.(rotation\.y|quaternion)\s*[=.]|camera\.lookAt\([^)]*(dir|heading|forward)/i.test(all),
+    firstPerson: input.pointerLock > 0 || /first[-\s]?person|PointerLockControls|FirstPersonControls/i.test(all),
+    twoDScroll: /(camera|viewport|cam)\.(x|y)\s*[+\-]?=|ctx\.translate\(/.test(all),
+  };
+  const storage = { localStorage: count(all, /localStorage/g), sessionStorage: count(all, /sessionStorage/g), indexedDB: count(all, /indexedDB/g), cookie: count(all, /document\.cookie/g) };
+  const audio = { webAudio: count(all, /AudioContext/g), media: count(all, /new Audio\(|<audio|\.play\(\)/g), howler: count(everything, /Howl\b|howler/g), tone: count(all, /Tone\./g) };
+  const network = {
+    fetch: count(all, /\bfetch\s*\(/g), xhr: count(all, /XMLHttpRequest|\$\.(get|getJSON|ajax)\(/g), websocket: count(all, /new WebSocket\(/g),
+    absolutePaths: [...new Set([...(indexText + all).matchAll(/(?:src|href)=["'](\/[^/"'][^"']*)["']|fetch\(\s*["'](\/[^/"'][^"']*)["']/g)].map((m) => m[1] ?? m[2]))].slice(0, 12),
+    cdn: [...new Set([...indexText.matchAll(/(?:src|href)=["'](https?:\/\/[^"']+)["']/g)].map((m) => new URL(m[1]).host))],
+  };
+  const workers = count(all, /new (Shared)?Worker\(/g);
+  const wasm = files.filter((f) => f.ext === '.wasm').length + count(all, /WebAssembly\./g);
+  const dialogs = count(all, /\b(alert|confirm|prompt)\s*\(/g);
+  const random = count(all, /Math\.random\(/g);
+  const multiplayer = /socket\.io|peerjs|new RTCPeerConnection|colyseus|firebase/i.test(everything);
+  const homiePackage = existsSync(join(dir, 'homie.json'));
+  const houseApi = /@homie\/(tabletop|arcade)|\bhomie\.(ready|report|showPrivate|on\(|seats)|__homie\//.test(all);
+  // Real time: a body moved by time (dt, velocity, speed × delta, a game loop); turn-based: moves on input only.
+  const realtime = count(all, /\bdt\b|deltaTime|\bdelta\b|velocity|\.vel\b|\.vx\b|\.vy\b|\bvx\b|\bvy\b|speed\s*\*|mainLoop|gameLoop|getDelta\(|update\(\s*(dt|delta|step)/g);
+  const boardWords = count(all, /\b(turn|board|grid|tile|cell|move\(\s*(direction|dir)|swipe)s?\b/gi);
+  const turnBased = (loop.raf === 0 && loop.interval === 0) || (realtime <= 2 && boardWords >= 3);
+  const timing = /\b(rhythm|beat|bpm|frame[-\s]?perfect|metronome)\b/i.test(all);
+  const sideView = !threeD && /gravity/i.test(all) && /jump/i.test(all);
+  const ammo = /bullet|projectile|missile|shoot|fire/i.test(all);
+
+  // ---------------------------------------------------------------- grade
+  const reasons = [];
+  let grade = 'easy';
+  const up = (to, why) => { const order = ['easy', 'medium', 'hard', 'not a fit']; if (order.indexOf(to) > order.indexOf(grade)) grade = to; reasons.push(`${to}: ${why}`); };
+  if (!index) up('not a fit', 'no index.html: a studio game is a web page');
+  if (multiplayer) up('not a fit', 'it already has its own networking (socket.io/peer/firebase): port its rules instead, or keep it on its own server');
+  if (network.websocket) up('hard', 'it opens its own WebSocket: a server it depends on will not be there');
+  if (wasm && /SharedArrayBuffer/.test(all)) up('not a fit', 'WebAssembly threads need cross-origin isolation, which the sandboxed play frame cannot give');
+  if (totalBytes > 60 * 1024 * 1024) up('hard', `${Math.round(totalBytes / 1048576)} MB of files: every visitor downloads all of it (keep a game well under 30 MB)`);
+  if (timing) up('hard', 'precise timing (rhythm/beat): every screen needs the same clock; run the beat from the room clock (net.now())');
+  if (physics.length && !turnBased) up('hard', `fast physics (${physics.join(', ')}): the host simulates the world; each player owns only their own body`);
+  if (threeD && !turnBased) up(physics.length ? 'hard' : 'medium', `real-time 3D (${engine.join(', ')}): camera rules, screen-relative input and a stable yaw are needed`);
+  if (camera.followsHeading) up('medium', 'the camera turns with the character: it must stop (input on screen axes, yaw only on look input)');
+  if (camera.firstPerson) up('medium', 'first person with pointer lock: phones need a look-drag and a stick, and hits need the host');
+  if (!turnBased && !threeD) up(customPhysics ? 'medium' : 'easy', customPhysics ? 'real-time 2D with its own gravity/velocity: owner movement keeps jumps local, the host runs everything else' : 'real-time 2D movement: owner movement');
+  if (turnBased) reasons.push('easy: turn-based or grid rules: the host runs the rules from intents (host movement); or a race where everyone plays the same seed');
+  if (loc > 6000) up('hard', `${loc} lines of game code: huge state; find the few things other players must see`);
+  else if (loc > 2500) up('medium', `${loc} lines of game code`);
+  if (ammo && !turnBased) up('medium', 'projectiles and hits: the host decides every hit and carries projectiles in the snapshot');
+  if (workers) up('medium', 'it starts Web Workers: a sandboxed frame (opaque origin) cannot load a worker script by URL; inline it or drop it');
+  if (network.absolutePaths.length) up('medium', `absolute paths (${network.absolutePaths.slice(0, 3).join(', ')}): the game is served under /<id>/__game/, so every path must be relative`);
+  if (grade === 'easy' && !reasons.length) reasons.push('easy: a small game with simple state');
+
+  const movement = turnBased ? 'host' : 'owner';
+  const view = turnBased ? 'board' : camera.firstPerson ? 'first-person' : sideView ? 'side' : 'top';
+  const buildMode = pkg?.scripts?.build && Object.keys(deps).some((d) => /^(vite|webpack|parcel|rollup|esbuild|@sveltejs|next)/.test(d)) ? 'command'
+    : scripts.some((s) => s.module) || indexText.includes('importmap') ? 'static'
+      : 'static';
+
+  const risks = [];
+  if (storage.localStorage || storage.sessionStorage || storage.cookie) risks.push('storage: localStorage/cookies throw in the sandboxed frame; the port toolkit (homie-port.js / port/early) puts in-memory stand-ins first. High scores last for the visit.');
+  if (storage.indexedDB) risks.push('indexedDB is blocked in the sandboxed frame: guard every open() or drop it.');
+  if (dialogs) risks.push(`${dialogs} alert/confirm/prompt call(s): they block every browser in the room and the host's clock; replace with in-game text.`);
+  if (audio.webAudio || audio.media || audio.howler) risks.push('audio: starts suspended; the toolkit resumes it on the first touch/key. Remove any "click to start sound" gate that blocks play.');
+  if (input.keys && !input.touch && !input.pointer) risks.push('keyboard only: phones need the touch kit (a floating stick that presses the same keys, small buttons for actions).');
+  if (input.mouse && !input.touch) risks.push('mouse input: map it to touch (tap/drag) explicitly; do not rely on emulated mouse events on phones.');
+  if (input.pointer && /pointerId\s*[<>]=?\s*0|pointerId\s*===?\s*-1|=\s*-1\s*;?\s*\/\/.*(touch|pointer)/.test(all)) risks.push('a negative pointer id is used as "no finger": iOS Safari ids are negative half the time. Use null.');
+  if (loop.raf === 0 && loop.interval > 0) risks.push('the loop runs on setInterval: keep the rules on the host, and make rendering follow snapshots.');
+  if (random > 0 && !turnBased) risks.push(`${random} Math.random() call(s): randomness that changes the world must happen on the host only (replicas get the result in snapshots or keyed state).`);
+  if (network.cdn.length) risks.push(`loads from other hosts (${network.cdn.join(', ')}): copy those files into the game so it cannot break when a CDN does.`);
+  if (camera.perspective && !camera.firstPerson) risks.push('3D camera: verify the owner tests (hold 5 s: straight line, yaw < 10°; alternate 10 s: every press goes the pressed way).');
+  if (/antialias\s*:\s*true/.test(all) && threeD) risks.push('MSAA (antialias: true) drew a black world on iPhone WebKit in a past port; turn it off on WebKit or everywhere.');
+  if (ammo && !turnBased) risks.push('projectiles/hits: the host decides every hit (a shooter\'s claim may be checked against recent positions); projectiles ride the snapshot.');
+
+  if (houseApi) risks.push('it is written for a shared TV screen with phone pads (a Homie package): on the web every browser is its own screen and there is no pad. Keep its rules, drive them from netplay seats, keys and the touch kit, and give it a page of its own (index.html that boots the rules and draws them).');
+  if (houseApi) up('medium', 'written for a shared TV screen and phone pads: the rules are reusable, the seats and the screen are not');
+  const licence = licenceOf(dir);
+  if (!licence.file && homiePackage) { licence.kind = 'a Homie package (the house\'s own game; no licence file)'; licence.permissive = true; }
+  if (!licence.permissive) risks.push(`licence: ${licence.kind}${licence.file ? ` (${licence.file})` : ''} — publish only what its licence allows; with no licence, do not publish it.`);
+
+  return {
+    ok: true, command: 'port plan', folder: dir, grade, reasons,
+    facts: {
+      files: files.length, bytes: totalBytes, loc, index, scripts: scripts.slice(0, 12), engine, physics, customPhysics, loop, input, camera, storage, audio,
+      network, workers, wasm, dialogs, random, realtime, boardWords, turnBased, sideView, houseApi, package: pkg ? { name: pkg.name, scripts: Object.keys(pkg.scripts ?? {}), deps: Object.keys(deps).slice(0, 30) } : null,
+    },
+    recommend: { movement, view, build: buildMode },
+    risks, licence,
+  };
+}
+
+/** Copy a game into games/<id>/ as this studio's port of it. */
+export function importPort(root, folder, id, { name, mode } = {}) {
+  if (!GAME_ID.test(String(id ?? ''))) throw new Error('give the port an id: --id <lowercase-id> (letters, digits, hyphens)');
+  const src = resolve(folder ?? '');
+  if (!existsSync(src) || !statSync(src).isDirectory()) throw new Error(`${src} is not a folder`);
+  const dest = join(root, 'games', id);
+  if (existsSync(dest)) throw new Error(`games/${id} already exists; pick another id`);
+  const rel = relative(src, dest);
+  if (!rel.startsWith('..') && rel !== '') throw new Error('the game folder cannot contain the studio');
+  const plan = planPort(src);
+  if (!plan.facts.index) throw new Error(`${src} has no index.html; nothing to port`);
+  const buildMode = mode ?? plan.recommend.build;
+  mkdirSync(dest, { recursive: true });
+  const copied = [];
+  const copy = (rel2 = '') => {
+    for (const e of readdirSync(join(src, rel2), { withFileTypes: true })) {
+      if (SKIP.has(e.name) || (buildMode !== 'command' && e.name === 'dist')) continue;
+      const p = rel2 ? `${rel2}/${e.name}` : e.name;
+      if (e.isDirectory()) { mkdirSync(join(dest, p), { recursive: true }); copy(p); }
+      else if (e.isFile()) { cpSync(join(src, p), join(dest, p)); copied.push(p); }
+    }
+  };
+  copy();
+  // A static game needs index.html at its root (the Worker serves games/<id>/index.html).
+  if (buildMode === 'static' && plan.facts.index !== 'index.html') throw new Error(`the game's page is ${plan.facts.index}; move it to the folder's root as index.html first`);
+  const title = /<title>([^<]{1,80})<\/title>/i.exec(readFileSync(join(src, plan.facts.index), 'utf8'))?.[1]?.trim();
+  const meta = {
+    id,
+    name: String(name ?? title ?? id).slice(0, 60),
+    blurb: '',
+    players: { min: 1, max: 8 },
+    roundSeconds: 120,
+    build: buildMode === 'command' ? { mode: 'command', command: 'npm run build', out: 'dist' } : { mode: buildMode },
+    netplay: { v: 1, public: true, movement: plan.recommend.movement },
+    port: { from: basename(src), licence: plan.licence.kind, licenceFile: plan.licence.file, grade: plan.grade, view: plan.recommend.view, at: new Date().toISOString() },
+  };
+  writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
+  const edits = [];
+  if (buildMode === 'static') {
+    const indexPath = join(dest, 'index.html');
+    let html = readFileSync(indexPath, 'utf8');
+    if (!/homie-port\.js/.test(html)) {
+      const tag = '<script src="./homie-port.js"></script>';
+      // First script in <head>, after a charset declaration if there is one.
+      if (/<meta[^>]+charset[^>]*>/i.test(html)) html = html.replace(/<meta[^>]+charset[^>]*>/i, (m) => `${m}\n${tag}`);
+      else html = /<head[^>]*>/i.test(html) ? html.replace(/<head([^>]*)>/i, (m) => `${m}\n${tag}`) : `${tag}\n${html}`;
+      edits.push('index.html: loads ./homie-port.js first (sandbox shims, first-touch audio, window.HomiePort)');
+    }
+    const vp = 'width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover';
+    if (/<meta[^>]+name=["']viewport["'][^>]*>/i.test(html)) {
+      html = html.replace(/<meta[^>]+name=["']viewport["'][^>]*>/i, `<meta name="viewport" content="${vp}">`);
+      edits.push('index.html: phone-safe viewport (no pinch-zoom under a thumb)');
+    } else {
+      html = /<meta[^>]+charset[^>]*>/i.test(html) ? html.replace(/<meta[^>]+charset[^>]*>/i, (m) => `${m}\n<meta name="viewport" content="${vp}">`) : html.replace(/<head([^>]*)>/i, (m) => `${m}\n<meta name="viewport" content="${vp}">`);
+      edits.push('index.html: added a phone-safe viewport');
+    }
+    writeFileSync(indexPath, html);
+  }
+  return {
+    ok: true, command: 'port import', id, dir: dest, from: src, mode: buildMode, files: copied.length, edits, plan: { grade: plan.grade, movement: plan.recommend.movement, view: plan.recommend.view },
+    next: [
+      `Write games/${id}/PORT.md: the grade and why, the movement mode, what the host owns, what each browser owns, bots, touch, camera.`,
+      buildMode === 'static' ? 'Add the netplay layer as a script after the game\'s own (HomiePort.createRoom …), or an "entry" in game.json bundled to assets/main.js.' : 'Import \'@homie-rocks/studio/port/early\' first, then build the netplay layer with createRoom.',
+      `npm run dev (in the background), then: npx --no-install homie-studio port check ${id} --url http://127.0.0.1:8787`,
+    ],
+  };
+}

package/lib/scaffold.mjs

@@ -80,6 +80,10 @@ studio's pinned copy, never a registry lookup of the bare name.
 
 - \`npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>"\` — a new game from a
   multiplayer starter (one live public room from its first build, bots fill seats).
+- \`npx --no-install homie-studio port plan <folder>\` — read an existing single-player web game and grade
+  how hard making it multiplayer will be; \`port import\` brings it into \`games/\`, \`port check\` runs the
+  owner tests (real touch, a late joiner, a killed host, two browsers finishing a round). The Homie
+  plugin's \`port\` skill does the whole job.
 - \`npm run build\` — bundle every game into \`site/dist\`.
 - \`npm run dev\` — the whole site locally (pages, the netplay relay in a local
   Durable Object, D1): open the printed address in two browsers and they share a room.
@@ -153,6 +157,8 @@ site/.wrangler/
 .dev.vars
 .env
 *.log
+# Port checks: receipts and screenshots of each run (games/<id>/.port/check-*/).
+games/*/.port/
 # Large media lives in this studio's R2; the manifests beside it are committed.
 music/**/*.wav
 music/**/*.mp3

package/netplay/netplay.ts

@@ -254,6 +254,17 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   readonly spectator: boolean;
   readonly offline: boolean;
   readonly connected: boolean;
+  /** Why the client stopped for good (a refusal reconnecting would repeat: 'replaced', 'room-full', ...), else null. */
+  readonly closedWhy: string | null;
+  /** How long the socket has been down while it reconnects (ms; 0 while connected). */
+  readonly downMs: number;
+  /**
+   * Host: hand the room to another browser — a checkpoint, then the protocol's `yield` (the same road a hidden
+   * tab takes). The relay elects the best other candidate, or keeps me host when nobody else can host.
+   * Use it when a big screen or a struggling phone should give the room to a seated computer (never in a
+   * host's first 30 s, at most once a minute); false when not sent.
+   */
+  handOff(): boolean;
   /** Seated replica: true while my browser moves my body; false while the host does (host movement, or taken). */
   readonly owned: boolean;
   readonly id: string | null;
@@ -476,8 +487,26 @@ export class Roster {
 /* --------------------------------------------------------------- the client */
 
 const LADDER = [250, 500, 1000, 2000, 4000];
-/** Relay errors after which reconnecting would only repeat the refusal. */
-const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many', 'flood']);
+/**
+ * Relay errors after which reconnecting would only repeat the refusal. A 'flood' kick is NOT one: a replica's
+ * inputs bunch up behind a stall it did not cause (a host migration, a relay or network hiccup that delivers a
+ * second of frames at once), and a kick that ended the page's play for good left a phone frozen with no word.
+ * After one it comes back (its seat token keeps its body), sending at the slow rate below.
+ */
+const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many']);
+/**
+ * Input pacing (NETPLAY.md §5): at most this many `in` frames in any rolling second from this browser, whatever
+ * the frame rate or the press rate: two thirds of the relay's cap of 60, so frames that reach it bunched (a
+ * stall anywhere between) still fit under the cap.
+ */
+const IN_CAP_PER_S = 32;
+/** Longest a page with a live socket listens for the relay's welcome before it plays alone (ms of time it could listen). */
+const CONNECT_OPEN_MAX_MS = 10_000;
+/** After the relay reports dropped inputs (or kicked this browser for them): the cap for the next while. */
+const IN_SLOW_CAP_PER_S = 15;
+const IN_SLOW_MS = 8000;
+/** A socket with this much still unsent does not queue another input frame (the newest one waits instead). */
+const IN_BACKLOG_BYTES = 2048;
 
 function heldList(held: Iterable<string> | Record<string, boolean> | undefined): string[] {
   if (!held) return [];
@@ -606,6 +635,13 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let prevHeld = new Set<string>();
   let pendingPresses: Record<string, number> = {};
   let inputTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Wall times of the input frames sent in the last second, and until when the slow cap holds. */
+  const inSent: number[] = [];
+  let inSlowUntil = 0;
+  /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
+  let closedWhy: string | null = null;
+  /** Wall time the socket went down (0 while connected): how long a reconnect has taken. */
+  let downSince = 0;
   const sentHist: { q: number; a: A; h: string[]; at: number; r: number }[] = [];
   const inputs = new Map<number, InputFrame<A>>();
   const presses = new Map<number, Record<string, number>>();
@@ -798,12 +834,15 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       }
       case 'error': {
         const code = String(m['code'] ?? '');
+        // Inputs over the relay's cap were dropped: send fewer for a while (the newest frame still goes out).
+        if ((code === 'rate' && m['of'] === 'in') || code === 'flood') inSlowUntil = wall() + IN_SLOW_MS;
         if (code === 'rate' || code === 'state-full') { warnOnce(`${code}:${String(m['of'] ?? '')}`, m['message']); return; }
         console.warn('[netplay] relay refused:', code, m['message']);
         // The same seat opened in another tab, a full room, a version the relay does not speak: reconnecting
         // would repeat the refusal (or, for 'replaced', make the two tabs evict each other for ever).
         if (FINAL_ERRORS.has(code)) {
           closed = true;
+          closedWhy = code;
           post?.({ what: 'closed', why: code });
         }
         return;
@@ -846,6 +885,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (next === 'host' && !snap && !continuing) snap = localSnap();
     offline = false;
     connected = true;
+    downSince = 0;
     attempt = 0;
     emit('status', true);
     post?.({ what: 'token', token, seat, room: cfg?.room ?? null });
@@ -897,10 +937,14 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         if (ages.length > 40) ages.shift();
         const sorted = [...ages].sort((x, y) => x - y);
         ageP90 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.9))] as number;
+        // The 95th percentile and 1.4 intervals, not the 90th and 1.2. A phone host's frame
+        // quantisation (snapshots at 50/67 ms) plus 30-50 ms relay jitter held the picture on 5-8 % of a desktop
+        // replica's frames in the contract e2e (interpolation-not-starved); this buys ~20 ms of delay for it.
+        const ageP95 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))] as number;
         // Render far enough back that the next snapshot is normally here before we need it: its age, plus one
         // interval. Rise up to 6 ms a snapshot (a hold is visible); fall 6% of the excess a snapshot, at least 3 ms
         // (boot-time jank clears in about a second, as a brief time-warp nobody sees).
-        const target = Math.max(50, Math.min(400, ageP90 + iv * 1.2 + 4));
+        const target = Math.max(50, Math.min(400, ageP95 + iv * 1.4 + 6));
         if (!delaySmooth || ages.length <= 3) delaySmooth = target;
         else if (target > delaySmooth) delaySmooth += Math.min(6, target - delaySmooth);
         else delaySmooth -= Math.min(delaySmooth - target, Math.max(3, (delaySmooth - target) * 0.06));
@@ -1010,9 +1054,24 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     raw({ t: 'ckpt', k: c.k, st: c.st, d: c.d, c: c.c });
   }
 
+  /** How long until one more input frame fits the rolling-second cap (0: now). */
+  function inputBudgetWait(): number {
+    const t = wall();
+    while (inSent.length && (inSent[0] as number) <= t - 1000) inSent.shift();
+    const cap = t < inSlowUntil ? IN_SLOW_CAP_PER_S : IN_CAP_PER_S;
+    if (inSent.length < cap) return 0;
+    return Math.max(1, (inSent[inSent.length - cap] as number) + 1000 - t);
+  }
+
   function flushInput(): void {
     inputTimer = null;
     if (role === 'host' || seat === null || offline || !connected || pendingA === undefined) return;
+    // Never a burst: over the cap, or with the last frames still unsent on the socket, the newest frame waits
+    // (it replaces whatever was pending, so nothing stale is ever flushed after a stall).
+    const budget = inputBudgetWait();
+    const backlog = (ws?.bufferedAmount ?? 0) > IN_BACKLOG_BYTES;
+    if (budget > 0 || backlog) { inputTimer = setTimeout(flushInput, backlog ? Math.max(budget, 30) : budget); return; }
+    inSent.push(wall());
     inSeq += 1;
     const msg: Record<string, unknown> = { t: 'in', q: inSeq, a: pendingA, h: pendingHeld, r: mine.rs };
     if (Object.keys(pendingPresses).length) msg['p'] = pendingPresses;
@@ -1026,7 +1085,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
 
   function scheduleInput(urgent: boolean): void {
     const since = wall() - lastInputSentAt;
-    const wait = urgent ? Math.max(0, 16 - since) : Math.max(0, inputMs - since);
+    const wait = Math.max(inputBudgetWait(), urgent ? Math.max(0, 16 - since) : Math.max(0, inputMs - since));
     if (wait <= 0) { if (inputTimer) { clearTimeout(inputTimer); inputTimer = null; } flushInput(); return; }
     if (inputTimer) return;
     inputTimer = setTimeout(flushInput, wait);
@@ -1071,6 +1130,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (why !== 'closed') { try { sock.close(4000, why); } catch { /* gone */ } }
     const was = connected;
     connected = false;
+    if (was) downSince = wall();
     if (was) emit('status', false);
     notifyStats(true);
     retry();
@@ -1106,8 +1166,24 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   } else {
     post?.({ what: 'attached', v: NETPLAY_VERSION });
     open();
-    // A relay that never answers must not leave a game on a black screen.
-    connectTimer = setTimeout(() => { if (!roleKnown) goOfflineHost('relay-timeout'); }, connectTimeoutMs);
+    // A relay that never answers must not leave a game on a black screen. But the wait is counted only while
+    // this page is able to listen: a phone compiling shaders under load is blocked for seconds at a time, and
+    // neither its socket's open nor the relay's welcome can be handled meanwhile. Giving up on the wall clock
+    // started a private fight 1 at every loaded boot and swapped it for the room's a moment later. A socket
+    // that is connecting or open gets CONNECT_OPEN_MAX_MS of that listening time; one that failed outright
+    // (ws is null between retries) gets connectTimeoutMs.
+    let listenedMs = 0;
+    let lastCheckAt = wall();
+    const connectCheck = (): void => {
+      if (roleKnown) return;
+      const t = wall();
+      listenedMs += Math.min(t - lastCheckAt, 600);
+      lastCheckAt = t;
+      const live = Boolean(ws && (ws.readyState === 0 || ws.readyState === 1));
+      if (listenedMs < (live ? CONNECT_OPEN_MAX_MS : connectTimeoutMs)) { connectTimer = setTimeout(connectCheck, 250); return; }
+      goOfflineHost('relay-timeout');
+    };
+    connectTimer = setTimeout(connectCheck, 250);
     pingTimer = setInterval(ping, 2000);
     ckptTimer = setInterval(sendCheckpoint, checkpointMs);
     statsTimer = setInterval(() => notifyStats(true), 500);
@@ -1133,6 +1209,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     get spectator() { return seat === null && !offline; },
     get offline() { return offline; },
     get connected() { return connected; },
+    get closedWhy() { return closedWhy; },
+    get downMs() { return connected || !downSince ? 0 : wall() - downSince; },
     get owned() { return role === 'host' || offline || seat === null ? true : mine.own; },
     get id() { return id; },
     get name() { return name; },
@@ -1161,8 +1239,10 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       const c = ctlWire();
       const text = JSON.stringify(c.length ? { t: 'snap', k: tick, st, d, c } : { t: 'snap', k: tick, st, d });
       if (!ws || ws.readyState !== 1) return false;
-      // A congested socket drops a snapshot rather than queueing a stale one.
-      if ((ws.bufferedAmount ?? 0) > 256 * 1024) return false;
+      // A congested socket drops a snapshot rather than queueing a stale one. At 3 KB (about six
+      // snapshots), not 256 KB. A starved network thread on a loaded phone held a second of snapshots and then
+      // flushed them at once; the relay counted 30+ in a second, dropped them, and called the host stalled.
+      if ((ws.bufferedAmount ?? 0) > 3 * 1024) return false;
       try { ws.send(text); } catch { return false; }
       countBytes(bytesOut, text.length);
       lastSnapSentAt = wall();
@@ -1173,6 +1253,11 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       return true;
     },
     checkpointNow: sendCheckpoint,
+    handOff() {
+      if (role !== 'host' || offline || !connected || peers.size < 2) return false;
+      sendCheckpoint();
+      return raw({ t: 'yield' });
+    },
     round(r) {
       roundInfo = r;
       post?.({ what: 'round', round: r });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.2.0",
-  "description": "A game studio on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, the site Worker with public rooms (Table/Lobby Durable Objects, D1, R2), deploy, and the homie.rocks directory.",
+  "version": "0.3.0",
+  "description": "A game studio on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects, D1, R2), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://homie.rocks/studio/",
@@ -18,6 +18,14 @@
       "types": "./netplay/netplay.ts",
       "default": "./netplay/netplay.ts"
     },
+    "./port": {
+      "types": "./port/index.ts",
+      "default": "./port/index.ts"
+    },
+    "./port/early": {
+      "types": "./port/early.ts",
+      "default": "./port/early.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -25,6 +33,7 @@
     "bin/",
     "lib/",
     "netplay/",
+    "port/",
     "worker/",
     "starters/",
     "README.md",

package/port/audio.ts

@@ -0,0 +1,96 @@
+/*
+ * Sound that starts on the first touch, with no "tap for sound" screen.
+ *
+ * Browsers start every AudioContext suspended and refuse media.play() until a
+ * person has touched the page. A single-player game usually handled that with
+ * a title screen; a multiplayer port drops the player straight into a live
+ * round, so the unlock has to ride the first real input instead:
+ *
+ *   - every AudioContext the game makes is remembered (the constructor is
+ *     wrapped, so install this BEFORE the game's code runs);
+ *   - on pointerdown / pointerup / touchstart / touchend / keydown / click
+ *     (capture phase, so a game that stops propagation still unlocks), every
+ *     suspended context is resumed inside the gesture and plays one silent
+ *     sample (iOS needs a sound started inside the gesture);
+ *   - a media element whose play() was refused is played again on that gesture;
+ *   - iOS's silent switch mutes Web Audio unless the audio session says
+ *     "playback".
+ * A held stick only counts as a gesture when the finger lifts (browsers grant
+ * activation on touchend), so the first tap or the first release is when sound
+ * begins. Say so nowhere: it just works.
+ */
+
+type Ctx = AudioContext;
+const contexts = new Set<Ctx>();
+const refused = new Set<HTMLMediaElement>();
+let installed = false;
+let unlockedAt = 0;
+let gestures = 0;
+
+function silentTick(ctx: Ctx): void {
+  try {
+    const b = ctx.createBuffer(1, 1, 22050);
+    const s = ctx.createBufferSource();
+    s.buffer = b;
+    s.connect(ctx.destination);
+    s.start(0);
+  } catch { /* a closed context */ }
+}
+
+function onGesture(): void {
+  gestures += 1;
+  for (const ctx of contexts) {
+    if (ctx.state === 'closed') { contexts.delete(ctx); continue; }
+    if (ctx.state !== 'running') { void ctx.resume().catch(() => {}); silentTick(ctx); }
+  }
+  for (const el of [...refused]) {
+    refused.delete(el);
+    const p = realPlay?.call(el);
+    if (p && typeof p.catch === 'function') p.catch(() => { refused.add(el); });
+  }
+  if (!unlockedAt && [...contexts].some((c) => c.state === 'running')) unlockedAt = performance.now();
+}
+
+let realPlay: (() => Promise<void>) | null = null;
+
+/** Wrap AudioContext and media play() so the first gesture unlocks everything. Idempotent. */
+export function installAudioUnlock(): void {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+  const w = window as unknown as Record<string, unknown>;
+  for (const name of ['AudioContext', 'webkitAudioContext']) {
+    const Real = w[name] as (new (...a: unknown[]) => Ctx) | undefined;
+    if (typeof Real !== 'function') continue;
+    // A subclass keeps instanceof, static members and every method; it only remembers the instance.
+    const Tracked = class extends (Real as new (...a: unknown[]) => Ctx) {
+      constructor(...args: unknown[]) { super(...args); contexts.add(this as unknown as Ctx); }
+    };
+    try { Object.defineProperty(window, name, { value: Tracked, configurable: true, writable: true }); } catch { /* keep the real one */ }
+  }
+  try {
+    const session = (navigator as unknown as { audioSession?: { type: string } }).audioSession;
+    if (session) session.type = 'playback';
+  } catch { /* not iOS */ }
+  if (typeof HTMLMediaElement !== 'undefined') {
+    realPlay = HTMLMediaElement.prototype.play;
+    const play = realPlay;
+    HTMLMediaElement.prototype.play = function patchedPlay(this: HTMLMediaElement): Promise<void> {
+      const p = play.call(this);
+      if (!p || typeof p.catch !== 'function') return p;
+      // Refused for want of a gesture: it plays on the first one. Any other failure is the game's to see.
+      return p.catch((e: unknown) => {
+        if (e && (e as { name?: string }).name === 'NotAllowedError') { refused.add(this); return undefined; }
+        throw e;
+      }) as Promise<void>;
+    };
+  }
+  for (const ev of ['pointerdown', 'pointerup', 'touchstart', 'touchend', 'mousedown', 'keydown', 'click']) {
+    window.addEventListener(ev, onGesture, { capture: true, passive: true });
+  }
+  document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') for (const c of contexts) if (c.state === 'suspended' && gestures) void c.resume().catch(() => {}); });
+}
+
+/** What the check harness reads: each context's state, and when the first one started running. */
+export function audioReport(): { contexts: string[]; refusedMedia: number; gestures: number; unlockedAtMs: number | null } {
+  return { contexts: [...contexts].map((c) => c.state), refusedMedia: refused.size, gestures, unlockedAtMs: unlockedAt || null };
+}