@homie-rocks/studio 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+Homie
+https://homie.rocks/
+
+Copyright 2026 1243116 B.C. Ltd.
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+The names "Homie" and "homie.rocks" are not licensed by it (section 6 of the
+License).

package/README.md

@@ -0,0 +1,40 @@
+# @homie-rocks/studio
+
+A game studio on its own Cloudflare. One repository (`AGENTS.md`, `games/`, `music/`,
+`videos/`, `posts/`, `site/`), multiplayer games on the Homie netplay contract (every
+browser renders, strangers meet in public rooms, bots fill seats, rounds restart), and a
+site Worker with Table/Lobby Durable Objects, D1 and R2 that the studio deploys to its
+own Cloudflare account with Wrangler. The homie.rocks directory lists the games.
+
+Most people never run this by hand: the Homie plugin for Claude Code and Codex does,
+and the person approves Cloudflare once in their browser.
+
+```sh
+npx -y --package=https://homie.rocks/npm/homie-studio-0.2.0.tgz homie-studio new ./night-owls --name "Night Owls"
+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 deploy                                # the studio's own Cloudflare
+npx homie-studio publish                               # the homie.rocks directory
+```
+
+| Path | What it is |
+| --- | --- |
+| `bin/homie-studio.mjs` | The CLI. |
+| `lib/scaffold.mjs` | `new`: the studio monorepo, only into a new or empty folder, every file listed. |
+| `lib/build.mjs` | `build`: games bundled with esbuild into `site/dist`, `games.json`, each game's shared `source.json`. |
+| `lib/cloudflare.mjs` | `deploy`: Wrangler, D1, R2, migrations, the directory claim; refuses resources it did not create. |
+| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round. |
+| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects. |
+| `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |
+| `starters/gem-rush/` | The reference multiplayer starter. |
+
+Versions are immutable: a published version never changes, so a studio that pinned one
+never changes by surprise. A change ships as a new `version`. Until the package is on the
+npm registry, each version's tarball is served at
+`https://homie.rocks/npm/homie-studio-<version>.tgz`.
+
+## License
+
+Apache-2.0. See `LICENSE` and `NOTICE`.

