@homie-rocks/studio 0.30.2 → 0.31.1

package/README.md

@@ -15,6 +15,7 @@ cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
 npx homie-studio check crown-thief --url http://127.0.0.1:8787
+npx homie-studio shoot crown-thief --url http://127.0.0.1:8787  # frames on a stepped clock (works without a GPU) and a two-client seat smoke check
 npx homie-studio perf crown-thief --url http://127.0.0.1:8787   # how fast it runs: a computer and an emulated phone, host and replica
 npx homie-studio lab crown-thief                       # the Game Lab: how a move feels, New beside Today, frame by frame
 npx homie-studio style board crown-thief               # its look as decisions: three directions drawn by the engine (free)
@@ -42,7 +43,7 @@ npx -y @homie-rocks/studio mcp --studios "<the folder the studios live in>"   #
 ```
 
 The toolkit as MCP tools, so the chat that shows Homie's cards also does the work: the setup status, a new studio,
-the live demo, make / remix / port / plan a game and its Game Codex, build, run it here, the two-browser check, a
+the live demo, make / port / plan a game and its Game Codex, build, run it here, the two-browser check, a
 playtest, deploy, publish, the progress feed, the studio's files, and the music, sound, art and video scripts where
 their provider is set up. Where a tool overlaps the remote Homie MCP (homie.rocks/mcp) it has the same name and
 input shape. Long work (npm install, a check, a deploy) runs in the background and reports through the progress
@@ -99,10 +100,11 @@ featured game, live rooms, the latest posts), Games, Music, Videos, Rooms (every
 joinable and watchable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
 page answers 404. Every game gets a landing at `/<game>/`: a full-bleed hero from its own footage or art, the
 pitch, a big Play button into a public room, how to play on a phone, a computer and a TV (with the join code),
-live rooms, credits (the original and its licence for a port; "Remix of <game> by <studio>", linked, for a
-remix), and "Make a game like this". A game's shared source (`/games/<id>/source.json`) says who made it and the
-licence its owner picked in game.json `"license"`: `"remix-with-credit"` (the default), `"remix-freely"` or
-`"no-remix"`, which `game remix` refuses. Every page ends with "Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
+live rooms and credits (the original and its licence for a port; "Based on <game> by <studio>", linked, for a
+game that was made from another studio's). game.json `"license": "MIT"` (an SPDX identifier) is the licence the game
+names for itself, said in its credits; a game that names none says nothing. No game's source is served: games build on
+each other through parts ("Game parts", below). studio.json `"site": { "order": ["<id>", …] }` is the
+order of the games in every list, the directory's manifest included. Every page ends with "Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
 files. `site/SITE.md` says all of it.
 
 The play page never opens blank (0.26.0): from its first paint an arrival card shows the game's own look (its title,
@@ -118,7 +120,7 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 
 Search engines and AI agents read a studio correctly (0.27.0): every generated page carries schema.org JSON-LD
 (`worker/schema.mjs`: the studio's `Organization` and `WebSite` on Home, a full `VideoGame` on each landing with its
-players, platforms, licence, remix original, trailer, dates and a free-to-play offer whose add-ons are what the shop
+players, platforms, licence, trailer, dates and a free-to-play offer whose add-ons are what the shop
 really sells, `MusicRecording`, `VideoObject`, `BlogPosting`, `ItemList` and `BreadcrumbList`; never a rating), and the
 site makes `/robots.txt`, `/sitemap.xml`, `/llms.txt` and `/llms-full.txt` from its public catalogue
 (`worker/discover.mjs`). `lib/schema-check.mjs` checks every block against schema.org's own vocabulary and what Google
@@ -155,6 +157,29 @@ shows how it differs from the template. `--apply` also pins this version in pack
 `homie.studio`. When the template's words change, `node scripts/studio-template-history.mjs` records them (a test
 fails until it has).
 
+### Remix was retired
+
+Handing over a whole game (`game remix`, the `game_remix` tool, a game's `/games/<id>/source.json`, the office's
+Remixable switch, the "Make a game like this" band) is gone. Games build on each other through **parts**: pieces of a
+game its studio chooses to share, each with its own licence ("Game parts", below). For a studio that upgrades:
+
+- **Old settings still build.** A game.json that carries `"remix"`, `"share"`, `landing.make`, or a `"license"` that
+  is one of the old words (`"remix-with-credit"`, `"remix-freely"`, `"no-remix"`, or an object with `"kind"`) builds
+  as before. The keys do nothing, and the build says so in one note that lists them; delete them when convenient. An
+  SPDX identifier in `"license"` (`"MIT"`, or `{ "spdx": "MIT" }`) is still the licence the game names on its page.
+- **A game that was a remix keeps its credit.** game.json `"remixOf"` is still read: the landing and the credits page
+  say "Based on <game> by <studio>", linked to the original. That credit is owed, so leave the key where it is. The
+  files such a game carried keep saying whose they were in its `assets/RIGHTS.md`.
+- **No source is served.** The build writes no `source.json` or `assets.json` and takes out the ones an older build
+  left. `/games/<id>/source.json` answers 410 with `{ "retired": "remix", "see": "/parts/" }`, and
+  `/.well-known/homie-studio.json` no longer has `remix`, `source` or `remixOf`. The first deploy after the upgrade
+  asks the directory to read a listed studio again, once, so it drops the old offer.
+- **Nothing is dropped from the database.** The office's `office_games.remix` column stays in D1 with whatever it
+  held; nothing reads or writes it.
+- **Asset records.** `license.remix` on an entry of `assets/manifest.json` is ignored and no longer written, and
+  RIGHTS.md has no "A remix" line. Whether a file may be handed on in a shared part is still its licence's.
+- `homie-studio game remix` answers with a sentence that points to parts; `office launch --remixable` is ignored.
+
 ## Rooms of up to 32
 
 Every room of a game has the seats its netplay manifest names: game.json's `netplay`
@@ -164,6 +189,24 @@ Bots, a late joiner taking a bot's body and a new host after the old one leaves
 the same at 32 as at 4. One address may hold every seat plus four sockets, so a party
 on one Wi-Fi (or strangers behind one carrier's address) fills a room with a TV beside it.
 
+## A game's netplay manifest
+
+game.json `"netplay"` says more than the room's size. All of it is optional, and `homie-studio build`
+writes it to the catalogue for the site's rooms (`netplay/NETPLAY.md` sections 22 to 24):
+
+| Field | What it does |
+|---|---|
+| `maxPlayers` | Seats in a room, up to 32. |
+| `version` | The game's revision (a word or a number). Bump it when a change makes an already-open tab unable to play with a new one: a room then runs one build at a time, strangers are matched within the live build, and an old tab is told to reload at its round's break. |
+| `stallMs` | How long a host may send no snapshot before the room is handed to another browser: 1500 (the default) to 10000. A heavy 3D game whose frames hitch on a slow phone raises it; the helper also sends a heartbeat for up to 4 s while a host's frames are stuck. |
+| `params` | Names of the play page's query parameters to hand the game (`/<id>/play?seed=42`), beside `debug` and `q`, which always are. The game reads them as `net.params`. |
+
+The game's frame is sandboxed without `allow-same-origin` (it must never read the site's storage or
+the owner's session), so `localStorage` throws inside it: a setting or a personal best goes in
+`net.prefs` (the play page keeps 16 KB a game), and progress that must last in saves, below.
+`net.link` says whether the browser is in its room, reconnecting, or playing alone because the room
+never answered; `guardGestures()` stops a long press on a phone from selecting text in a touch game.
+
 ## Player accounts and cloud saves
 
 A game whose progress must last (a character that levels up for days, unlocks, a collection, a hardcore mode)
@@ -228,7 +271,7 @@ it):
 - **Close** a room: everyone is sent out with a thank-you; nobody gets in until it opens.
 - Per game: **players per room**, the **launch state** (`private`: only the owner;
   `invite`: an invite-only beta, where each invite link or code lets a browser in;
-  `public`: anyone, listed), and **remixable** (publish or withdraw the game's source).
+  `public`: anyone, listed).
   A game that is not public is in no list and not in the directory manifest, so the
   directory drops it the next time it reads the studio. A new game is private from its
   first deploy with `"launch": "private"` in its game.json.
@@ -453,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`.
@@ -478,8 +521,8 @@ redraws itself whenever the feed changes and refreshes in the browser while a bu
 puts each game's codex on the site at `/_studio/codex/<id>/`, served only to the studio's owner (the same
 one-time sign-in as the stats page), never listed or indexed. Text is escaped and the page runs only its own
 script (the site allows it by its hash); pictures and fonts come only from inside the studio and are
