@homie-rocks/studio 0.22.0 → 0.24.0

package/port/view.ts

@@ -11,6 +11,10 @@
  *                         label is placed first and nothing covers it; a moved label keeps its new spot while it is
  *                         free (no flicker), and labels fade in and out rather than pop.
  *
+ *   createBubbles()       speech bubbles over characters (room chat, NETPLAY.md section 19): what a player said, over
+ *                         their body for a few seconds, the player's own placed first, never covering another bubble;
+ *                         `paintBubbles` draws them on a canvas, and their boxes keep the name labels off them.
+ *
  * Everything is in CSS pixels (screen) and world units; the game draws. See the starters (gem-rush, ember-vale).
  */
 
@@ -211,3 +215,237 @@ export function createLabels(opts: LabelOptions = {}): { place(labels: LabelIn[]
     },
   };
 }
+
+/* ------------------------------------------------------------------ speech bubbles (room chat, NETPLAY.md section 19) */
+
+export interface BubbleOptions {
+  /** A line's width as drawn, CSS px: `(t) => ctx.measureText(t).width` with the bubble's font set (paintBubbles uses BUBBLE_FONT). */
+  measure: (text: string) => number;
+  /** A text line's height, CSS px (default 17). */
+  lineHeight?: number;
+  /** The widest a bubble's text gets before it wraps, CSS px (default 190). */
+  maxWidth?: number;
+  /** Lines at most; the rest is cut with "…" (default 3). */
+  maxLines?: number;
+  /** How long a message stays, ms: default 4 s and 50 ms a character (at most 9 s); an emoji 2.6 s. */
+  ms?: (b: { text: string; kind: 'text' | 'line' | 'react' }) => number;
+  /** Space inside the bubble, CSS px (default x 8, y 5). */
+  pad?: { x: number; y: number };
+  /** The tail under the bubble, CSS px (default 7). */
+  tail?: number;
+  /** CSS px kept clear between two bubbles (default 4). */
+  gap?: number;
+  /** The screen, so a bubble is never pushed off it (default the window). */
+  screen?: () => { w: number; h: number };
+  /** Milliseconds now (default performance.now()). */
+  now?: () => number;
+  /** Boxes bubbles keep clear of, CSS px (a game's own speech bubbles, a panel): a bubble moves up past them. */
+  avoid?: () => LabelBox[];
+}
+
+export interface BubbleIn {
+  /** Whose bubble: the key `say(key, …)` was given (a seat, a slot). */
+  key: string | number;
+  /** Where the tail points, CSS px: just over the body's name label (its box's top middle) or its head. */
+  x: number;
+  y: number;
+  /** The player's own (or the player a watcher follows): placed first. */
+  self?: boolean;
+}
+
+export interface BubbleOut extends LabelBox {
+  key: string | number;
+  id: string;
+  kind: 'text' | 'line' | 'react';
+  /** The text, wrapped: one string per line (one line with the glyph for an emoji). */
+  lines: string[];
+  /** An emoji-only bubble (a reaction): draw it bigger, no words. */
+  emoji: boolean;
+  lineHeight: number;
+  pad: { x: number; y: number };
+  /** Where the tail points (the anchor), and the bubble's middle. */
+  tip: { x: number; y: number };
+  cx: number;
+  cy: number;
+  /** 0..1: fading in and out. `scale` pops in from 0.86. */
+  alpha: number;
+  scale: number;
+}
+
+export interface Bubbles {
+  /** A message over `key`'s character: it replaces what that key was saying. `id` lets `remove(id)` take it down. */
+  say(key: string | number, text: string, o?: { id?: string; kind?: 'text' | 'line' | 'react' }): void;
+  /** The studio took a message down (net.on('unchat')): its bubble goes at once. */
+  remove(id: string): void;
+  /** Every bubble, or one key's, goes. */
+  clear(key?: string | number): void;
+  /** Each frame: where every speaking key's anchor is now. Keys not in the list are not drawn (off screen). */
+  place(anchors: BubbleIn[], dt?: number): BubbleOut[];
+  /** The boxes placed last frame: give them to createLabels' `avoid` so names keep off the bubbles. */
+  boxes(): LabelBox[];
+  /** How many keys are speaking now. */
+  readonly size: number;
+}
+
+/** The bubble's font (paintBubbles draws with it; measure with it too). */
+export const BUBBLE_FONT = '600 14px ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif';
+
+/** Words to lines no wider than `max` (a word wider than a line is broken), at most `n` lines (the last cut with …). */
+export function wrapText(text: string, max: number, measure: (t: string) => number, n = 3): string[] {
+  const words = String(text ?? '').replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
+  const lines: string[] = [];
+  let cur = '';
+  const push = (s: string): void => { lines.push(s); };
+  for (const w0 of words) {
+    let w = w0;
+    // A word wider than a line: broken by characters.
+    while (measure(w) > max) {
+      let cut = [...w].length - 1;
+      const chars = [...w];
+      while (cut > 1 && measure(chars.slice(0, cut).join('')) > max) cut -= 1;
+      if (cur) { push(cur); cur = ''; }
+      push(chars.slice(0, cut).join(''));
+      w = chars.slice(cut).join('');
+    }
+    const next = cur ? `${cur} ${w}` : w;
+    if (measure(next) <= max) cur = next; else { if (cur) push(cur); cur = w; }
+  }
+  if (cur) push(cur);
+  if (lines.length <= n) return lines;
+  const kept = lines.slice(0, n);
+  let last = `${kept[n - 1]}…`;
+  while (measure(last) > max && last.length > 2) last = `${[...last].slice(0, -2).join('')}…`;
+  kept[n - 1] = last;
+  return kept;
+}
+
+/**
+ * Speech bubbles over characters: what a player said in the room's chat, over their body, for a few seconds. Feed it
+ * from the netplay helper (`net.on('say', (s) => bubbles.say(s.seat, s.text, { id: s.id, kind: s.kind }))` and
+ * `net.on('unchat', (e) => e.ids.forEach((id) => bubbles.remove(id)))`), place it each frame with every speaking
+ * body's anchor (over its name label), and draw what comes back (`paintBubbles` on a canvas, or your own). Bubbles
+ * never cover each other: a bubble that would sits above the one in its way; the player's own is placed first.
+ */
+export function createBubbles(opts: BubbleOptions): Bubbles {
+  const lh = opts.lineHeight ?? 17;
+  const maxW = opts.maxWidth ?? 190;
+  const maxLines = opts.maxLines ?? 3;
+  const pad = opts.pad ?? { x: 8, y: 5 };
+  const tail = opts.tail ?? 7;
+  const gap = opts.gap ?? 4;
+  const clock = opts.now ?? ((): number => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+  const screen = opts.screen ?? ((): { w: number; h: number } => ({ w: typeof innerWidth === 'number' ? innerWidth : 1e9, h: typeof innerHeight === 'number' ? innerHeight : 1e9 }));
+  const life = opts.ms ?? ((b: { text: string; kind: string }): number => (b.kind === 'react' ? 2600 : Math.min(9000, 4000 + 50 * [...b.text].length)));
+  type Live = { id: string; key: string | number; kind: 'text' | 'line' | 'react'; text: string; lines: string[]; w: number; h: number; at: number; until: number };
+  const live = new Map<string | number, Live>();
+  let last: LabelBox[] = [];
+  let seq = 0;
+  return {
+    say(key, text, o = {}) {
+      const kind = o.kind ?? 'text';
+      const t = String(text ?? '').trim();
+      if (!t) return;
+      const emoji = kind === 'react';
+      const lines = emoji ? [t] : wrapText(t, maxW, opts.measure, maxLines);
+      const w = emoji ? lh * 1.6 : Math.max(...lines.map((l) => opts.measure(l)));
+      const h = emoji ? lh * 1.6 : lines.length * lh;
+      const at = clock();
+      seq += 1;
+      live.set(key, { id: o.id ?? `b${seq}`, key, kind, text: t, lines, w, h, at, until: at + life({ text: t, kind }) });
+    },
+    remove(id) { for (const [k, b] of live) if (b.id === id) live.delete(k); },
+    clear(key) { if (key === undefined) live.clear(); else live.delete(key); },
+    get size() { return live.size; },
+    boxes() { return last; },
+    place(anchors) {
+      const t = clock();
+      for (const [k, b] of live) if (t >= b.until) live.delete(k);
+      const { w: sw, h: sh } = screen();
+      const keep = opts.avoid?.() ?? [];
+      const placed: LabelBox[] = [];
+      const out: BubbleOut[] = [];
+      // The player's own first, then the newest: a new message keeps its spot and an older one moves up.
+      const order = anchors.filter((a) => live.has(a.key)).sort((a, b) => Number(Boolean(b.self)) - Number(Boolean(a.self)) || (live.get(b.key)!.at - live.get(a.key)!.at));
+      for (const a of order) {
+        const b = live.get(a.key)!;
+        const bw = b.w + pad.x * 2;
+        const bh = b.h + pad.y * 2;
+        const left = Math.max(2, Math.min(sw - bw - 2, a.x - bw / 2));
+        let bottom = a.y - tail;
+        let box = { left, top: bottom - bh, right: left + bw, bottom };
+        const hits = (x: LabelBox): boolean => box.left < x.right + gap && x.left < box.right + gap && box.top < x.bottom + gap && x.top < box.bottom + gap;
+        for (let i = 0; i < 6; i += 1) {
+          const other = placed.find(hits) ?? keep.find(hits);
+          if (!other) break;
+          bottom = other.top - gap;
+          box = { left, top: bottom - bh, right: left + bw, bottom };
+        }
+        if (box.top < 0 || box.left > sw || box.right < 0 || a.y > sh + bh) continue;
+        placed.push(box);
+        const age = t - b.at;
+        const leftMs = b.until - t;
+        const alpha = Math.max(0, Math.min(1, age / 120, leftMs / 400));
+        const scale = 0.86 + 0.14 * Math.min(1, age / 160);
+        out.push({ ...box, key: b.key, id: b.id, kind: b.kind, lines: b.lines, emoji: b.kind === 'react', lineHeight: lh, pad, tip: { x: Math.max(box.left + 8, Math.min(box.right - 8, a.x)), y: a.y }, cx: (box.left + box.right) / 2, cy: (box.top + box.bottom) / 2, alpha: Math.round(alpha * 100) / 100, scale: Math.round(scale * 1000) / 1000 });
+      }
+      last = placed;
+      return out;
+    },
+  };
+}
+
+export interface BubbleStyle {
+  font?: string;
+  /** The bubble's paper and ink (default white paper, near-black ink), its edge, and the player's own bubble's edge. */
+  paper?: string;
+  ink?: string;
+  edge?: string;
+  selfEdge?: string;
+  /** Corner radius, CSS px (default 10). */
+  radius?: number;
+}
+
+/** Draw placed bubbles on a 2D canvas (CSS px, the context's transform already set for the device pixel ratio). */
+export function paintBubbles(ctx: CanvasRenderingContext2D, list: BubbleOut[], style: BubbleStyle = {}): void {
+  const font = style.font ?? BUBBLE_FONT;
+  const paper = style.paper ?? '#ffffff';
+  const ink = style.ink ?? '#15171f';
+  const edge = style.edge ?? 'rgba(0,0,0,0.18)';
+  const r = style.radius ?? 10;
+  for (const b of list) {
+    if (b.alpha <= 0) continue;
+    ctx.save();
+    ctx.globalAlpha = b.alpha;
+    const cx = b.cx;
+    const cy = b.bottom;
+    ctx.translate(cx, cy);
+    ctx.scale(b.scale, b.scale);
+    ctx.translate(-cx, -cy);
+    ctx.fillStyle = paper;
+    ctx.strokeStyle = edge;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.roundRect(b.left, b.top, b.right - b.left, b.bottom - b.top, Math.min(r, (b.bottom - b.top) / 2));
+    ctx.fill();
+    ctx.stroke();
+    // The tail: a small triangle from the bubble's bottom to where it points.
+    const tx = b.tip.x;
+    ctx.beginPath();
+    ctx.moveTo(tx - 6, b.bottom - 1);
+    ctx.lineTo(tx, Math.min(b.tip.y, b.bottom + 7));
+    ctx.lineTo(tx + 6, b.bottom - 1);
+    ctx.closePath();
+    ctx.fill();
+    ctx.fillStyle = ink;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    if (b.emoji) {
+      ctx.font = font.replace(/\d+(?:\.\d+)?px/, `${Math.round(b.lineHeight * 1.35)}px`);
+      ctx.fillText(b.lines[0] ?? '', b.cx, b.cy + 1);
+    } else {
+      ctx.font = font;
+      b.lines.forEach((line, i) => ctx.fillText(line, b.cx, b.top + b.pad.y + b.lineHeight * (i + 0.5) + 0.5));
+    }
+    ctx.restore();
+  }
+}

package/shop/SELLING.md

@@ -0,0 +1,83 @@
+# Selling things in your games: what you are taking on
+
+Plain words for a studio's owner, from the Homie studio kit. **This is not legal or tax advice.** If you will
+sell for real, ask an accountant where you must register for tax, and a lawyer anything this page leaves you
+unsure about.
+
+## The short version
+
+You sell with **your own Stripe account**. Money goes straight from your players to you. Homie never sees it,
+never holds it, and takes no cut. That also means **you are the shop**: you set the prices, you answer refund
+requests, you deal with card disputes, and the tax on your sales is yours to handle.
+
+## Who does what
+
+| | You (the studio) | Stripe | Homie |
+|---|---|---|---|
+| Prices, what you sell | yes | | |
+| Taking the card, the receipt email | | yes | |
+| Refunds | yes: one tap in your office | carries them out | |
+| Card disputes (chargebacks) | yes: you answer them in Stripe and carry the loss if you lose | runs the process | |
+| Sales tax and VAT | yes, with Stripe Tax's help (or Managed Payments, below) | calculates and collects | |
+| Your players' data | yes: you are responsible for it | keeps the card and email | stores nothing |
+| The kids rules | built into the kit, and you can be stricter | | wrote the kit |
+
+## Refunds
+
+- A player can refund an **unused** item themselves within your refund window (at least 14 days) from their
+  account page. Fewer people turn to card disputes when a refund is easy.
+- Anything else, you refund with **one tap** on your office's shop page. Your AI can only *ask* you to refund; it
+  can never do it by itself.
+- Stripe does not give back its processing fee on a refund. That is the cost of a happy player.
+
+## Disputes (chargebacks)
+
+- A buyer's bank can reverse a payment. Stripe charges a dispute fee (about US$15) whether you win or lose, and
+  you lose the sale's money if the bank decides for the buyer. On a US$5 item one dispute costs more than the
+  sale, which is why the kit makes refunds easy and suggests items of US$3 or more.
+- **A dispute never deletes or locks the player's account.** While it is open nothing changes. If you lose it,
+  that one item is taken back, as a refund would.
+
+## Tax
+
+You choose who the seller is when you connect your Stripe (`homie-studio shop connect` shows both):
+
+- **You are the seller** (`"till": "stripe"`): Stripe Tax is on. It works out and collects tax **only where you
+  have told Stripe you are registered**, and it does not file your returns. Some places expect a foreign seller
+  of digital goods to register from the first sale (the EU and the UK do). Cheapest; the most work.
+- **Stripe is the seller** (`"till": "stripe-managed"`, Stripe Managed Payments): **3.5% more** a sale. Stripe's
+  Link, LLC becomes the seller of record and registers, collects, files and pays sales tax and VAT in 80+
+  countries, runs fraud checks and answers disputes for you. You still carry the money of a lost dispute, and
+  Stripe may refund a buyer within 60 days. You turn it on in Stripe first (after Stripe's eligibility review).
+
+## Kids
+
+The kit keeps you out of the worst trouble, and you cannot switch these off in it (you can be stricter):
+
+- nothing is sold on a kids server, or anywhere in a studio made for children (`"audience": "kids"`);
+- spending is off on every account until one neutral question (the year you were born) says the player is an
+  adult; the answer is kept only as "adult", "teen" or "child";
+- nothing is ever sold to an account that said it is under 13;
+- a 13 to 17 year old can only pass a link to a parent, who pays in their own name on Stripe's page;
+- no loot boxes or anything random for money, nothing that changes the game on beginner servers, no countdowns;
+- every price is in real money, every purchase goes through Stripe's own page, one at a time, with a monthly cap;
+- the television never sells: it shows a code to buy on a phone.
+
+Even so, if children play your games you are the one responsible to the law for them (for example COPPA in the
+US, the Children's Code in the UK, GDPR in the EU). Keep what you collect small, and keep chat with strangers off
+on kids servers.
+
+## Referrals
+
+If another studio (or homie.rocks, or a creator) sends you a new player who buys something, you owe them the
+referral share you published in `shop.json` (10% if you kept the suggestion; 0 if you turn it off). Your office
+shows what you owe and to whom, and signs a monthly statement for each. **They invoice you, and you pay them
+yourself.** Nothing moves through Homie.
+
+## Before the first real sale
+
+1. Make (or pick) your Stripe account, verify it, and add a bank account.
+2. Test everything in **test mode** first: buy your own item with a Stripe test card, refund it from the office.
+3. Fill in your public business details in Stripe (name, support email, the refund page `/shop/refunds/`).
+4. Talk to an accountant about where you must register for tax, or choose Managed Payments.
+5. Then, and only then, connect a live key (`homie-studio shop connect --live`).

package/shop/SHOP.md

@@ -0,0 +1,154 @@
+# The shop: selling in a studio's games with the studio's own Stripe
+
+`@homie-rocks/studio` 0.24.0. A studio sells items for its games through **its own Stripe account**. The studio
+is the seller; homie.rocks never holds, routes or settles its money, is not a Stripe Connect platform, and takes
+no cut. There is no shared currency between studios. `SELLING.md` beside this file is the owner's plain-words
+note on what selling means for them (refunds, disputes, tax, kids; not legal advice).
+
+## shop.json
+
+At the studio's root, reviewed in git. Nothing secret is ever in it.
+
+```json
+{
+  "till": "stripe",
+  "currency": "usd",
+  "refundDays": 14,
+  "capPerPlayerMonth": 5000,
+  "items": [
+    { "id": "supporter", "kind": "supporter", "name": "Supporter", "price": 500, "days": 365,
+      "gives": ["badge:supporter", "credits-name"], "badge": "Supporter" },
+    { "id": "ember-skin", "kind": "cosmetic", "game": "orbit", "name": "Ember hull", "price": 300, "gives": ["skin:ember"] },
+    { "id": "season-1", "kind": "pass", "name": "Season 1", "price": 800, "ends": "2027-01-31", "gives": ["track:season-1"] },
+    { "id": "tip", "kind": "tip", "name": "Buy the studio a coffee", "price": "choose", "min": 200, "max": 5000 }
+  ],
+  "referrals": { "rate": 0.10, "windowDays": 30, "capPerPlayer": 1000, "holdDays": 30, "minimumInvoice": 2500 }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `till` | `stripe`: the studio is the seller, Stripe Tax on (`automatic_tax`). `stripe-managed`: Stripe Managed Payments, Stripe's Link, LLC is the seller of record and files the tax (3.5% more; turn it on in Stripe first). `off`. |
+| `currency` | one currency with cents (`usd`, `cad`, `eur`, `gbp`, `aud`…). |
+| `refundDays` | 14 to 60: a player refunds an unused item themselves within it. |
+| `capPerPlayerMonth` | cents one player may spend here in a month: 100 to 5000. Lower it, never remove it. |
+| `items[].kind` | `cosmetic` (a look), `supporter` (a badge, thanks), `pass` (a season), `unlock` (a mode, a chapter, the full game), `tip` (pay what you want, `min` to `max`). |
+| `items[].price` | whole cents, real money. Under 300 the check warns (fees eat it). |
+| `items[].gives` | the entitlement keys the game reads: `skin:ember`, `badge:supporter`. A `badge:` key shows beside the player's name in rooms and on their account page. |
+| `items[].days` / `starts` / `ends` | how long it lasts; a season's dates (shown as dates, never a countdown). |
+| `items[].game` | only in that game's shop (left out: every game's). |
+| `items[].advantage` | `true` when it changes how the game plays: never offered, and never counted as owned, on a beginner or kids server. |
+| `items[].taxCode` | a Stripe product tax code. Managed Payments needs one: by default `txcd_10201000` (video games, downloaded, permanent) or `txcd_10201001` (limited time). |
+| `referrals` | what this studio pays a referrer for a new player's purchase (left out: nothing). |
+
+`homie-studio shop check`, and every `homie-studio build`, refuse: anything that names chance, odds, random, a
+crate, a box, a mystery, loot, a gacha, a spin or a roll; fields for odds or drop pools; a countdown, timer or
+"hurry" field; gems, coins, points or any currency of the studio's own; subscriptions and paid services (later
+versions); a cap over 5000 or a refund window under 14 days. A studio whose studio.json says
+`"audience": "kids"` sells nothing at all.
+
+## Who may buy
+
+The Worker decides, for every item and every player (`worker/shop-rules.mjs` `wayFor`):
+
+| The player | What happens |
+|---|---|
+| on a kids server, or in a kids studio | no shop at all: nothing listed, `shop.open()` says nothing is sold here |
+| a guest (no passkey) | "make an account first" (a purchase would be lost with a cookie) |
+| an account that has not answered | the one neutral age question: the year they were born, no default, nothing hinting which answer opens anything; kept only as a band |
+| an account that said under 13 | nothing, ever; the account is treated as a kids account from then on |
+| 13 to 17 | "ask a grown-up": a one-time link (a week) the teen passes on; the parent opens it on their own device, sees what and for whom, ticks that they are the parent or guardian, and pays in their own name on Stripe's page; the item lands on the teen's account |
+| an adult | Stripe's own hosted Checkout, one item at a time, with the real-money price and its own confirm |
+| over the monthly cap | not until next month |
+
+## In a game
+
+```ts
+import { createShop } from '@homie-rocks/studio/shop';
+const shop = createShop();
+await shop.ready;                        // { open, kids, screen }
+if (shop.has('skin:ember')) useEmber();  // synchronous: fine in a render loop
+shop.on('change', (owns) => redraw());   // a purchase landed, or a refund took one back
+buyButton.onclick = () => shop.open('ember-skin');   // the store sheet (a code to scan on a TV)
+shop.used('skin:ember');                 // equipped: it leaves the player's own refund window
+```
+
+Rules for the game: open the shop only from a button the player pressed, never from the play, start or wake
+button, never on a timer; show prices in real money; never draw a countdown; never sell randomness; do nothing
+differently for a supporter on a beginner server.
+
+The play shell around the game answers these calls (the game never sees a card, an email, an order or a
+session). The room button's sheet has a **Shop** button too. A purchase opens Stripe's page in a new tab, the game
+keeps running, and the shell looks again when the tab comes back: `change` fires once it is paid.
+
+**Badges in rooms.** A player whose account owns a `badge:` key carries it on their seat: `net.players()` gives
+`peer.badge` ("Supporter"), set by the studio's Worker from what the account owns when the player connects (a
+hello can never claim one). None on a kids server, none for an AI.
+
+## The money path
+
+```
+phone (signed in) ─ POST /api/shop/buy ─► studio Worker ─ Checkout Session (the studio's restricted key) ─► Stripe
+      ◄──────────────── Stripe's hosted page (new tab): the player pays ─────────────────────────────────┘
+Stripe ─ signed webhook ─► POST /api/shop/hook: order paid → entitlements → referral line (held)
+homie.rocks: not involved at any step.
+```
+
+- The order row is written before Stripe is called; the Checkout Session carries the order, the player and the
+  item in its metadata; the hook checks the session matches the order (player, price) before it grants anything.
+- The webhook's `Stripe-Signature` is checked (HMAC-SHA256 of `<t>.<payload>` with the endpoint's `whsec_`
+  secret, within five minutes); each event id is handled once; a test event never touches a live shop.
+- Paid: the entitlements are granted. Refunded: that one order's entitlements are revoked. A dispute: nothing
+  changes until it is decided; lost: that one item goes, as a refund would; won: it stays. **The account is never
+  locked or deleted over a dispute.**
+- Receipts come from Stripe by email (the buyer types it on Stripe's page, never on the studio's). The account
+  page lists the player's orders and badges; `/api/player/export` includes them; deleting an account asks first
+  when it owns things, and keeps the order rows without the player.
+- Each Checkout Session says beside the pay button that the item is delivered at once (the EU and UK withdrawal
+  acknowledgement) and that an unused item can still be refunded.
+
+## Setting it up (Claude does the commands; the owner only uses pages)
+
+1. `npx --no-install homie-studio shop init --supporter` (shop.json and SELLING.md), then `shop check`, commit,
+   `npm run deploy` (it applies migration `0008_studio_shop.sql`; the shop stays closed).
+2. In Stripe (the owner): a restricted key with **Checkout Sessions: Write, Charges: Write (refunds),
+   PaymentIntents: Read, Disputes: Read**, and a webhook endpoint at `https://<site>/api/shop/hook` for
+   `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`,
+   `checkout.session.expired`, `charge.refunded`, `refund.created`, `refund.updated`, `charge.dispute.created`,
+   `charge.dispute.closed`.
+3. `npx --no-install homie-studio shop connect`: a page on the owner's computer (127.0.0.1, one use, ten minutes)
+   with those steps, both fields and the seller choice (the studio, or Stripe Managed Payments, with what each
+   costs and does). The key and the secret go straight to the Worker secrets `STRIPE_KEY` and
+   `STRIPE_WEBHOOK_SECRET` on Wrangler's standard input. Test keys only, unless `--live`.
+4. `homie-studio shop` says whether anything is still missing. Buy your own item with a Stripe test card, and
+   refund it from `/_studio/office/shop`.
+
+Never ask for a key in a chat, never put one in a file, an argument, a log or a commit.
+
+## The office
+
+`/_studio/office/shop` (the owner's browser) and `/_studio/api/shop` (an office key): open or what is missing,
+the last 30 days, every order with its Stripe page, Refund (one tap), disputes, payouts, balance and tax as links
+to the studio's own Stripe Dashboard, a CSV for the accountant, and the referral books. From an office key a
+refund (`POST /_studio/api/shop/refund`, `homie-studio shop refund <order>`) is always an ASK the owner confirms
+with one tap; so is marking a referrer paid.
+
+## Referrals
+
+- A link with `?via=<host>` (another studio, homie.rocks, anywhere) opened by a person whose browser has never
+  been to this studio leaves a signed cookie with the host and the time (only on a studio that pays referrals;
+  never a prefetch, a crawler, this site, or a server's page or room).
+- A paid order by an account made after that arrival, within `windowDays`, writes a referral line in THIS
+  studio's D1, if the referrer's own `/.well-known/homie-studio.json` says it takes statements. Held for
+  `holdDays`; a refund or a lost dispute inside the hold voids it, after it a clawback nets off the next statement.
+- `homie-studio shop statements [--send]` signs each referrer's statement with the studio's Ed25519 key (the
+  public half is in the manifest's `referrals.key`) and POSTs it to the referrer's `/api/referrals/statement`,
+  which checks the signature against the seller's own manifest. No player, name or email is in a statement.
+- Paying stays outside Homie: the referrer invoices the seller from its own Stripe; the seller pays and marks it
+  paid in the office.
+
+## Testing without money
+
+The kit's tests run the Worker against `stripe-mock` (Stripe's open-source API mock, which checks every parameter
+against Stripe's own API description) and sign webhooks with a test secret. `STRIPE_API_BASE` (a loopback address
+only) points a Worker at such a mock; it is never honoured for anything but 127.0.0.1 or localhost.

package/shop/shop.ts

@@ -0,0 +1,130 @@
+/*
+ * shop.ts — what a player owns in a game on a Homie studio (@homie-rocks/studio/shop). SHOP.md beside it is the guide.
+ * =============================================================================
+ *
+ *   import { createShop } from '@homie-rocks/studio/shop';
+ *   const shop = createShop();
+ *   await shop.ready;
+ *   if (shop.has('skin:ember')) hull.material = ember;     // what the player bought, by the key shop.json gives
+ *   shop.on('change', () => redrawSkins());                // a purchase landed (or a refund took one back)
+ *   button.onclick = () => shop.open('ember-skin');        // the store sheet; on a TV, a code to buy on a phone
+ *   shop.used('skin:ember');                               // equipped: it is no longer refundable by the player
+ *
+ * WHERE IT COMES FROM. The game runs in a sandboxed frame that can see no cookie and send no request as the site. The
+ * play shell around it (on the studio's own origin) asks the studio's Worker what the signed-in player owns and
+ * answers this module by postMessage, only for THIS game. The Worker decides: an item bought with the studio's own
+ * Stripe, paid (the signed webhook said so), not refunded, not ended. A game never sees a card, an email or an order.
+ *
+ * THE KIDS RULES (the kit's, not the game's to change): on a kids server there is no shop (`open` is false, `kids` is
+ * true, `open()` shows "nothing is sold here"); on a beginner or kids server anything with a play advantage counts as
+ * NOT owned; on a television `open()` shows only a code to scan and buy on a phone. A game never shows a countdown, a
+ * random reward for money, or a buy button on its play button.
+ *
+ * Without a shell (a game opened as a file, a dev server, a studio with no shop) everything is empty and `open()` does
+ * nothing, so the same code runs everywhere. It has no imports and uses only erasable TypeScript.
+ * =============================================================================
+ */
+
+export const SHOP_VERSION = 1;
+
+export interface ShopState {
+  /** The studio sells something in this game, and this room may show it. */
+  open: boolean;
+  /** A kids server: nothing is sold or shown. */
+  kids: boolean;
+  /** This is the big screen: `open()` shows a code to buy on a phone. */
+  screen: boolean;
+}
+export type ShopEvent = 'change' | 'closed';
+
+export interface ShopOptions {
+  /** Tests and custom shells: where messages go (default: the parent frame). */
+  target?: { postMessage: (m: unknown, origin: string) => void } | null;
+  /** How long to wait for the shell's first answer before treating the game as having no shop (ms). */
+  timeoutMs?: number;
+}
+
+export interface Shop {
+  /** Resolves once the shell answered (or after `timeoutMs` with no shell: an empty, closed shop). */
+  readonly ready: Promise<ShopState>;
+  readonly state: ShopState;
+  /** Whether the player owns this entitlement key now ("skin:ember", "badge:supporter"). Synchronous, for a render loop. */
+  has(key: string): boolean;
+  /** Every key the player owns now. */
+  entitlements(): string[];
+  /** Ask the shell for a fresh answer (the shell also looks again by itself after a purchase). */
+  refresh(): Promise<string[]>;
+  /** Show the store sheet, at one item if given. Call it from a button the player pressed, never on a timer. */
+  open(item?: string): void;
+  close(): void;
+  /** The player used something (equipped it, played with it): it leaves the player's own refund window. */
+  used(key: string): Promise<boolean>;
+  on(ev: 'change', fn: (owns: string[]) => void): () => void;
+  on(ev: 'closed', fn: () => void): () => void;
+}
+
+type Msg = Record<string, unknown> & { t?: string; q?: number; ev?: string; ok?: boolean };
+const KEY = /^[a-z0-9][a-z0-9_.:-]{0,63}$/;
+
+export function createShop(opts: ShopOptions = {}): Shop {
+  const g = globalThis as unknown as { HOMIE_NET?: { shop?: boolean }; parent?: unknown; addEventListener?: typeof addEventListener };
+  const inShell = Boolean(g.HOMIE_NET?.shop);
+  const target = opts.target !== undefined ? opts.target : (inShell && g.parent && g.parent !== g ? (g.parent as { postMessage: (m: unknown, o: string) => void }) : null);
+  const listeners = new Map<string, Set<(x: unknown) => void>>();
+  const emit = (ev: string, x: unknown): void => { for (const fn of listeners.get(ev) ?? []) { try { fn(x); } catch { /* the game's */ } } };
+  let owns: string[] = [];
+  const state: ShopState = { open: false, kids: false, screen: false };
+  let seq = 0;
+  const waiting = new Map<number, (m: Msg) => void>();
+  const send = (m: Record<string, unknown>): Promise<Msg> => {
+    if (!target) return Promise.resolve({ ok: false });
+    const q = ++seq;
+    return new Promise((resolve) => {
+      waiting.set(q, resolve);
+      try { target.postMessage({ t: 'homie-shop', q, ...m }, '*'); } catch { waiting.delete(q); resolve({ ok: false }); }
+      setTimeout(() => { if (waiting.has(q)) { waiting.delete(q); resolve({ ok: false, error: 'timeout' }); } }, 8000);
+    });
+  };
+  const setOwns = (next: unknown): boolean => {
+    const list = Array.isArray(next) ? next.map(String).filter((k) => KEY.test(k)) : [];
+    const before = owns.slice().sort().join(',');
+    owns = list;
+    return list.slice().sort().join(',') !== before;
+  };
+  if (target && g.addEventListener) {
+    g.addEventListener('message', (e: MessageEvent) => {
+      const m = e.data as Msg;
+      if (!m || typeof m !== 'object' || m.t !== 'homie-shop') return;
+      if (typeof m.q === 'number' && waiting.has(m.q)) { const r = waiting.get(m.q)!; waiting.delete(m.q); r(m); return; }
+      if (m.ev === 'owns') { if (setOwns(m.owns)) emit('change', owns.slice()); }
+      if (m.ev === 'closed') emit('closed', undefined);
+    });
+  }
+  const ready: Promise<ShopState> = target
+    ? Promise.race([
+      send({ op: 'hello', v: SHOP_VERSION }).then((m) => {
+        state.open = Boolean(m.ok && m.open); state.kids = Boolean(m.kids); state.screen = Boolean(m.screen);
+        if (setOwns(m.owns)) emit('change', owns.slice());
+        return { ...state };
+      }),
+      new Promise<ShopState>((r) => setTimeout(() => r({ ...state }), opts.timeoutMs ?? 4000)),
+    ])
+    : Promise.resolve({ ...state });
+
+  const shop: Shop = {
+    ready,
+    get state() { return { ...state }; },
+    has: (key) => owns.includes(String(key)),
+    entitlements: () => owns.slice(),
+    refresh: async () => { const m = await send({ op: 'owns' }); if (m.ok && setOwns(m.owns)) emit('change', owns.slice()); return owns.slice(); },
+    open: (item) => { void send({ op: 'open', ...(typeof item === 'string' ? { item } : {}) }); },
+    close: () => { void send({ op: 'close' }); },
+    used: async (key) => (KEY.test(String(key)) && owns.includes(String(key)) ? Boolean((await send({ op: 'used', key })).ok) : false),
+    on: ((ev: ShopEvent, fn: (x: unknown) => void) => {
+      if (!listeners.has(ev)) listeners.set(ev, new Set());
+      listeners.get(ev)!.add(fn);
+      return () => { listeners.get(ev)?.delete(fn); };
+    }) as Shop['on'],
+  };
+  return shop;
+}

package/site/SITE.md

@@ -30,7 +30,17 @@ songs (each with a `cover`), videos (each with a `poster`), the latest posts, an
 (`games[].played`, `{ "days": 7, "plays", "rounds" }`). To keep the studio's rooms off the hub, studio.json takes
 `"rooms": { "share": false }`: the manifest then names no `rooms` (the studio's own pages still list them).
 Each room in `/api/rooms` carries `play` and, unless its game says `"watch": false`, `watch` (its watch door), so
-the hub offers Watch beside Join.
+the hub offers Watch beside Join. From 0.23.0 a room whose chat is on and whose rules let homie.rocks show it
+(`hub`, on by default) also says `chat: true`: the hub's room card then has Chat, which opens the room's own watch
+socket from the visitor's browser and shows its lines and reactions live (NETPLAY.md section 19). A visitor there
+sends what a watcher may send (reactions and quick lines when the room's `react` is `anyone`), never types.
+
+## Room chat on the play, watch and TV pages
+
+Every play page, big screen and watch page carries room chat (worker/chat-page.mjs; chat/CHAT.md): the Chat pill
+and its sheet, the float, the ticker, the big screen's corner. Reports go to `POST /<id>/api/chat/report` (this
+site's pages only); the owner's tools are `/_studio/api/chat`, `/_studio/api/chat/rules`, `/_studio/api/chat/remove`,
+`/_studio/api/chat/report` (dismiss) and `/_studio/api/chat/budget`, and `mute`/`kick` take a chat line.
 
 ## A game's landing: `/<id>/`
 
@@ -256,6 +266,17 @@ everything. The play page of such a game carries the saves bridge and a "who is
 and shows a passkey sheet over the game when the game asks (`saves.signIn()`); its landing links the account page.
 `/account/` belongs to the site: `site/pages/account/` and `site/public/account/` are refused.
 
+## The shop: `/shop/` (0.24.0)
+
+A studio with a `shop.json` ([../shop/SHOP.md](../shop/SHOP.md)) has `/shop/` (its items in real money, sign in, the
+one neutral age question, Buy on Stripe's own page, or a link for a parent), `/shop/thanks`, `/shop/refunds/` (the
+refund policy every seller publishes) and `/shop/parent/<link>` (what a parent opens). The account page lists the
+player's purchases and badges, with the self-serve refund of an unused item. A play page whose game the studio
+sells something for carries the store sheet (the game's `shop.open()`, and Shop in the room sheet); on a kids server
+there is none, and the big screen's sheet is a code to buy on a phone. With a `shop.json`, `/shop/` belongs to the
+shop (a `site/pages/shop/` is not served); without one it is the studio's own. The directory manifest says only
+whether the shop is open and its till.
+
 ## The arcade knock
 
 A game made with Homie's arcade controls asks its page's origin for a Homie box (`GET /__homie/call`), and a score