package/bin/homie-studio.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * homie-studio — make a game studio, make its games, put its site on the
+ * studio's own Cloudflare, and list its games in the homie.rocks directory.
+ *
+ *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install]
+ *   homie-studio starters
+ *   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 dev [--port 8787]
+ *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio deploy
+ *   homie-studio publish
+ *   homie-studio media put <file> [--as <key>]
+ *   homie-studio status
+ *
+ * Every command prints a few lines for a person; --json prints the result.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { build } from '../lib/build.mjs';
+import { check } from '../lib/check.mjs';
+import { deploy, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { publish } from '../lib/directory.mjs';
+import { newStudio } from '../lib/scaffold.mjs';
+import { listGames, newGame, readStudio, remixGame, requireStudio, starters, writeStudio } from '../lib/studio.mjs';
+import { STUDIO_VERSION } from '../lib/version.mjs';
+
+const argv = process.argv.slice(2);
+const flags = new Map();
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) {
+    const [k, v] = a.slice(2).split(/=(.*)/s, 2);
+    if (v !== undefined) flags.set(k, v);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !['json', 'yes', 'detach', 'no-install'].includes(k)) flags.set(k, argv[++i]);
+    else flags.set(k, true);
+  } else positional.push(a);
+}
+const asJson = flags.has('json');
+const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
+
+function print(result) {
+  if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
+  if (result.ok === false) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  const lines = [];
+  switch (result.command) {
+    case 'new':
+      lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`));
+      break;
+    case 'game remix':
+      lines.push(`games/${result.id} is a remix of ${result.from} (${result.files.length} files). Make it yours in games/${result.id}/src/, then: npx homie-studio dev`);
+      break;
+    case 'game new':
+      lines.push(`games/${result.id} is a new game from the ${result.from} starter. Change it in games/${result.id}/src/, then: npx homie-studio dev`);
+      break;
+    case 'build':
+      lines.push(`Built ${result.games.map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'nothing'} into ${relative(process.cwd(), result.dist) || result.dist}`);
+      break;
+    case 'deploy':
+      lines.push(`Live: ${result.url}`, ...result.games.map((g) => `  ${g.id}: ${g.play}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}${result.r2 ? `, R2 ${result.r2}` : ', no R2 (not enabled on this account)'}`,
+        result.claim ? 'Directory claim stored: list the games with the Homie MCP tool studio_publish, or: npx homie-studio publish' : 'No directory claim yet (the directory did not answer); publish will try again.');
+      break;
+    case 'publish':
+      lines.push(`Listed in the directory: ${result.studioPage ?? result.directory}`, ...(result.games ?? []).map((g) => `  ${g.name}: ${g.play}`));
+      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`));
+      break;
+    default:
+      lines.push(JSON.stringify(result, null, 2));
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+async function main() {
+  const [cmd, sub] = positional;
+  if (!cmd || cmd === 'help' || flags.has('help')) {
+    const text = readFileSync(new URL(import.meta.url), 'utf8').split('*/')[0].split('\n').slice(1).map((l) => l.replace(/^ \* ?/, '')).join('\n');
+    process.stdout.write(`homie-studio ${STUDIO_VERSION}\n${text}\n`);
+    return { ok: true, command: 'help' };
+  }
+  if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
+  if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install') });
+  if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
+
+  const root = requireStudio();
+  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 build(root, { only: positional[1] ?? null, log });
+  if (cmd === 'status') {
+    const studio = readStudio(root);
+    return { ok: true, command: 'status', root, studio, games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
+  }
+  if (cmd === 'dev') return dev(root);
+  if (cmd === 'check') {
+    const game = positional[1] ?? listGames(root)[0]?.id;
+    const url = flags.get('url') ?? readStudio(root).cloudflare?.url;
+    if (!url) return { ok: false, command: 'check', why: 'give --url (the local dev address or the live site)' };
+    return check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log });
+  }
+  if (cmd === 'deploy') return deploy(root, { log, homie: flags.get('homie') });
+  if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site') });
+  if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
+  return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
+}
+
+/** The whole site locally: pages, rooms (room.mjs in a local Durable Object), D1. */
+async function dev(root) {
+  const port = String(flags.get('port') ?? 8787);
+  const b = await build(root, { log });
+  if (!b.catalogue.length) return { ok: false, command: 'dev', why: 'no games yet: npx homie-studio game new <id> --from gem-rush' };
+  const bin = wranglerBin(root);
+  if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
+  const studio = readStudio(root);
+  const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1' };
+  await new Promise((done) => {
+    const m = spawn(bin, ['d1', 'migrations', 'apply', studio.cloudflare.d1, '--local'], { cwd: join(root, 'site'), env, stdio: ['ignore', 'ignore', 'inherit'] });
+    m.on('close', done);
+  });
+  log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
+  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: join(root, 'site'), env, stdio: 'inherit' });
+  await new Promise((done) => child.on('close', done));
+  return { ok: true, command: 'dev', stopped: true };
+}
+
+/** A big file into the studio's R2, and its line in music/ or videos/ manifest.json. */
+function mediaPut(root, file, as) {
+  if (!file || !existsSync(file) || !statSync(file).isFile()) return { ok: false, command: 'media put', why: 'usage: homie-studio media put <file> [--as <key>]' };
+  const studio = readStudio(root);
+  const r2 = studio.cloudflare?.r2;
+  if (!r2 || !(studio.cloudflare?.created ?? []).includes(`r2:${r2}`)) return { ok: false, command: 'media put', why: 'this studio has no R2 bucket yet (deploy first; R2 needs to be enabled on the Cloudflare account)' };
+  const rel = relative(root, resolve(file));
+  const folder = rel.startsWith('videos/') ? 'videos' : 'music';
+  const key = as ?? `${folder}/${basename(file)}`;
+  const bin = wranglerBin(root);
+  return new Promise((done) => {
+    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--remote'], { cwd: join(root, 'site'), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    p.on('close', (code) => {
+      if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
+      const manifest = join(root, folder, 'manifest.json');
+      const m = existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf8')) : { items: [] };
+      m.items = [...(m.items ?? []).filter((i) => i.key !== key), { key, file: rel, bytes: statSync(file).size, url: studio.cloudflare?.url ? `${studio.cloudflare.url}/media/${key}` : null, at: new Date().toISOString() }];
+      writeFileSync(manifest, `${JSON.stringify(m, null, 2)}\n`);
+      writeStudio(root, studio);
+      done({ ok: true, command: 'media put', key, manifest: relative(root, manifest) });
+    });
+  });
+}
+
+try {
+  const result = await main();
+  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') process.exit(process.exitCode ?? 0);
+} catch (error) {
+  print({ ok: false, why: error instanceof Error ? error.message : String(error) });
+  process.exitCode = 1;
+}

package/lib/build.mjs

