@homie-rocks/studio 0.50.7 → 0.51.0

package/CHANGELOG.md

@@ -17,6 +17,48 @@ 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.51.0] - 2026-10-14
+
+**Plugin 0.51.0** · Take the money through your own Stripe, keyless by default.
+
+One Stripe approval enables mixed menus, paid capacity bookings and monthly giving through the owner’s own account.
+
+### Added
+
+- Mixed-item Stripe menus with adjustable quantities, signed paid invoice lines
+  and app references such as table 7 on `order.paid`.
+- Booking collections with pending/confirmed/released records and versioned staff
+  moves. Each published slot has its own Stripe Payment Link with a completed-session
+  capacity limit; the owner's AI syncs slots with `stripe_bookings_sync`.
+- Recurring Payment Links for monthly giving and memberships, paid invoice periods,
+  subscription lifecycle events and an API-configured no-code customer portal login.
+- Real sandbox acceptance for menus, two guests with the last-seat link open,
+  full-link deactivation, monthly payment, portal, and clock-driven renewal/failure.
+
+### Changed
+
+- The one-approval CLI connection remains keyless. Homie has no platform credential,
+  backend or cut in the payment path. A key alone never selects session checkout;
+  `STRIPE_CHECKOUT_MODE=sessions` explicitly opts into the fuller connection.
+- Keyless unpaid bookings are pending, not exclusive holds. Payment secures the seat.
+  The optional keyed path retains exclusive expiring holds and exact app-built carts.
+- The giving starter opens real Checkout for suggested one-time/monthly gifts and
+  disables payment before connection. It never counts intentions as gifts.
+
+### Fixed
+
+- Records-only app shells include the shop bridge without needing a multiplayer room.
+- Signed menu invoices and Checkout events tolerate either arrival order, and paid
+  membership access never extends on a failed renewal or revives after cancellation.
+
+### Upgrade notes
+
+Existing studios keep their pinned version until they opt in. Apply booking and
+subscription migrations when adding those capabilities. Run connect after changing
+shop items; the owner's AI syncs published slot manifests after schedule changes.
+Stripe's Payment Link and invoice snapshot limits split large catalogues into menus;
+custom amounts and monthly presets use separate links. No studio catalogue cap is added.
+
 ## [0.50.7] - 2026-10-14
 
 **Plugin 0.50.7** · Prove your needs on every screen, with fixes from studio testers.

package/app-starters/giving/README.md

@@ -1,5 +1,28 @@
 # Together we can
 
-Edit app.json words and starter settings. Phone: /<id>/open; wall: /<id>/tv. A site/pages/<id>/index.html replaces only the landing. Records are public; use references, never private contact details. Staff updates require an account grant.
+This starter opens real Checkout for one-time or monthly gifts from your studio's
+shop. Run `shop init --giving --currency CAD`, then connect the organisation's
+Stripe. The default gift options include $20 monthly. Existing studios and apps
+are unchanged; generate this starter to opt in.
 
-Giving totals are public intentions, not received money. The gift link opens the studio shop. Use `shop init --giving --currency CAD` and connect the organisation’s Stripe account. Monthly renewals are managed in Stripe.
+The phone reads the actual shop's donation options and availability. Without
+Stripe, the options are a disabled preview (`screen.shopPreview: true`). A chosen-amount item (`price: 'choose'`)
+shows an amount field using the item's minimum and maximum. See `shop/SHOP.md`
+for the keyless Payment Links setup and “give $20 monthly” example.
+
+Checkout opening never increments a total or creates an intention record. Stripe's
+verified payment supplies `order.paid` and `subscription.started`; subsequent
+invoices supply `subscription.renewed` or `subscription.failed`. Connect these
+events to your own public progress display if desired. The starter deliberately
+shows no collected total until you implement that verified projection.
+
+The Manage my gifts link opens the studio shop, where the giver can open their
+own Stripe customer portal. Connect creates the no-code portal login through Stripe's API; no Dashboard toggle is needed.
+Set `giving.receiptText` in shop.json for your organisation's receipt wording.
+Edit app.json name, blurb and colour for your cause. Phone: /<id>/open; wall:
+/<id>/tv. Capture and check both surfaces before sharing.
+
+Add the cause’s actual needs to its CODEX.md before running `check`. This starter
+has no pretend shared-record action for the checker to click. For a disconnected
+preview, assert `[data-action]:disabled` on the phone; verify paid flows with the
+Checkout harness and signed events once the keyless connection is available.

package/app-starters/giving/app.json