-embedded, so it loads nothing but Google Fonts. CODEX.md is never in a game's remix source or among a
-static game's served files.
+embedded, so it loads nothing but Google Fonts. CODEX.md is never among a static game's
+served files.
 
 ## The Claude Code status line
 
@@ -519,7 +562,7 @@ one runs, a shared feed asks whether Stop was pressed; a stopped command closes
 browsers and says so, and nothing already built or deployed is undone.
 
 **From the Claude app.** The chat can open the build first (the Homie MCP tool `build_open`, or the "Build it"
-card on a make, port or remix) and hand the work to a Claude Code session with a prefilled prompt. The session
+card on a make or a port) and hand the work to a Claude Code session with a prefilled prompt. The session
 takes the build once, with no key in the prompt, and the card follows it; the change goes out as a pull request
 the person merges with one tap:
 
@@ -564,12 +607,103 @@ hours so the Claude app can show it: the feed only (plain bounded text, pictures
 never printed; the shared id is printed for the MCP tool `build_progress`. Without an open
 feed every command behaves exactly as before. `lib/progress.mjs` has the whole format.
 
-## The site's address
+## Running it here: `homie-studio dev`
+
+```sh
+npx homie-studio dev [--port 8787] [--timestamps]   # the whole site on this computer, until it is stopped
+npx homie-studio dev --stop                         # this studio's dev server only
+```
+
+Every command needs Node.js 22 or newer and says so at once on an older one, before it does anything.
+
+**Rooms here are always local.** A studio that is live on its own domain has routes in `wrangler.jsonc`, and Wrangler
+serves a config with a route as that production hostname: games would be handed a room socket on the live site. So
+`dev` runs Wrangler from a copy of the config without `routes` (in `.wrangler/`; `wrangler.jsonc` is never changed),
+then reads one game's page back and checks that the room socket it hands out is this computer's own address, port
+included. If it is not (a `dev.host` in the config, say), `dev` stops and says so. No wrapper script is needed for a
+route-free preview.
+
+**A game added while it runs** is picked up. `dev` serves what `build` wrote: a new game folder that is not built is
+named with the command, and once it is built, a running site that still answers 404 for it is restarted by `dev`
+itself, on the same address.
+
+**Stopping, and stale state.** `dev --stop` stops exactly the processes this studio's dev server registered, and
+nothing else. A server stopped another way (a closed terminal, a kill by process id or by port) leaves its
+registration behind; `dev` and `dev --stop` both notice, remove it and say it was stale, stop a local runtime left on
+the port when it runs from this studio's folder, and name anything else on the port without touching it. Never stop
+a dev server with `pkill` or by port: another project's would go too.
+
+The registration is one file, `<folder of wrangler.jsonc>/.wrangler/homie-dev.json`, and it is the whole contract:
+
+```json
+{ "pid": 4242, "child": 4243, "port": 8787, "at": "2026-10-06T12:00:00.000Z" }
+```
+
+`pid` is the process that owns the server, `child` the Wrangler it started (optional), `port` the local port, `at`
+when it started. `dev --stop` and the MCP tools `preview_run` / `preview_stop` read only this. A process it names is
+signalled only while it is still this studio's: alive, and its command line names the studio's folder, or its working
+directory is inside it, or it is still the kind of program its key says (`pid`: homie-studio; `child`: wrangler or
+workerd). So a studio's own wrapper script that writes this file, and is started from the studio's folder, is stopped
+by `dev --stop` like the built-in one; it should delete the file when it ends.
+
+**Room lines carry a time.** Wrangler prints a room socket opening (`GET /<game>/__net 101`) and a runtime error such
+as `Network connection lost` with no time on them. `dev` puts this computer's clock in front of those lines (every
+line with `--timestamps`), so they can be laid beside a check's own report. A connection-loss line is printed when a
+browser or a host leaves abruptly, and also when a room operation really failed: the time is what tells them apart.
+
+## The site's address, its routes, and what a deploy says
 
 `deploy` keeps the `workers.dev` address in `.studio/local.json`, which git ignores: it
 names the Cloudflare account, often after its owner. A custom domain goes in studio.json
 as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `stats` use.
 