@@ -0,0 +1,86 @@
+/**
+ * `homie-studio build` — every game in games/ bundled into site/dist, plus the
+ * catalogue the Worker serves (games.json).
+ *
+ *   site/dist/games/<id>/index.html        the game's page (the Worker adds HOMIE_NET)
+ *   site/dist/games/<id>/assets/main.js    its bundle (esbuild; @homie-rocks/studio/netplay inlined)
+ *   site/dist/games/<id>/...               everything in games/<id>/public/
+ *   site/dist/games.json                   { studio, games[] } from studio.json and game.json files
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { listGames, readStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler']);
+const TEXT = /\.(ts|tsx|js|mjs|jsx|json|html|css|md|txt|svg|glsl|wgsl|frag|vert)$/i;
+/** Text files of a game folder, capped (2 MB total, 512 KB each): what `homie-studio game remix` takes. */
+export function sourceOf(dir, id) {
+  const files = {};
+  let total = 0;
+  const walk = (rel) => {
+    for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name)) continue;
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(path);
+      else if (TEXT.test(entry.name)) {
+        const text = readFileSync(join(dir, path), 'utf8');
+        if (text.length > 512 * 1024 || total + text.length > 2 * 1024 * 1024) continue;
+        files[path] = text;
+        total += text.length;
+      }
+    }
+  };
+  walk('');
+  return { v: 1, kind: 'homie-game-source', id, files };
+}
+
+export async function build(root, { only = null, log = () => {} } = {}) {
+  const require = createRequire(join(root, 'package.json'));
+  let esbuild;
+  try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
+  const studio = readStudio(root);
+  const dist = join(root, 'site', 'dist');
+  const games = listGames(root).filter((g) => !only || g.id === only);
+  if (only && !games.length) throw new Error(`no game "${only}" in games/`);
+  if (!only) rmSync(dist, { recursive: true, force: true });
+  mkdirSync(dist, { recursive: true });
+  const built = [];
+  for (const g of games) {
+    const out = join(dist, 'games', g.id);
+    rmSync(out, { recursive: true, force: true });
+    mkdirSync(join(out, 'assets'), { recursive: true });
+    const entry = join(g.dir, g.entry ?? 'src/main.ts');
+    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${g.entry ?? 'src/main.ts'} not found`);
+    const started = Date.now();
+    const result = await esbuild.build({
+      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
+      outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
+      loader: { '.png': 'file', '.jpg': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.glb': 'file', '.svg': 'file' },
+      assetNames: '[name]-[hash]',
+    }).catch((error) => {
+      const first = error.errors?.[0];
+      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+    });
+    const html = join(g.dir, 'index.html');
+    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+    writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
+    if (existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+    // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
+    if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id))}\n`);
+    const bytes = statSync(join(out, 'assets', 'main.js')).size;
+    built.push({ id: g.id, name: g.name, bytes, ms: Date.now() - started, warnings: result.warnings.length });
+    log(`built ${g.id} (${Math.round(bytes / 1024)} KB)`);
+  }
+  const all = listGames(root);
+  const catalogue = {
+    studio: { name: studio.name, slug: studio.slug, version: STUDIO_VERSION },
+    games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => ({
+      id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: g.players ?? { min: 1, max: 8 },
+      roundSeconds: g.roundSeconds ?? null, movement: g.netplay?.movement ?? null, cover: g.cover ?? null,
+    })),
+  };
+  writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
+  return { ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id) };
+}

package/lib/check.mjs