@@ -1,29 +1,20 @@
 {
   "id": "giving",
   "name": "Together we can",
-  "blurb": "Support our goal with a one-time or monthly gift. Intentions below are not payments.",
+  "blurb": "Support our work with a one-time or monthly gift, paid securely through Stripe.",
   "entry": "src/view.ts",
   "roles": {
     "customer": {
       "signIn": false,
-      "can": [
-        "read:entries",
-        "create:entries"
-      ]
+      "can": []
     },
     "wall": {
       "signIn": false,
-      "can": [
-        "read:entries"
-      ]
+      "can": []
     },
     "staff": {
       "signIn": true,
-      "can": [
-        "read:entries",
-        "update:entries",
-        "delete:entries"
-      ]
+      "can": []
     }
   },
   "surfaces": {
@@ -37,14 +28,14 @@
     "join": "Scan to join",
     "one": "person",
     "many": "people",
-    "action": "Record my intention",
-    "total": "Giving intentions",
+    "action": "Give on Stripe",
+    "total": "Your gift",
     "choice": "Choose an option",
     "monthly": "Gift frequency",
     "once": "One time",
     "month": "Monthly",
     "give": "Give securely on Stripe",
-    "goal": "Intention goal \u00b7 not payments received",
+    "goal": "Our goal",
     "prompt": "Choose what works for you.",
     "finished": "All three answers are in. Thank you!",
     "complete": "Mark complete",
@@ -54,33 +45,6 @@
     "live": "Together \u00b7 live",
     "reconnecting": "Reconnecting\u2026"
   },
-  "records": {
-    "persist": true,
-    "collections": {
-      "entries": {
-        "fields": {
-          "choice": {
-            "type": "string",
-            "required": true,
-            "maxLength": 100
-          },
-          "status": {
-            "type": "string",
-            "required": true,
-            "maxLength": 60
-          },
-          "amount": {
-            "type": "number",
-            "required": true
-          },
-          "monthly": {
-            "type": "boolean",
-            "required": true
-          }
-        }
-      }
-    }
-  },
   "parts": [],
   "netplay": {
     "v": 1,
@@ -100,7 +64,8 @@
   "watch": "overview",
   "screen": {
     "join": "bottom-right",
-    "share": "top-right"
+    "share": "top-right",
+    "shopPreview": true
   },
   "needs": {
     "three": "0.185.1",
@@ -108,12 +73,9 @@
     "@homie-rocks/geom": "0.1.1",
     "@types/three": "0.185.1"
   },
-  "check": {
-    "action": "[data-action]",
-    "observe": "[data-count]"
-  },
+  "check": {},
   "landing": {
-    "pitch": "Support our goal with a one-time or monthly gift. Intentions below are not payments."
+    "pitch": "Support our work with a one-time or monthly gift, paid securely through Stripe."
   },
   "room": {
     "host": "server"
@@ -126,6 +88,7 @@
     "kind": "giving",
     "choices": [
       "10",
+      "20",
       "25",
       "50"
     ],
@@ -158,5 +121,9 @@
         ]
       }
     ]
+  },
+  "records": {
+    "persist": false,
+    "collections": {}
   }
 }

package/app-starters/giving/index.html

@@ -1,3 +1,3 @@
 <!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Live together</title><style>
