@homie-rocks/studio 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -17,9 +17,69 @@ 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.24.0] - 2026-10-03
+
+**Plugin 0.25.0** · [#34](https://github.com/homie-rocks/homie/pull/34)
+
+Sell things in your games with your own Stripe account: a supporter pack, cosmetics, a pass, an unlock or a tip, in real money, with refunds from your office and the kids rules built in; Homie never sees the money.
+
+### Added
+
+- The shop: `shop.json` at your studio's root lists what you sell (`cosmetic`, `supporter`, `pass`, `unlock`, `tip`), each in real money with the entitlement keys your game reads. `homie-studio shop init --supporter` writes a US$5 Supporter pack (a badge on the player's profile and beside their name in rooms, for a year) and `SELLING.md`, plain words on what selling makes you responsible for (refunds, disputes, tax, kids; not legal advice).
+- Checkout is Stripe's own hosted page, opened by your studio's Worker with your own restricted key, one item at a time. Stripe Tax is on by default; Stripe Managed Payments (Stripe as the seller of record: it registers, files and pays the tax and answers disputes, for 3.5% more) is one switch, `"till": "stripe-managed"`. Stripe's receipt email is the receipt.
+- A signed webhook (`/api/shop/hook`: Stripe's signature, within five minutes, each event once) is the only thing that marks an order paid, refunded or disputed. What a player owns is tied to their passkey account and follows them to every device.
+- `homie-studio shop connect`: a page on your own computer where you paste the restricted key and the webhook secret. It says exactly what to make in Stripe, offers Managed Payments in plain words, and puts both straight into your Worker's secrets: never the chat, a file or a log. Test keys only unless `--live`.
+- In a game: `createShop()` from `@homie-rocks/studio/shop` gives `shop.has('skin:ember')`, `shop.entitlements()`, `shop.on('change')`, `shop.open(item)` and `shop.used(key)`. The play page has a store sheet (from the game, or Shop in the room sheet) that opens Stripe in a new tab while the game keeps running; on a television it shows only a code to buy on a phone.
+- A supporter's badge rides on their seat in every room (`peer.badge`, set by your Worker from what the account owns; a hello can never claim one), and their account page lists their purchases and badges.
+- Refunds: one tap in your office (`/_studio/office/shop`), and a player's own refund of an unused item within your refund window (at least 14 days). Your AI can only ask for a refund (`homie-studio shop refund <order>`), and you confirm it with one tap.
+- The office's shop page: the last 30 days, every order with its Stripe page, disputes, and payouts, balance and tax as links to your own Stripe Dashboard, plus a CSV for your accountant with no names in it.
+- Referrals: a `?via=` link from another site (another studio, or homie.rocks on the same terms) is remembered on a new player's first visit; a kept sale owes that referrer the rate in `shop.json`. `homie-studio shop statements` signs each referrer's monthly statement with your studio's key; the referrer checks it against your manifest and invoices you. Nothing moves through Homie.
+- New D1 migration `0008_studio_shop.sql`: orders, entitlements, the age band, parent links, webhook events and referral books. No card, no address, no email.
+- The kids and fairness rules are built in, not settings. No shop on a kids server, and none at all in a studio whose `studio.json` says `"audience": "kids"`.
+- Spending is off on every account until one neutral question (the year you were born, no default) says adult; the answer is kept only as adult, teen or child. Under 13: nothing, ever. 13 to 17: a one-time link a parent opens on their own phone and pays in their own name.
+- Nothing random for money, no gems or coins, no countdown offers, and nothing that changes play on a beginner server (`"advantage": true` items are not sold or counted there). `shop check` and every build refuse a `shop.json` that breaks these. A monthly cap per player (US$50 at most).
+- A card dispute never locks or deletes an account: nothing changes while it is open, and a lost one takes back only that item.
+
+### Changed
+
+- Deleting a player account that owns things asks first, and keeps the orders without the player. A player's export includes their orders.
+- The directory manifest says whether the shop is open and its till, and how this studio takes referral statements (with the public half of its statement key). Never a key or a sale.
+
+### Upgrade notes
+
+- `homie-studio upgrade --apply`, then `npm run deploy` applies migration 0008. Nothing is sold until you add `shop.json` and connect a key.
+## [0.23.0] - 2026-10-03
+
+**Plugin 0.24.0** · [#33](https://github.com/homie-rocks/homie/pull/33) · [release-2026-10-03-studio-0.23.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.23.0)
+
+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)
+**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.
 

package/README.md

@@ -26,6 +26,7 @@ npx homie-studio publish                               # the homie.rocks directo
 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)
 ```
 
@@ -286,6 +287,64 @@ 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.
+
+## Selling things: the shop
+
+A studio sells items for its games (0.24.0) with **its own Stripe account**: the studio is the seller, money goes
+straight from players to its Stripe, and homie.rocks never sees, holds or moves it (Homie takes no cut; no shared
+currency; not a Connect platform). Real-money prices only, nothing random, the kids rules built in (no shop on a kids
+server, spending off until a neutral age question says adult, nothing for under-13s, 13-17 through a parent's own
+checkout, a monthly cap), and the television only shows a code to buy on a phone.
+
+```sh
+npx homie-studio shop init --supporter        # shop.json with a US$5 Supporter pack, and SELLING.md (the owner's plain words)
+npx homie-studio shop check                   # the kit's rules; every build checks them too
+npx homie-studio shop connect                 # a page on THIS computer: the owner pastes a restricted key and the webhook secret
+npx homie-studio shop                         # open (test or live) or what is missing
+npx homie-studio shop refund ord_…            # an ASK: the owner taps once (or Refund in /_studio/office/shop)
+```
+
+In a game: `createShop()` from `@homie-rocks/studio/shop` (`has`, `entitlements`, `on('change')`, `open`, `used`); a
+supporter's badge rides on their seat (`peer.badge`). Stripe Checkout (hosted), Stripe Tax on, or Stripe Managed
+Payments (Stripe as seller of record, 3.5% more) as one switch; a signed, idempotent webhook; refunds from the
+office; a dispute never touches the account; referral statements signed per referrer (homie.rocks is one more
+referrer). The guide: `shop/SHOP.md`.
+
 ## Setup status
 
 ```sh

