@homie-rocks/studio 0.22.0 → 0.24.0

package/netplay/NETPLAY.md

@@ -1,10 +1,26 @@
-# Homie netplay contract, v1 (revision 7)
+# Homie netplay contract, v1 (revision 8)
 
-Status: **v1, revision 7** (2026-10-02, `@homie-rocks/studio` 0.17.0). The wire version is
-`v: 1`. Everything revisions 2 to 7 added is either an optional field, a new message type,
+Status: **v1, revision 8** (2026-10-03, `@homie-rocks/studio` 0.23.0). The wire version is
+`v: 1`. Everything revisions 2 to 8 added is either an optional field, a new message type,
 a new refusal, or a change of pace inside the old caps, and both sides ignore types they do
 not know. A change to the contract bumps `v` and keeps v1 working.
 
+**What revision 8 added** (a game that knows none of it has room chat anyway: the play page's
+panel, the float and the big screen's corner need no game code):
+- **Room chat** (section 19): anyone in a room (a player, a watcher, the big screen's page, a
+  homie.rocks room page) says a line (`say`) or sends a reaction (`react`), on the game's socket
+  or the shell's watch socket. The relay checks the room's chat rules (`policy.chat`), runs the
+  floor on typed text, waits for the studio's own review (Cloudflare's Clef decision model on its
+  Workers AI) and fans the line out to every socket and every watching shell, in homie.rocks's
+  room-chat shapes (`line`, `react`). It keeps the last few minutes in memory and nothing else.
+- New frames `say` and `react` (client → relay), `line`, `react`, `lines`, `unline` and `held`
+  (relay → client; `slow` as homie.rocks says it); `policy.chat`; the owner's `unsay` control, and
+  `line` and `purge` on `mute` and `kick`.
+- The helper: `net.on('chat' | 'say' | 'unchat' | 'held')`, `net.say(text)`, `net.sayLine(id)`,
+  `net.react(kind)`, `net.chatRules`, `net.chatShown`; `NETPLAY_REVISION` 8 and the build mark
+  `homie-netplay-rev:8`. The port kit: `createBubbles` and `paintBubbles` (speech bubbles over
+  characters, beside `createLabels`).
+
 **What revision 7 added** (a game that knows none of it plays on every server; its AI guide
 seats are the game's own bots, silent):
 - **Agent hands and brains** (section 18): an AI with no game client of its own (hands
@@ -97,6 +113,9 @@ the notices and the banner):
 | `agents/agents.ts` | `useAgents`, the AI guides' host side and every browser's asks and lines (section 18), imported as `@homie-rocks/studio/agents`. |
 | `worker/brain.mjs` | The vocabulary, prompts, `parseDecision`, the scripted floor and the providers (section 18). |
 | `starters/ember-vale/` | Ember Vale: saves (a hero that lasts), and the AI guides' reference (`agents.json`, section 18). |
+| `worker/chat.mjs` | Room chat's rules, the floor every typed message passes, and the studio's review on Clef (section 19). |
+| `worker/chat-page.mjs` | The chat panel, the float and the big screen's corner: one component for the play, watch and TV pages. |
+| `chat/CHAT.md`, `chat/OWNERS.md` | Room chat for game makers, and a plain note for studio owners on chat and children's data. |
 
 ---
 
@@ -330,7 +349,9 @@ A socket that is kicked for silence is closed with code 4000, and the helper rec
 Record types:
 
 ```ts
-Peer        = { id, seat: number|null, name, colour, device, want, role, muted?: true, watch?: true, agent?: AgentFacts }
+Peer        = { id, seat: number|null, name, colour, device, want, role, muted?: true, watch?: true, agent?: AgentFacts, badge?: string }
+              (badge: a word the studio's Worker verified from what the player's account owns, such as a supporter's
+              "Supporter"; a hello can never set it; never on a kids server, never for an AI. @homie-rocks/studio 0.24.0)
 RoundInfo   = { n, phase: 'live'|'over', startedAt, endsAt, results?: RoundResult[] }   // server ms
 RoundResult = { slot, seat: number|null, name, score, bot, place, agent?: true }
 Slot        = { slot, seat: number|null, name, bot, agent?: { seat: number|null, role, hands } }
@@ -1154,3 +1175,172 @@ A beginner server's chat is quick lines only; on a kids server names are handles
 text ever reaches a brain. The owner's controls work on AI, and "AI talk off" (agents_brain
 `script`) silences every AI at once. Quiet AI hides every AI line on a player's own screen.
 
+
+---
+
+## 19. Room chat (revision 8)
+
+Every room has a chat: reactions that float up every screen in it, the game's quick lines,
+and typed messages where the room's rules allow them. 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
+(fire 🔥, clap 👏, laugh 😂, heart ❤️, wow 🤯), the same frames (`line` and `react`), the same
+slow word ("One line at a time."), the same float on the big screen.
+
+**Where it runs.** In the room's own Table on the studio's Worker. A line goes up on the game's
+socket (`net.say`) or on the shell's watch socket (the play page's panel, the watch page, the big
+screen's page, a homie.rocks room page); the relay checks it, the floor reads typed text, the
+studio's review reads what the floor let through, and the relay fans it out to every socket and
+every watching shell. homie.rocks runs nothing: its room page opens the room's own watch socket.
+
+### The rules: `policy.chat`
+
+| Field | Values (default) | |
+|---|---|---|
+| `mode` | `off`, `emoji`, `lines`, `text` (`text`) | What may be sent: each mode allows what the one before it does. |
+| `who` | `anyone`, `signed-in`, `members` (`signed-in`) | Who may type. Signed in: a player account with a passkey (saves/SAVES.md), never a guest. Members: players who belong to the room's server (on Quick play: any signed-in player). |
+| `react` | the same (`anyone`) | Who may send a reaction or a quick line. |
+| `slow` | 0–120 s (2) | Slow mode: between one person's lines (reactions have their own bucket). |
+| `max` | 20–280 characters (140) | A typed line. |
+| `links` | `block`, `allow` (`block`) | A link is never clickable either way. |
+| `swears` | `block`, `allow` (`block`) | Slurs, sexual words, threats and contact details are held whatever this says. |
+| `ai` | `true`, `false` (`true`) | The studio's review of typed text. |
+| `bubbles`, `watchers`, `hub` | `true` | A line may show over its sender's character; watchers may send (not only read); homie.rocks's page for the room may show it. |
+| `emoji` | the five, then up to 3 of the game's own | `{ k, e }`: a kind and its glyph. |
+| `lines` | 8 default lines, or up to 12 of the game's own | `{ id, text }`: the game's words; each passes the floor at build. |
+| `capped` | `kids`, `server-lines`, `server-off` | Why the mode is lower than the game asks. |
+
+The rules come in layers: game.json `"chat"` (the game's defaults, or `false` for none), then
+the owner's for the game, then the owner's for a server (worker/chat-store.mjs, D1 `chat_rules`),
+then the server's own caps: **a kids server, or a server whose speech is quick lines (every
+beginner server), keeps chat to emoji and quick lines; speech `off` turns it off.** The Worker
+composes them for every socket and the room applies the newest; an owner's change reaches every
+live room at once (a signed `policy` control). The studio's own word list (`block`, `allow`)
+stays in the room; clients get the rest in `welcome.policy.chat` and every `policy` frame.
+
+```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!" }
+}
+```
+
+### Frames
+
+| `t` | Direction | Fields | |
+|---|---|---|---|
+| `say` | up | `text` or `say` (a quick line's id), `n?`, `bubble?: false` | A typed line or a quick line. `n`: the sender's own id for it (1–16 of `A-Za-z0-9_-`), back on its own copy only. `bubble: false`: not over my character. |
+| `react` | up | `kind`, `n?`, `bubble?: false` | One of the room's reactions. |
+| `line` | down, everyone | `id`, `at`, `name`, `seat`, `colour`, `by`, `text`, `say?`, `bubble?`, `acct?`, `owner?`, `n?` | `by`: `player`, `watcher`, `hub` (a page of another site), `studio` (an announcement, which is a line too). |
+| `react` | down, everyone | `id`, `at`, `name`, `seat`, `colour`, `by`, `react`, `glyph`, `bubble?`, `n?` | |
+| `lines` | down, a watching shell as it opens | `lines` | The window: the last 50 lines of the last 15 minutes. Never to a page the room holds out. |
+| `unline` | down, everyone | `ids` | The owner took them down: hide them, and their bubbles. |
+| `held` / `slow` | down, the sender | `why`, `message`, `n?`, `until?` | Not sent. `why`: `off`, `emoji`, `lines`, `sign-in`, `sign-in-react`, `members`, `members-react`, `watchers`, `hub`, `muted`, `slow`, `repeat`, `words`, `harm`, `contact`, `link`, `swears`, `ai`, `busy`, `unknown`, `empty`, `ai_seat`. |
+
+A line's sender is the socket's own client, or for a watch socket the client of the same browser
+(its room key) or account in the room: its seat, name and colour. A page with no client in the
+room (homie.rocks, a watch page before its game connects) is a watcher with a handle. **An AI never
+types in room chat** (section 18: it says only its game's lines, as `ev`). The relay's caps: a
+`say` frame at most 1.5 KB and 4 a second, a `react` 256 B and 10 a second; token buckets per
+sender (lines: 4 at once, then one every 2 s, as homie.rocks; reactions: 6, then one every
+0.4 s), 30 at once per address (then one every 0.15 s), and at most 40 reactions a second fanned
+out per room (the float draws six a second anyway); the same words from one person within 30 s
+are a `repeat`.
+
+### The floor and the review
+
+**The floor** (worker/chat.mjs `floor`) always runs, needs nothing, and costs nothing: a short
+built-in English list (slurs, sexual words, telling someone to hurt themselves, moving a player to
+another app or asking for pictures; worker/chat-words.mjs, `homie-studio chat words` prints it),
+emails and phone numbers, links, swears, and the studio's own words (`block`, `word*` inside words;
+`allow` lets one through). It reads through spacing ("f u c k"), repeats, leet and look-alike
+letters, and never across two words ("this hit").
+
+**The review** (`reviewChat`) reads what the floor let through, on the studio's own Workers AI:
+Cloudflare's **Clef** decision model (`@cf/cloudflare/clef-flash`, launched 2026-10-01; var
+`HOMIE_CHAT_MODEL` changes it to `@cf/cloudflare/clef` or `@cf/meta/llama-guard-3-8b`). One
+typed question: is this message `ok`, an `insult`, `hate`, `sexual`, `grooming` (asks a player's
+age, where they live, for photos or to move apps), `harm` or `spam`? Clef answers with a
+probability for each; the message is held when `ok` is under 0.5, and the likeliest other answer
+is kept as why (in the office's counts, never shown to anyone as a label). The message waits for
+the answer (Clef-flash: about 40 ms median by Cloudflare's numbers, plus the round trip) and goes
+out only after it. **Emoji and quick lines are never reviewed** (they are the studio's own words)
+and reach every screen at once.
+
+| Review | |
+|---|---|
+| Budget | A day, for the whole studio (meta `chat_budget`): 2,000 neurons by default. With the AI guides' 8,000 that is the 10,000 Workers AI gives an account free a day. A short message measured about 2.3 neurons (clef-flash: $0.09 per million input tokens, no output charge; the question and its answers are most of the input), so about 850 reviewed messages a day. Counted in `stats_daily` (`chat-reviews`, `chat-neurons`). |
+| No review | No `AI` binding (`homie-studio dev` without `--remote-ai`), the day's budget used, the model failing or slower than 1.5 s, more than 8 messages waiting: the floor alone decides, the message goes out, and the office counts it. |
+| The owner | The studio's owner is never reviewed or held by slow mode (their lines are marked `owner`). |
+
+### The owner's tools
+
+`unsay { id | ids | all }` takes lines down on every screen. `mute` and `kick` take `line` (a
+chat line's id) instead of a seat: the room holds that line's sender by token, browser and
+account, a watcher with no seat too; `purge: true` takes their lines down with it. The office
+(`/_studio/office`, `/_studio/api/chat…`) shows each live room's last minutes with Remove, Mute
+and Kick, each game's rules (and each server's) with what set them, the reports, and the review's
+day; the owner in their own game has Remove, Mute and Kick on every line in the chat sheet. An
+office key (the owner's AI) changes rules that tighten chat at once and only ASKS for a change
+that opens it up (a wider mode or audience, less slow, links or swears allowed, the review off,
+new lines or emoji).
+
+**Reports.** A player taps a line, then Report, and picks a reason (mean, hate, sexual, unsafe,
+spam, other). The Worker files **the room's own copy** of that one line (its words, its sender's
+room name and account id if signed in, the room, when) for 30 days or until the owner dismisses
+it, once per line; never who reported it, never an address. 8 reports per browser per 10 minutes.
+
+### What the game does (the helper)
+
+```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 }));     // over the speaker's character
+net.on('unchat', (e) => e.ids.forEach((id) => bubbles.remove(id)));                // the studio took it down
+// each frame, after the names: anchors just over each speaking body's name label
+paintBubbles(ctx, bubbles.place(seats.map((s) => ({ key: s.seat, x: s.labelX, y: s.labelTop, self: s.mine }))));
+```
+
+| Call | Meaning |
+|---|---|
+| `net.on('chat', m)` | Every line and reaction: `{ id, at, kind: 'text'\|'line'\|'react'\|'studio', name, seat, colour, by, text?, say?, react?, glyph?, bubble?, acct?, owner?, mine? }`. A game with its own chat log draws these. |
+| `net.on('say', s)` | One to draw over a character: `{ id, seat, name, text, glyph?, kind }`. Only when its sender wants it there (`bubble`), the room's `bubbles` rule allows it, the sender holds a seat, and this browser shows chat. |
+| `net.on('unchat', { ids })`, `net.on('held', h)` | Lines taken down; a line of mine not sent (`why`, `message`). |
+| `net.say(text)`, `net.sayLine(id)`, `net.react(kind)` | The game's own chat UI (a keyboard key, a wheel of quick lines): checked by the relay like the panel's. False when not sent. |
+| `net.chatRules`, `net.chatShown` | The room's rules; whether this browser shows chat. |
+| `createBubbles({ measure, lineHeight?, maxWidth?, maxLines?, ms?, avoid?, screen? })` | `say(key, text, { id, kind })`, `remove(id)`, `clear(key?)`, `place(anchors, dt)` → `BubbleOut[]` (the player's own first, none covering another, wrapped to 3 lines, popping in and fading out), `boxes()` (for `createLabels`' `avoid`), `size`. |
+| `paintBubbles(ctx, list, { font, paper, ink, edge, radius })` | Draws them on a 2D canvas; a reaction alone is a bigger glyph. |
+
+Gem Rush, Ember Vale and Gem Rush 3D draw bubbles over the speaker's name; Ember Vale keeps them
+clear of its guides' own bubbles. A game that draws none still has the panel, the float and the
+ticker.
+
+### What the page does (worker/chat-page.mjs)
+
+- **Play:** a Chat pill in the room button's band (game.json `screen.share` already keeps that
+  corner clear of the game's HUD), with a count of unread lines; its sheet: the room's last
+  minutes, a row of reactions (2.5 rem circles that pop), the quick lines, typing where the rules
+  allow it (and why not where they do not: "Sign in to type here. Emoji are open to everyone."),
+  Report on a line, and two switches kept in this browser: **Show my messages over my character**
+  and **Show chat on this screen** (off: no ticker, no float, no bubbles in this game). New lines
+  show for a moment where the status chip sits (game.json `"screen": { "chat": "bottom-right" }`
+  moves them; `false` keeps only the pill's count).
+- **Float:** every reaction rises up every screen in the room, as on the television: at most six
+  a second and eighteen at once, 2.4 s each with a little sway. The sender's own floats at once.
+- **TV** (`/<game>/tv`): the room's lines in the corner the QR card does not use, no typing.
+- **Watch:** a Chat button in the band; its panel over the stage (a bottom sheet on a phone).
+
+**Privacy.** Nothing a person says is stored: the room keeps the last 50 lines of the last 15
+minutes in its memory (never in Durable Object storage), and an empty room forgets them with
+everything else a minute after its last person leaves. The counts (lines, reactions, held by why,
+reviews and neurons) are daily numbers in the studio's own D1, never a message or a sender. A
+report keeps one message for 30 days. The review sends the message's words (and nothing about who
+said it) to the studio's own Workers AI; Cloudflare says it does not keep or train on them.
+
+**Cost.** A line or a reaction is one incoming message on the room's object (billed 20:1); the
+fan-out is outgoing (free). A homie.rocks page or a watcher is one more socket. The review is
+about 2.3 neurons a typed line, inside the free allocation by default.
+
+**Old games and old relays.** A game built before revision 8 has the panel, the float, the ticker
+and the TV corner; it draws no bubbles and its own UI cannot send. A revision-8 helper on an older
+relay never hears a `line` and has `chatRules` null.

package/netplay/netplay.ts

@@ -44,6 +44,12 @@
  *     sends its seat and moves through `agent:do` goals; it speaks only the
  *     game's `agents.json` lines (`say:<lineId>`). `@homie-rocks/studio/agents`
  *     (`useAgents`) is the host's side of it; this file only carries the frames.
+ *   - Room chat (revision 8, NETPLAY.md section 19): everyone's lines and
+ *     reactions (`on('chat')`), the ones to draw over a character
+ *     (`on('say')`: a speech bubble, `createBubbles` in the port kit draws
+ *     them), messages taken down (`on('unchat')`), and the game's own chat UI
+ *     (`net.say(text)`, `net.sayLine(id)`, `net.react(kind)`); the room's rules
+ *     are `net.chatRules`. The play page's chat panel needs none of it.
  *
  * WHAT IT DOES NOT DO: rendering, physics, input devices, bots. `Roster` below
  * is the bot-yield bookkeeping a host needs; the bots themselves are the game's.
@@ -52,9 +58,9 @@
 
 export const NETPLAY_VERSION = 1;
 /** The contract revision this helper speaks (NETPLAY.md): its hello says so (`rev`), and so does every build of it. */
-export const NETPLAY_REVISION = 7;
+export const NETPLAY_REVISION = 8;
 /** In every bundle that includes the helper: `homie-studio build` reads it to tell the office which revision a build speaks. */
-export const NETPLAY_MARK = 'homie-netplay-rev:7';
+export const NETPLAY_MARK = 'homie-netplay-rev:8';
 
 export type Role = 'host' | 'replica' | 'screen';
 export type Device = 'phone' | 'desk' | 'tv';
@@ -100,8 +106,70 @@ export interface NetConfig {
   agent?: { hands: 'self' | 'host'; role: AgentRole };
   /** Revision 6: the play page's "Quiet AI" is on: AI speech is not shown on this browser. */
   hush?: boolean;
+  /** Revision 8: this browser hides room chat (the play page's "Show chat" is off): no `say` bubbles either. */
+  chatOff?: boolean;
+  /** Revision 8: this player does not want their own messages over their character (the play page's toggle). */
+  bubbleOff?: boolean;
 }
 
+/* ------------------------------------------------- room chat (revision 8, section 19) */
+
+export type ChatMode = 'off' | 'emoji' | 'lines' | 'text';
+export type ChatWho = 'anyone' | 'signed-in' | 'members';
+/** A room's chat rules (the policy's `chat`): what may be sent, who may send it, and the room's reactions and lines. */
+export interface ChatRules {
+  mode: ChatMode;
+  /** Who may type (`text`), and who may send a reaction or a quick line. */
+  who: ChatWho;
+  react: ChatWho;
+  /** Slow mode: seconds between one person's messages (0: off). */
+  slow: number;
+  /** A typed message's length. */
+  max: number;
+  links: 'block' | 'allow';
+  swears: 'block' | 'allow';
+  /** The studio's Workers AI reviews typed messages (the word list always runs). */
+  ai: boolean;
+  /** A message may show over its sender's character. */
+  bubbles: boolean;
+  watchers: boolean;
+  hub: boolean;
+  /** The room's reactions: homie.rocks's five (fire, clap, laugh, heart, wow) and up to three of the game's own. */
+  emoji: { k: string; e: string }[];
+  /** The room's quick lines: the game's own words (game.json "chat": { "lines" }). */
+  lines: { id: string; text: string }[];
+  kids?: boolean;
+  /** Why the mode is lower than the game asks: `kids`, `server-lines` or `server-off`. */
+  capped?: string;
+}
+/**
+ * One message in the room (`on('chat')`): a typed line, a quick line (`say`: its id), a reaction (`react`, `glyph`), or
+ * the studio's own line (an announcement). `seat` is the sender's (null: a watcher, a homie.rocks page, the studio);
+ * `bubble`: the sender wants it over their character. Names and text are data: draw them as text, never as markup.
+ */
+export interface ChatLine {
+  id: string;
+  at: number;
+  kind: 'text' | 'line' | 'react' | 'studio';
+  name: string;
+  seat: number | null;
+  colour: number | null;
+  by: 'player' | 'watcher' | 'hub' | 'studio';
+  text?: string;
+  say?: string;
+  react?: string;
+  glyph?: string;
+  bubble?: boolean;
+  acct?: boolean;
+  owner?: boolean;
+  /** This browser sent it. */
+  mine?: boolean;
+}
+/** A message to draw over a character (`on('say')`): the seat's, with its words or its emoji. */
+export interface SayBubble { id: string; seat: number; name: string; text: string; glyph?: string; kind: 'text' | 'line' | 'react' }
+/** A message that was not sent (to this browser only): `why` is a word (slow, sign-in, words, link, ai…), `message` says it. */
+export interface ChatHeld { why: string; message: string; until?: number }
+
 /* ------------------------------------------------- servers and agent seats (revision 6, section 17) */
 
 export type PolicyKind = 'open' | 'humans-only' | 'hybrid' | 'beginner';
@@ -130,6 +198,8 @@ export interface Policy {
   brain: string;
   skill: Skill;
   by?: 'vote' | 'owner';
+  /** Revision 8: the room's chat rules (section 19). */
+  chat?: ChatRules;
 }
 /** What a room says about an AI in a seat (`peer.agent`). */
 export interface AgentFacts { pass: string; role: AgentRole; hands: 'self' | 'host'; by: 'studio' | 'guest' | 'service' }
@@ -199,6 +269,12 @@ export interface Peer {
   watch?: boolean;
   /** Revision 6: an AI in a seat (always named "<label> · AI"). */
   agent?: AgentFacts;
+  /**
+   * A badge the player's account owns on this studio (a supporter's, from the shop: @homie-rocks/studio 0.24.0), as
+   * a word to show beside their name. Only the studio's Worker sets it, from what the account bought; a hello cannot.
+   * Never on a kids server, never for an AI.
+   */
+  badge?: string;
 }
 
 /** One seat's entry in the body-control table: [seat, rs, own (1|0), ack]. */
@@ -411,6 +487,14 @@ export interface NetHandlers<S, A, C> {
   policy: (p: Policy) => void;
   /** Revision 6: the party's vote on the dial opened, moved or closed. */
   vote: (v: VoteState) => void;
+  /** Revision 8: a line or a reaction in the room's chat (anyone's, the studio's, mine). */
+  chat: (m: ChatLine) => void;
+  /** Revision 8: a message to draw over a seat's character (its sender wants it there and this browser shows chat). */
+  say: (s: SayBubble) => void;
+  /** Revision 8: the studio took messages down: hide them (and their bubbles). */
+  unchat: (e: { ids: string[] }) => void;
+  /** Revision 8: a message of mine was not sent (slow mode, sign in to type, a word, the studio's filter…). */
+  held: (h: ChatHeld) => void;
 }
 
 export interface Netplay<S = unknown, A = unknown, C = unknown> {
@@ -503,6 +587,17 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   /** Resolves with the first role (welcome, or offline fallback). */
   readonly ready: Promise<RoleChange<S, C>>;
   on<K extends keyof NetHandlers<S, A, C>>(kind: K, fn: NetHandlers<S, A, C>[K]): () => void;
+  /**
+   * ROOM CHAT (revision 8, NETPLAY.md section 19). `chatRules`: the room's rules (null before the relay says them).
+   * `say(text)` types a line, `sayLine(id)` sends one of the room's quick lines, `react(kind)` an emoji (fire, clap,
+   * laugh, heart, wow, or the game's own): checked by the relay like the play page's own panel; false when not sent
+   * (offline, or the room's rules say no). `chatShown`: this browser shows chat (its player can turn it off).
+   */
+  readonly chatRules: ChatRules | null;
+  say(text: string, opts?: { bubble?: boolean }): boolean;
+  sayLine(id: string, opts?: { bubble?: boolean }): boolean;
+  react(kind: string, opts?: { bubble?: boolean }): boolean;
+  readonly chatShown: boolean;
   /** Server time in ms (relay clock). Offline: Date.now(). */
   now(): number;
   /** Host: true when the next `snapshot()` would be sent. Build the state only then. */
@@ -890,7 +985,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   const handlers: { [K in keyof NetHandlers<S, A, C>]: Set<NetHandlers<S, A, C>[K]> } = {
     role: new Set(), join: new Set(), leave: new Set(), input: new Set(), event: new Set(),
     snapshot: new Set(), control: new Set(), state: new Set(), round: new Set(), roster: new Set(), status: new Set(), announce: new Set(), mute: new Set(), view: new Set(),
-    policy: new Set(), vote: new Set(),
+    policy: new Set(), vote: new Set(), chat: new Set(), say: new Set(), unchat: new Set(), held: new Set(),
   };
   const emit = <K extends keyof NetHandlers<S, A, C>>(kind: K, arg: Parameters<NetHandlers<S, A, C>[K]>[0]): void => {
     for (const fn of [...handlers[kind]]) {
@@ -1018,6 +1113,10 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   const asAgent = cfg?.agent && typeof cfg.agent === 'object' ? { hands: cfg.agent.hands === 'host' ? 'host' : 'self', role: cfg.agent.role ?? 'party' } : null;
   let hushed = cfg?.hush === true;
   let aloneUntil = 0;
+  // room chat (section 19): this browser shows chat (the play page's "Show chat"), and wants its own lines over its character.
+  let chatShown = cfg?.chatOff !== true;
+  let bubbleMine = cfg?.bubbleOff !== true;
+  let chatSeq = 0;
 
   const wall = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());
   const now = (): number => (offline ? Date.now() : Date.now() + offset);
@@ -1255,6 +1354,27 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         if (voteState) { emit('vote', voteState); post?.({ what: 'vote', vote: voteState }); }
         return;
       }
+      case 'line':
+      case 'react': {
+        // Room chat (section 19): a line or a reaction, anyone's. One the sender wants over their character is a `say`.
+        const line = readChatLine(m);
+        if (!line) return;
+        emit('chat', line);
+        if (line.bubble && line.seat !== null && chatShown && line.kind !== 'studio') {
+          emit('say', { id: line.id, seat: line.seat, name: line.name, text: line.kind === 'react' ? (line.glyph ?? '') : (line.text ?? ''), ...(line.glyph ? { glyph: line.glyph } : {}), kind: line.kind === 'react' ? 'react' : line.kind === 'line' ? 'line' : 'text' });
+        }
+        return;
+      }
+      case 'unline': {
+        const ids = Array.isArray(m['ids']) ? (m['ids'] as unknown[]).filter((x): x is string => typeof x === 'string').slice(0, 64) : [];
+        if (ids.length) emit('unchat', { ids });
+        return;
+      }
+      case 'held':
+      case 'slow': {
+        emit('held', { why: String(m['why'] ?? (m['t'] === 'slow' ? 'slow' : 'held')), message: String(m['message'] ?? ''), ...(typeof m['until'] === 'number' ? { until: m['until'] } : {}) });
+        return;
+      }
       case 'state': if (typeof m['k'] === 'string') applyState(m['k'], m['d']); return;
       case 'pong': return onPong(m);
       case 'announce': {
@@ -1784,6 +1904,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       if (ev.source !== g.parent || !ev.data || typeof ev.data !== 'object') return;
       const d = ev.data as { t?: unknown; on?: unknown };
       if (d.t === 'homie-hush') hushed = d.on === true;
+      // Room chat (section 19): the play page's "Show chat" and "Show my messages over my character".
+      if (d.t === 'homie-chat') {
+        const c = d as { show?: unknown; bubble?: unknown };
+        if (typeof c.show === 'boolean') chatShown = c.show;
+        if (typeof c.bubble === 'boolean') bubbleMine = c.bubble;
+      }
     });
   } catch { /* not a browser */ }
 
@@ -1813,6 +1939,24 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       skill: { ...skillPreset(Number(sk.level) || 3, kids), ...sk },
     } as Policy;
   }
+  function readChatLine(m: Record<string, unknown>): ChatLine | null {
+    if (typeof m['id'] !== 'string') return null;
+    const react = m['t'] === 'react';
+    const by = m['by'] === 'watcher' || m['by'] === 'hub' || m['by'] === 'studio' ? m['by'] : 'player';
+    return {
+      id: m['id'], at: Number(m['at']) || now(), kind: react ? 'react' : by === 'studio' ? 'studio' : typeof m['say'] === 'string' ? 'line' : 'text',
+      name: String(m['name'] ?? '').slice(0, 40), seat: typeof m['seat'] === 'number' ? m['seat'] : null, colour: typeof m['colour'] === 'number' ? m['colour'] : null, by,
+      ...(typeof m['text'] === 'string' ? { text: m['text'] } : {}), ...(typeof m['say'] === 'string' ? { say: m['say'] } : {}),
+      ...(react ? { react: String(m['react'] ?? ''), glyph: String(m['glyph'] ?? '') } : {}),
+      ...(m['bubble'] === true ? { bubble: true } : {}), ...(m['acct'] === true ? { acct: true } : {}), ...(m['owner'] === true ? { owner: true } : {}),
+      ...(typeof m['n'] === 'string' ? { mine: true } : {}),
+    };
+  }
+  function chatSend(msg: Record<string, unknown>, bubble?: boolean): boolean {
+    if (offline || asAgent) return false;
+    chatSeq += 1;
+    return raw({ ...msg, n: `g${chatSeq}`, ...((bubble ?? bubbleMine) ? {} : { bubble: false }) });
+  }
   function readVote(m: Record<string, unknown>): VoteState | null {
     if (!Array.isArray(m['options']) || typeof m['id'] !== 'string') return null;
     return {
@@ -1894,6 +2038,15 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     },
     get hushed() { return hushed; },
     set hushed(on: boolean) { hushed = Boolean(on); },
+    get chatRules() { return policy.chat ?? null; },
+    get chatShown() { return chatShown; },
+    say(text: string, o?: { bubble?: boolean }): boolean {
+      const t = String(text ?? '').trim();
+      if (!t) return false;
+      return chatSend({ t: 'say', text: t.slice(0, 280) }, o?.bubble);
+    },
+    sayLine(id: string, o?: { bubble?: boolean }): boolean { return chatSend({ t: 'say', say: String(id ?? '').slice(0, 16) }, o?.bubble); },
+    react(kind: string, o?: { bubble?: boolean }): boolean { return chatSend({ t: 'react', kind: String(kind ?? '').slice(0, 16) }, o?.bubble); },
     get asAgent() { return Boolean(asAgent); },
     ready,
     on(kind, fn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,6 +30,10 @@
       "types": "./saves/saves.ts",
       "default": "./saves/saves.ts"
     },
+    "./shop": {
+      "types": "./shop/shop.ts",
+      "default": "./shop/shop.ts"
+    },
     "./agents": {
       "types": "./agents/agents.ts",
       "default": "./agents/agents.ts"
@@ -53,12 +57,14 @@
     "worker/",
     "mcp/",
     "saves/",
+    "shop/",
     "agents/",
     "lab/",
     "assets/",
     "starters/",
     "media/",
     "site/",
+    "chat/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

package/port/index.ts

@@ -8,9 +8,9 @@
  *                keys on computers, a floating stick and small buttons on phones
  *   groundBasis / screenToGround / PlayerYaw
  *                the camera rules: input on screen axes, a yaw only the player turns
- *   fitView / easeView / toScreen / createLabels
+ *   fitView / easeView / toScreen / createLabels / createBubbles
  *                a flat world on every screen (the whole of it, or filling an upright phone and following the
- *                player) and name labels that never pile up
+ *                player), name labels that never pile up, and speech bubbles over characters (room chat)
  *   exposePort   what `homie-studio port check` reads (owner tests)
  *   createHud    a minimal clock / scores / results overlay
  *   BotBrain, seek, nearest, rubberBand
@@ -31,6 +31,7 @@ export { createTouchControls, type TouchControls, type TouchOptions, type TouchB
 export { createControls, type Controls, type ControlsOptions } from './controls';
 export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLike } from './camera';
 export { fitView, easeView, toScreen, createLabels, type Fit, type FitOptions, type LabelIn, type LabelOut, type LabelOptions, type LabelBox } from './view';
+export { createBubbles, paintBubbles, wrapText, BUBBLE_FONT, type Bubbles, type BubbleOptions, type BubbleIn, type BubbleOut, type BubbleStyle } from './view';
 export { exposePort, type PortProbeOptions, type View } from './probe';
 export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
 export { createHud, type HudOptions } from './hud';