+**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
+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 }`).
+
+**One deploy at a time.** A second `deploy` of the same studio is refused while one runs (`.studio/deploy.lock` names
+its process and start time); a lock left by a deploy that was killed is taken over by the next one.
+
+**Which games changed.** Each deploy prints, per game, `changed`, `unchanged` or `new` against the last deploy from
+this computer, and the game's **build hash**: the one `homie-studio build` printed for it, that
+`site/dist/_site/build.json` keeps, that `perf` names a run's build by, and that the live site answers with in
+`/.well-known/homie-studio.json` (`games[].build.hash`). There is one hash, so a local build is matched to what is
+live by comparing two strings. `build` says changed "since the last build here"; `deploy` says changed "since the
+last deploy from this computer", from its own record in `.studio/local.json`. A deploy from another computer, or the first one, has nothing to compare with and says so.
+
+**The directory.** Going online lists nothing. For a studio this computer already listed with `publish`, the first
+deploy after an older toolkit's (one that still offered a game's whole source) asks the directory to read the studio
+again, once, so it does not keep that offer. `publish` says how many publishes are left today when the directory gives the number (the
+beta has a daily cap), and before it sends, how many this computer has sent today; a refusal for the cap is said as
+that, with when it ends.
+
+**This computer's network.** When Node.js cannot look a public hostname up (a browser on the same computer may still
+open it), the command says "network preflight failed", not that the site or a game is broken, and offers the local
+dev site instead.
+
+## A trailer: `homie-studio trailer`
+
+```sh
+npx homie-studio trailer crown-thief --url http://127.0.0.1:8787 --seconds 45 --length 20 --title "CROWN THIEF"
+```
+
+One command, into `videos/crown-thief-trailer/`: the game rendered frame by frame on a virtual clock (its
+`requestAnimationFrame`, `performance.now`, `Date`, timers and CSS and Web animations all move 1/30 s a frame, so no
+frame is held however heavy the game), its sound rebuilt from the game's own sound files and the log its sound player
+keeps of what it played, the shots picked from that log, an end card, and 16:9, 1:1 and 9:16 files. The work is the
+Homie plugin's video skill; this command finds its script and hands over (`--skills <folder>` when the plugin is not
+beside the package). The skill's guide says what the virtual clock does not reach (the audio clock, media elements,
+Web Workers, a live server) and what a game must do for its sound to be in the film.
+
 ## How fast it runs: `homie-studio perf`
 
 ```sh
@@ -585,15 +719,28 @@ on a fast computer is less than its rate). They play the same seeded presses thr
 window, and each run's JSON says, per browser: the time between animation frames (median, p95, p99, the share over 33
 and 50 ms), the game's JavaScript per frame (every requestAnimationFrame callback timed), the main thread per frame
 (Chrome's TaskDuration), time to the first meaningful frame (`load.look`: the play page's arrival card), to the