package/bin/homie-studio.mjs

@@ -100,6 +100,10 @@
  *                                          tap in their own browser, from the link this prints)
  *   homie-studio office revoke            (every office key, play ticket and pending ask ends)
  *
+ *   homie-studio chat [--game <id>]       room chat (NETPLAY.md section 19): each game's rules, every live room's last
+ *                                          minutes, players' reports, the review's day; chat rules <game> [--server <id>]
+ *                                          --mode off|emoji|lines|text --who anyone|signed-in|members … | --reset;
+ *                                          chat remove <game> <room> <line id>; chat budget <neurons>; chat words
  *   homie-studio servers [--game <id>]    every server of every game (worker/servers.mjs): its policy, door, the AI's
  *                                          level, live rooms and AI, members, and builds that predate servers
  *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>]
@@ -117,6 +121,16 @@
  *                                          time AI guides may talk are ASKED for, like office kick; --budget is
  *                                          Workers AI neurons a day, or dollars a day for the owner's key)
  *   homie-studio agents brain key [--remove]   (the owner's AI key, typed into a page on this computer only)
+ *   homie-studio shop                     is the studio's shop selling (its own Stripe), and if not, what is missing
+ *   homie-studio shop init [--supporter] [--currency usd] [--price 500] [--managed]   shop.json and SELLING.md
+ *   homie-studio shop check               shop.json against the kit's rules (real money, nothing random, the kids rules)
+ *   homie-studio shop connect [--managed] [--live]   a page on THIS computer where the owner pastes the studio's
+ *                                         restricted Stripe key and webhook secret: straight to the Worker secrets,
+ *                                         never a chat or a file (test keys only unless --live)
+ *   homie-studio shop disconnect          both secrets gone: the shop closes
+ *   homie-studio shop orders              the latest orders (never a card or an email)
+ *   homie-studio shop refund <order> [--reason …] [--note "<why>"]   ASKS the owner (a one-tap link)
+ *   homie-studio shop statements [--period YYYY-MM] [--send]   signed referral statements this studio owes
  *   homie-studio agents sit <game> [--server <id>] [--pass hap_…] [--label Claude]
  *                                         (an AI guide's seat from this terminal: then lines of `do <goal> {args}`,
  *                                          `say <line> {args}`, `look`, `stand`)
@@ -219,8 +233,10 @@ import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { playersOwner, playersShow } from '../lib/players.mjs';
 import { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeMute, officeRevoke, officeShow } from '../lib/office.mjs';
+import { chatBudget, chatLines, chatRemove, chatRulesSet, chatShow, chatWords } from '../lib/chat-cli.mjs';
 import { agentsBrain, agentsBrainKey, agentsPass, agentsPasses, agentsRevoke, serversClose, serversLevel, serversLines, serversList, serversMember, serversNew, serversSet } from '../lib/servers.mjs';
 import { AgentSeat } from '../lib/agent-seat.mjs';
+import { shopCheck, shopConnect, shopDisconnect, shopInit, shopLines, shopOrders, shopRefund, shopStatements, shopStatus } from '../lib/shop.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
@@ -233,7 +249,7 @@ import { formatHandoff, handoff } from '../lib/handoff.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'];
+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', 'supporter', 'managed', 'live', 'send'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -426,6 +442,30 @@ function print(result) {
     case 'servers':
       lines.push(...serversLines(result));
       break;
