@homie-rocks/studio 0.21.0 → 0.23.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.23.0] - 2026-10-03
+
+**Plugin 0.24.0** · [#33](https://github.com/homie-rocks/homie/pull/33)
+
+Room chat in every game: reactions that float up every screen, quick lines, typing where the rules allow, speech bubbles over characters, rules per game and server, moderation in your own Worker, and the owner's tools.
+
+### Added
+
+- Room chat on every game's play page, with no game code: a Chat pill beside the room button (the corner `screen.share` keeps clear of the game's HUD) and its sheet: the room's last minutes, the five reactions (fire, clap, laugh, heart, wow, in homie.rocks's order, plus up to three of the game's own), the game's quick lines, typing where the rules allow it (and why not where they do not), and Report on a line. New lines show for a moment where the status chip sits (game.json `"screen": { "chat": … }` moves them).
+- Reactions float up every screen in the room, as on the television: the players', the watchers' and the big screen's (at most six a second, eighteen at once). The big screen (`/<game>/tv`) shows the room's lines in a corner, and the watch page has a Chat button and panel. Measured in Chrome with four browsers in one room: a reaction is on the other screens within about 15 ms of the press locally.
+- Speech bubbles over characters: the port kit's `createBubbles` and `paintBubbles` (beside `createLabels`), and the helper's `net.on('say')`. Gem Rush, Ember Vale and Gem Rush 3D draw what a player says over their name. Each player chooses "Show my messages over my character" and "Show chat on this screen".
+- Rules per game and per server: game.json `"chat"` sets a game's defaults (off, emoji, quick lines or typing; who may type and who may react: anyone, signed in with a passkey, or members; slow mode, length, links, swears, the review, bubbles, watchers, homie.rocks), and the owner overrides them in the office or with `homie-studio chat rules`. A kids server and every beginner server keep chat to emoji and quick lines. By default emoji and quick lines are open to everyone and typing needs a signed-in player account.
+- Moderation in the studio's own Worker before a typed line reaches anyone: a built-in word list and patterns (slurs, sexual words, self-harm, personal questions such as a player's age or where they live, contact details and other apps, links, swears) plus your own words, then a review on your own Workers AI with Cloudflare's Clef decision model (`@cf/cloudflare/clef-flash`), within a daily budget of 2,000 neurons (about 850 typed messages; inside the free allocation). Emoji and quick lines are never reviewed. When the review cannot answer, the word list decides alone. `chat/CHAT.md` says why Clef and what the alternatives cost.
+- The owner's tools: every live room's last minutes in the office with Remove (from every screen), Mute and Kick from a line (a watcher too, their lines taken down with them), the same three in the owner's own game, players' reports with Dismiss, the review's day, and an announcement as a studio line in the chat. `homie-studio chat` (rules, rooms, reports), `chat rules`, `chat remove`, `chat budget` and `chat words`.
+- A studio's `/api/rooms` says which rooms let homie.rocks show their chat (`chat: true`), so homie.rocks's room cards can show a room's chat and emoji live from the room's own socket (the hub's side ships with homie.rocks). Turn it off per game or server with the `hub` rule.
+- `chat/OWNERS.md`: a plain note for studio owners on what the chat tooling does, what is stored and for how long, and children's data (not legal advice).
+- Netplay revision 8 (NETPLAY.md section 19): `say` and `react` frames up, `line`, `react`, `lines`, `unline` and `held` down, `policy.chat`, and the owner's `unsay`; the helper's `net.say`, `net.sayLine`, `net.react`, `net.chatRules` and `on('chat' | 'say' | 'unchat' | 'held')`.
+
+### Changed
+
+- `homie-studio deploy` binds Workers AI when a game lets its players type (the review), not only when an AI guide thinks with it.
+- `homie-studio dev --remote-ai` works again: Wrangler's `--local` turned every remote binding off.
+
+### Upgrade notes
+
+- `homie-studio upgrade --apply` (or the next deploy) adds migration `0007_studio_chat.sql`: the owner's chat rules and players' reports. The chat itself is never stored.
+- Games get the chat panel, the float and the ticker as soon as the studio deploys this version. Rebuild a game to draw speech bubbles (its netplay helper is revision 8).
+- Typing needs a signed-in player account by default. To let guests type, or to keep a game to emoji and quick lines, set game.json `"chat"` or use `homie-studio chat rules`.
+
+## [0.22.0] - 2026-10-02
+
+**Plugin 0.23.0** · [#32](https://github.com/homie-rocks/homie/pull/32) · [release-2026-10-03-studio-0.22.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.22.0)
+
+Your game's look as decisions you can steer and lock, a style board the engine draws for free, free CC0 3D models, props made on your own fal account, and every asset licensed and checked for phones.
+
+### Added
+
+- `homie-studio style`: your game's look as about thirty decisions (render style, palette, shape, proportions, materials, light, camera, fonts, effects; the cast, its library family, scale and phone budgets; rigs and animation for later). `style init <game> --prompt "…"` picks each from your words, the codex and the genre, with a one-line why, and the Game Codex's Art direction tab draws them. `style steer` nudges one in your words ("warmer", "closer", "golden hour"), `style lock` freezes one for you, and the first model built on an automatic decision pins it.
+- `homie-studio style board <game>`: three coherent directions, each drawn by the game's own engine (its palette, light, camera, material model, fonts and proportions, with the starter library's pieces re-tinted into its palette). Free, in about 20 seconds. Pick one, mix rows from several, steer, lock. A painted mood image per direction is optional and paid, on your own fal account, and labelled a target.
+- Changing a locked decision shows its blast radius first (`style blast`): every model made under it that would go stale, what remaking each would cost, and what a free palette re-tint fixes. Nothing is ever remade by itself.
+- `homie-studio assets`: every model, texture and sky a game ships is recorded in `games/<id>/assets/manifest.json` with where it came from, each step that made it, its licence and what a remix gets. `assets rights` writes `RIGHTS.md` in plain words, credits go on the game's landing, and `assets remove` takes a model out with the copy the game ships.
+- Homie's starter library: free CC0 models, materials and skies from Kenney, KayKit, Poly Haven and ambientCG, made phone-sized, with thumbnails and their licences. `assets find "pine tree"` searches it and `assets add <game> <item>` copies one into the game (never hot-linked). It is served from homie.rocks; `HOMIE_LIBRARY` points at another copy.
+- `assets add <game> --file <model> --license <kind>`: your own models, checked first (a file that loads anything from an address, or is too big, is refused), made phone-sized (meshopt geometry, WebP pictures, the pivot at the bottom centre, scaled to metres) and recorded. The raw file stays in `art/<slug>/raw/`, which git ignores, and `assets redo <game> <asset>` makes it again from there for free. Unless the game's render style is `pbr`, models are made non-metal: metal with nothing to reflect draws black on a phone.
+- `assets check <game>`: every model against phone budgets (triangles, draw calls, picture memory, the first-play download), the Khronos glTF-Validator, its licence, and whether a decision it was made under has changed. `assets lineup <game>` draws them side by side at true scale on a 1 m grid, with their silhouettes and how far their colours drift from the palette. The first-play download counts one file per sound (a browser fetches the .ogg or its .wav fallback, never both).
+- `@homie-rocks/studio/assets`: one model loader for three.js games. It refuses unsafe or oversized files before three.js reads them, decodes meshopt, clones skinned models properly, and says in development when a model is over its budget. `stylize` draws a model in the game's material model and ink outline from `style.json`, the way the style board drew it.
+- A starter in 3D: `game new <id> --from gem-rush-3d` is Gem Rush's rules drawn with three.js and dressed with models from the starter library. `game new` fetches them, checked by SHA-256 (the repository holds no model file), and a game you already planned keeps its decisions, its `style.json` and its own models. Its light, ground and materials follow the style board: faceted low-poly ground and grass in the palette's greens, every model drawn in the style's materials and outline, the gem in the palette's gold, the animals' colours pulled toward the palette, and the sun's real shadows on a computer (soft discs on a phone). The camera looks past the clearing into the woods; a phone held upright follows its player from closer and lower, so the action fills it. The game opens on a short title card with its name, and its HUD, results and name labels share one paper-and-ink look that reads in any palette. The meadow is a clearing with a campfire at its heart and a few solid rocks, bushes and a tree players move round; game.json `"scoring": "together"` turns the ranking into one total the room fills, for a cozy game. `assets lineup` draws each model at the height and in the colours the game gives it.
+- A remix now arrives with its models: the original site serves `/games/<id>/assets.json`, and `game remix` fetches every model its licence lets a remix carry, checked by SHA-256, with a grey placeholder of the same size for the rest. It adds three.js when the game needs it, and no other package by itself.
+- Homie for Claude Desktop: the tools `style_explore`, `style_board`, `decision_set`, `assets_plan`, `assets_find`, `asset_add`, `asset_make`, `asset_check`, `asset_lineup` and `asset_rights`, with style board, look decision, cast, lineup and rights cards.
+- Plugin: the `style` skill (decisions, the board, locks and the blast radius) and the `models` skill (the starter library, your own models, and generated props: a concept in the locked style, then Tripo P1 image-to-3D, on your own fal account under a budget with a receipt per call, about US$0.54 a prop). The plan asks whether you want to steer the look and what art budget you have.
+- Plugin: the Studio mod's Art tab and its commands `/look`, `/lock`, `/assets`, `/lineup` and `/rights`; it refuses a hand edit to a locked decision, a deploy that ships an unlicensed model, and a commit of a big binary under `games/`, and holds a paid prop past the budget.
+- `games/<id>/style.json`: the palette, fonts, light and camera a game draws with. Its landing takes its accents from it, and the video skill's title cards (`card --game <id>`) wear its palette and font.
+
+### Changed
+
+- A game with an art direction gets its play page's buttons in its own paper and ink (from `style.json`), so they match its HUD.
+- Gather games pick a low three-quarter camera: down among the players, the woods beyond the clearing in view.
+- Local development never shows a phone an address it cannot open: the TV view drops its join card, the landing drops its code, and the room button's sheet says to deploy to share (every starter: the page is the studio's).
+- `publish` refuses to list a studio while a public game ships a model with no licence record, or one whose licence forbids it.
+- `check` refuses a game with a binary over 5 MB committed under `games/` (it belongs in R2).
+- The remix source leaves out each game's `codex/` folder (its decisions and style board), like `CODEX.md`.
+- `@homie-rocks/studio` now depends on three.js, @gltf-transform, meshoptimizer, sharp and the Khronos glTF-Validator (about 60 MB more in a studio's `node_modules`).
+
+### Upgrade notes
+
+- `homie-studio upgrade --apply` adds the art section to AGENTS.md and `.gitignore` lines for raw 3D files (`art/**/raw/`, `*.blend`, `*.fbx`). Commit no raw model file: move any already committed into `art/<slug>/raw/`.
+- The starter library is served from homie.rocks once it is online; until then `assets find` says so, and `HOMIE_LIBRARY` can point at a local copy.
+
 ## [0.21.0] - 2026-10-02
 
-**Plugin 0.22.0** · [#31](https://github.com/homie-rocks/homie/pull/31)
+**Plugin 0.22.0** · [#31](https://github.com/homie-rocks/homie/pull/31) · [release-2026-10-02-studio-0.21.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.21.0)
 
 The Homie mod for Claude Code: your studio, its rooms and a real seat in a live game beside the chat, with a look
 before protected files, deploys and spending, and keys kept out of what Claude reads.

package/README.md

@@ -17,12 +17,16 @@ npx homie-studio dev                                   # the whole site locally
 npx homie-studio check crown-thief --url http://127.0.0.1:8787
 npx homie-studio perf crown-thief --url http://127.0.0.1:8787   # how fast it runs: a computer and an emulated phone, host and replica
 npx homie-studio 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)
+npx homie-studio assets find "pine tree"               # free CC0 models from Homie's starter library, phone-sized
+npx homie-studio assets check crown-thief              # every model against phone budgets, the validator and its licence
 npx homie-studio deploy --plan                         # what deploy will create, and what it costs; changes nothing
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
 npx homie-studio office                                 # who is playing now, in every live room (the back office)
 npx homie-studio servers                                # each game's servers: humans-only, hybrid AI seats, beginner guides
+npx homie-studio chat                                   # room chat: each game's rules, the rooms' last minutes, reports
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
@@ -283,6 +287,42 @@ npx homie-studio agents pass night-rush --label Claude
 - Everything is in the studio's own Worker and D1 (migration `0006_studio_servers.sql`). The site's side is in
   [site/SITE.md](site/SITE.md); the room's in [netplay/NETPLAY.md](netplay/NETPLAY.md) sections 17 and 18.
 
+## Room chat
+
+Every game has room chat (0.23.0), with no game code: reactions that float up every screen in the room (players,
+watchers, the big screen), the game's quick lines, and typing where the room's rules allow it. It is the Homie app's
+live-room chat and homie.rocks's room chat in a studio's own game: the same five reactions in the same order, the
+same message shapes, the same float on a television.
+
+```sh
+npx homie-studio chat rules night-rush --mode lines                    # emoji and quick lines only
+npx homie-studio chat rules night-rush --who anyone --slow 5           # guests may type, one line every 5 s
+npx homie-studio chat rules night-rush --server first-light --mode emoji
+npx homie-studio chat                                                   # rules, every room's last minutes, reports
+npx homie-studio chat remove night-rush pub-3 <line id>                 # take a line down on every screen
+npx homie-studio chat words                                             # the built-in word list the floor holds
+```
+
+- **The play page:** a Chat pill beside the room button (the corner `screen.share` keeps clear of the HUD), its
+  sheet (the last minutes, the reactions, the quick lines, typing, Report), a short ticker of new lines, and two
+  switches each player keeps: "Show my messages over my character" and "Show chat on this screen". The big screen
+  shows the lines in a corner; the watch page has a Chat button; homie.rocks shows a room's chat on its card.
+- **Rules** per game (game.json `"chat"`) and per server, in the office or with `chat rules`: off, emoji, quick
+  lines or typing; who may type and who may react (anyone, signed in with a passkey, members); slow mode, length,
+  links, swears, the review, bubbles, watchers, homie.rocks. Default: emoji and quick lines for anyone, typing for
+  signed-in players. A kids server and every beginner server keep chat to emoji and quick lines.
+- **Moderation, in the studio's own Worker, before anyone sees a typed line:** a built-in word list and patterns
+  (slurs, sexual words, self-harm, personal questions and contact details, links, swears, your own words), then
+  Cloudflare's **Clef** decision model on the studio's own Workers AI (`@cf/cloudflare/clef-flash`, about 2.3
+  neurons a message measured, 2,000 a day by default: inside the free allocation). Emoji and quick lines are never reviewed.
+- **The owner:** every live room's last minutes in the office with Remove, Mute and Kick (from a line, with their
+  lines taken down), the same in the owner's own game, the reports players make, and Announce (a studio line).
+- **Speech bubbles:** `net.on('say')` and the port kit's `createBubbles` / `paintBubbles`; Gem Rush, Ember Vale and
+  Gem Rush 3D draw them over the speaker.
+- **Nothing is stored** but a report (the one message, 30 days): the room keeps 15 minutes in memory.
+  [chat/CHAT.md](chat/CHAT.md) is the short version and why Clef; [chat/OWNERS.md](chat/OWNERS.md) a plain note for
+  studio owners on chat and children's data; NETPLAY.md section 19 the wire.
+
 ## Setup status
 
 ```sh
@@ -491,6 +531,58 @@ replay check), REPORT.md (New against Today), sheet.png (the lab at each phase's
 The local MCP's `game_lab` starts the lab and answers with a card. The Homie plugin's `lab` skill has the method:
 instrument and commit first (Today is the game as it is), then change how it feels, and keep what the person likes.
 
+## Art direction and models (`homie-studio style`, `homie-studio assets`)
+
+```sh
+npx homie-studio style init crown-thief --prompt "a cozy low-poly forest where foxes gather berries"
+npx homie-studio style crown-thief                       # every decision: · auto  ~ steered  ● pinned by use  ■ locked
+npx homie-studio style board crown-thief                 # three directions, drawn by the game engine: codex/board/*.jpg
+npx homie-studio style pick crown-thief b --mix style.camera=a
+npx homie-studio style steer crown-thief style.palette "warmer"
+npx homie-studio style lock crown-thief style.palette --words "keep that palette"
+npx homie-studio style blast crown-thief style.palette   # what a change would make stale, and what remaking costs
+npx homie-studio assets find "fox" --kind creature        # the starter library (HOMIE_LIBRARY: another copy)
+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 lineup crown-thief               # true scale, silhouettes, palette drift: .studio/art/<id>/
+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
+```
+
+A game's look is a set of decisions (`games/<id>/codex/decisions.json`, private like the codex, drawn in its Art
+direction tab): render style, palette, shape, proportions, materials, light, camera, fonts and effects; the cast, its
+library family, scale and phone budgets; rigs and animation (later phases). Each starts as an automatic pick with a
+why. A person's nudge makes it steered, their lock freezes it, and the first asset built on an automatic one pins it.
+Every asset records the revision of each decision it was made under, so changing one lists exactly what went stale and
+what remaking it would cost; nothing is remade by itself. `games/<id>/style.json` (public) is the palette, fonts, light
+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
+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.
+
+In a three.js game, `@homie-rocks/studio/assets` is the one loader:
+
+```ts
+import { createModels } from '@homie-rocks/studio/assets';
+const models = createModels();
+const fox = await models.instance('./models/fox.glb').catch(() => models.placeholder({ x: 0.6, y: 0.7, z: 0.9 }));
+```
+
+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.
+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.
+
 ## 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