@@ -0,0 +1,123 @@
+/**
+ * `homie-studio check <game> --url <site>` — the promise, measured: two fresh
+ * browsers (separate Chrome processes and profiles, one a computer and one a
+ * phone) press Play, land in the SAME public room, play, and both see the round
+ * finish. Exit 0 only when all of that happened. Uses this Mac's Chrome through
+ * puppeteer-core, on the GPU (a software renderer fakes a stuck game).
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const CHROMES = [
+  process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+].filter(Boolean);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function check({ url, game, roundTimeoutMs = 150_000, shots = null, userAgentTag = 'homie-studio-check', log = () => {} }) {
+  if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
+  const chrome = CHROMES.find((p) => existsSync(p));
+  if (!chrome) return { ok: false, command: 'check', why: 'no Chrome found (set CHROME_PATH)' };
+  let puppeteer;
+  try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
+  const base = String(url).replace(/\/+$/, '');
+  const play = `${base}/${game}/play`;
+  if (shots) mkdirSync(shots, { recursive: true });
+  const profiles = [];
+  const browsers = [];
+  const started = Date.now();
+  const kinds = [
+    { name: 'computer', viewport: { width: 1280, height: 800 } },
+    { name: 'phone', viewport: { width: 390, height: 844, isMobile: true, hasTouch: true, deviceScaleFactor: 2 } },
+  ];
+  const players = [];
+  try {
+    for (const kind of kinds) {
+      const profile = mkdtempSync(join(tmpdir(), 'homie-studio-check-'));
+      profiles.push(profile);
+      const browser = await puppeteer.launch({
+        executablePath: chrome, headless: true, userDataDir: profile,
+        args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+      });
+      browsers.push(browser);
+      const page = await browser.newPage();
+      await page.setViewport(kind.viewport);
+      const ua = await browser.userAgent();
+      await page.setUserAgent(`${ua} ${userAgentTag}`);
+      const t0 = Date.now();
+      await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+      players.push({ kind: kind.name, page, t0 });
+      log(`${kind.name} opened ${play}`);
+    }
+    // Seated: the shell knows its room and the game reported a seat.
+    const seated = await Promise.all(players.map(async (p) => {
+      const deadline = Date.now() + 45_000;
+      while (Date.now() < deadline) {
+        const s = await p.page.evaluate(() => { const s = window.__shell; return s ? { room: s.room, seat: s.seat, role: s.stats?.role ?? null, players: s.facts?.counts?.players ?? null } : null; }).catch(() => null);
+        if (s?.room && s.seat !== null && s.seat !== undefined && s.role) { p.seatedAt = Date.now(); p.seat = s.seat; return { ...s, ms: Date.now() - p.t0 }; }
+        await sleep(250);
+      }
+      return null;
+    }));
+    if (seated.some((s) => !s)) return { ok: false, command: 'check', why: 'a browser never got a seat within 45 s', seated };
+    const sameRoom = seated[0].room === seated[1].room;
+    log(`seated: ${seated.map((s, i) => `${kinds[i].name} room ${s.room} seat ${s.seat} ${s.role}`).join('; ')}`);
+    if (!sameRoom) return { ok: false, command: 'check', why: `the two browsers landed in different rooms (${seated[0].room}, ${seated[1].room})`, seated };
+    // Play: the computer holds keys, the phone drags from the lower left.
+    const playing = (async () => {
+      const keys = ['KeyD', 'KeyS', 'KeyA', 'KeyW'];
+      for (let i = 0; Date.now() - started < roundTimeoutMs && i < 400; i++) {
+        const k = keys[i % keys.length];
+        await players[0].page.keyboard.down(k).catch(() => {});
+        await sleep(600);
+        await players[0].page.keyboard.up(k).catch(() => {});
+        const vp = kinds[1].viewport;
+        await players[1].page.touchscreen.touchStart(vp.width * 0.2, vp.height * 0.8).catch(() => {});
+        await players[1].page.touchscreen.touchMove(vp.width * 0.2 + (i % 2 ? 60 : -60), vp.height * 0.8 - 40).catch(() => {});
+        await sleep(300);
+        await players[1].page.touchscreen.touchEnd().catch(() => {});
+        if (players.every((p) => p.over)) break;
+      }
+    })();
+    if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-playing.png`) }).catch(() => {});
+    // Only a round that finishes AFTER both browsers were seated, with BOTH of them in its results, counts: an
+    // idle room remembers its last round for a while, and that stale result proves nothing.
+    const bothSeated = Math.max(...players.map((p) => p.seatedAt));
+    const seats = players.map((p) => p.seat);
+    const over = await Promise.all(players.map(async (p) => {
+      const deadline = Date.now() + roundTimeoutMs;
+      while (Date.now() < deadline) {
+        const r = await p.page.evaluate((after, want) => {
+          const s = window.__shell;
+          const hit = (s?.results ?? []).find((x) => x.at > after && want.every((seat) => x.results.some((row) => row.seat === seat)));
+          return hit ? { n: hit.n, endsAt: hit.endsAt, results: hit.results, room: s.room } : null;
+        }, bothSeated, seats).catch(() => null);
+        if (r) { p.over = true; return { ...r, ms: Date.now() - p.t0 }; }
+        await sleep(500);
+      }
+      return null;
+    }));
+    await playing.catch(() => {});
+    if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-round-over.png`) }).catch(() => {});
+    if (over.some((o) => !o)) return { ok: false, command: 'check', why: 'a browser did not see a round finish in time', seated, over };
+    const humans = over[0].results.filter((r) => !r.bot).length;
+    const sameRound = over[0].n === over[1].n && over[0].endsAt === over[1].endsAt && over[0].room === over[1].room;
+    return {
+      ok: sameRoom && sameRound && humans >= 2,
+      command: 'check',
+      play,
+      room: seated[0].room,
+      seats: seated.map((s, i) => ({ browser: kinds[i].name, seat: s.seat, role: s.role, seatedMs: s.ms })),
+      round: { n: over[0].n, humans, bots: over[0].results.length - humans, results: over[0].results, overMs: over.map((o) => o.ms) },
+      why: !sameRound ? 'the two browsers saw different rounds finish' : humans >= 2 ? undefined : `the round's results list ${humans} human(s); both browsers should be in it`,
+      totalMs: Date.now() - started,
+    };
+  } finally {
+    for (const b of browsers) await b.close().catch(() => {});
+    for (const p of profiles) rmSync(p, { recursive: true, force: true });
+  }
+}