-*{box-sizing:border-box}body{margin:0;background:var(--tone,#183b55);color:#fff7df;font-family:system-ui,sans-serif}main{min-height:100svh;padding:clamp(24px,5vw,64px);display:grid;grid-template-columns:1.1fr 1fr;gap:40px;align-items:center}h1{font-size:clamp(44px,6vw,88px);line-height:1;letter-spacing:-.05em;margin:20px 0}p{line-height:1.6;max-width:40em}#connection{font-size:12px;text-transform:uppercase;letter-spacing:.18em}.panel{background:#fff7df;color:#20352e;border-radius:28px;padding:28px;box-shadow:0 30px 80px #0003}#count{font-size:80px;font-weight:800;line-height:1}ul{padding:0;list-style:none}li{padding:12px 0;border-bottom:1px solid #20352e22}button,select,a{font:inherit;min-height:48px;border-radius:12px}button,select{padding:10px 16px;width:100%;margin-top:8px}button{background:var(--tone);color:#fff7df;border:0;cursor:pointer}button:disabled{opacity:.5}a{display:inline-flex;align-items:center;color:inherit}label{display:block;margin-top:14px}select{background:white;color:#20352e;border:1px solid #20352e66}progress{width:100%;height:22px;accent-color:var(--tone)}#status{min-height:24px}#amount{font-size:40px;font-weight:700}button:focus-visible,select:focus-visible,a:focus-visible{outline:3px solid #df9325;outline-offset:4px}.wall #controls{display:none}#giving-link[hidden],[hidden]{display:none!important}@media(max-width:650px){main{display:block;padding:72px 22px 24px}h1{font-size:46px}.panel{margin-top:24px;padding:22px}#count{font-size:58px}li{font-size:14px}}@media(max-height:520px) and (min-width:651px){main{padding:65px 25px 20px;gap:22px}h1{font-size:38px}.panel{padding:18px}}
+*{box-sizing:border-box}body{margin:0;background:var(--tone,#183b55);color:#fff7df;font-family:system-ui,sans-serif}main{min-height:100svh;padding:clamp(24px,5vw,64px);display:grid;grid-template-columns:1.1fr 1fr;gap:40px;align-items:center}h1{font-size:clamp(44px,6vw,88px);line-height:1;letter-spacing:-.05em;margin:20px 0}p{line-height:1.6;max-width:40em}#connection{font-size:12px;text-transform:uppercase;letter-spacing:.18em}.panel{background:#fff7df;color:#20352e;border-radius:28px;padding:28px;box-shadow:0 30px 80px #0003}#count{font-size:80px;font-weight:800;line-height:1}ul{padding:0;list-style:none}li{padding:12px 0;border-bottom:1px solid #20352e22}button,select,input,a{font:inherit;min-height:48px;border-radius:12px}button,select,input{padding:10px 16px;width:100%;margin-top:8px}button{background:var(--tone);color:#fff7df;border:0;cursor:pointer}button:disabled{opacity:.5}a{display:inline-flex;align-items:center;color:inherit}label{display:block;margin-top:14px}select,input{background:white;color:#20352e;border:1px solid #20352e66}progress{width:100%;height:22px;accent-color:var(--tone)}#status{min-height:24px}#amount{font-size:40px;font-weight:700}button:focus-visible,select:focus-visible,a:focus-visible{outline:3px solid #df9325;outline-offset:4px}.wall #controls{display:none}#giving-link[hidden],[hidden]{display:none!important}@media(max-width:650px){main{display:block;padding:72px 22px 24px}h1{font-size:46px}.panel{margin-top:24px;padding:22px}#count{font-size:clamp(28px,9vw,46px)}li{font-size:14px}}@media(max-height:520px) and (min-width:651px){main{padding:65px 25px 20px;gap:22px}h1{font-size:38px}.panel{padding:18px}}
 </style><main><header><span id="connection"></span><h1></h1><p id="intro"></p><div id="goal"><p id="goal-label"></p><div><span id="amount"></span> / <span id="target"></span></div><progress></progress></div><ul id="entries" aria-live="polite"></ul></header><section class="panel"><div id="label"></div><div id="count" data-count>0</div><div id="controls"><p id="prompt"></p><label><span id="choice-label"></span><select id="choice"></select></label><label id="frequency"><span id="frequency-label"></span><select id="monthly"><option id="once" value="once"></option><option id="month" value="month"></option></select></label><button data-action></button><a id="giving-link" href="/shop/" target="_blank" rel="noopener"></a></div><p id="status" role="status"></p></section></main><script type="module" src="./assets/main.js"></script></html>

package/app-starters/giving/src/rules.ts

@@ -15,7 +15,7 @@ export default defineRules({
   },
   room: {
     rounds: { seconds: 0, breakSeconds: 0 }, bots: { keep: 0 },
-    join() { return { kind: 'participant', at: { x: 0, y: 0 } }; },
+    join() { return { kind: 'participant', at: { x: 0, y: 0, z: 0 } }; },
     on: { refresh(world) { world.shared.revision += 1; world.emit('refresh', { x: 0, y: 0 }, {}); } },
   },
 });

package/app-starters/giving/src/view.ts

@@ -1,74 +1,72 @@
 import app from '../app.json';
 import { openRoom } from '@homie-rocks/studio/rules/view';
 import type rules from './rules';
-import { createAppRecords, type AppRecord } from '@homie-rocks/studio/apps';
-import { randomId } from '@homie-rocks/studio/links';
-type Entry = { choice: string; status: string; amount: number; monthly: boolean };
+import { createShop, type ShopCatalog } from '@homie-rocks/studio/shop';
 const room = openRoom<typeof rules>();
-const net = room.net;
-const role = net.params.role ?? 'customer';
-const words: Record<string, string> = app.words;
-const config = app.starter;
+const shop = createShop();
 const $ = <T extends HTMLElement = HTMLElement>(s: string) => document.querySelector<T>(s)!;
-const records = createAppRecords<Entry>({ collection: 'entries' });
-let rows: AppRecord<Entry>[] = [], busy = false, ready = false, question = 0;
 const action = $<HTMLButtonElement>('[data-action]');
-document.body.className = role;
-document.body.style.setProperty('--tone', config.color);
-$('h1').textContent = app.name; $('#intro').textContent = app.blurb;
-$('#label').textContent = words.total; action.textContent = words.action;
-$('#choice-label').textContent = words.choice;
-$('#frequency-label').textContent = words.monthly;
-$('#once').textContent = words.once; $('#month').textContent = words.month;
-$('#giving-link').textContent = words.give;
-$('#giving-link').hidden = config.kind !== 'giving';
-$('#frequency').hidden = config.kind !== 'giving';
-$('#goal').hidden = config.kind !== 'giving';
-$('#controls').hidden = role === 'wall';
-const select = $<HTMLSelectElement>('#choice');
-function choices() {
- select.replaceChildren();
- const list = config.kind === 'quiz' ? config.questions[question]?.choices ?? [] : config.choices;
- for (const value of list) { const option = document.createElement('option'); option.value = value; option.textContent = value; select.append(option); }
- $('#prompt').textContent = config.kind === 'quiz' ? config.questions[question]?.text ?? words.finished : words.prompt;
- action.hidden = config.kind === 'quiz' && question >= config.questions.length;
-}
-choices();
+const choice = $<HTMLSelectElement>('#choice');
+const frequency = $<HTMLSelectElement>('#monthly');
+let catalog: ShopCatalog | undefined, busy = false;
+const wall = room.net.params.role === 'wall';
+document.body.className = room.net.params.role ?? 'customer';
+document.body.style.setProperty('--tone', app.starter.color);
+$('h1').textContent = app.name;
+$('#intro').textContent = app.blurb;
+$('#label').textContent = wall ? 'Give with us' : 'Your gift';
+$('#choice-label').textContent = 'Choose a gift';
+$('#frequency-label').textContent = 'Gift frequency';
+$('#once').textContent = 'One time'; $('#month').textContent = 'Monthly';
+$('#giving-link').textContent = 'Manage my gifts';
+$('#goal').hidden = true;
+$('#entries').hidden = true;
+$('#prompt').textContent = 'Choose what works for you. Payments go directly to our Stripe account.';
+const amountLabel = document.createElement('label'); amountLabel.textContent = 'Your amount';
+const amount = document.createElement('input'); amount.type = 'number'; amount.inputMode = 'decimal'; amountLabel.append(amount);
+choice.parentElement!.after(amountLabel);
+function selected() { return catalog?.items.find(i => i.id === choice.value); }
 function paint() {
- $('[data-count]').textContent = String(rows.length);
- const amount = rows.reduce((n, r) => n + r.data.amount, 0);
- $('#amount').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(amount);
- $('#target').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(config.goal);
- $<HTMLProgressElement>('progress').max = config.goal; $<HTMLProgressElement>('progress').value = amount;
- $('#goal-label').textContent = words.goal;
- action.disabled = busy || !ready;
- $('#entries').replaceChildren();
- for (const row of rows.slice(-6).reverse()) {
-  const li = document.createElement('li');
-  li.textContent = `${row.data.choice} · ${row.data.status}${row.data.monthly ? ' · ' + words.month : ''}`;
-  if (role === 'staff' && row.data.status !== words.done) {
-   const button = document.createElement('button'); button.textContent = words.complete;
-   button.onclick = () => { void records.update(row, { ...row.data, status: words.done }).then(refresh).catch(e => { $('#status').textContent = e.message; }); }; li.append(button);
-  }
-  $('#entries').append(li);
+ const item = selected();
+ amountLabel.hidden = item?.price !== 'choose';
+ action.disabled = busy || !catalog?.open || !item || item.way === 'closed';
+ action.textContent = frequency.value === 'month' ? 'Give monthly on Stripe' : 'Give on Stripe';
+ $('[data-count]').textContent = wall ? 'Thank you' : item?.shown ?? 'Preview';
+ if (item?.price === 'choose') {
+  const scale = catalog!.currencyScale;
+  amount.min = String((item.min ?? 0) / scale);
+  amount.max = item.max == null ? '' : String(item.max / scale);
+  amount.step = String(1 / scale);
  }
 }
-async function refresh() {
- try { rows = await records.list(); ready = true; paint(); net.playable(); }
- catch (error) { $('#status').textContent = (error as Error).message; }
+function options() {
+ choice.replaceChildren();
+ for (const item of catalog?.items ?? []) {
+  if (item.kind !== 'donation' || Boolean(item.interval) !== (frequency.value === 'month')) continue;
+  const option = document.createElement('option'); option.value = item.id; option.textContent = `${item.name} · ${item.shown}`; choice.append(option);
+ }
+ paint();
 }
+choice.onchange = paint; frequency.onchange = options;
 action.onclick = async () => {
+ const item = selected(); if (!item || !catalog?.open) return;
+ const value = item.price === 'choose' ? Math.round(Number(amount.value) * catalog.currencyScale) : undefined;
+ if (item.price === 'choose' && (!amount.value || !Number.isSafeInteger(value) || value! < (item.min ?? 0) || item.max != null && value! > item.max)) {
+  $('#status').textContent = 'Enter an amount within the displayed range.'; return;
+ }
  busy = true; paint();
  try {
-  const choice = select.value;
-  await records.create({ choice: config.kind === 'quiz' ? `${question + 1}. ${choice}` : choice, status: words.pending, amount: config.kind === 'giving' ? Number(choice) : 0, monthly: $<HTMLSelectElement>('#monthly').value === 'month' }, randomId());
-  $('#status').textContent = words.thanks;
-  if (config.kind === 'quiz') { question++; choices(); }
-  room.command('refresh', {}); await refresh();
- } catch (error) { $('#status').textContent = (error as Error).message; }
- finally { busy = false; paint(); }
+  // Opening Checkout is not a payment. Only Stripe's verified webhook records a gift.
+  const opened = await shop.buy(item.id, 1, value);
+  $('#status').textContent = opened ? 'Finish your gift on Stripe. Your receipt confirms payment.' : 'Open the shop to sign in or complete the steps for this gift.';
+  if (!opened) shop.open(item.id);
+ } finally { busy = false; paint(); }
 };
-room.on('refresh', () => { void refresh(); });
-net.on('link', () => { void refresh(); });
-setInterval(() => { $('#connection').textContent = net.link === 'online' ? words.live : words.reconnecting; void refresh(); }, 2000);
+async function refresh() {
+ catalog = await shop.catalog(); options();
+ $('#status').textContent = wall ? 'Join on your phone to choose a one-time or monthly gift.' : catalog.open ? 'Monthly gifts renew until you cancel through Stripe. Manage your gifts using the link below.' : 'Preview — giving is unavailable until the organisation connects Stripe.';
+ $('#connection').textContent = room.net.link === 'online' ? 'Together · live' : 'Connecting…';
+ room.net.playable();
+}
+shop.on('closed', () => { void refresh(); });
 void refresh();

package/apps/APPS.md

@@ -49,7 +49,7 @@ Parts import exactly as games do (`@parts/<id>` or `@parts/<host>/<id>`), with t
 
 ## Shop button on the screen
 
-An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to hide this button (merge with any existing screen settings). The room panel and your own shop buttons still work. Closed shops, kids policies and an empty selection show no button.
+An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to disable the experience’s shop (merge with any existing screen settings). Keep it true or omitted when your app uses its own `createShop` buttons; false also refuses their checkout bridge requests. Closed shops, kids policies and an empty selection show no button.
 
 ```ts
 import { createShop } from '@homie-rocks/studio/shop';
@@ -103,3 +103,27 @@ and the `app_records` tool schema explain the contract; validation errors name i
 Live and local unconnected shop/giving pages display the declared items and amounts
 with disabled payment controls. They say they are not taking payments yet. A fresh
 `/shop/` has an empty preview; an authored shop page still takes precedence.
+
+## Booking capacity
+
+See `shop/SHOP.md` for “book a tune and hold the slot”. A collection opts in with
+`booking: {slots: 'slots', item: 'full-tune'}`. Slots are ordinary staff-managed
+records with integer `capacity`. Bookings are server-managed records created by
+`shop.book`; their public data is only slot, quantity and state. Keep personal
+information in a separate private collection. Public roles must not have write
+capabilities for slots or bookings. Staff movement is a versioned record update
+containing only `slot`; confirmation and release follow verified Checkout state.
+The default keyless connection uses one Payment Link per published slot. Call
+`stripe_bookings_sync` after publishing/changing slots. Pending checkout does not
+block others; payment secures the seat. Use record.booking.full/available/synced
+for slot display. Read SHOP.md for the complete manifest and limitations.
+
+The giving starter now reads the actual shop donation options with `shop.catalog()`.
+`shop init --giving --currency CAD` includes $20 monthly; `app new giving --from giving`
+opens Checkout for the selected amount and frequency. A disconnected shop displays
+a disabled preview. No intention record or unverified collected total is created.
+Use the Manage my gifts link for the buyer-owned Stripe portal in the shop.
+
+Records-only apps support the same shop bridge as room apps. In the sandboxed
+view, use `createShop({target: parent})` to send checkout and booking requests to
+the authenticated outer shell; a room simulation is not required for payments.

package/apps/apps.ts

@@ -1,6 +1,6 @@
 /** Lasting records through the same sandbox bridge used by saves and the shop. */
 import { randomId } from '../links/links.mjs';
-export interface AppRecord<T> { id: string; data: T; version: number; updatedAt: number }
+export interface AppRecord<T> { id: string; data: T; version: number; updatedAt: number; booking?: {full: boolean; available: number; synced: boolean} }
 export function createAppRecords<T extends Record<string, unknown>>({ collection }: { collection: string }) {
   if (!/^[a-z][a-z0-9-]{0,39}$/.test(collection)) throw new Error('invalid collection');
   const pending = new Map<string, { resolve: (v: any) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();

package/bin/homie-studio.mjs

@@ -788,7 +788,11 @@ function print(result) {
         `Written: ${result.file}`);
       break;
     case 'check':
-      if (result.kind === 'app') { lines.push(`PASS: app ${result.game ?? ''}: wall and two phones shared an action; reconnect ${result.reconnect ? 'passed' : 'failed'}.`, `  ${result.before} → ${result.after}`); break; }
+      if (result.kind === 'app') {
+        if (result.needs?.length) lines.push(`PASS: app ${result.game ?? ''}: ${result.needs.length} Codex needs checked on ${(result.surfaces ?? []).join(', ')}.`);
+        if (result.reconnect) lines.push(`PASS: app ${result.game ?? ''}: wall and two phones shared an action; reconnect passed.`, `  ${result.before} → ${result.after}`);
+        break;
+      }
       if (result.results) { for (const r of result.results) lines.push(`${r.game}: PASS at ${r.site}: room ${r.room}, round ${r.round?.n} (${r.round?.humans} humans, ${r.round?.bots} bots), connection ${r.uninterrupted === true ? 'uninterrupted' : r.uninterrupted === false ? 'INTERRUPTED' : 'unknown'}`); break; }
       if (result.site) lines.push(`Checked ${result.local ? 'this studio\'s own build' : 'the site'} at ${result.site}.`);
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,

package/guides/app/SKILL.md

@@ -108,6 +108,8 @@ await shop.buy('full-tune', 1, undefined, { reference: booking.id });
 await shop.checkout({ reference: booking.id });
 ```
 
+On the default keyless connection, `shop.checkout({ reference: 'table-7' })` opens the studio's synced Stripe menu: the guest sets quantities on Stripe's page and `order.paid.data.lines` carries what was actually paid. A slot with capacity uses `shop.book` (see below), not `shop.buy`. Monthly gifts and memberships are recurring items on their own links. None of these needs a key.
+
 These retain their existing boolean result: true means checkout opened, not payment received. The durable `order.paid` function event includes `data.order` (the order ID), `data.reference` (your reference or null), and `data.app` (the app ID). A verified provider payment emits it. Validate the referenced record, expected amount/currency and app, deduplicate by event/order ID, then fulfil that booking or add that gift to the confirmed meal table. A buyer supplies the reference: it is correlation, never proof they own a private record or paid the expected price. Do not put personal data in it.
 
 For each offer, build the promised action and fulfilment, not just a price label: a naming purchase needs the proposed name and the staff/customer outcome; a ticket needs its receipt. Keep an unpaid request distinct when charging is unavailable.
@@ -175,7 +177,7 @@ Scaffold businesses with `new <folder> --kind business`; causes with `--kind cau
 
 For giving, set the studio currency and run `shop init --giving --currency CAD` (use the organisation’s currency). It creates one-time/monthly suggested gifts. The owner supplies `giving.receiptText` in shop.json; Homie supplies no legal or tax text. Before Stripe is connected, local /shop/ previews items and prices with checkout disabled. Run the connection step yourself; the owner approves their Stripe account in the browser.
 
-Booking requests are not capacity reservations. Calendar availability and seat capacity are the next app capability; do not promise them.
+Use `shop.book` and the booking collection declaration in SHOP.md. Default keyless booking links show pending while paying; an unpaid guest does not block others. Stripe limits completed sessions to capacity. The owner’s AI syncs published/changed slots with `stripe_bookings_sync`. Say “Pay to secure your seat.” Exclusive unpaid holds require the explicitly selected optional keyed connection.
 
 
 ## Tell my AI when a booking comes in
@@ -256,3 +258,13 @@ and the `app_records` tool schema explain the contract; validation errors name i
 Live and local unconnected shop/giving pages display the declared items and amounts
 with disabled payment controls. They say they are not taking payments yet. A fresh
 `/shop/` has an empty preview; an authored shop page still takes precedence.
+
+The giving starter now reads the actual shop donation options with `shop.catalog()`.
+`shop init --giving --currency CAD` includes $20 monthly; `app new giving --from giving`
+opens Checkout for the selected amount and frequency. A disconnected shop displays
+a disabled preview. No intention record or unverified collected total is created.
+Use the Manage my gifts link for the buyer-owned Stripe portal in the shop.
+
+For a records-only booking app, use `createShop({target: parent})` inside its
+sandboxed view. The shell includes the authenticated shop bridge; do not add a
+room simulation merely to make a payment button work.

package/guides/shop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shop
-description: Sell things in a Homie studio's games with the studio's OWN Stripe - a supporter pack, cosmetics, a season pass, a one-time unlock, a tip - in real money, with Stripe Checkout, Stripe Tax or Stripe Managed Payments, refunds from the office, and optional studio policies with an open default; set up with Stripe's own agent tools (Stripe's MCP server and skills) with one browser approval and Payment Links by default, no human-handled key and no API key in the Worker. Use when someone asks to sell something, add a shop or store, take payments or donations, make money from a game, set up or connect Stripe, make the products in Stripe, asks "how are sales?", about tax or Managed Payments, to add a supporter badge, refund a player, or about chargebacks.
+description: Sell things in a Homie studio's games with the studio's OWN Stripe - a supporter pack, cosmetics, a season pass, a one-time unlock, a tip, a round of several items to a table, a paid booking with slot capacity, monthly giving or a membership - in real money, with Stripe Checkout, Stripe Tax or Stripe Managed Payments, refunds from the office, and optional studio policies with an open default; set up with Stripe's own agent tools (Stripe's MCP server and skills) with one browser approval and Payment Links by default, no human-handled key and no API key in the Worker. Use when someone asks to sell something, add a shop or store, take payments or donations, take paid bookings, set up monthly giving or memberships, make money from a game, set up or connect Stripe, make the products in Stripe, asks "how are sales?", about tax or Managed Payments, to add a supporter badge, refund a player, or about chargebacks.
 compatibility: The studio's own current toolkit with stripe_login or shop connect --renew, Wrangler, and the official Stripe CLI. Stripe's own agent plugin (MCP and skills) is optional for catalog work and analytics.
 metadata:
   providers: stripe
@@ -43,13 +43,18 @@ The Worker redirects buyers to Stripe and grants purchases from signed events. N
 Homie service or API key is needed when someone pays. Run connect again after editing shop.json;
 it updates changed objects and archives removed ones. Existing connections need no new approval.
 
-Only when the person asks for combined carts, spending reservations, custom checkout expiry,
-automatic recovery of lost webhooks or office refunds, explain one sentence:
-“The fuller connection adds combined carts, spending limits, automatic recovery and refunds here.”
-A pre-existing Worker key selects that path automatically. Never silently select `--manual` or ask
-for a key: explain its remaining Dashboard step only if the person explicitly chooses that route.
-Before relying on spending restrictions after switching, deactivate old Payment Links with the approved CLI and resolve in-flight checkouts; a credential change does not cancel them.
-`shop connect` selects keyless again and removes an existing Worker API key after saving the links.
+Keyless also supports mixed fixed-price menus, capacity-limited booking links and fixed
+monthly gifts/memberships. Read SHOP.md's 0.51 examples before implementing these.
+Guests choose menu quantities on Stripe. Booking links show pending without holding
+an unpaid seat; Stripe's completion limit is the hard capacity. Use
+`stripe_bookings_sync` after publishing/changing slots (complete manifest), or update
+`.studio/booking-slots.json` and rerun connect. Sync creates the no-code portal login
+through the API; no Dashboard toggle is needed. Never ask for a key.
+
+Only when explicitly selected, an existing Worker key plus
+`STRIPE_CHECKOUT_MODE=sessions` enables exact app carts, exclusive expiring holds,
+spending reservations, provider reads and runtime refunds. A key alone never selects
+it. Default connect selects links and removes the runtime key.
 
 ## Never
 
@@ -124,7 +129,7 @@ No toolkit amount or duration ceiling applies. Stripe currency constraints and s
 A refund window includes used items unless `policy.refundUsedItems` is false. A player cannot refund a tip;
 the owner can refund through Stripe; keyed shops also offer office refunds. Guest purchases stay owned when the buyer signs in later.
 
-For keyed shops, carts: `shop.add(item, quantity, amount?)`, then `shop.checkout()`; `shop.buy(item)` buys directly.
+For menus or explicitly keyed shops, carts: `shop.add(item, quantity, amount?)`, then `shop.checkout()`; `shop.buy(item)` buys directly.
 Free and paid lines share one order and one Stripe Session. The studio chooses where to open the shop.
 
 ## The first sale (the acceptance)
@@ -133,17 +138,11 @@ In test mode: buy the supporter pack on a phone with Stripe's test card `4242 42
 see the badge on the account page and beside the name in a room (from the next room the player joins), refund it
 in Stripe (or through the connected AI), and see the badge go. With the protective preset, a kids server's room shows no shop and `/<game>/tv` shows only a code.
 
-Keyless purchases buy one item type at a time, with quantity confirmed on Stripe. Tips choose the
-amount on Stripe and always have quantity one. Free orders grant locally without Stripe.
-Refund and dispute snapshots are stored by provider object ID and tolerate retries and reordering.
-A missing webhook stays pending: ask Stripe to resend the event (Dashboard or official CLI
-`stripe events resend <event> --webhook-endpoint <endpoint>`). Never grant based on the return URL.
-Payment Links are public and reusable; do not promise that local sale dates, repeat-purchase or
-eligibility checks revoke a previously opened link. Deactivation stops new sessions after re-sync;
-already opened sessions may still complete. Strict pre-payment enforcement needs the keyed way.
-Stripe always enables Adaptive Pricing on Payment Links; the buyer can use the original currency.
-Keyless has no per-session expiry or provider-read reconciliation. The keyed path retains both,
-carts, cap reservations, local refunds. Managed Payments is supported on Payment Links when Stripe enables it for the account. The studio chooses its needs.
+Keyless menus offer several fixed-price items with adjustable quantities on Stripe.
+Custom amounts and monthly preset gifts have their own links. Free orders stay local.
+A missing webhook stays pending; ask Stripe to resend it. Never grant from a return
+URL. Keyless has no exclusive unpaid hold or custom session expiry. Consult SHOP.md
+for menu limits, signed invoice fulfilment, slot sync and honest pending/full wording.
 
 For a cause, use `shop init --giving --currency <organisation currency>`: one-time and monthly suggested gifts, no badge or game access. Read `giving.receiptText` from the organisation; leave it empty until provided. Local /shop/ previews before Stripe. Monthly gifts use the existing keyless Payment Links connection and Stripe handles renewals.
 
@@ -152,3 +151,25 @@ For a cause, use `shop init --giving --currency <organisation currency>`: one-ti
 Create the booking/ticket/gift intention first. `shop.buy('full-tune', 1, undefined, { reference: booking.id })` or `shop.checkout({ reference: booking.id })` sends the app's own reference through checkout. Existing boolean returns are unchanged: checkout opened is not paid. The verified durable `order.paid` event carries `data.order`, `data.reference` (null if omitted) and `data.app`. Reopened Payment Links retain the reference. A reference is buyer-supplied correlation, not authorization: verify the record, app, amount and currency, deduplicate by event/order ID, then fulfil it. Keep personal data out of references. Before Stripe is connected, local prices and unpaid requests can be demonstrated; actual payment and recurring collection remain unverified. Test events must be labelled simulations.
 
 For referrals, use Stripe Connect to split payments or a Stripe-based affiliate service; Homie builds none.
+
+## Earning with the keyless default
+
+Read SHOP.md for a round to table 7, `shop.book` and $20 monthly giving.
+Menus let guests choose several quantities on Stripe; signed invoices provide actual
+paid lines and the app reference. Slot Payment Links enforce completed-session
+capacity. Pending guests do not block others. The owner's AI syncs published slots
+with `stripe_bookings_sync`; the app shows Full from verified availability.
+Recurring Prices provide monthly preset gifts and memberships. Connect enables the
+no-code customer portal login through Stripe's API, without a Dashboard toggle.
+Paid invoice periods govern membership; failed renewal never extends it.
+The giving starter opens real keyless Checkout and shows a disabled preview before
+connection. It never counts an intention as a gift.
+
+For real sandbox acceptance use `startKeylessStripeSandbox` from the installed
+`lib/dev-stripe-sandbox.mjs` as documented in SHOP.md. Only its explicitly authorised
+sandbox CLI profile creates Stripe objects. No Worker API key. Keep returned signing
+secret bindings private and temporary. Complete payments with Stripe's published
+CLI fixture/API tokens; never enter card digits into a page. The local listener is
+for development; production sends signed events directly to the studio's webhook.
+The optional keyed fixture remains available for testing explicitly selected session
+checkout. Label offline fixtures simulations.

package/lib/dev-stripe-fixture.mjs

@@ -0,0 +1,37 @@
+/** Offline Checkout fixture for local acceptance. No Stripe account, cards, or
+ * real credentials. This is a simulator, not evidence of Stripe sandbox access. */
+import { createServer } from 'node:http';
+import { signPayload } from '../worker/stripe.mjs';
+export async function startStripeFixture({ origin }) {
+  const target=new URL(origin);
+  if (target.protocol!=='http:' || !['localhost','127.0.0.1'].includes(target.hostname)) throw new Error('Fixture requires a loopback studio');
+  const sessions=new Map(), idempotency=new Map(); let seq=0, base;
+  const key='rk_test_homieLocalFixture', secret='whsec_homieLocalFixture';
+  const server=createServer(async(req,res)=>{
+    const send=(data,status=200)=>{res.writeHead(status,{'content-type':'application/json'});res.end(JSON.stringify(data));};
+    try {
+      const url=new URL(req.url,base);let body='';for await(const chunk of req){body+=chunk;if(body.length>262144)return send({error:{message:'fixture body limit'}},413);}
+      const form=new URLSearchParams(body);
+      if(url.pathname==='/v1/checkout/sessions'&&req.method==='GET') return send({data:[...sessions.values()].filter(s=>s.created>=Number(url.searchParams.get('created[gte]')??0)),has_more:false});
+      if(url.pathname==='/v1/checkout/sessions'&&req.method==='POST') {
+        const idem=req.headers['idempotency-key'];if(idem&&idempotency.has(idem))return send(sessions.get(idempotency.get(idem)));
+        const id=`cs_fixture_${++seq}`,lines=[];
+        for(let i=0;form.has(`line_items[${i}][quantity]`);i++) {const p=`line_items[${i}]`;lines.push({quantity:Number(form.get(`${p}[quantity]`)),amount_subtotal:Number(form.get(`${p}[quantity]`))*Number(form.get(`${p}[price_data][unit_amount]`)),name:form.get(`${p}[price_data][product_data][name]`)});}
+        const s={id,object:'checkout.session',livemode:false,mode:form.get('mode'),status:'open',payment_status:'unpaid',created:Math.floor(Date.now()/1000),expires_at:Number(form.get('expires_at')),currency:form.get('line_items[0][price_data][currency]'),amount_subtotal:lines.reduce((n,l)=>n+l.amount_subtotal,0),metadata:{homie:form.get('metadata[homie]'),order:form.get('metadata[order]')},client_reference_id:form.get('client_reference_id'),url:`${base}/checkout/${id}`,success_url:form.get('success_url'),cancel_url:form.get('cancel_url'),lines};
+        s.amount_total=s.amount_subtotal;sessions.set(id,s);if(idem)idempotency.set(idem,id);return send(s);
+      }
+      const api=/^\/v1\/checkout\/sessions\/(cs_fixture_\d+)(\/expire)?$/.exec(url.pathname);
+      if(api){const s=sessions.get(api[1]);if(!s)return send({error:{code:'resource_missing'}},404);if(api[2]){if(s.status!=='open')return send({error:{message:'Session is not open'}},400);s.status='expired';await hook(s,'checkout.session.expired');}return send(s);}
+      const page=/^\/checkout\/(cs_fixture_\d+)$/.exec(url.pathname);
+      if(page){const s=sessions.get(page[1]);if(!s)return send({},404);res.writeHead(200,{'content-type':'text/html'});return res.end(`<!doctype html><meta name="viewport" content="width=device-width"><title>Offline Stripe fixture</title><style>body{font:20px system-ui;max-width:32em;margin:3em auto;padding:1em}button{padding:1em;font:inherit}</style><h1>Offline Stripe test fixture</h1><p>This is a simulation. No card or money is used.</p><p>${s.amount_total/100} ${s.currency.toUpperCase()}</p><form method="post" action="/complete/${s.id}"><button>Simulate successful test payment</button></form><form method="post" action="/expire/${s.id}"><button>Simulate expiry</button></form>`);}
+      const finish=/^\/(complete|expire)\/(cs_fixture_\d+)$/.exec(url.pathname);
+      if(finish&&req.method==='POST'){const s=sessions.get(finish[2]);if(!s||s.status!=='open')return send({error:'not open'},409);const paid=finish[1]==='complete';s.status=paid?'complete':'expired';s.payment_status=paid?'paid':'unpaid';if(paid){s.payment_intent={id:`pi_fixture${seq}`,status:'succeeded',latest_charge:{id:`ch_fixture${seq}`,created:Math.floor(Date.now()/1000),refunded:false,disputed:false}};if(s.mode==='subscription'){s.subscription=`sub_fixture${seq}`;s.customer=`cus_fixture${seq}`;}}await hook(s,paid?'checkout.session.completed':'checkout.session.expired');res.writeHead(303,{location:(paid?s.success_url:s.cancel_url).replace('{CHECKOUT_SESSION_ID}',s.id)});return res.end();}
+      if(url.pathname.startsWith('/v1/payment_intents/')) { const payment=[...sessions.values()].map(s=>s.payment_intent).find(p=>p?.id===url.pathname.split('/').at(-1));return payment?send(payment):send({error:{code:'resource_missing'}},404); }
+      if(url.pathname==='/v1/refunds')return send({data:[],has_more:false});
+      return send({error:{message:'Unsupported offline fixture operation'}},404);
+    }catch{send({error:{message:'Offline fixture failed'}},500);}
+  });
+  async function hook(session,type){const event={id:`evt_fixture_${session.id}_${type}`,type,livemode:false,created:Math.floor(Date.now()/1000),data:{object:session}};const payload=JSON.stringify(event),t=event.created;const response=await fetch(`${target.origin}/api/shop/hook`,{method:'POST',headers:{'stripe-signature':`t=${t},v1=${await signPayload(payload,secret,t)}`},body:payload});if(!response.ok)throw new Error('Studio rejected fixture webhook');}
+  await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));base=`http://127.0.0.1:${server.address().port}`;
+  return {base,bindings:{STRIPE_CHECKOUT_MODE: 'sessions', STRIPE_KEY:key,STRIPE_WEBHOOK_SECRET:secret,STRIPE_API_BASE:base},close:()=>new Promise(resolve=>server.close(resolve))};
+}