+    case 'chat':
+      lines.push(...chatLines(result));
+      break;
+    case 'chat words':
+      for (const [k, v] of Object.entries(result.groups)) lines.push(`${k}: ${v.join(', ')}`);
+      lines.push(result.note);
+      break;
+    case 'chat remove':
+      lines.push(result.message);
+      break;
+    case 'shop':
+    case 'shop orders':
+    case 'shop check':
+    case 'shop init':
+    case 'shop statements':
+    case 'shop connect':
+    case 'shop disconnect':
+      lines.push(...shopLines(result));
+      break;
+    case 'chat rules':
+    case 'chat budget':
+    case 'shop refund':
+      lines.push(result.asked ? `Asked: ${result.what}` : result.message, ...(result.asked ? [`Owner's one-tap link (until the ask ends, 15 min): ${result.link}`, result.use] : []));
+      break;
     case 'servers new':
       lines.push(result.message, ...(result.notes ?? []).map((n) => `  ${n}`));
       break;
@@ -590,6 +630,8 @@ async function main() {
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
   if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install'), 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.
+  if (cmd === 'chat' && sub === 'words') return chatWords();
   if (cmd === 'demo') return demoGames();
   if (cmd === 'mcp') {
     // stdout carries MCP messages only from here on (lib/mcp.mjs); every word for a person goes to stderr.
@@ -706,6 +748,16 @@ async function main() {
     if (sub === 'close') return officeClose(root, positional[2], positional[3], { url, minutes: flags.get('minutes'), reopen: flags.has('reopen') });
     if (sub === 'revoke') return officeRevoke(root, { url });
   }
+  if (cmd === 'chat') {
+    // Room chat (0.23.0, NETPLAY.md section 19): rules, the room's last minutes, reports, the review's budget.
+    const url = flags.get('url');
+    if (sub === 'words') return chatWords();
+    if (!sub) return chatShow(root, { url, game: flags.get('game') });
+    if (sub === 'rules') return chatRulesSet(root, positional[2], flags, { url });
+    if (sub === 'remove') return chatRemove(root, positional[2], positional[3], positional[4], { url, all: flags.has('all') });
+    if (sub === 'budget') return chatBudget(root, positional[2], { url });
+    return { ok: false, command: 'chat', why: `unknown: chat ${sub} (rules, remove, budget, words)` };
+  }
   if (cmd === 'servers') {
     const url = flags.get('url');
     if (!sub || sub === 'list') return serversList(root, { url, game: flags.get('game') });
@@ -716,6 +768,18 @@ async function main() {
     if (sub === 'member') return serversMember(root, positional[2], positional[3], positional[4], { url, role: flags.get('role'), remove: flags.has('remove') });
     return { ok: false, command: 'servers', why: `unknown: servers ${sub} (list, new, set, close, level, member)` };
   }
+  if (cmd === 'shop') {
+    const url = flags.get('url');
+    if (!sub) return shopStatus(root, { url });
+    if (sub === 'init') return shopInit(root, { supporter: flags.has('supporter'), currency: flags.get('currency') ?? 'usd', price: flags.get('price') ?? 500, managed: flags.has('managed') });
+    if (sub === 'check') return shopCheck(root);
+    if (sub === 'connect') return shopConnect(root, { managed: flags.has('managed') ? true : null, live: flags.has('live'), log });
+    if (sub === 'disconnect') return shopDisconnect(root);
+    if (sub === 'orders') return shopOrders(root, { url });
+    if (sub === 'refund') return shopRefund(root, positional[2], { url, reason: flags.get('reason'), note: flags.get('note') });
+    if (sub === 'statements') return shopStatements(root, { url, period: flags.get('period'), send: flags.has('send') });
+    return { ok: false, command: 'shop', why: `unknown: shop ${sub} (init, check, connect, disconnect, orders, refund, statements)` };
+  }
   if (cmd === 'agents') {
     const url = flags.get('url');
     if (sub === 'pass') return agentsPass(root, positional[2], { url, label: flags.get('label'), server: flags.get('server'), hands: flags.get('hands'), role: flags.get('role'), days: flags.get('days') });
@@ -928,7 +992,9 @@ async function dev(root) {
   log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
   const ai = devConfig(root, flags.has('remote-ai'));
   if (ai.note) log(ai.note);
-  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port, ...ai.args], { cwd: workerDir(root), env, stdio: 'inherit' });
+  // --remote-ai: Wrangler's --local turns every remote binding off ("not supported"), so a dev with the real Workers AI
+  // (the guides' brains, room chat's review) runs without it; everything else stays local all the same.
+  const child = spawn(bin, ['dev', ...(flags.has('remote-ai') ? [] : ['--local']), '--ip', '127.0.0.1', '--port', port, ...ai.args], { cwd: workerDir(root), env, stdio: 'inherit' });
   mkdirSync(dirname(devFile(root)), { recursive: true });
   writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
   log(`Stop it with: npx --no-install homie-studio dev --stop   (this studio's dev server only)`);

package/chat/CHAT.md

@@ -0,0 +1,101 @@
+# Room chat
+
+Every studio game has room chat from `@homie-rocks/studio` 0.23.0: reactions that float up every
+screen in the room (the players', the watchers', the big screen's), the game's quick lines, and
+typed messages where the room's rules allow them. It feels like the Homie app's live rooms and
+homie.rocks's room chat because it is the same thing: the same five reactions in the same order,
+the same message shapes, the same float on a television.
+
+The wire, the rules and the helper are in [NETPLAY.md section 19](../netplay/NETPLAY.md). This
+page is the short version for a game's author, and why the review uses what it uses. For what a
+studio's owner is responsible for, read [OWNERS.md](OWNERS.md).
+
+## What a game gets with no work
+
+- **The Chat pill** on the play page, beside the room button: the room's last minutes, the
+  reactions, the quick lines, typing where allowed, Report on a line, and two switches ("Show my
+  messages over my character", "Show chat on this screen").
+- **The float:** every reaction rises up every screen in the room.
+- **The ticker:** a new line shows for a moment where the play page's status chip sits.
+- **The big screen** (`/<game>/tv`) shows the room's lines in a corner; the **watch page** has a
+  Chat button; **homie.rocks** shows the room's chat on its card when the studio allows it.
+
+## What a game can add
+
+**Its rules, in game.json** (the owner can change every one in the office):
+
+```json
+"chat": {
+  "mode": "text",
+  "who": "signed-in",
+  "react": "anyone",
+  "slow": 2,
+  "max": 140,
+  "emoji": { "gem": "💎" },
+  "lines": { "gg": "Good game!", "gem": "Grab that gem!", "help": "Help me!", "wait": "Wait for me!" }
+}
+```
+
+| Field | | Default |
+|---|---|---|
+| `mode` | `off`, `emoji` (reactions only), `lines` (and quick lines), `text` (and typing) | `text` |
+| `who` | who may type: `anyone`, `signed-in` (a player account with a passkey), `members` (of the room's server) | `signed-in` |
+| `react` | who may send reactions and quick lines (the same three) | `anyone` |
+| `slow`, `max` | seconds between one person's lines; a typed line's length | 2, 140 |
+| `links`, `swears` | `block` or `allow` (a link is never clickable; slurs, sexual words, threats and contact details are always held) | `block` |
+| `ai` | review typed messages with the studio's own Workers AI | `true` |
+| `bubbles`, `watchers`, `hub` | over the speaker's character; watchers may send; homie.rocks may show it | `true` |
+| `emoji`, `lines` | up to 3 more reactions; up to 12 quick lines (each passes the chat floor at build) | the five; 8 friendly lines |
+| `block`, `allow` | the studio's own words to hold (`word*` inside words) or to let through | none |
+
+`"chat": false` turns it off. A kids server, and every beginner server, keeps chat to emoji and
+quick lines whatever the game says. Where new lines show for a moment: game.json
+`"screen": { "chat": "bottom-right" }` (any corner, `top-center` or `bottom-center`), or `false`
+for only the pill's count.
+
+**Speech bubbles over characters**, with the port kit (the starters draw them):
+
+```ts
+import { createBubbles, paintBubbles, BUBBLE_FONT } from '@homie-rocks/studio/port';
+const bubbles = createBubbles({ measure: (t) => { ctx.font = BUBBLE_FONT; return ctx.measureText(t).width; } });
+net.on('say', (s) => bubbles.say(s.seat, s.text, { id: s.id, kind: s.kind }));
+net.on('unchat', (e) => e.ids.forEach((id) => bubbles.remove(id)));
+// each frame, after the names: the anchor is just over each speaking body's name
+paintBubbles(ctx, bubbles.place(speakers.map((s) => ({ key: s.seat, x: s.x, y: s.nameTop, self: s.mine }))));
+```
+
+A 3D game draws them the same way on its HUD canvas (Gem Rush 3D does), or reads `place()`'s boxes
+and draws its own. **The game's own chat UI** (a key that opens a wheel of quick lines, say):
+`net.sayLine('gg')`, `net.react('fire')`, `net.say(text)`; `net.on('chat')` for a log of your own.
+
+## Moderation: what it uses, and why
+
+The owner asked for "Cloudflare's new decisions API". That is **Clef**, Cloudflare's decision
+models, launched on Workers AI on 2026-10-01 (Birthday Week): `@cf/cloudflare/clef-flash` (9B) and
+`@cf/cloudflare/clef` (27B). They do not write text: you send a `state` (here, the message) and
+typed questions, and they return a probability for every allowed answer. Cloudflare names "trust
+and safety: score user submissions against your own policy rubric" as a use.
+
+| | Clef-flash (the default) | Clef | Llama Guard 3 8B | AI Gateway Guardrails |
+|---|---|---|---|---|
+| What | a decision model: our own question, a probability per answer | the same, larger | Meta's fixed safety categories (S1–S14) | Llama Guard run on prompts and responses of model calls through a gateway |
+| Price | $0.09 per M input tokens, no output charge: measured about 2.3 neurons a short message (the question is most of it) | $0.24 per M: about 6 neurons | $0.48 per M in, $0.03 out: up to about 10 neurons a message with its policy prompt | Llama Guard's price, plus the model call it guards |
+| Speed | about 40 ms median, 120 ms p95 (Cloudflare's numbers) | about 210 ms median | about 500 ms (Cloudflare's guardrails notes) | a model call plus about 500 ms |
+| Fits game chat | our categories: insults, hate, sexual, grooming, harm, spam | the same, more accurate | no insults or bullying category; most game-chat abuse reads as "safe" | not for arbitrary text: it guards model traffic |
+
+Clef-flash is the default because it is the cheapest per message by about five times, the fastest
+by far (a message waits for it before anyone sees it), and lets the studio ask exactly what game
+chat needs. Honest caveats: it is one day old as this ships, Cloudflare publishes no moderation
+accuracy numbers for it, and the message it reads is a player's, so a player can try to steer it
+(less of a risk than with a model that writes, since it only scores fixed answers). That is why
+**the word list always runs first and decides alone** whenever the review cannot (no binding, the
+day's budget used, an error, a slow answer). `HOMIE_CHAT_MODEL` switches to Clef or Llama Guard.
+Firewall for AI (now "AI Security for Apps") was ruled out: it reads HTTP requests at the zone, not
+messages inside a Durable Object, and its detections are an Enterprise add-on.
+
+**What it costs a studio.** Workers AI gives every account 10,000 neurons a day free, on the free
+Workers plan too, with no payment method. The review's day is 2,000 neurons by default (about
+850 typed messages, measured), leaving the AI guides their 8,000; `homie-studio chat budget <n>` changes it. On the free plan, past the allocation
+Workers AI refuses (the floor decides); on Workers Paid, past it is $0.011 per 1,000 neurons, which
+is why the review stops at its own budget. `homie-studio deploy` binds Workers AI when a game lets
+players type; `homie-studio dev --remote-ai` uses the real one (billed to the signed-in account).

package/chat/OWNERS.md

@@ -0,0 +1,78 @@
+# Room chat: a note for studio owners
+
+**This is not legal advice.** It says what Homie's tooling does and does not do, so you can decide
+what your studio needs. Laws about online chat and children's data differ by country and change;
+if your games are for children, or many children play them, talk to someone who advises on that
+where you and your players are.
+
+## Your studio, your rooms, your responsibility
+
+A Homie studio runs on **your own Cloudflare account**: your Worker, your Durable Objects, your D1
+database, your Workers AI. Homie (and homie.rocks) does not run your rooms, does not see your
+players' chat, and does not moderate it for you. You choose the rules, you hold the owner's
+controls, and you are the one responsible for what happens in your rooms, as the operator of the
+service. Homie gives you the tools to do that well; it cannot do it for you.
+
+What that means in practice:
+
+- **Choose rules that fit your players.** Each game sets its defaults in game.json, and you change
+  them per game and per server in the office (`/_studio/office`) or with `homie-studio chat rules`.
+  If your players are young, keep chat to emoji and quick lines, or put them on a kids server (a
+  beginner server with `kids` on): typing is then off whatever the game says.
+- **Watch your rooms, and act.** The office shows every live room's last minutes. Remove a message,
+  mute or kick its sender (their messages come down with them), and read what players report.
+- **Answer reports.** Players can report a message. You see it in the office and with
+  `homie-studio chat`; dismiss it once you have dealt with it.
+- **Say who your game is for, and what chat it has,** on your game's page and in your own terms or
+  rules, if you have them.
+
+## What the tooling does
+
+| | |
+|---|---|
+| **Who can say what** | By default: everyone can send emoji and the game's quick lines; only **signed-in players** (an account with a passkey on your studio) can type. You can open typing to guests, keep it to members of a server, keep a room to emoji or quick lines, or turn chat off. |
+| **Before anyone sees a typed message** | 1) a built-in word list and patterns (slurs, sexual words, telling someone to hurt themselves, asking a player's age or where they live, asking for pictures, moving a player to another app, email addresses and phone numbers, links, swears), plus your own words; 2) a review on your own Workers AI (Cloudflare's Clef decision model) that holds insults, hate, sexual content, grooming, threats and spam. The list always runs; the review runs within a daily budget. Neither is perfect: both are English-first, and a determined person can get past any filter. |
+| **Emoji and quick lines** | Fixed words you (the game) chose. They are never reviewed and reach every screen at once. |
+| **Children** | A kids server keeps chat to emoji and quick lines, gives players handles instead of names, and never asks anyone's age. Homie never asks for a player's age, birthday or address anywhere. |
+| **AI players** | An AI never types in room chat. |
+| **Slow mode and limits** | One line every 2 s by default (you choose), and message length, repeats and floods are capped. |
+
+## What is stored, and for how long
+
+| What | Where | How long |
+|---|---|---|
+| The chat itself (every message and reaction) | Only in the room's memory, on your Cloudflare account | The last 50 messages of the last 15 minutes, for someone who just opened the room. **Never written to storage.** An empty room forgets them a minute after the last person leaves. |
+| Who said what | The same memory, for your office's Mute and Kick | As long as the message is in that memory. Never an IP address. |
+| A **report** | Your D1 (`chat_reports`) | The one message reported (its words, its sender's name and account id if they had one, the room, when, the reason picked), for **30 days** or until you dismiss it. Never who reported it. |
+| Your chat rules and your words | Your D1 (`chat_rules`) | Until you change them. |
+| Counts (messages sent, held and why, reviews) | Your D1 (`stats_daily`) | Daily numbers, never a message and never a person. |
+| Player accounts | Your D1 (the players tables, `saves/SAVES.md`) | A random id, a display name, a passkey's public key. No email unless a player adds one; players can download and delete everything of theirs at `/account/`. |
+
+**The review** sends a typed message's words (and nothing about who wrote it) to Workers AI on your
+own Cloudflare account. Cloudflare says it does not store or train on Clef's requests or responses.
+**homie.rocks** stores nothing of your chat: when your rules allow it, a visitor's own browser opens
+your room's socket to show its chat on your room's card there. Turn that off with `hub` off.
+
+## Children's data, in plain words
+
+Laws in many places (for example COPPA in the United States, GDPR and the UK's Children's Code in
+Europe and the UK) set rules for online services that collect personal information from children,
+or that are directed at children. A typed message can contain personal information. What helps:
+
+- **Keep chat to emoji and quick lines for games aimed at children** (or a kids server). Then no
+  child types anything, and there is nothing personal in your chat to keep or lose.
+- **Typing for signed-in players only** (the default) means a person behind each typed line has an
+  account you can act on.
+- **Little is stored**, and only briefly (see above). Reports are the exception, kept 30 days.
+- **You can delete**: a report with Dismiss, a message with Remove, a player's whole account in
+  their own account page (or `players` in the office).
+
+Homie does not know your players' ages and does not verify them. Whether your game is "directed at
+children", and what that requires of you, is for you to decide with advice where you need it.
+
+## What the tooling cannot promise
+
+No filter catches everything, and a review model can be wrong both ways. The word list is English;
+other languages rely on the review. A studio past its daily review budget, or whose Worker has no
+Workers AI binding yet, relies on the word list alone until the next day (the office says so). Your
+attention, your rules and your owner's controls are the real safety net.

package/lib/build.mjs

@@ -9,9 +9,10 @@
  *                                          (games/<id>/assets/manifest.json; lib/asset-manifest.mjs servedAssets)
  *   site/dist/games/<id>/agents.json       the AI guides' vocabulary (games/<id>/agents.json, checked; NETPLAY.md
  *                                          section 18): the only goals and lines an AI in its rooms has
- *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site } from studio.json,
+ *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site, shop } from studio.json,
  *                                          game.json files, the music/ and videos/ manifests (media/MEDIA.md),
- *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
+ *                                          posts/*.md, the studio's site/ folder (site/SITE.md) and shop.json (checked
+ *                                          against the kit's rules: a shop that breaks them stops the build)
  *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
  *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
  *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
@@ -45,7 +46,10 @@ import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { licenseOf, remixRow } from '../worker/license.mjs';
 import { SERVER_LIMITS, serverOf } from '../worker/servers.mjs';
+import { chatProblems } from '../worker/chat.mjs';
 import { vocabularyOf } from '../worker/brain.mjs';
+import { shopForBuild } from './shop.mjs';
+import { audienceOf } from '../worker/shop-rules.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
@@ -299,6 +303,8 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
 export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
+  // The shop first (shop/SHOP.md): a shop.json that breaks the kit's rules stops the build before anything is built.
+  const shop = shopForBuild(root, { log });
   const dist = join(root, 'site', 'dist');
   const games = listGames(root).filter((g) => !only || g.id === only);
   if (only && !games.length) throw new Error(`no game "${only}" in games/`);
@@ -312,6 +318,9 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
     const { mode, warnings } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log });
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
+    // Room chat (NETPLAY.md section 19): game.json "chat", checked here (its quick lines pass the chat floor too).
+    const chatBad = chatProblems(g.chat);
+    if (chatBad.length) throw new Error(`games/${g.id}/game.json: ${chatBad.join('; ')}`);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id, { studio: studio.name ?? null, game: g.name ?? g.id, license: g.license }))}\n`);
     // Its assets' licences, and the address and SHA-256 of each one a remix may carry (`game remix` fetches them).
@@ -356,6 +365,9 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
       // game.json `"watch"` (NETPLAY.md section 16): watchers see any player's view (the default), only the whole room
       // ("overview": hidden hands or roles), or nothing (false: no watch door).
       ...(g.watch === 'overview' ? { watch: 'overview' } : g.watch === false || g.watch === 'off' ? { watch: 'off' } : {}),
+      // game.json `"chat"` (0.23.0, NETPLAY.md section 19): the room chat's defaults for this game (the owner's office
+      // overrides them), or false for none.
+      ...(g.chat === false ? { chat: false } : g.chat && typeof g.chat === 'object' ? { chat: g.chat } : {}),
       // Servers (0.16.0): the seeds game.json ships, the netplay revision its build speaks (the office warns when it
       // predates servers), and game.json "agents": { "vote": "game" | false } (the game draws its own vote card, or none).
       ...(seeds.length ? { servers: seeds } : {}),
@@ -395,6 +407,10 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
         : studio.homie?.directory === false || studio.homie?.directory === null ? null : String(studio.homie?.directory ?? 'https://homie.rocks'),
       // A copy of the public template that nobody has named yet shows the name typed in Cloudflare's form.
       ...(studio.template === true ? { template: true } : {}),
+      // studio.json "audience": "kids" (a studio made for children: no shop at all) or "teens"; and "referrals": false
+      // (this studio takes no referral statements as a referrer).
+      ...(audienceOf(studio) !== 'general' ? { audience: audienceOf(studio) } : {}),
+      ...(studio.referrals === false ? { referrals: false } : {}),
       build: buildInfo(root),
     },
     games: rows,
@@ -403,6 +419,8 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
     // Summaries only; each post's HTML is in _site/posts.json.
     posts: posts.map(({ html, record, ...p }) => p),
     site: { pages: site.pages, partials: site.partials, ...(site.css ? { css: site.css } : {}) },
+    // shop.json, checked (nothing secret is ever in it): the Worker sells from this and checks it again.
+    ...(shop ? { shop } : {}),
   };
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   return {