@homie-rocks/studio 0.23.0 → 0.24.2

package/lib/template-history.json

@@ -1000,6 +1000,84 @@
      }
     }
    }
+  },
+  "0.24.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "124772c374de7390",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Selling things (the shop)": "9d5c3c58d446bfa5",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
+  },
+  "0.24.2": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "124772c374de7390",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Selling things (the shop)": "9d5c3c58d446bfa5",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -349,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 } }

package/netplay/netplay.ts

@@ -269,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]. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.23.0",
+  "version": "0.24.2",
   "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,6 +57,7 @@
     "worker/",
     "mcp/",
     "saves/",
+    "shop/",
     "agents/",
     "lab/",
     "assets/",

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

@@ -266,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

package/worker/account-page.mjs

@@ -160,6 +160,10 @@ export function accountPage(cat, { origin = '', next = '/account/', owner = null
     <label for="acct-email">Email</label><input id="acct-email" data-email type="email" autocomplete="email">
     <div class="row"><button class="ghost" type="button" data-email-save>Send a confirmation</button><button class="ghost" type="button" data-email-remove hidden>Remove it</button></div>
   </div>` : ''}
+  <div class="card shop-card" data-shop-card hidden>
+    <h2>Your purchases</h2>
+    <div data-shop-body></div>
+  </div>
   <div class="card" data-servers-card hidden>
     <h2>Your servers</h2>
     <p>The servers you belong to in this studio's games. Your home server is where Play takes you.</p>
@@ -193,8 +197,9 @@ ${back}
 </details>
 </section>
 <script type="application/json" id="account-boot">${JSON.stringify(boot).replace(/</g, '\\u003c')}</script>
-<script src="/_homie/account.js" defer></script>`;
-  return layout(cat, { title: `Your account · ${studio}`, description: `Your player account on ${studio}.`, origin, path: '/account/', page: 'account', head: `<style>${ACCOUNT_CSS}</style><meta name="robots" content="noindex">`, main });
+<script src="/_homie/account.js" defer></script>
+<script src="/_homie/shop.js" defer></script>`;
+  return layout(cat, { title: `Your account · ${studio}`, description: `Your player account on ${studio}.`, origin, path: '/account/', page: 'account', head: `<style>${ACCOUNT_CSS}.shop-card .badge{display:inline-block;padding:3px 10px;border-radius:999px;background:var(--hot,#ffcf5a);color:var(--hot-ink,#0b0b10);font:800 12px/1.3 ui-sans-serif,system-ui,sans-serif;margin-right:6px}.shop-card ul{margin:8px 0 0;padding-left:18px}.shop-card li{margin:4px 0}</style><meta name="robots" content="noindex">`, main });
 }
 
 /** /_homie/account.js */
@@ -343,6 +348,13 @@ export const ACCOUNT_JS = `${PASSKEY_JS}
     var typed = prompt('This deletes your account and everything it kept on ' + boot.studio + ', in every game. It cannot be undone. Type DELETE to go ahead.');
     if (!typed || typed.trim().toUpperCase() !== 'DELETE') { say('Nothing was deleted.'); return; }
     P.api('POST', '/api/player/delete', { confirm: 'delete' }).then(function (r) {
+      if (!r.ok && r.error === 'purchases') {
+        var again = prompt(r.message + ' Type DELETE again to give them up and delete the account.');
+        if (!again || again.trim().toUpperCase() !== 'DELETE') return { ok: false, message: 'Nothing was deleted.' };
+        return P.api('POST', '/api/player/delete', { confirm: 'delete', purchases: 'forfeit' });
+      }
+      return r;
+    }).then(function (r) {
       if (!r.ok) throw new Error(r.message);
       me = null; P.remember(null); render();
       say('Your account and everything it kept are deleted. You can also remove the passkey from your device\\'s passwords.', 'good');