-game's first frame, to a seat and to playable, the game's files on the wire, the heap
-after a garbage collection, and netplay messages and kilobytes a second each way. `--profile` adds a CPU profile per
+game's first frame, to a seat and to playable (control-ready: seated, a body reported, the loading cover gone) and,
+beside it, `load.ready` (when the game itself called `net.playable()`) with the arrival mode (`load.arrival`: `auto`,
+`game`, or `seat` for an older helper; under `auto`, `lateMs` is how long after the cover lifted the game said it was
+ready, which is a game that should declare `arrival: 'game'`), the game's files on the wire, the heap
+after a garbage collection, and netplay messages and kilobytes a second each way. Two more are measurements of the
+running game, not estimates from its files: `load.prePlay` (every request the browser really made up to playable,
+with the bytes that had arrived of any still in flight; the metric is `load.prePlayKb`), which is first-play traffic
+and not the shipped payload that `perf sizes` and `assets check` total from the built folder; and `render` (the
+renderer's own draw calls and triangles while playing, metrics `render.calls` and `render.triangles`), read when the
+game exposes them on its port probe (`exposePort(net, { extra: { drawCalls: () => renderer.info.render.calls,
+triangles: () => renderer.info.render.triangles } })`, as the 3D starters do; `PortExtra` in the port kit types these
+and the other names the playtest reads: `alive`, `mode`, `loadout`, `touchHeld`). A game that exposes neither has no
+`render` numbers: the run says the cost was not measured, never zero. `--profile` adds a CPU profile per
 browser in a window of its own (a `.cpuprofile` for Chrome DevTools) and its hottest functions, read through the
 game's source map when the build kept one (`homie-studio build --maps` keeps it in `.studio/maps/<id>/`, never in
 `site/dist`).
 
 The computer is shared, so every run waits for the 1-minute load to fall under 0.8 per core (`--max-load`) and
 records the load before and after; a run that started busy says `loaded` and `compare` leaves it out. A software
