@homie-rocks/studio 0.33.1 → 0.34.0

package/CHANGELOG.md

@@ -17,9 +17,49 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.34.0] - 2026-10-08
+
+**Plugin 0.35.0** · [#64](https://github.com/homie-rocks/homie/pull/64)
+
+A plain shop: nothing is imposed unless you write it. A shop is open to guests by default, the protective rules 0.33.0 started with are a preset you choose, and a player can put several items in a cart and pay once.
+
+### Added
+
+- **A cart.** A cart holds several items and quantities, free and paid lines together, and is paid in one Stripe Checkout Session. `shop.add(item, quantity, amount?)` and `shop.checkout()` build and pay for a cart; `shop.buy(item)` still buys one thing directly. Each line keeps the item as it was defined at the time of sale, grants exactly once, and can be refunded on its own in the office.
+- A cart with only free lines grants its items without going to Stripe.
+- `checkoutMinutes` in `shop.json` sets how long a checkout stays open, within Stripe's bounds of 30 to 1440 minutes.
+- The shop accepts a restricted (`rk_`) or a full secret (`sk_`) Stripe key. A preview you give its own database and both Stripe secrets can sell; previews normally have no database.
+
+### Changed
+
+- **Your shop is open by default.** 0.33.0 started every shop on the protective preset. Now a shop that names no preset has no policy: guests can buy, and buy again, without an age question or a parent step, from any page. You choose your items, wording, kinds, prices, dates, caps, refund windows and referral terms. `shop init` writes no policy.
+- **Every policy is optional.** The account, age, kids-server, advantage, repeat-purchase, used-item refund and TV rules apply only when you write them, one by one or with `"preset": "protective"` or `"preset": "adults-only"`. Stripe Tax and the withdrawal acknowledgement are optional too. The toolkit no longer scans your items' wording in any preset. Flood protection stays, with rates you can change.
+- **A player cannot refund a tip.** A refund window you set covers items, including used ones unless you choose otherwise. You can refund any order or any line from your office.
+- A checkout now stays open for Stripe's default of 24 hours instead of 31 minutes.
+- Shop and owned-item pages now ask Stripe about unfinished payments in the background (up to three at a time), instead of only when a purchase was refused by your spending cap. A paid order nobody came back to is found after a minute, with or without a cap, and by your Worker's scheduled handler if you set one.
+- With a spending cap, a refund of one line gives back that line's amount. Before, a partial refund kept the whole price counted.
+
+### Fixed
+
+- **The webhook signing secret is required.** The shop is ready only with both the Stripe key and the webhook signing secret, whichever kind of key you use, and the shop's setup steps and readiness name whichever is missing. Payment is confirmed by Stripe's signed event, not only by the buyer's return to your site.
+- Cancelling or replacing a checkout asks Stripe to expire the open session before freeing its place under your spending cap. A checkout with no Stripe session frees its place after the checkout lifetime plus one minute.
+- Refunds follow Stripe's own list of refunds and their statuses. A refund that names a line affects only that line, a pending refund keeps the item, and a failed refund gives it back. A partial refund made in the Stripe Dashboard lowers the order's balance, cap and referral totals without guessing a line. A refund of the whole order takes back the whole order, and a refund of a paid line leaves free lines in the same order alone. A refund event that arrives before its payment was recorded records the payment first.
+- An order in dispute cannot be refunded until Stripe resolves the dispute, and a lost dispute keeps the refunds made before it. Every recorded payment is checked against Stripe's refunds and dispute state.
+- A payment, its items and its referral share are recorded together, including a verified payment that arrives late. A paid order that is missing an item is repaired once.
+- Shop errors no longer show Stripe keys or secrets. Deleting an account clears the checkout's buyer too. An older order whose item name is missing falls back to the catalog; an item with no definition gives an answer that can be retried and a note in the office.
+- Checkout from inside a game keeps the running game in its tab and explains a blocked tab or blocked cookies. When a new tab cannot open, game and TV checkout use the current tab and return to the game or TV page.
+- Signed Stripe events that are not about your shop are ignored. Optional cron triggers survive a deploy.
+
+### Upgrade notes
+
+- **To keep the 0.33.0 behaviour, write one line.** A `shop.json` that names no preset was protective in 0.33.0 and is open in 0.34.0. To keep the account and age rules you had, write `"policy": { "preset": "protective" }` in `shop.json`. Settings you wrote yourself stay as written. The wording scans are gone in every preset.
+- To keep Stripe Tax, write `"automaticTax": true`. To count referrals for new players only, write `"referralNewPlayersOnly": true`. To keep the shorter checkout, write `"checkoutMinutes": 31`.
+- **Deploy applies one new database step, `0012_shop_lines.sql`.** It only adds: your orders become one-line orders, and nothing is removed, so the 0.33.0 Worker keeps working while you deploy and if you roll back. Until the step has run, owned items and office refunds work and checkout says which step is missing.
+- **The webhook signing secret is required, with either kind of key.** A shop with a key and no signing secret reports not ready and does not sell. `homie-studio shop connect` makes the webhook and stores the secret, or takes one you made yourself.
+
 ## [0.33.1] - 2026-10-08
 
-**Plugin 0.34.1** · [#65](https://github.com/homie-rocks/homie/pull/65)
+**Plugin 0.34.1** · [#65](https://github.com/homie-rocks/homie/pull/65) · [release-2026-10-08-studio-0.33.1](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-08-studio-0.33.1)
 
 A fix for studios upgrading to 0.33.0, found by upgrading one of Homie's own.
 

package/README.md

@@ -452,9 +452,9 @@ npx homie-studio lounge mod <player id>                                 # a mode
 A studio sells items for its games (0.24.0; Stripe's own agent tools since 0.24.3) with **its own Stripe account**: the studio is the seller, money goes
 straight from players to its Stripe, and homie.rocks never sees, holds or moves it (Homie takes no cut; no shared
 currency; not a Connect platform). The studio chooses its prices, item kinds and optional spending and refund
-settings, with no Homie ceiling. New shops start with the editable `protective` policy: accounts and an age
-question, no purchases for under-13s, parent checkout for teens, no shop on kids servers, and no paid randomness.
-The studio can inspect and change each rule in shop.json; [shop/SHOP.md](shop/SHOP.md) explains every preset.
+settings, with no Homie ceiling. The default is open: guests can buy repeatedly without an age question,
+from any page, with any wording. `protective` and `adults-only` are optional presets; neither scans content.
+The studio chooses its settings in shop.json; [shop/SHOP.md](shop/SHOP.md) explains them.
 
 ```sh
 npx homie-studio shop init --supporter        # shop.json with a US$5 Supporter pack, and SELLING.md (the owner's plain words)
@@ -473,10 +473,10 @@ connect page, which makes the webhook with it, so its signing secret goes straig
 chat. A webhook is never made through Stripe's MCP (its answer carries the secret). From 2026-10-31 Stripe's MCP takes
 only OAuth or Agent-tagged keys; the shop's own key is a plain restricted key and is not affected.
 
-In a game: `createShop()` from `@homie-rocks/studio/shop` (`has`, `entitlements`, `on('change')`, `open`, `used`); a
-supporter's badge rides on their seat (`peer.badge`). Stripe Checkout (hosted), Stripe Tax on, or Stripe Managed
+In a game: `createShop()` from `@homie-rocks/studio/shop` (`has`, `entitlements`, `on('change')`, `open`, `used`, `add`, `checkout`, `buy`); a
+supporter's badge rides on their seat (`peer.badge`). Stripe Checkout (hosted), optional Stripe Tax, or Stripe Managed
 Payments (Stripe as seller of record, 3.5% more) as one switch; a signed, idempotent webhook; refunds from the
-office; a dispute never touches the account; referral statements signed per referrer (homie.rocks is one more
+office, per order or line; a dispute never touches the account; referral statements signed per referrer (homie.rocks is one more
 referrer). The guide: `shop/SHOP.md`.
 
 ## Setup status

package/lib/build.mjs

@@ -18,7 +18,7 @@
  *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site, shop } from studio.json,
  *                                          game.json files, the music/ and videos/ manifests (media/MEDIA.md),
  *                                          posts/*.md, the studio's site/ folder (site/SITE.md) and shop.json (checked
- *                                          against the kit's rules: a shop that breaks them stops the build)
+ *                                          against studio settings, Stripe constraints and arithmetic correctness)
  *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
  *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
  *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
@@ -489,7 +489,7 @@ export function orderGames(games, order, log = () => {}) {
 export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false } = {}) {
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
-  // The shop first (shop/SHOP.md): a shop.json that breaks the kit's rules stops the build before anything is built.
+  // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
   const shop = shopForBuild(root, { log });
   const live = join(root, 'site', 'dist');
   const games = listGames(root).filter((g) => !only || g.id === only);
@@ -677,7 +677,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
         : studio.homie?.directory === false || studio.homie?.directory === null ? null : String(studio.homie?.directory ?? 'https://homie.rocks'),
       // A copy of the public template that nobody has named yet shows the name typed in Cloudflare's form.
       ...(studio.template === true ? { template: true } : {}),
-      // studio.json "audience": "kids" (a studio made for children: no shop at all) or "teens"; and "referrals": false
+      // studio.json "audience": "kids" (a studio audience label; shop policies are optional) or "teens"; and "referrals": false
       // (this studio takes no referral statements as a referrer).
       ...(audienceOf(studio) !== 'general' ? { audience: audienceOf(studio) } : {}),
       ...(studio.referrals === false ? { referrals: false } : {}),

package/lib/cloudflare.mjs

@@ -238,6 +238,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
   let routes = keptRoutes(root, studio);
+  const triggers = readConfig(root)?.triggers;
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -352,7 +353,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes }));
+  writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes, triggers }));
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
@@ -360,7 +361,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   step('D1 migrations applied');
   // Workers AI (0.17.0): bound only when a server's AI guides think with it.
   if (needsWorkersAi(root, w, cf.d1)) {
-    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes }));
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes, triggers }));
     step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
   }
 

package/lib/scaffold.mjs

@@ -29,7 +29,7 @@ import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs
 import { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { SERVERS_MIGRATION, SERVERS_MIGRATION_FILE } from '../worker/servers.mjs';
 import { CHAT_MIGRATION, CHAT_MIGRATION_FILE } from '../worker/chat-store.mjs';
-import { SHOP_MIGRATION, SHOP_MIGRATION_FILE, SHOP_RESERVATIONS, SHOP_RESERVATIONS_FILE, SHOP_STATEMENTS, SHOP_STATEMENTS_FILE } from '../worker/shop-store.mjs';
+import { SHOP_MIGRATION, SHOP_MIGRATION_FILE, SHOP_RESERVATIONS, SHOP_RESERVATIONS_FILE, SHOP_STATEMENTS, SHOP_STATEMENTS_FILE, SHOP_LINES, SHOP_LINES_FILE } from '../worker/shop-store.mjs';
 import { LOUNGE_MIGRATION, LOUNGE_MIGRATION_FILE } from '../worker/lounge-store.mjs';
 import { themeFile } from './site.mjs';
 import { rulesIndex } from './studio.mjs';
@@ -64,7 +64,7 @@ export function slugify(name) {
  * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
  * the binding names and keep it linked.
  */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false, routes = null }) {
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false, routes = null, triggers = null }) {
   const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
     : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
@@ -85,6 +85,7 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // every deploy, and one written without them sends the studio's domain back to whatever else the zone routes
     // (lib/routes.mjs). A studio without routes gets no key at all.
     ...(routes?.length ? { routes } : {}),
+    ...(triggers ? { triggers } : {}),
     assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: true },
     durable_objects: { bindings: rooms },
     migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
@@ -433,41 +434,30 @@ studio's pinned copy, never a registry lookup of the bare name.
 
 ## Selling things (the shop)
 
-- **The studio sells with its OWN Stripe account.** The studio is the seller: its prices, its refunds, its tax, its
-  disputes. Money goes from players to the studio's Stripe; homie.rocks never sees it and Homie takes no cut.
-  \`SELLING.md\` says what that means for the owner in plain words (not legal advice).
-- **\`shop.json\`** is the studio's settings file: \`till\` (\`stripe\`, \`stripe-managed\`, or \`off\`), \`currency\`,
-  optional \`refundDays\` and \`capPerPlayerMonth\`, and items with studio-chosen kinds, names, prices and entitlement
-  keys. No Homie ceiling on prices, tips, item count, keys, text, durations or referral terms. Stripe currency
-  units and provider minimums still apply, including zero-decimal currencies. \`shop init --supporter\` writes a
-  supporter item and explicit protective policy, with no spending cap or refund window. Existing values stay.
-- **The studio chooses who may buy:** \`policy.preset\` is \`protective\` (the default), \`adults-only\`, or \`custom\`.
-  Each rule can be read and edited in shop.json; SHOP.md lists them. Protective keeps the account and age
-  question, under-13 refusal, parent checkout for teens, closed kids shops, beginner fairness, refusal of paid
-  randomness and countdowns, and TV code to a phone. Do not silently relax protection for children. The studio
-  is responsible for law and provider terms where it sells; presets are not legal advice.
-- **Flood protection:** \`purchaseAttemptsPerMinute\` (default 6) is per account; \`purchaseAttemptsPerAddressPerMinute\` (default 600) is per address. Both are per Worker instance and configurable.
-  New guest buyers use \`guestBuyersPerAddressPerHour\` (default 600). These protect against floods, not spending.
-- **In a game:** \`import { createShop } from '@homie-rocks/studio/shop'\`; \`shop.has('skin:ember')\`,
-  \`shop.entitlements()\`, \`shop.on('change', …)\`, \`shop.open(item)\` from a button the player pressed (never the
-  play button, never on a timer), \`shop.used(key)\` when it is equipped. A supporter's badge rides on their seat
-  (\`peer.badge\`, set by the Worker, never by a hello). The guide is \`node_modules/@homie-rocks/studio/shop/SHOP.md\`.
-- **Stripe's own tools** (set up when the studio starts selling): \`npm install -g @stripe/cli@latest && stripe agent
-  setup\` installs Stripe's agent plugin (its MCP server and skills); the owner signs in once on Stripe's page and
-  gives access to a sandbox first. With it you make the catalog (\`npx --no-install homie-studio shop catalog\` says
-  the read, then the exact \`stripe_api_write\` calls), check tax settings, and answer "how are sales?" read-only.
-  Never make a webhook or an API key through the MCP (a secret would land in the chat), and never retry a write
-  Stripe sent to the owner for confirmation until they approved it.
-- **The key** goes in only from a page on the owner's own computer: \`npx --no-install homie-studio shop connect\`
-  prints a 127.0.0.1 link; the owner pastes one restricted key there, the page makes the webhook with it, and the
-  key and the webhook's secret go straight to the Worker secrets. Test keys only unless \`--live\`. Never ask for a
-  key in the chat; never write one anywhere.
-- **Refunds:** the owner's one tap in the office (\`/_studio/office/shop\`). You may only ASK:
-  \`homie-studio shop refund <order>\` gives the owner a one-tap link. A card dispute never touches the player's
-  account. \`shop\` says what is missing; \`shop orders\` lists orders (never a card or an email).
-- **Referrals:** a \`?via=<host>\` link from another site (homie.rocks is one more referrer) is remembered on a new
-  player's first visit; a kept sale owes that referrer the rate in \`shop.json\` \`referrals\`. \`shop statements\`
-  signs them; the referrer invoices the studio. Nothing moves through Homie.
+Your shop, your choices. The studio sells through its own Stripe account and is responsible for the law
+where it sells and for Stripe's terms. Homie takes no cut.
+
+- \`shop.json\` lists items, wording, kinds, prices, quantities and entitlements. Optional settings include
+  sale dates, tips, currency, \`automaticTax\`, refund windows, spending caps and referral terms.
+- The default is open: guests can buy repeatedly, without age questions, from any page. Signing in keeps
+  guest purchases. \`shop init --supporter\` writes an example item without a policy, cap or refund window.
+- Choose \`policy.preset: "protective"\` or \`"adults-only"\` to enable an account and age policy. Omitted
+  presets, including in existing files, use the open default. Individual overrides are in SHOP.md.
+- \`createShop()\` from \`@homie-rocks/studio/shop\` supplies \`open\`, \`has\`, \`entitlements\`, \`used\`, and \`change\`.
+  \`shop.add(item, quantity)\` builds a cart; \`shop.checkout()\` pays; \`shop.buy(item)\` buys directly.
+- A cart has independent lines and quantities. The office can refund a whole order or line. The optional
+  player refund window covers items; a tip is never taken back by the player.
+- Flood settings are configurable: buyer attempts 6/minute, address attempts 600/minute,
+  new guest buyers 600/hour. Stripe constraints, integer arithmetic, ownership and signatures protect payments.
+- \`shop check\` validates settings; \`shop connect\` provides a local page for credentials, stored as Worker
+  secrets. Stripe's agent tools can manage Products through \`shop catalog\`; the connect page creates the
+  webhook so its secret stays out of chat. Both the key and signing secret are part of working payment setup.
+  Stripe's approval links belong to the owner. \`checkoutMinutes\` is optional (Stripe: 30 to 1440 minutes,
+  default 1440; values below 31 use 31 for transport margin); cancelling a named checkout, or replacing one at least a minute old, expires the open session on Stripe's confirmation.
+- \`shop orders\` and \`/_studio/office/shop\` show sales. \`shop refund <order>\` asks the owner to confirm.
+  \`shop statements\` records optional referral shares; studios pay their referrers directly.
+
+The guide is \`node_modules/@homie-rocks/studio/shop/SHOP.md\`.
 
 ## Continuing a build from the Claude app
 
@@ -730,6 +720,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_MIGRATION_FILE}`]: SHOP_MIGRATION,
     [`site/migrations/${SHOP_RESERVATIONS_FILE}`]: SHOP_RESERVATIONS,
     [`site/migrations/${SHOP_STATEMENTS_FILE}`]: SHOP_STATEMENTS,
+    [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -852,6 +843,14 @@ function ensureShopStatements(root) {
   return `site/migrations/${SHOP_STATEMENTS_FILE}`;
 }
 
+function ensureShopLines(root) {
+  const file = join(root, 'site', 'migrations', SHOP_LINES_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, SHOP_LINES);
+  return `site/migrations/${SHOP_LINES_FILE}`;
+}
+
 /** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
 /** A studio made before 0.23.0 has no room chat tables: the owner's chat rules and players' reports. */
 function ensureChatMigration(root) {
@@ -872,7 +871,7 @@ function ensureLoungeMigration(root) {
 }
 
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/shop-catalog.mjs

@@ -31,11 +31,11 @@ export async function wantedProducts(shop, slug) {
   return Promise.all((shop?.items ?? []).map(async (it) => {
     const id = await productIdOf(slug, it.id);
     return {
-      id, item: it.id, name: it.name, description: it.blurb ?? null, tax_code: defaultTaxCode(it),
+      id, item: it.id, name: it.name, description: it.blurb ?? null, tax_code: it.taxCode ?? (shop.till === 'stripe-managed' ? defaultTaxCode(it) : null),
       // Stripe metadata values: 500 characters. https://docs.stripe.com/metadata (fetched 2026-10-08).
       metadata: { homie: MARK, homie_studio: String(slug), homie_item: it.id.length <= 500 ? it.id : id },
-      price: it.kind === 'tip' ? null : { currency: shop.currency, unit_amount: it.price, tax_behavior: 'exclusive' },
-      shown: it.kind === 'tip' ? `pay what you want, ${money(it.min, shop.currency)}${it.max === null ? ' or more' : ` to ${money(it.max, shop.currency)}`}` : money(it.price, shop.currency),
+      price: it.price === 'choose' ? null : { currency: shop.currency, unit_amount: it.price, tax_behavior: 'exclusive' },
+      shown: it.price === 'choose' ? `pay what you want, ${money(it.min, shop.currency)}${it.max === null ? ' or more' : ` to ${money(it.max, shop.currency)}`}` : money(it.price, shop.currency),
     };
   }));
 }
@@ -96,7 +96,7 @@ export async function catalogPlan(root, { have = null, mode = null, record = tru
     if (!p) {
       writes.push({
         tool: 'stripe_api_write', method: 'POST', path: '/v1/products', why: `make ${w.name} (${w.shown})`,
-        params: { id: w.id, name: w.name, ...(w.description ? { description: w.description } : {}), tax_code: w.tax_code, metadata: meta, ...(w.price ? { default_price_data: w.price } : {}) },
+        params: { id: w.id, name: w.name, ...(w.description ? { description: w.description } : {}), ...(w.tax_code ? { tax_code: w.tax_code } : {}), metadata: meta, ...(w.price ? { default_price_data: w.price } : {}) },
       });
       continue;
     }

package/lib/shop.mjs

@@ -32,7 +32,7 @@ import { fileURLToPath } from 'node:url';
 import { askedFor, withKey } from './office.mjs';
 import { runner } from './cloudflare.mjs';
 import { listGames, readStudio, siteUrl } from './studio.mjs';
-import { POLICY_PRESETS, SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
+import { SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
 import {
   KEY_SHAPE, STRIPE_VERSION, StripeError, WEBHOOK_SECRET_SHAPE, createWebhookEndpoint, expireCheckoutSession, isPermissionError, listWebhookEndpoints, modeOf,
   stripeCall, updateWebhookEndpoint,
@@ -43,7 +43,7 @@ const SELLING = join(HERE, '..', 'shop', 'SELLING.md');
 /** The events the webhook endpoint listens to (the owner ticks these in Stripe). */
 export const HOOK_EVENTS = Object.freeze([
   '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',
+  'charge.refunded', 'refund.created', 'refund.updated', 'refund.failed', 'charge.dispute.created', 'charge.dispute.closed',
 ]);
 /** The restricted key's permissions, as Stripe's key page names them. Nothing else. */
 export const KEY_PERMISSIONS = Object.freeze([
@@ -77,10 +77,10 @@ export function shopForBuild(root, { log = () => {} } = {}) {
 export function shopCheck(root) {
   const r = readShop(root);
   if (r.absent) return { ok: true, command: 'shop check', absent: true, message: 'No shop.json: this studio sells nothing (homie-studio shop init writes one).' };
-  return { ok: r.ok, command: 'shop check', policy: r.shop?.policy, capPerPlayerMonth: r.shop?.capPerPlayerMonth, refundDays: r.shop?.refundDays, errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.kind === 'tip' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
+  return { ok: r.ok, command: 'shop check', policy: r.shop?.policy, capPerPlayerMonth: r.shop?.capPerPlayerMonth, refundDays: r.shop?.refundDays, errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.price === 'choose' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
 }
 
-/** The Supporter pack the kit suggests first: deterministic, never pay-to-win, a badge on the profile and in rooms. */
+/** The Supporter pack the kit suggests first: a badge on the profile and in rooms; the studio can replace or edit it. */
 export function supporterItem({ price = 500, days = 365, name = 'Supporter' } = {}) {
   return { id: 'supporter', kind: 'supporter', name, price, days, gives: ['badge:supporter'], badge: 'Supporter', blurb: 'A Supporter badge on your account and beside your name in rooms, for a year. It changes nothing about how any game plays.' };
 }
@@ -91,7 +91,6 @@ export function shopInit(root, { supporter = false, currency = 'usd', price = 50
   const studio = readStudio(root);
   const shop = {
     till: managed ? 'stripe-managed' : 'stripe', currency: String(currency).toLowerCase(),
-    policy: { preset: 'protective', ...POLICY_PRESETS.protective },
     items: supporter ? [supporterItem({ price: Number(price) })] : [],
   };
   const r = checkShop(shop, { games: listGames(root).map((g) => g.id) });
@@ -99,7 +98,7 @@ export function shopInit(root, { supporter = false, currency = 'usd', price = 50
   writeFileSync(file, `${JSON.stringify(shop, null, 2)}\n`);
   const wrote = [SHOP_FILE];
   if (!existsSync(join(root, 'SELLING.md')) && existsSync(SELLING)) { writeFileSync(join(root, 'SELLING.md'), readFileSync(SELLING, 'utf8')); wrote.push('SELLING.md'); }
-  return { ok: true, command: 'shop init', wrote, till: shop.till, items: shop.items.map((i) => i.id), next: ['homie-studio shop check', 'npm run deploy (the shop stays closed until the key is in)', 'homie-studio shop connect (the owner pastes a restricted key into a page on this computer)'] };
+  return { ok: true, command: 'shop init', wrote, till: shop.till, items: shop.items.map((i) => i.id), next: ['homie-studio shop check', 'npm run deploy (the shop stays closed until the key and webhook signing secret are in)', 'homie-studio shop connect (the owner pastes a Stripe key into a page on this computer)'] };
 }
 
 /** The office's view of the live shop: open or what is missing, the last 30 days, links to Stripe. */
@@ -162,8 +161,9 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2.5rem auto;padding:0 1rem;color:#1b1b1b}h1{font-size:1.6rem}h2{font-size:1.1rem;margin-top:1.8rem}input[type=password]{width:100%;box-sizing:border-box;font:inherit;padding:.6rem;border:1px solid #999;border-radius:8px}label{display:block;margin:.8rem 0 .3rem;font-weight:600}fieldset{border:1px solid #ccc;border-radius:10px;padding:.6rem 1rem}fieldset label{font-weight:400;display:flex;gap:.6rem;align-items:flex-start}button{margin-top:1.2rem;font:inherit;font-weight:700;padding:.7rem 1.3rem;border:0;border-radius:8px;background:#1b1b1b;color:#fff}small{color:#555}code{font-size:.85em;background:#f2f2f2;padding:0 .25em;border-radius:4px}ol li,ul li{margin:.25rem 0}.box{background:#f6f6f2;border-radius:10px;padding:.8rem 1rem}details{margin-top:1rem}summary{cursor:pointer}</style>
 <h1>Connect ${esc(studio)}'s shop to your Stripe</h1>
 <p>Money goes straight from players to <b>your own Stripe account</b>. Homie never sees it and takes no cut. What you paste here goes from this page to Stripe (one check) and to your studio's Worker as a secret, and nowhere else: not to the chat, not to a file, not to a log.</p>
-<p class="box">${test ? '<b>Test mode first.</b> Use your Stripe sandbox or test mode (the key starts with <code>rk_test_</code>): nothing real is charged, and test cards work. Live keys only when you say the shop is ready to sell.' : '<b>Live mode.</b> Real cards, real money.'}</p>
-<h2>1. In Stripe: one restricted key</h2>
+<p class="box">${test ? '<b>Test mode first.</b> Use your Stripe sandbox or test mode (the key starts with <code>rk_test_</code> or <code>sk_test_</code>): nothing real is charged, and test cards work. Live keys only when you say the shop is ready to sell.' : '<b>Live mode.</b> Real cards, real money.'}</p>
+<h2>1. In Stripe: a key for this shop</h2>
+<p>You can use a restricted (<code>rk_</code>) or full secret (<code>sk_</code>) key. To choose a restricted key with just the permissions this shop uses:</p>
 <ol><li>Open <a href="${dash}/apikeys" target="_blank" rel="noopener">Developers → API keys</a> and press <b>Create restricted key</b>. If Stripe asks what the key is for, choose your own integration, <b>not</b> "Authorizing agent access" (Stripe holds an agent key's refunds for a second approval).</li>
 <li>Name it "${esc(studio)} shop" and give it exactly these permissions (leave everything else at None):<ul>${perms}</ul></li>
 <li>Create it and copy the key (it starts with <code>rk_</code>).</li></ol>
@@ -171,7 +171,7 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <p>With your key, this page makes the endpoint where Stripe tells your shop about payments (<code>${esc(hookUrlOf(site))}</code>, for ${HOOK_EVENTS.length} events), and its signing secret goes straight to your Worker. Nobody sees it. An older one this page made for the same address is turned off, never deleted.</p>
 <form method="post" action="/key"><input type="hidden" name="n" value="${esc(nonce)}">
 <h2>3. Paste the key here</h2>
-<label for="key">Restricted key</label><input id="key" name="key" type="password" autocomplete="off" placeholder="rk_test_…" required>
+<label for="key">Stripe key</label><input id="key" name="key" type="password" autocomplete="off" placeholder="rk_test_…" required>
 <details><summary>I made the webhook myself (or my key has no Webhook Endpoints permission)</summary>
 <ol><li>Open <a href="${dash}/workbench/webhooks" target="_blank" rel="noopener">Webhooks</a> and press <b>Create an event destination</b> (Your account, a Webhook endpoint).</li>
 <li>Endpoint URL: <code>${esc(hookUrlOf(site))}</code></li><li>Events: ${events}</li>
@@ -179,7 +179,7 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <label for="hook">Webhook signing secret</label><input id="hook" name="hook" type="password" autocomplete="off" placeholder="whsec_…"></details>
 <h2>4. Who is the seller?</h2>
 <fieldset>
-<label><input type="radio" name="till" value="stripe"${till !== 'stripe-managed' ? ' checked' : ''}> <span><b>You are</b> (standard Stripe). Stripe takes its usual card fee (in the US 2.9% + 30¢ a sale; in Canada 2.9% + CA$0.30). Stripe Tax is on: it works out and collects sales tax and VAT where you have told Stripe you are registered (0.5% a sale there). Registering and filing are yours, and some countries (the EU, the UK) expect a foreign seller to register from the first sale.</span></label>
+<label><input type="radio" name="till" value="stripe"${till !== 'stripe-managed' ? ' checked' : ''}> <span><b>You are</b> (standard Stripe). Stripe takes its usual card fee (in the US 2.9% + 30¢ a sale; in Canada 2.9% + CA$0.30). Set automaticTax: true in shop.json to enable Stripe Tax: it works out and collects sales tax and VAT where you have told Stripe you are registered (0.5% a sale there). Registering and filing are yours, and some countries (the EU, the UK) expect a foreign seller to register from the first sale.</span></label>
 <label><input type="radio" name="till" value="stripe-managed"${till === 'stripe-managed' ? ' checked' : ''}> <span><b>Stripe is</b> (Stripe Managed Payments). <b>3.5% more</b> a sale, on top of the card fee. Stripe becomes the seller of record: it registers for, collects, files and pays sales tax and VAT in 80+ countries, runs fraud checks, answers card disputes for you and handles buyers' payment questions. Statements read <code>LINK.COM*</code>. You still cover the money of a lost dispute, and Stripe may refund a buyer within 60 days. Turn it on in Stripe first (<a href="${dash}/settings/managed-payments" target="_blank" rel="noopener">Managed Payments</a>, after Stripe's eligibility review; Canada and the US are among the countries it serves).${test ? ' In test mode this page tries one test checkout with Managed Payments (expired at once) and says whether Stripe takes it.' : ''}</span></label>
 </fieldset>
 <button>Save to my Worker</button></form>
@@ -225,7 +225,7 @@ async function makeWebhook(env, site, { fetcher }) {
  * (there is no API to read it). Never in live mode.
  */
 async function probeManaged(env, shop, { fetcher }) {
-  const item = shop?.items?.find((i) => i.kind !== 'tip') ?? null;
+  const item = shop?.items?.find((i) => i.price !== 'choose') ?? null;
   try {
     const s = await stripeCall(env, 'POST', '/v1/checkout/sessions', {
       mode: 'payment', success_url: 'https://example.com/homie-shop-check', cancel_url: 'https://example.com/homie-shop-check',
@@ -270,10 +270,9 @@ export async function shopConnect(root, { managed = null, live = false, log = ()
           const say = ({ status, text }) => { res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }); res.end(text); };
           if (form.get('n') !== nonce || finished) { say(said(403, 'This page was used already.')); return; }
           if (busy) { say(said(409, 'Still saving the last press. Wait a moment.')); return; }
-          if (/^sk_live_/.test(key)) { say(said(400, 'That is a full secret key. The shop takes only a RESTRICTED key (rk_…) with the permissions on the page. Go back and make one.')); return; }
-          if (!KEY_SHAPE.test(key) || !/^rk_/.test(key)) { say(said(400, 'That does not look like a restricted key (rk_test_… or rk_live_…). Go back and try again.')); return; }
+          if (!KEY_SHAPE.test(key)) { say(said(400, 'That does not look like a Stripe key (rk_test_…, rk_live_…, sk_test_… or sk_live_…). Go back and try again.')); return; }
           // Test mode unless the owner's AI ran it with --live on purpose: a live key on the test page is refused.
-          if (modeOf(key) !== (live ? 'live' : 'test')) { say(said(400, live ? 'This page takes a LIVE restricted key (rk_live_…).' : 'This page is for TEST mode: paste a test key (rk_test_…). Live keys go in only when the shop is ready to sell for real (shop connect --live).')); return; }
+          if (modeOf(key) !== (live ? 'live' : 'test')) { say(said(400, live ? 'This page takes a LIVE Stripe key (rk_live_… or sk_live_…).' : 'This page is for TEST mode: paste a test key (rk_test_… or sk_test_…). Live keys go in only when the shop is ready to sell for real (shop connect --live).')); return; }
           if (hook && !WEBHOOK_SECRET_SHAPE.test(hook)) { say(said(400, 'That does not look like a webhook signing secret (whsec_…). Go back and try again, or leave it empty and this page makes the webhook.')); return; }
           busy = true;
           try {

package/lib/template-history.json

@@ -1822,6 +1822,46 @@
      }
     }
    }
+  },
+  "0.34.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "57c04f6526e16890",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.33.1",
+  "version": "0.34.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",

package/shop/SELLING.md

@@ -1,97 +1,19 @@
-# Selling things in your games: what you are taking on
+# Your shop, your choices
 
-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.
+You sell with your own Stripe account. Money goes directly to you; Homie takes no cut.
+The studio is the seller and is responsible for the law where it sells and for Stripe's terms.
 
-## The short version
+Your `shop.json` chooses items, wording, prices, currency, tax integration, sale dates, entitlements,
+referral terms, optional spending caps and optional refund windows. Nothing requires an account or age
+question by default. Guests can buy repeatedly and keep their purchases when signing in later.
 
-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.
+You can choose `policy.preset: "protective"` or `"adults-only"`, or set individual options.
+Without a preset the shop is open. SHOP.md describes each setting and the game cart API.
 
-## Who does what
+A cart is one payment with several lines and quantities. Your office can refund a whole order or a line.
+A player can refund items within a window you set; a tip stays given unless you refund it.
+Stripe handles payments, receipts, payment limits, held refunds and disputes. Stripe Tax is optional;
+Managed Payments is another selectable integration. Your office links Stripe's own pages.
 
-| | 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 |
-| Who may buy | your editable shop policy; protective defaults | provider terms | supplies presets |
-
-## Refunds
-
-- A player can refund an **unused** item themselves within the optional refund window you set from their
-  account page. Set `policy.refundUsedItems` to include used items. Without a window, buyers ask you for a refund.
-  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, so consider your costs when setting prices. Homie imposes no price or earnings ceiling.
-- **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
-
-Your shop starts with the `protective` preset in shop.json. It requires an account and a neutral age question,
-blocks purchases under 13, uses a parent's checkout for teens, closes shops on kids servers and kids studios,
-hides advantages on beginner and kids servers, refuses paid randomness, countdowns and virtual-currency items,
-and sends TV shoppers to a phone. Existing shops without a policy keep these protections.
-
-These are **your settings**: read and edit `policy` in shop.json. `adults-only` also blocks teens;
-`custom` enables all policies. You can override individual rules without changing the others. SHOP.md lists
-every setting. No spending cap or refund window applies unless you set one; existing written values stay yours.
-
-As the seller, you are responsible for the law and your payment provider's terms wherever you sell, including
-rules protecting children. Choosing a preset does not establish compliance. This is information, not legal advice.
-
-## 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.
-
-## What you do, and what your AI does
-
-Your AI sets the shop up with Stripe's own tools for AI (Stripe's agent plugin: its MCP server and skills). It
-makes your products in Stripe, checks your tax settings, makes the webhook, and answers "how are sales?" by reading
-your Stripe. What stays yours, in Stripe's own pages:
-
-- making the Stripe account, and later activating it (your business details, bank account and identity checks);
-- one sign-in page that lets your AI use Stripe's tools: give it your **sandbox** (test) first;
-- one restricted key you make in Stripe and paste into a page on your own computer (never into a chat);
-- approving anything Stripe asks you to confirm (a refund your AI asked Stripe for, for example), and every refund
-  in your office.
-
-If your AI's app cannot use Stripe's sign-in page, Stripe offers an "Agent" key for it instead. From 31 October 2026
-Stripe's tools for AI accept only those (or the sign-in page). The shop's own key is a different, ordinary
-restricted key; never make that one an Agent key, or Stripe will hold every refund for a second approval.
-
-## 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`).
+`homie-studio shop connect` provides a local page for the key and webhook signing secret; both are part of payment setup, credentials stay in Worker secrets.
+The scaffold has no policy, cap or refund window. Test mode is available before choosing live mode.