@homie-rocks/studio 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -17,9 +17,76 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.32.0] - 2026-10-06
+
+**Plugin 0.33.0** · [#54](https://github.com/homie-rocks/homie/pull/54)
+
+A game can now be an app of its own: a desktop app for macOS, Windows and Linux and a phone app for iOS and Android, the same web game in a thin shell that still plays through your studio's own site.
+
+### Added
+
+- **Standalone copies of a game.** `homie-studio standalone build <game>` makes the game you already have into a desktop app (Electron) for macOS, Windows and Linux, and a phone app (Capacitor) for iOS and Android. The app shows the same files your site serves, so the game is not ported or rewritten. It finds its rooms on your studio's own deployed site, so a player in the app and a player in a browser meet in the same room; with no connection it plays offline with its bots. In chat it is the `game_standalone` tool, and the plugin has a `standalone` skill.
+- **What the standalone game does not have (v1).** Say this to anyone who will ship one; the web game has all of these, and the app does not yet. No player accounts and no sign-in: a player in the app is a guest. No cloud saves: saves and settings are kept on the device only, do not follow a player to the site or to another device, and are lost when the app is uninstalled. No shop: nothing is sold in the app. No room chat: it is off until the app has report and mute controls. No watch page, no big screen and no owner's controls. Only the public server through an open door: a private or invite-only game, or a server behind an account or an invite, plays offline in the app. No automatic updates: a newer version reaches players only when you build again and ship it through Steam or the store. Steam's overlay, achievements and friends: none of it has been run, and Electron apps often show no overlay. Nothing is uploaded for you: the steps for Steam, App Store Connect and Google Play are printed, and you run them. The Windows build is unsigned.
+- **What has been run and what has not.** Each build is the kind of file Steam or a store accepts for upload; whether a store takes your game is the store's decision, with its own review, fees and rules. On one Mac we started the macOS build (the game loaded, found a room on a local dev server and played), the iOS build in the Simulator and the Android build in the emulator. **The Windows and Linux builds have never been started on any computer.** Nothing has been started by Steam. A Developer ID signature, notarization and the iOS archive for the App Store have never been made. Nothing has run on a real phone. The GitHub workflow has never been run. `standalone/STANDALONE.md` has the whole list, and what each store asks before you pay it anything.
+- `standalone plan <game>` says, before anything is built or downloaded: which of the five this computer can build, what each of the others needs and how to get it, the address that will be built into every copy, and what a standalone copy does not have. It changes nothing. A row says "ok" only for what it looked at: a signing name in the environment is "set, checked later", and a keychain it could not read is "could not check".
+- A build's result says what is true of each target. **Built** means the file is at the path given. The desktop build for the computer it is made on is also started once, and says "started here and loaded the game: yes" or "NO"; every other target says "built, not started on this computer". **Skipped** means a tool is missing, with its fix. A release that could not be signed is **UNSIGNED**, and the command does not report success. The command succeeds only when something was built, nothing failed and no release came out unsigned.
+- A target whose tool is missing on your computer is skipped, and the others still build. A Windows build can be made on a Mac (no Wine needed). An Android build uses Android Studio's own JDK when the Java on your PATH is too new for it. Nothing is installed for you.
+- `standalone ci <game>` writes a GitHub workflow that builds all five on GitHub's own Windows, Linux and macOS machines when you start it by hand, for a target your computer cannot make. Its macOS and iOS builds are never releases: it has no Apple certificate.
+- `standalone steam <game>` writes Steam's build file from the App ID and Depot IDs in `game.json`, prints the one `steamcmd` command to run yourself, and says the launch options to set in Steamworks (the Linux one needs `--no-sandbox`). `standalone run <game>` starts the built copy here.
+- A release (`--release`) is signed from environment variables you set yourself, never from a file or the chat: `HOMIE_APPLE_IDENTITY` and `HOMIE_APPLE_NOTARY_PROFILE` for macOS, `HOMIE_APPLE_TEAM` for iOS, and the four `HOMIE_ANDROID_*` for Android. Only the one tool that signs is given them. A macOS app is called notarized only when Apple's own tool confirms it on the finished app, and an Android bundle is called signed only when its signature is read back from it. A release and a build to try are kept in separate folders.
+- An optional `"standalone"` block in a game's `game.json`: the app's id, version, build number, how a phone holds it, its icon, and Steam's numbers. With no icon the app wears the game's cover, or a tile with its first letter.
+- `homie-studio deploy` and `deploy --plan` say when a deploy makes a different netplay version live than the standalone copies you built, and what that means for them.
+- `setup status` lists what the standalone builds need (Xcode with its iOS platform, the Android SDK with its platform, a JDK, signing) in a studio where a game has a `"standalone"` block.
+
+### Changed
+
+- The netplay helper knows when it runs in an app (`HOMIE_NET.app`): its lines about a newer version read "A new version is out. Update the app to play online." and a tap on one reloads nothing, because a reload cannot bring a newer build to an app. Nothing on the wire changed, and a game on the web behaves as before.
+- Your site's Worker lets a standalone copy read one answer from another origin: which public room to join. Nothing else is opened: no sign-in, saves, shop or office request is accepted from an app, and no cookie crosses.
+- The Lobby keeps a bounded list of rooms: at most 512 for a game (rooms nobody is seated in make way first), rooms for the live version of a game and at most eight others at a time, and never more rooms on a server than the server may have, whatever version asks. When that last limit is reached by rooms still on an older version, a visitor on the new one waits at one of them instead of getting an extra room.
+
+### Upgrade notes
+
+- **Upgrade and deploy before a standalone copy can find rooms.** A copy talks to your live site, and only a site deployed with 0.32.0 or later answers it. Until then every copy plays offline.
+- The address of your site is built into every copy and cannot be changed in a copy that has shipped. Put the studio on its own domain before you ship: a workers.dev address belongs to the Cloudflare account.
+- Before you ship, name the game's revision in `game.json` (`"netplay": { "version": "1" }`) and raise it with every change an older copy cannot play with. Older copies then keep playing with each other, and say "Update <Name> to play online with everyone." when they meet a newer one.
+- In an app the game's code is trusted with everything the app's page has, and on phones with Capacitor's native bridge. That is fine for your own code; do not load scripts from the network in a game you ship as an app.
+- The first standalone build downloads the wrapper tools (a few hundred MB) into the studio's `.studio/` folder, which is not committed. `@homie-rocks/studio` itself gained no dependency.
+
+## [0.31.1] - 2026-10-06
+
+**Plugin 0.32.1** · [#53](https://github.com/homie-rocks/homie/pull/53) · [release-2026-10-06-studio-0.31.1](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-06-studio-0.31.1)
+
+Fixes from two creators' notes on 0.31.0: Homie's holds run in Grok, `publish --before` publishes nothing, a page that loses its room is never stuck, a missing setting is never a silent zero, and a part's preview fits a phone.
+
+### Added
+
+- `@homie-rocks/camera/heading.js` (camera 0.2.1): `headingFrom({ zero: '+x', toward: '+z' })` converts your game's own heading into the camera's and back, and `headingOfVector(dx, dz)` does it from a forward vector. The package now says plainly which way its heading points (yaw 0 faces +Z, a positive yaw turns toward +X, in radians), with a picture in the README and in the types. In development the follow camera warns once when the subject keeps travelling one way while its heading says another, and names the adapter; mark reversing frames with `reversing: true`, or turn it off with `followState({ headingCheck: false })`.
+- `net.prefs.number`, `net.prefs.boolean` and `net.prefs.string` read a setting with your fallback for a missing key, a null, a wrong type or a read before the prefs arrived, and say so once in the console. `net.prefs.set` refuses a `NaN` or anything else that would be kept as `null`.
+- `createRoom({ fallback })`, seat or solo: `'solo'` plays a private round with bots until the room has a body for the player, `'spectate'` watches, and `room.standing` says where the player stands. NETPLAY.md section 28 is the recipe, and the late-join checklist has the slow-boot, mid-round join.
+- A shared part can say the shape of its preview: `"aspect": "4:3"` and, for phones, `"phoneAspect": "3:4"` in `preview` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; 16:9 if you say nothing). Every part preview has an "Open the preview" link that shows it in a tab of its own.
+- On a custom domain, a deploy and its plan warn before anything goes live when another site's catch-all or wildcard route covers your studio's address: leave that route alone, and add the one line shown (or `deploy --own-route`). When the routes cannot be read, it says so rather than saying all is well.
+
+### Fixed
+
+- **Homie's holds run in Grok once you trust the plugin.** 0.30.2 said Grok runs no plugin's hooks. That was wrong: Grok takes a plugin's hooks from its main manifest, ours named none there, and Grok was loading the Claude Code file instead and finding nothing. A secret is also now really taken out of what the AI reads in Grok (it was only being flagged beside the output). `setup status --client grok` says whether the holds ran and how to turn them on.
+- **`publish --before` publishes nothing.** It asks the directory whether you are listed and how many publishes are left today. In 0.31.0 the command line ignored the flag and published.
+- Commands that change something outside your computer (deploy, publish, storage, the office and others) stop at a flag they do not know, before anything is sent. `deploy --dry-run` was one such flag: it used to deploy.
+- A page that loses its room no longer shows "Reconnecting…" for ever: after 20 seconds (`reconnectMaxMs`) it plays on its own with bots, says so, and rejoins when the room answers. The line over the game says what is true: "Reconnecting…" only to a page that was connected, and a full room is said in words with a way to another room.
+- A player who is seated while every body is taken gets one as soon as a body frees up or the next round starts, instead of watching for the rest of the visit.
+- A browser that freezes for a few seconds while a heavy game boots no longer drops its connection when it wakes.
+- A part's preview is no longer cut off on a phone: a narrow frame is at least 320 px tall instead of about 197.
+- The 3D starters say which of their angles a camera can take as it stands and which needs converting.
+
+### Upgrade notes
+
+- Grok: install or reinstall the plugin with trust, `grok plugin install homie-rocks/homie#plugins/homie --trust`. From then on a deploy, a Cloudflare change and a paid call are held for your "proceed", as in Codex.
+- A studio that pins 0.31.0 still publishes on `publish --before` from its own command line until it upgrades.
+- If your game reads settings with `net.prefs.get`, move numbers to `net.prefs.number(key, fallback)`: a `null` kept by an older build is now read as nothing kept.
+- `@homie-rocks/camera` is 0.2.1.
+
 ## [0.31.0] - 2026-10-06
 
-**Plugin 0.32.0** · [#50](https://github.com/homie-rocks/homie/pull/50)
+**Plugin 0.32.0** · [#50](https://github.com/homie-rocks/homie/pull/50) · [release-2026-10-06-studio-0.31.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-06-studio-0.31.0)
 
 Fixes from two creators' logs of building real studios: games now build on each other by sharing parts (remix is retired), a slow 3D game keeps its host, local play stays local, and synthesized bass plays at its written pitch.
 

package/README.md

@@ -496,8 +496,8 @@ this toolkit alone (`new`, `deploy`, `publish`), and the connector row says so.
   an address or a command; the command itself is never read out.
 - **Homie's holds**: whether the plugin's hooks ran in this app in the last ten minutes, from the dated mark
   they leave in `.cache/homie-studio/holds/` of the home folder. Off means nothing is held: Codex runs no plugin's hooks
-  until the person trusts them in `/hooks`, and the row says so; Grok Build 1.0.41 runs no plugin's hooks at all, so
-  there the row is off until a Grok that does.
+  until the person trusts them in `/hooks`, and Grok Build runs them once the plugin is trusted
+  (`grok plugin install … --trust`); the row says which.
 
 `homie-studio demo` answers without a network too (0.30.2): where it cannot reach the arcade it names the arcade's
 standing first pick, with `reached: false`.
@@ -659,10 +659,14 @@ as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `
 
 **Routes.** `deploy` writes `wrangler.jsonc` again each time, and keeps the routes that are the studio's own exactly
 as they were written: a custom domain (`{ "pattern": "play.example.com", "custom_domain": true }`) and an exact-host
-route (`{ "pattern": "play.example.com/*", "zone_name": "example.com" }`). A zone's other routes are never listed,
-changed or removed. When the zone already has a wildcard route on another Worker (`*example.com/*`), that Worker
-answers the studio's hostname first; the deploy notices that its own domain answers as something else and prints the
-exact-host route to add, once. A wildcard or catch-all route (`*/*`) in the studio's own config would hand every
+route (`{ "pattern": "play.example.com/*", "zone_name": "example.com" }`). A zone's other routes are never
+changed or removed. On a custom domain, `deploy` and `deploy --plan` read the domain's Worker routes first (two GETs
+with the sign-in Wrangler already has) and warn, before anything is deployed, when another Worker's catch-all (`*/*`)
+or wildcard (`*example.com/*`) covers the studio's hostname: that route answers the hostname before the studio does,
+it belongs to another site on the domain, and it must not be edited or removed. The warning gives the one safe fix,
+the studio's own exact-host route, as the exact line; `deploy --own-route` adds that line and nothing else, only when
+the read showed it is needed. Routes that could not be read are said as unmeasured, never as fine; after the deploy,
+a domain that answers as something else still gets the route to add. A wildcard or catch-all route (`*/*`) in the studio's own config would hand every
 hostname of the zone to the studio's Worker, so `deploy` refuses it before it asks Cloudflare anything; a studio that
 really owns the whole zone says so in studio.json (`"cloudflare": { "allowWildcardRoutes": true }`).
 
@@ -792,6 +796,40 @@ it, named like the asset tools: `parts_find`, `part_add`, `part_new` and `part_s
   `package.json` is left as it is, and a package the part builds on that the studio lacks is named NOT INSTALLED
   with the npm command that installs it.
 
+## A game as an app of its own (`homie-studio standalone`)
+
+`homie-studio standalone` turns a game into a desktop app for macOS, Windows and Linux (the kind of build Steam
+accepts for upload) and a phone app for iOS and Android (the files the App Store and Google Play accept for
+upload; each store's review, fees and rules are its own). It is the same web build of
+the game in the thinnest shell each platform has (Electron on computers, Capacitor on phones), and nothing about
+one game lives in a shell. Multiplayer still goes through your studio's own deployed site; with no connection the
+game plays offline with its bots. [`standalone/STANDALONE.md`](standalone/STANDALONE.md) is the guide; the
+plugin's `standalone` skill is the method, and in chat it is the `game_standalone` tool.
+
+```sh
+npx --no-install homie-studio standalone plan <id>     # what would be built and what is missing; changes nothing
+npx --no-install homie-studio standalone build <id>    # every target this computer can make
+npx --no-install homie-studio standalone run <id>      # the built desktop copy, here
+npx --no-install homie-studio standalone steam <id>    # Steam's build file; uploads nothing
+npx --no-install homie-studio standalone ci <id>       # a GitHub workflow that builds all five
+```
+
+The wrapper tools are installed at exact versions into `.studio/standalone/<id>/` on the first build, so this
+package gains no dependency and a studio that never makes a standalone copy downloads none of them. A target
+whose tool is missing on this computer is skipped with its fix, and the others still build. Signing reads
+environment variables only, and nothing is ever uploaded to Steam or a store: the exact steps are printed. The
+desktop build for the computer it is made on is started once, and the result says whether the game loaded;
+every other target says "built, not started on this computer".
+
+**What the standalone game does not have (v1):** player accounts and sign-in, cloud saves (saves stay on the
+device and are lost when the app is uninstalled), the shop, room chat, watching and the big screen, servers
+other than the public one, automatic updates, and a signed Windows build. A studio must be on 0.32.0 or later
+**and deployed** before a copy can find rooms.
+
+**What has not been run:** the Windows and Linux builds have never been started; nothing has been started by
+Steam (its overlay, which Electron apps often do not show, included); a Developer ID signature, notarization and
+the iOS archive have never been made; nothing has run on a real phone. The guide lists it all.
+
 ## How it feels: the Game Lab (`homie-studio lab`)
 
 ```sh

package/bin/homie-studio.mjs

@@ -87,9 +87,17 @@
  *                                         One deploy of a studio at a time (a lock in .studio/); it says which games changed
  *                                         with each one's content hash, keeps the studio's own custom-domain and exact-host
  *                                         routes in wrangler.jsonc, and never deploys a wildcard or catch-all route.
+ *                                         On a custom domain, the plan and the deploy read the domain's Worker routes and
+ *                                         warn when another site's catch-all or wildcard covers the studio's hostname
+ *                                         (never edit or remove that route). --own-route adds the studio's own
+ *                                         exact-host route, the one safe fix, when that read shows it is needed.
  *                                         In Cloudflare's Workers Builds (WORKERS_CI=1, or --ci) it only applies the D1
  *                                         migrations and deploys: the Worker and database are the Deploy button's.
- *   homie-studio publish                  (the directory's beta has a daily cap: it says how many publishes are left)
+ *   homie-studio publish [--before]       (the directory's beta has a daily cap: it says how many publishes are left)
+ *                                         --before publishes NOTHING: it asks the directory (a read) whether the site
+ *                                         is listed and how many publishes are left today, and says the parts' licences.
+ *                                         A command that changes something outside this computer (deploy, publish,
+ *                                         storage add, the office, …) stops at a flag it does not know: nothing is sent.
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
  *   homie-studio media list               (every song and video page, where each file is served from, what moves to R2)
  *   homie-studio media move [<file>...] [--dry-run] [--verify]
@@ -271,6 +279,23 @@
  *                                          its own games from other studios. The plumbing behind the chat tools
  *                                          parts_find, part_add, part_new and part_share; nobody is asked to type it
  *
+ *   homie-studio standalone plan|build|run|steam|ci <game> [--for mac,windows,linux,ios,android] [--release]
+ *                                        [--site <address>] [--build <n>]
+ *                                         the game as an app of its own (standalone/STANDALONE.md): the same web build in
+ *                                          Electron for macOS, Windows and Linux and Capacitor for iOS and Android (the
+ *                                          files Steam and the stores accept for upload; their review is theirs), finding
+ *                                          its rooms on the studio's own site and playing offline with its bots when it
+ *                                          cannot. plan: what would be built, what each target needs on this computer,
+ *                                          and what a standalone copy does not have (no accounts, cloud saves, shop or
+ *                                          chat); build: every target this computer can make, in
+ *                                          .studio/standalone/<game>/out/<target>/<debug|release>/ (a missing
+ *                                          prerequisite skips that target with its fix; this computer's own desktop
+ *                                          build is started once and the result says whether the game loaded;
+ *                                          --release: signed from the environment only, game.json must name the app's
+ *                                          id, and an unsigned release is said as UNSIGNED and is not a success); run:
+ *                                          the built copy, here; steam: Steam's build file; ci: a GitHub workflow that
+ *                                          builds all five. Nothing is ever uploaded to Steam or a store
+ *
  *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
  *   homie-studio statusline --install [--project <folder>]
  *                                         turn it on in Claude Code for this studio (.claude/settings.local.json);
@@ -287,11 +312,11 @@ import { basename, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { PREVIEW_PORT, previewServer } from '../lib/preview.mjs';
 import { check } from '../lib/check.mjs';
-import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin, zonePlan } from '../lib/cloudflare.mjs';
 import { setupAttach } from '../lib/setup.mjs';
 import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { deployWords } from '../lib/deploy-state.mjs';
-import { publish } from '../lib/directory.mjs';
+import { publish, publishBefore } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
@@ -330,10 +355,13 @@ import { formatHandoff, handoff } from '../lib/handoff.mjs';
 import { partsCommand, partsLines } from '../lib/parts-cli.mjs';
 import { partsPlanLines, partsPublishReport } from '../lib/parts-build.mjs';
 import { trailerCommand, trailerLines } from '../lib/trailer.mjs';
+// STANDALONE COPIES (standalone/STANDALONE.md): `standalone …` is lib/standalone-cli.mjs; a deploy says what it means for them.
+import { standaloneCommand, standaloneLines } from '../lib/standalone-cli.mjs';
+import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', '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', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite'];
+const BOOL_FLAGS = ['off', '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', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -349,6 +377,8 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
+  // A standalone plan or build says every target, built or not, and what a standalone copy does not have.
+  if (/^standalone( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${standaloneLines(result).join('\n')}\n`); return; }
   // A check that found problems still prints them (its rows say what to fix), never a bare "failed".
   if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows) && !(result.command === 'assets check' && result.rows) && !(result.command === 'parts check' && result.rows) && !(result.command === 'shoot' && result.frames !== undefined)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}${result.instead ? `\n${result.instead}` : ''}\n`); return; }
   if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
@@ -452,18 +482,24 @@ function print(result) {
         // (lib/deploy-state.mjs): the hash `build` printed and the one the live site's manifest answers with.
         ...result.games.map((g) => `  ${g.id}: ${g.play}${g.hash ? `  [${deployWords(g)}]` : ''}`), ...(result.removed?.length ? [`  no longer on the site: ${result.removed.join(', ')}`] : []), ...(result.notes ?? []).map((n) => `  Note: ${n}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`),
         ...(result.media?.moved ?? []).map((m) => `  moved to R2 (checked by SHA-256): ${m.path}, still at ${m.url}`), ...(result.media?.failed ?? []).map((m) => `  not moved to R2: ${m.path}: ${m.why}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