-renderer (SwiftShader) makes the run `blocked`: nothing on it is judged. `compare` calls a metric better only when a
+renderer (SwiftShader) makes the run `blocked`: nothing on it is judged. So does an address this computer's Node.js
+cannot look up (Node and a browser do not look names up the same way): "network preflight failed", with the local
+site as the way round it, never "the site is down". `compare` calls a metric better only when a
 rank test says it is unlikely to be chance (p < 0.05), the 95% bootstrap interval of the change stays below zero, and
 it is at least 3% better; runs taken side by side with the same `--pair` label are judged as pairs (a signed-rank
 test on their ratios), so a computer that drifted busier cancels. Guards (frame time, main thread per frame, time to
@@ -607,6 +754,48 @@ Minified JavaScript gzips about as well as source text, and a bundle with three.
 source in strings, which no minifier touches; the line for such a file says `minified, 19% GLSL shader source in
 strings`, and the JSON's `code` has every measure.
 
+## Game parts: how games build on each other
+
+Games build on each other by sharing **parts**: a piece of a game that its studio chooses to share, so somebody
+making another game can use it. A creature from one game, a level from another, a bot brain from a third. Without
+parts, a creator's AI has to come up with everything on its own. [`parts/PARTS.md`](parts/PARTS.md) is the design;
+the plugin's `parts` skill is the method.
+
+Creators work in chat and never type a command: "what parts are there for a chase camera?", "add the Pickup field
+part from owls.example/pickup-field to my game", "make my creature a part", "share it under CC BY". Four tools do
+it, named like the asset tools: `parts_find`, `part_add`, `part_new` and `part_share`.
+
+- **A part is a piece of a game, never the whole game**, in whatever form suits it: code, assets, data, a JSON
+  description, a tuned config, or a mix.
+- **Agents look first.** `game_plan` and the game and plan skills tell an agent to check the `@homie-rocks/*`
+  packages for the general mechanism and `parts_find` for pieces other studios shared, before writing from
+  scratch, and to record in the game's CODEX (Built from) and its credits what came from where. `parts_find` reads
+  the hub's catalogue and the studio's own parts; when the hub cannot be reached it says so and still answers with
+  the studio's own, so an empty list never stands in for "could not look".
+- **Packages are not parts.** `@homie-rocks/*` packages come from npm and are never in the catalogue. A part says
+  which packages it builds on, and npm does the rest: `npm ls` says whether the studio has one, `npm install`
+  installs what is missing after one line saying what and why, and npm's own output is relayed. There is no
+  resolver, no version ranges and no lockfile of Homie's.
+- **Use.** `part_add` fetches one exact version (the latest shared unless named), checks every file's SHA-256 and
+  size before a byte is written, copies it into `parts/_vendor/<site>/<id>/` where the studio owns and tunes it,
+  records where it came from (`parts/origins.json`), and credits it in the game's `credits.json` with its licence,
+  who made it and the game it came from. The game imports it in one line,
+  `import { createPickupField } from '@parts/owls.example/pickup-field'` (one of the studio's own is
+  `@parts/<id>`). Adding it again brings the newer version: what changed is shown, `tuning.json` is kept, and a
+  file the studio edited is never replaced without saying so.
+- **Share.** `part_new` lifts a piece out of a game (the game still builds and plays the same) and records the
+  game and studio it came from. A part is private until `part_share`, which needs an SPDX licence, an attribution
+  when the licence asks for credit, and known rights to every file. It is live after the studio's next deploy.
+- **What the site serves** is `sharedPartsOf(studio)` and nothing else: `/.well-known/homie-parts.json`, each
+  shared version's content at `/parts/<id>/<version>/…` exactly as hashed (immutable, CORS open for GET), the
+  studio's own pages `/parts/` and `/parts/<id>/`, and a **Parts from this game** band on a game's landing. A
+  private part is never copied into the built site, and the Worker answers only what the built index names.
+- **Publishing a game that uses parts**: `deploy --plan` shows each part's licence and attribution and says
+  plainly when licences cannot be combined; `publish` (and `studio_publish`, also with `before: true`) says the
+  same lines before the studio is listed. `parts add --no-install` brings a part in and installs nothing:
+  `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.
+
 ## How it feels: the Game Lab (`homie-studio lab`)
 
 ```sh
@@ -659,7 +848,9 @@ npx homie-studio assets find "fox" --kind creature        # the starter library
 npx homie-studio assets add crown-thief kenney-cube-pets/animal-fox --height 0.7 --card "Characters/Fox"
 npx homie-studio assets add crown-thief --file ./lantern.glb --license own --height 0.6
 npx homie-studio assets check crown-thief                # budgets, the glTF-Validator, licences, staleness, big files
+npx homie-studio assets use crown-thief old-tree unused  # what the game does with it now: cast, prop, environment, unused
 npx homie-studio assets lineup crown-thief               # true scale, silhouettes, palette drift: .studio/art/<id>/
+#   three lineups: the inventory (every recorded model), the cast (what is in play), the environment (the scenery)
 npx homie-studio assets rights crown-thief               # games/<id>/assets/RIGHTS.md and the credits
 npx homie-studio assets redo crown-thief lantern         # made again from its kept raw file, free
 npx homie-studio assets remove crown-thief lantern       # the record and the copy the game ships
@@ -674,14 +865,40 @@ what remaking it would cost; nothing is remade by itself. `games/<id>/style.json
 and camera the game, its landing and its title cards draw with.
 
 Every model, texture and sky a game ships has an entry in `games/<id>/assets/manifest.json`: its route (procedural,
-library, generated, imported), each step that made it, its licence and what a remix gets, its measurements. From it:
-`RIGHTS.md`, the credits on the game's landing, `assets check`, the licence check `publish` makes, and
-`/games/<id>/assets.json` on the site, from which `game remix` fetches every model its licence lets a remix carry
-(checked by SHA-256; a grey placeholder of the same size for the rest). Models are refused when they load anything
+library, generated, imported), each step that made it, its licence, its measurements. From it:
+`RIGHTS.md`, the credits on the game's landing, `assets check` and the licence check `publish` makes. Models are refused when they load anything
 from an address or are over the size caps; `assets add` makes them phone-sized (meshopt geometry, WebP pictures, the
 pivot at the bottom centre, scaled to metres) with @gltf-transform, meshoptimizer and sharp; raw files stay in
 `art/<slug>/raw/`, which git ignores.
 
+`assets check` is an **inventory estimate**, and says so in everything it prints: the recorded files' own triangles,
+draw calls and pictures, each times its declared `placements`. It never runs the game, so geometry the code builds,
+copies the code draws beyond `placements`, effects, and shadow and post passes are not in it; a pass is not a measured
+frame (the playtest and perf guides measure the running game). What it does measure:
+
+- **Standalone textures and skies** (a `texture` or `sky` record's own pictures): there, the file recorded (SHA-256),
+  decodable, within size (a note past 1,024 px, a problem past 2,048 px; a sky twice that), and their mipmapped memory
+  added once per unique picture. A row with nothing measured prints `??` and why, never `ok`. Shipped pictures under
+  `public/` that no record names are listed with their size, apart from pictures the folder keeps but never ships;
+  neither is in the sum.
+- **Maps the game does not draw.** A model's normal and roughness maps are counted unless the manifest says the game
+  draws base colour only (`stylize()` with a toon, flat, pixel or hand-painted material model keeps nothing else):
+  `"inGame": { "maps": "base" }` on a record, or once at the top of `assets/manifest.json` for every model
+  (`"maps": "all"` on a record keeps its own). The check never guesses this from the code; without the declaration it
+  says how many MB are such maps.
+- **The game's own model budget.** game.json `"assets": { "budgets": { "triangles": 4000, "bytes": 600000 } }` (the key
+  the loader's development warnings read) raises what a model may be in the check and in `assets add`, never past a
+  hard cap and never lowering a hero's. One key, read once: the check, `assets add` and the build (for the loader)
+  take the same numbers. A budget may also be set for one tier (`"hero": { "triangles": 12000 }`; tiers are hero,
+  npc, prop, signature, kit); the loader knows no tiers, so it is given the loosest one, and a number past a hard cap
+  is held to the cap by all three (the build says so).
+- **Usage.** `assets use <game> <asset> unused` marks a file the game no longer draws: it stays in the inventory
+  lineup, leaves the cast and environment lineups and the scene sums, and still counts in the shipped payload until
+  `assets remove`. Unset, usage follows the asset's kind.
+- **Shipped payload** (`totals.shippedPayloadMB`; `firstPlayMB` is its old name, kept for existing readers): every
+  file of the last build, gzipped. A conservative gate on what the game ships, not a trace of what a browser fetched
+  before the first round.
+
 In a three.js game, `@homie-rocks/studio/assets` is the one loader:
 
 ```ts
@@ -692,7 +909,8 @@ const fox = await models.instance('./models/fox.glb').catch(() => models.placeho
 
 It checks every file before three.js parses it (no external URIs, no buffer over the cap, only extensions three.js
 reads), decodes meshopt, clones skinned models properly, and says in development when a model is over its budget
-(`stats()`, `window.__homieModels`). `game new <id> --from gem-rush-3d` is Gem Rush in 3D, dressed from the library.
+(`stats()`, `window.__homieModels`). The budget is a small prop's (1,500 triangles, 300 KB) unless the game sets its
+own once, in game.json: `"assets": { "budgets": { "triangles": 8000, "bytes": 1500000 } }` (per model). `game new <id> --from gem-rush-3d` is Gem Rush in 3D, dressed from the library.
 The local MCP's `style_explore`, `decision_set`, `assets_plan`, `assets_find`, `asset_add`, `asset_make`,
 `asset_check`, `asset_lineup` and `asset_rights` do the same with cards. Generated props (on the person's own fal
 account, under a budget, receipted) are the Homie plugin's `models` skill.
@@ -717,7 +935,14 @@ clip library `public/anims/<skeleton>.glb`, shared by every character with that
 has them, else retargeted at build time from the starter library's CC0 humanoid clips (KayKit's): every bone turns in
 the world the way the source's turned from its rest, after the two rest poses are lined up bone by bone, so a T-pose
 clip plays on an A-pose rig; a one-piece limb aims where the source's whole limb points. It is plain matrix math in
-Node (no renderer), so it runs in CI and a cloud session too. `assets check` holds characters to four influences a
+Node (no renderer), so it runs in CI and a cloud session too. One clip library a skeleton: a second one is refused
+when it is recorded (it used to hide the first), unless its record says `"rig": { "supplemental": true }`, in which case
+its verbs join the character's coverage and previews and the game loads both
+(`loadCharacter(models, url, { anims: [base, extra] })`). `anim plan` and `anim preview` also show how fast each
+character's walk and run move its feet over the ground on its own rig (kept as `rig.gait`): animate's default
+`runSpeed` of 4.2 m/s is not measured on your rig, and a clip retargeted onto a taller character covers more ground,
+so start `tune: { runSpeed }` from that number. It is a guide from the foot bones, not a verified foot contact.
+Removing a starter character keeps its pack's credit while any clip retargeted from it remains. `assets check` holds characters to four influences a
 vertex, the tier's bones, a clip library of 1 MB at 30 samples a second, every verb the game's `anim.clips` names,
 and the skinning a room costs on a phone (players times the heaviest character: 60,000 vertices and 1,200 bones a
 frame).
@@ -743,6 +968,71 @@ move), `anim_add`, `anim_preview` and `character_make` do the same with cards. A
 in the locked style, then Meshy's mesh and auto-rig on the person's own fal account, about US$1.44, priced and
 receipted) is the Homie plugin's `models` skill; rigs, clips and feel are its `animate` skill.
 
