@homie-rocks/studio 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -17,9 +17,86 @@ 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.22.0] - 2026-10-02
+
+**Plugin 0.23.0** · [#32](https://github.com/homie-rocks/homie/pull/32)
+
+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) · [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.
+
+### Added
+
+- Plugin: the Homie mod (Claude Code 2.1.287 or later). Inside a studio, a one-row band above the prompt shows the
+  studio, the game, the build step, ▶ Play and how many people are playing now. Outside a studio it adds nothing.
+- Plugin: the Studio pane (`/studio`) opens by itself when a build starts, on a wide enough terminal. **Build** has the
+  live Plan, Build, Checks, Deploy feed and the latest check frame, or a live Watch of a room of the game being built.
+  **Rooms** lists who is playing and the AI players, with Watch and Join links; Announce, Mute and Kick go through
+  the office, and Mute and Kick are only ever asked for, so you still confirm them with one tap. **Games** has
+  launch states and the remix switch; **Stats** and **Codex** link to the rest. **Lab** shows each game's last Game
+  Lab check (New's phases beside Today's, whether the replays match) and the lab's link while it runs.
+- Plugin: the Arcade pane (`/arcade`). Take a real seat in a public room of a Homie game (Homie Arcade's, or your
+  studio's own) and play it in the pane with w/a/s/d or the arrow keys while Claude works. It runs in one headless
+  Chrome on your computer at the lowest priority, about 8 frames a second in a terminal, pauses while the pane is
+  hidden and stops when you leave.
+- Plugin: a Parts pane for the `parallel` skill: each part, its last step, and the merge waiting for all of them.
+- Plugin: instant commands that answer without a Claude turn: `/play`, `/watch [room]`, `/rooms`, `/build`, `/codex`,
+  `/deploy-status`, `/perf-numbers`, `/parts`, `/arcade`. They print links or open a pane; nothing opens a browser.
+- Plugin: guards. An edit to a file matched by studio.json `"protect"` (globs, such as `"games/*/game.json"`) shows
+  the diff and waits for Proceed or Cancel. So does a deploy (where it goes, what it creates, the commits and files
+  since the last one, the checks) and a paid fal or ElevenLabs run that would pass studio.json `"budget"`.
+- Plugin: Cloudflare tokens, provider keys, agent passes, office keys and one-time owner links are taken out of
+  command output before Claude reads it.
+- Plugin: setup status, check, playtest and deploy results are drawn as checklists and rows, with the live link.
+- `homie-studio office mute <game> <room> <seat | name> [--minutes 10] [--off]`, asked for like `office kick`.
+- A build's latest check frame is also kept as a small picture beside its progress feed, for the mod to draw.
+
+### Upgrade notes
+
+- Every part of the mod has its own switch (`/config`, or `pluginConfigs` in settings.json). Codex installs the plugin
+  as before; it does not run plugin hooks, so there it is the skills and tools you had.
+- `homie-studio upgrade --apply` adds `office mute` and the `protect` and `budget` lines to AGENTS.md.
+
 ## [0.20.0] - 2026-10-02
 
-**Plugin 0.21.0** · [#30](https://github.com/homie-rocks/homie/pull/30)
+**Plugin 0.21.0** · [#30](https://github.com/homie-rocks/homie/pull/30) · [release-2026-10-02-studio-0.20.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.20.0)
 
 A Game Lab: tune how one move of your game feels (a jump, a hit, a dash), your new version beside your last commit,
 frame by frame.

package/README.md

@@ -17,6 +17,9 @@ 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
@@ -491,6 +494,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