-        result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).');
+        result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).',
+        ...(result.standalone?.length ? ['', ...result.standalone] : []));
       break;
     case 'deploy plan':
       lines.push(`What \`npm run deploy\` does for ${result.studio}, on the Cloudflare account the person approves:`, '',
         ...result.cloudflare.map((r) => `  ${r.kind}${r.name ? ` ${r.name}` : ''}: ${r.what} [${r.state}${r.plan ? `; ${r.plan}` : ''}]`), '',
         `Cost: ${result.cost}`, `Sign-in: ${result.login}`, `Address: ${result.address}`,
         `The directory (${result.directory.site}) stores: ${result.directory.stores}`, result.never,
-        ...(result.parts && partsPlanLines(result.parts).length ? ['', ...partsPlanLines(result.parts)] : []));
+        ...(result.zone?.warning ? ['', `Warning: ${result.zone.warning}`] : result.zone?.why ? ['', result.zone.why] : []),
+        ...(result.parts && partsPlanLines(result.parts).length ? ['', ...partsPlanLines(result.parts)] : []),
+        ...(result.standalone?.length ? ['', ...result.standalone] : []));
       break;
     case 'storage add':
       lines.push(result.already ? `Storage is already added: R2 bucket ${result.bucket}.` : `Storage added: R2 bucket ${result.bucket}.`, 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
+    case 'publish before':
+      lines.push(...result.lines);
+      break;
     case 'publish':
       lines.push(`Listed in the directory: ${result.studioPage ?? result.directory}`, ...(result.games ?? []).map((g) => `  ${g.name}: ${g.play}`), ...(result.publishes?.line ? [result.publishes.line] : []),
         // The parts in what was listed, in the deploy plan's own lines (lib/parts-build.mjs).
@@ -743,6 +779,52 @@ function print(result) {
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 
+/*
+ * A COMMAND THAT CHANGES SOMETHING OUTSIDE THIS COMPUTER NEVER RUNS WITH A FLAG IT DOES NOT KNOW. The parser above
+ * keeps every `--word`, and a command reads the ones it knows: `publish --before` (a flag the MCP tool had and this
+ * command did not) was read as plain `publish`, and listed the studio while its caller believed it was a preflight.
+ * So each command below names every flag it takes, and anything else stops it before anything is sent: a typo, a
+ * flag of another command, or one from a newer toolkit's notes. The key is the command and its sub-command, else
+ * the command alone. Commands that only read, or only change files in this folder, are not in this table.
+ */
+const OUTWARD_FLAGS = {
+  publish: ['homie', 'site', 'before'],
+  deploy: ['plan', 'ci', 'homie', 'own-route'],
+  'storage add': [],
+  'media put': ['as'],
+  'media move': ['dry-run', 'plan', 'verify'],
+  'setup attach': ['homie', 'client'],
+  handoff: ['homie', 'client'],
+  'players owner': ['url', 'revoke'],
+  'stats key': ['url', 'hours'], 'stats link': ['url'], 'stats revoke': ['url'], 'stats share': [],
+  'office link': ['url', 'to'], 'office key': ['url', 'hours'], 'office announce': ['url', 'game', 'room', 'seconds'],
+  'office invite': ['url', 'label', 'uses', 'count', 'days', 'server'], 'office launch': ['url', 'max'],
+  'office kick': ['url', 'minutes'], 'office mute': ['url', 'minutes', 'off'], 'office close': ['url', 'minutes', 'reopen'], 'office revoke': ['url'],
+  'lounge mod': ['url', 'remove'], 'lounge remove': ['url', 'all'],
+  'chat remove': ['url', 'all'], 'chat budget': ['url'],
+  'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
+  'shop connect': ['url', 'managed', 'live'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send'],
+  'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
+  'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+};
+/** Every command takes these: how it answers, never what it does. */
+const ANY_COMMAND = ['json', 'help', 'version'];
+
+/** The refusal for a flag an outward-writing command does not take, or null. Nothing has run when this is asked. */
+function unknownFlags(words, given) {
+  const [cmd, sub] = words;
+  const key = sub !== undefined && OUTWARD_FLAGS[`${cmd} ${sub}`] ? `${cmd} ${sub}` : OUTWARD_FLAGS[cmd] ? cmd : null;
+  if (!key) return null;
+  const takes = OUTWARD_FLAGS[key];
+  const strange = [...given.keys()].filter((k) => !takes.includes(k) && !ANY_COMMAND.includes(k));
+  if (!strange.length) return null;
+  const named = strange.map((k) => `--${k}`).join(', ');
+  return {
+    ok: false, command: key, needs: 'flag', flags: strange, takes: takes.map((k) => `--${k}`),
+    why: `homie-studio ${key} does not take ${named}, so it did not run: nothing was sent or changed. It changes something outside this computer, and a flag it does not know is never guessed at. It takes: ${takes.length ? takes.map((k) => `--${k}`).join(', ') : 'no flags of its own'} (and --json).`,
+  };
+}
+
 async function main() {
   const [cmd, sub] = positional;
   if (!cmd || cmd === 'help' || flags.has('help')) {
@@ -751,6 +833,8 @@ async function main() {
     return { ok: true, command: 'help' };
   }
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
+  const strange = unknownFlags(positional, flags);
+  if (strange) return strange;
   if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install'), template: flags.has('template') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
   // The floor's built-in words need no studio: anyone can read what a studio's chat always holds.
@@ -786,6 +870,9 @@ async function main() {
   if (cmd === 'anim') return animCommand(root, sub, positional, flags, { log });
   if (cmd === 'collision') return collisionCommand(root, sub, positional, flags);
   if (cmd === 'parts') return partsCommand(root, sub, positional, flags, { log });
+  // A build takes minutes: its lines go to stderr even under --json (the result alone is on stdout), so a chat tool
+  // that runs it as a job has last lines to show; and into the progress feed, when one is open.
+  if (cmd === 'standalone') { const feed = currentFeed(root); return standaloneCommand(root, sub, positional, flags, { log: (line) => { process.stderr.write(`${line}\n`); try { feed?.log(String(line).slice(0, 200)); } catch { /* the feed is extra */ } } }); }
   if (cmd === 'cast') { const games = listGames(root); const id = sub ?? (games.length === 1 ? games[0].id : null); if (!id) return { ok: false, command: 'cast', why: `name the game: homie-studio cast <id>${games.length ? ` (${games.map((g) => g.id).join(', ')})` : ''}` }; return castView(root, id); }
   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);
@@ -870,16 +957,22 @@ async function main() {
     const only = flags.get('only') ? String(flags.get('only')).split(',').filter((d) => ['computer', 'phone', 'sideways'].includes(d)) : undefined;
     return look({ url, paths, shots: flags.get('shots') ? resolve(flags.get('shots')) : join(root, '.studio', 'look'), devices: only, log });
   }
-  if (cmd === 'deploy' && flags.has('plan')) return { ...deployPlan(root), parts: partsPublishReport(root) };
+  if (cmd === 'deploy' && flags.has('plan')) {
+    // On a custom domain the plan also reads the domain's Worker routes (lib/routes.mjs): a read, nothing changes.
+    const zone = await zonePlan(root);
+    return { ...deployPlan(root), parts: partsPublishReport(root), ...(zone ? { zone } : {}), standalone: standaloneDeployNotes(root) };
+  }
   // Cloudflare's Workers Builds runs `npm run deploy` with WORKERS_CI=1 (and its own token for this one account).
   if (cmd === 'deploy' && (process.env.WORKERS_CI === '1' || flags.has('ci'))) return tracked(root, 'deploy', () => ciDeploy(root, { log }), 'deploy');
-  if (cmd === 'deploy') return tracked(root, 'deploy', () => deploy(root, { log, homie: flags.get('homie') }), 'deploy');
+  // What the deploy means for standalone copies already made (a changed netplay version), read before it runs.
+  if (cmd === 'deploy') { const copies = standaloneDeployNotes(root); return tracked(root, 'deploy', async () => { const r = await deploy(root, { log, homie: flags.get('homie'), ownRoute: flags.has('own-route') }); return r?.ok ? { ...r, standalone: copies } : r; }, 'deploy'); }
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
   if (cmd === 'storage') {
     const cf = readStudio(root).cloudflare ?? {};
     const has = Boolean(cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`));
     return { ok: true, command: 'storage', storage: has ? { kind: 'r2', bucket: cf.r2 } : null, why: has ? undefined : 'no storage yet: the studio runs without it; `homie-studio storage add` adds an R2 bucket for large media (Cloudflare asks for a payment method before R2 works)' };
   }
+  if (cmd === 'publish' && flags.has('before')) return publishBefore(root, { homie: flags.get('homie'), site: flags.get('site'), log: () => {} });
   if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site'), log });
   if (cmd === 'players' && sub === 'owner') return playersOwner(root, { url: flags.get('url'), revoke: flags.has('revoke') });
   if (cmd === 'players' && !sub) return playersShow(root, { url: flags.get('url') });

package/lib/build.mjs

@@ -94,7 +94,7 @@ function dirBytes(dir) {
   return n;
 }
 /** From games/<id>/style.json: the light colour as paper, the dark as text, and the accent; null without one. */
-function uiOf(g) {
+export function uiOf(g) {
   let pal = null;
   try { pal = JSON.parse(readFileSync(join(g.dir, 'style.json'), 'utf8'))?.palette ?? null; } catch { pal = null; }
   const hex = (v) => (/^#[0-9a-f]{6}$/i.test(String(v ?? '')) ? String(v).toLowerCase() : null);

package/lib/cloudflare.mjs

@@ -19,21 +19,28 @@
  * It REFUSES to touch a Worker, database or bucket of that name that this
  * studio did not create (studio.json `cloudflare.created` is the record), so it
  * can never overwrite someone's existing site. `deploy --plan` says all of this
- * before anything happens and calls nothing.
+ * before anything happens and changes nothing.
+ *
+ * A studio on a CUSTOM DOMAIN shares that domain with whatever else its owner
+ * runs there. The plan and the deploy read the domain's Worker routes (a read,
+ * with Wrangler's own sign-in) and warn when another site's catch-all or
+ * wildcard covers the studio's hostname: that route is never the studio's to
+ * edit or remove (lib/routes.mjs, zoneCheck below).
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { cloudflareAuth } from './brain-probe.mjs';
 import { build } from './build.mjs';
 import { builtGames, compareDeploy, deployWords, lastDeploy, lastDeployRecord, lockDeploy, recordDeploy } from './deploy-state.mjs';
 import { listedHere, publish } from './directory.mjs';
 import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File, sizeOf } from './media.mjs';
 import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
-import { keptRoutes, readConfig, shadowedDomain, wideRouteRefusal } from './routes.mjs';
+import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, domainOrigin, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -106,6 +113,54 @@ export function explainCloudflare(out, accountId = null) {
   return null;
 }
 
+/** The studio's custom hostname ("play.example.com"), or null for a studio on its workers.dev address. */
+export function customHost(studio) {
+  const cf = studio?.cloudflare ?? {};
+  const origin = domainOrigin(cf.domain) ?? (cf.url && !isWorkersDev(cf.url) ? domainOrigin(cf.url) : null);
+  return origin ? new URL(origin).hostname : null;
+}
+
+/**
+ * For a studio on a custom domain: what the domain's other Worker routes mean for it (lib/routes.mjs zoneFinding),
+ * read from Cloudflare with the sign-in Wrangler already has (lib/brain-probe.mjs cloudflareAuth: a token in the
+ * environment, else `wrangler auth token`). Null for a studio with no custom domain, which is asked nothing. It
+ * only reads; a list that cannot be read comes back as state 'unmeasured' with the reason. `config` stands in for
+ * wrangler.jsonc (a deploy that is about to add a route), `fetchFn` for the network in tests.
+ */
+export async function zoneCheck(root, { studio = readStudio(root), config = readConfig(root), accountId = null, fetchFn = null } = {}) {
+  const hostname = customHost(studio);
+  if (!hostname) return null;
+  const worker = studio.cloudflare?.worker ?? null;
+  // The toolkit's own tests (HOMIE_STUDIO_WARM=0) with no stand-in network ask nobody, as readLiveSite does.
+  if (!fetchFn && process.env.HOMIE_STUDIO_WARM === '0') return zoneFinding({ hostname, worker, config, zone: { read: false, why: 'not asked' } });
+  const bin = wranglerBin(root);
+  let headers = null;
+  try {
+    const w = bin ? runner(root, accountId ? { CLOUDFLARE_ACCOUNT_ID: accountId } : {}) : null;
+    headers = await cloudflareAuth({
+      env: { ...process.env, ...projectsCloudflareEnv(root) }, bin, cwd: root,
+      exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; },
+    });
+  } catch { headers = null; }
+  const zone = await readZoneRoutes({ hostname, config, headers, ...(fetchFn ? { fetchFn } : {}) });
+  return zoneFinding({ hostname, worker, config, zone });
+}
+
+/** A zone finding as a deploy's result and its plan carry it: the state, the routes that are not the studio's, the one line. */
+function zoneView(z) {
+  return {
+    state: z.state, host: z.host, domain: z.zone, foreign: z.foreign.map((r) => ({ pattern: r.pattern, worker: r.script, kind: r.kind })),
+    ...(z.state === 'foreign' || z.state === 'unmeasured' ? { route: z.route, line: z.line } : {}),
+    ...(z.warning ? { warning: z.warning } : {}), ...(z.why ? { why: z.why } : {}),
+  };
+}
+
+/** `deploy --plan` for a studio on a custom domain: the plan, and what the domain's other routes mean for it. */
+export async function zonePlan(root, opts = {}) {
+  const z = await zoneCheck(root, opts);
+  return z ? zoneView(z) : null;
+}
+
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
 export function deployPlan(root) {
   const studio = readStudio(root);
@@ -150,7 +205,7 @@ export async function deploy(root, opts = {}) {
   try { return await deployLocked(root, opts); } finally { process.off('exit', onExit); lock.release(); }
 }
 
-async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}) {
+async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRoute = false } = {}) {
   const studio = readStudio(root);
   const cf = { r2: null, created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
@@ -159,7 +214,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   // studio's own routes exactly as its owner wrote them.
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
-  const routes = keptRoutes(root, studio);
+  let routes = keptRoutes(root, studio);
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -186,6 +241,25 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   };
   const steps = [];
   const step = (what, extra = {}) => { steps.push({ what, ...extra }); log(what); };
+  const notes = [];
+
+  // A studio on a custom domain: is another site's catch-all or wildcard route on the same domain covering its
+  // hostname? Read (never written) and said before Wrangler changes anything: the repair that suggests itself,
+  // editing or removing that route, takes the other site down (lib/routes.mjs). `--own-route` adds the one line
+  // that is the studio's to add, and only when the domain's routes were read and show it is needed.
+  let zone = await zoneCheck(root, { studio, accountId, fetchFn });
+  if (zone) {
+    if (ownRoute && zone.state === 'foreign') {
+      routes = [...(routes ?? []), zone.route];
+      step(`added the studio's own exact-host route to "routes" in wrangler.jsonc: ${zone.line}. It covers ${zone.host} only, and every deploy keeps it; the other site's route was not touched.`, { route: zone.route });
+      const config = readConfig(root) ?? {};
+      zone = await zoneCheck(root, { studio, accountId, fetchFn, config: { ...config, routes: [...routesOf(config), zone.route] } });
+    } else if (ownRoute) {
+      step(`--own-route added nothing: ${zone.state === 'unmeasured' ? 'the domain\'s routes could not be read, so the domain\'s name in Cloudflare is not known for sure' : zone.state === 'taken' ? `${zone.host} is routed to another Worker, which only the person can change` : zone.state === 'own-route' ? 'the studio\'s own exact-host route is already there' : `no other route covers ${zone.host}`}.`);
+    }
+    if (zone.warning) { notes.push(zone.warning); step(`warning: ${zone.warning}`, { needs: 'cloudflare-routes', ...(zone.state === 'foreign' ? { route: zone.route } : {}) }); }
+    else if (zone.why) step(zone.why);
+  } else if (ownRoute) step('--own-route added nothing: this studio has no custom domain (studio.json cloudflare.domain).');
 
   // The first deploy says what it is about to create, and what it costs, before it creates anything: the person
   // reads it in the transcript whether or not the AI repeated it.
@@ -290,7 +364,6 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   recordDeploy(root, builtNow);
   let claim = null;
-  const notes = [];
   if (url) {
     const read = await readLiveSite(url, fetchFn ? { fetchFn } : {});
     claim = read.claim;
@@ -340,6 +413,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
     games: b.catalogue.map((id) => { const g = delta.games.find((x) => x.id === id); return { id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: g?.hash ?? null, change: delta.first ? 'first deploy from this computer' : g?.change ?? null }; }),
     ...(delta.removed.length ? { removed: delta.removed } : {}),
     ...(routes ? { routes: routes.map((r) => r.pattern) } : {}),
+    ...(zone ? { zone: zoneView(zone) } : {}),
     ...(notes.length ? { notes } : {}),
     ...(reread ? { reread } : {}),
     songs: b.songs.map((slug) => ({ slug, page: url ? `${url}/music/${slug}/` : null })),