+## A model you can stand on (`homie-studio collision`)
+
+Importing a model records what it looks like. It does not say where a figure may walk on it, so the first playable
+version of a generated landmark is one figures fall through.
+
+```sh
+npx homie-studio collision bake harbour-run lighthouse.glb --cell 0.25   # a height grid off its triangles, beside it
+npx homie-studio collision check harbour-run                          # stale? proxies well formed? every route walked?
+```
+
+`bake` writes `lighthouse.collision.json` (the grid sampled off the model's outside surface at the cell size you give,
+the SHA-256 of the file and a checksum of its triangles) and `lighthouse.collision.svg`, the plan at true scale (40 px to
+the metre). Three things in the JSON are yours, and a re-bake keeps them: `"proxies"` (boxes, cylinders and ramps for
+what a figure walks around), `"mover"` (the body that must fit: radius, height, step, and the arrival radius the
+game's bots really use) and `"routes"` (ways a bot should be able to walk, as lists of points). `check` fails, with a
+row for each thing wrong, when the model's surface changed since the bake, a proxy is malformed, or a body of the
+mover's size cannot walk a route: it says where it fell or what was in the way, and marks the spot on the plan.
+
+The game loads the JSON with `unpackBake` and `bakeField` from `@homie-rocks/heightfield/MeshBake.js`, and calls
+`bakeStale` against the mesh it loaded. The command needs `@homie-rocks/heightfield` installed in the studio (it says
+so when it is not). Buildings with rooms and roofs, zone marks on every level and staged capture positions are that
+package's `Levels.js`, `Route.js`, `Markers.js` and `Pose.js`: its README has them.
+
+## Bots that want different things (`@homie-rocks/studio/personas`)
+
+```ts
+import { PERSONAS, createPersonaBrain, botStats, seededRng } from '@homie-rocks/studio/personas';
+
+const who = createPersonaBrain(PERSONAS.bully, { rng: seededRng(roomSeed + slot), arena: { solid } });
+const target = who.choose(self, candidates, rivals);          // candidates: { x, y, kind, value, size? }
+const push = who.steer(self, seek(self, target));             // turned off any wall ahead
+```
+
+One scorer (value against distance, with a target behind, a wall in the way, company near it and a bigger rival each
+costing some of the score) and five rows of weights: `glutton`, `bully`, `racer`, `scavenger`, `sneak`.
+`persona('sneak', { kinds: { beacon: 6 } })` extends one. `solid(x, y)` is the game's own wall test; line of sight
+and wall avoidance use nothing else. `who.chooser(...)` is the `choose` the port kit's `BotBrain.think` takes, so the
+room's skill dial still sets how late a bot reacts and how well it aims: a persona is what it wants.
+`who.stats()` / `botStats([...])` count what each bot picked (kinds, mean value, distance, facing, company, picks
+behind walls) and `personaSpread` is one number for how unlike each other they were: assert on those in the game's
+own test, because weights that look different often play the same. The only randomness is the `rng` you pass. The
+host owns the bots; nothing here is sent anywhere.
+
+## Power-ups whose timers survive a host change (`@homie-rocks/studio/powerups`)
+
+```ts
+import { createPowerups, stepPowerups, collectPowerups, resolveHit, biteRadius, collides, packPowerups, unpackPowerups } from '@homie-rocks/studio/powerups';
+
+let power = createPowerups(SPOTS.length, roomSeed);                    // host
+({ state: power } = stepPowerups(power, dtMs));                        // host tick: timers, expiry, spawns
+({ state: power, events } = collectPowerups(power, bodies, SPOTS));    // who touched what (lower slot on a tie)
+snapshot.power = packPowerups(power);                                  // host: in the snapshot AND the checkpoint
+power = unpackPowerups(snapshot.power);                                // replicas, and a new host, once
+```
+
+Everything is one plain object and pure functions over it, so the rules are unit-tested and nothing reads a clock.
+The state holds how long each power-up has **left**, not a deadline, and the spawn sequence's seed: a browser that
+becomes host mid-timer carries on from the last snapshot and spawns the same next pickup. Three kinds are built in:
+Magnet (`biteRadius` is wider, `magnetPull` draws loose things toward the mouth), Phase (`collides(state, a, b)` is
+false) and Shield (`resolveHit` blocks one hit and returns the velocity to bounce the attacker with). Add a kind by
+adding a row to the rules, last (a kind travels as its index). `powerFlags` is a bitmask per body. It is the game's
+own snapshot data: the netplay wire protocol is unchanged, and a tab on an older build drops kinds it does not know.
+`powerDraws` fills instance matrices for three instanced meshes the game owns (gems, magnet rings, shield bubbles) and
+`hudPills` says what the HUD shows; both are optional and import no renderer.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud
@@ -751,6 +1041,40 @@ the home folder's `.cache/homie-studio` (from storage.googleapis.com, which a cl
 renders with SwiftShader. `check` reports how fast each browser drew the game and on what renderer; on SwiftShader
 it says the frame rate is not a person's, and judges only seats, rooms and rounds.
 
+`check` reports three things apart: **seated** (a room, a seat, a role), **ready** (`readiness`: the play page's
+loading cover has lifted; the picture it calls `<browser>-playing.png` is taken only then, and a browser still
+covered is saved as `<browser>-loading.png`), and **connected** (`connection`, `reconnects`, `uninterrupted`: a
+round both browsers finished is `ok`, and whether one of them reconnected on the way is said beside it; a browser
+seen `reconnecting`, `alone`, `offline` or `closed` (the helper's link) is listed as `cutOff` and the connection is
+not called uninterrupted, whether or not a counter moved). `perf` leaves out a run whose browser ended its window cut
+off from the room. A site this computer's Node.js cannot look up does not stop `check` or `shoot` (their browsers may
+still open it); if the browsers cannot either, they report the same BLOCKED network preflight as `perf` and `port check`.
+Nothing listening on this computer's own address stops all four at once: "does not answer: start the site".
+`port check`'s big-screen row requires the join QR on an address a phone can reach and marks it not applicable on a
+loopback preview, where the page hides the join card on purpose.
+
+### Pictures on a stepped clock: `homie-studio shoot`
+
+```sh
+npx homie-studio shoot crown-thief --url http://127.0.0.1:8787 [--frames 60] [--fps 30] [--device computer|phone] [--hold KeyD] [--no-smoke] [--timeout 180]
+```
+
+For a 3D game where there is no GPU and the software renderer draws two frames a second. First a smoke check: two
+clients (a computer and a phone) open the play page in one private room (`?room=shoot-…`) and must both get a seat
+there, on different seats, with neither playing alone offline. Then the first client's clocks are frozen and stepped:
+`requestAnimationFrame`, `performance.now`, `Date`, `setTimeout`, `setInterval` and CSS/Web animations move by
+exactly 1/fps of a second per frame, in the page and in the game's frame, and each step is one picture
+(`.studio/shoot/<id>/frame-0001.png` …, with `shoot.json`: each frame's time, and the round phase, position and
+renderer counters when the game has a port probe). Not stepped, and said in the result: the room's socket and its
+server clock (other players arrive in real time), Web Audio's clock, `<video>`, workers. The frames show what was
+drawn; they are never a frame rate. Everything is bounded by `--timeout`; a run that hits it keeps the frames it has
+and says `partial`.
+
+`shoot <id> --preview` needs no site running: it serves the built game itself (the light server `preview <id>` uses:
+no Wrangler, no rooms, the game alone and offline with its bots) and shoots that page. The smoke check is not run
+there (it needs rooms: use `dev` and `--url`). The result names the build the frames are of, by the hash `build`
+printed and the hashed bundle the page loaded.
+
 ## Another way to Cloudflare: Stripe Projects (a prototype, 0.24.3)
 
 `npx wrangler login` stays the way. For a creator with no Cloudflare account (and no ElevenLabs), Stripe Projects
@@ -812,7 +1136,9 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | --- | --- |
 | `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/build.mjs`, `lib/stage.mjs` | `build`: games bundled with esbuild (ES modules with code splitting, the bundle named by its content) into `site/dist`, `games.json` and `_site/build.json` (each game's build hash and whether it changed). Built in a folder of its own and put in place only when all of it is there; a game that does not build fails the command and leaves `site/dist` as it was (`site/SITE.md`, "The build"). |
+| `lib/typecheck.mjs` | `build --types`: the games' TypeScript checked with the studio's own `typescript` before anything is built. |
+| `lib/preview.mjs` | `preview <id>`: one built game's files at an address on this computer, with no Wrangler and no rooms. |
 | `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket; `media move`: big media into it, checked by SHA-256 (every deploy runs it). |
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |

package/assets/animate.ts

@@ -49,7 +49,9 @@ const HERO_BUDGET = { triangles: 8000, texturePx: 1024, materials: 2, bytes: 153
 export const ANIM_TUNING = Object.freeze({
   fade: { value: 0.14, min: 0, max: 0.6, step: 0.01, unit: 's', group: 'Motion', note: 'How long one clip takes to blend into the next' },
   walkSpeed: { value: 1.5, min: 0.3, max: 6, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the walk clip\'s feet move at (feet slide when this is wrong)' },
-  runSpeed: { value: 4.2, min: 1, max: 12, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the run clip\'s feet move at' },
+  // 4.2 m/s suits the starter library's chibi rigs. It is a default, NOT a reading of your rig: a clip retargeted onto
+  // a taller character covers more ground a cycle (`homie-studio anim plan` shows the speed measured on each rig).
+  runSpeed: { value: 4.2, min: 1, max: 12, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the run clip\'s feet move at (a default, not measured on your rig: anim plan shows the measured speed)' },
   runFrom: { value: 2.4, min: 0.5, max: 8, step: 0.05, unit: 'm/s', group: 'Motion', note: 'From this speed up, the walk becomes a run' },
   actSpeed: { value: 1.25, min: 0.5, max: 3, step: 0.05, group: 'Motion', note: 'How fast actions (attacks, casts) play: higher is snappier' },
   jumpStretch: { value: 0.16, min: 0, max: 0.5, step: 0.01, group: 'Motion', note: 'How tall and thin the body goes as it leaves the ground' },
@@ -64,8 +66,11 @@ export const ANIM_TUNING = Object.freeze({
 export type AnimTuning = { -readonly [K in keyof typeof ANIM_TUNING]?: number };
 
 export interface CharacterOptions {
-  /** The clip library's address (default: the one the model names, beside it in ./anims/). */
-  anims?: string | null;
+  /**
+   * The clip library's address (default: the one the model names, beside it in ./anims/); null for none; or a list of
+   * addresses when its skeleton has a supplemental library too (the base first).
+   */
+  anims?: string | string[] | null;
   /** Live numbers (lab.tunables(tuning)): any ANIM_TUNING key, read every frame. */
   tune?: AnimTuning;
   /** Bones that swing on springs (default: names with tail, ear, cape, hair, antenna). */
@@ -157,10 +162,15 @@ export async function loadCharacter(models: ModelSource, url: string, opts: Char
   const loaded = await models.load(url, { budget: HERO_BUDGET });
   const info = (loaded.scene.userData?.homie ?? {}) as { anims?: string; family?: string; sockets?: Record<string, string> };
   let clips = loaded.animations ?? [];
-  const animsUrl = opts.anims === null ? null : (opts.anims ?? (info.anims ? new URL(info.anims, new URL(url, typeof location !== 'undefined' ? location.href : 'http://localhost/')).href : null));
-  if (animsUrl) {
-    try { clips = [...(await models.load(animsUrl, { budget: { triangles: 0, bytes: 3 * 1024 * 1024 } })).animations, ...clips]; } catch (error) { if (!clips.length) console.warn(`[animate] ${url}: its clips did not load (${(error as Error).message})`); }
+  // `anims`: the clip library to use instead of the one the model names; null for none; or a LIST, for a skeleton
+  // with a supplemental library beside its own (the base first: where two hold a verb, the earlier one's clip plays).
+  const own = info.anims ? new URL(info.anims, new URL(url, typeof location !== 'undefined' ? location.href : 'http://localhost/')).href : null;
+  const animsUrls = opts.anims === null ? [] : Array.isArray(opts.anims) ? opts.anims : [opts.anims ?? own].filter((u): u is string => Boolean(u));
+  const fromLibraries: AnimationClip[] = [];
+  for (const animsUrl of animsUrls) {
+    try { for (const c of (await models.load(animsUrl, { budget: { triangles: 0, bytes: 3 * 1024 * 1024 } })).animations) if (!fromLibraries.some((x) => x.name === c.name)) fromLibraries.push(c); } catch (error) { if (!clips.length && !fromLibraries.length) console.warn(`[animate] ${url}: its clips did not load (${(error as Error).message})`); }
   }
+  clips = [...fromLibraries, ...clips];
   const model = await models.instance(url, { budget: HERO_BUDGET });
   return createCharacter(model, clips, { ...opts, family: info.family ?? null, sockets: info.sockets ?? {} });
 }