@homie-rocks/studio 0.51.4 → 0.51.6

package/lib/shop-mcp.mjs

@@ -0,0 +1,58 @@
+/** Pure, incremental Stripe plan. The owner's AI supplies public API reads; no Stripe transport here. */
+import {createHash} from 'node:crypto';
+import {existsSync, readFileSync, mkdirSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {readShop, SHOP_HOOK_EVENTS} from './shop.mjs';
+import {readStudio, siteUrl} from './studio.mjs';
+import {reconcilePaymentLinks} from './shop-links.mjs';
+import {fullerReason, LINKS_STRIPE_VERSION} from '../worker/shop-links.mjs';
+const hash = x => createHash('sha256').update(JSON.stringify(x)).digest('hex');
+export const readKey = (path, params) => JSON.stringify([path,Object.fromEntries(Object.entries(params).sort(([a],[b])=>a.localeCompare(b)))]);
+export async function shopMcpPlan(root, {observations = [], mode = 'test', url, slots, verify = false} = {}) {
+  const checked=readShop(root);
+  if(!checked.ok || checked.absent) return {ok:false,why:'Create and check shop.json first.'};
+  if(!['test','live'].includes(mode))throw new Error('Choose test or live mode');
+  const reason=fullerReason(checked.shop);
+  if(reason)return {ok:false,why:reason+' Adjust those settings to use Payment Links; no key is required.'};
+  const studio=readStudio(root), address=url??siteUrl(root);
+  if(!address)return {ok:false,needs:'site',why:'Supply the local test URL, or deploy the studio before planning its public checkout links.'};
+  const site=new URL(address).origin;
+  const local=new URL(site).protocol==='http:';
+  if(local && (mode!=='test' || !/^(localhost|127\.0\.0\.1|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)$/.test(new URL(site).hostname)))throw new Error('Local checkout requires a private HTTP address and test mode');
+  if(!local && new URL(site).protocol!=='https:')throw new Error('Use the studio HTTPS address');
+  const bookingSlots=slots??(existsSync(join(root,'.studio','booking-slots.json'))?JSON.parse(readFileSync(join(root,'.studio','booking-slots.json'),'utf8')):[]);
+  const slug=local?'local-'+createHash('sha256').update(root).digest('hex').slice(0,16):studio.slug;
+  // Reject secrets before persisting observations. Webhook creation is never part of this plan.
+  if(/(?:whsec_|[rs]k_(?:test|live)_)/.test(JSON.stringify(observations)))throw new Error('Supply only public catalog reads, never credentials or webhook creation responses');
+  const api=async(method,path,params={},idempotency)=>{
+    if(method!=='GET')throw {next:{method,path,params,...(idempotency?{idempotency}:{}),retry:'Read fresh before retrying; updates set desired fields and are idempotent.'}};
+    const found=observations.find(o=>readKey(o.path,o.params??{})===readKey(path,params));
+    if(!found)throw {next:{method,path,params}};
+    const body=found.body;
+    if(!body || body.error || body.livemode !== undefined && body.livemode !== (mode==='live') || body.data?.some(o=>o.livemode !== undefined && o.livemode !== (mode==='live')))throw new Error('Stripe read has an error or wrong mode');
+    return body;
+  };
+  const base={command:verify?'shop verify':'shop plan',mode,site,apiVersion:LINKS_STRIPE_VERSION,
+    webhook:{method:'POST',path:'/v1/webhook_endpoints',private:true,params:{url:`${site}/api/shop/hook`,enabled_events:SHOP_HOOK_EVENTS,api_version:LINKS_STRIPE_VERSION,metadata:{homie:'shop-v1'},description:'Studio shop'}}};
+  try {
+    const catalog=await reconcilePaymentLinks({api,shop:checked.shop,slug,site,mode,bookingSlots,verifyObjects:true});
+    if(checked.shop.items.some(item=>item.interval) && !/^https:\/\/billing\.stripe\.com\//.test(catalog.config.portal??''))throw new Error('Invalid Stripe portal URL');
+    const result={...base,ok:true,verified:true,verifiedAt:new Date().toISOString(),...catalog,local, fingerprint:hash({shop:checked.shop,bookingSlots,site,mode,catalog})};
+    return result;
+  } catch(e) {
+    if(!e.next)throw e;
+    return {...base,ok:!verify,verified:false,next:e.next,instructions:e.next.method==='GET'?'Read through Stripe MCP; append {path,params,body} to observations, including every pagination page.':'Perform this exact operation through Stripe MCP. Then discard observations and read fresh before planning again. Do not create the webhook through MCP.'};
+  }
+}
+export async function saveMcpVerification(root, options) {
+  const result=await shopMcpPlan(root,{...options,verify:true});
+  if(result.verified) {
+    if(result.local) {
+      const {saveLocalStripe}=await import('./shop-listen.mjs');
+      saveLocalStripe(root,{STRIPE_CHECKOUT_MODE:'links',STRIPE_SHOP_LINKS:'base64:'+Buffer.from(JSON.stringify(result.config)).toString('base64')});
+    }
+    mkdirSync(join(root,'.studio'),{recursive:true});
+    writeFileSync(join(root,'.studio','stripe-mcp.json'),JSON.stringify({options,result},null,2));
+  }
+  return result;
+}

package/lib/stripe-connect.mjs

@@ -72,6 +72,10 @@ export function completionArgs(step) {
 }
 
 export async function shopConnect(root, options = {}) {
+  const fail=(...args)=>{
+    const result=failure(...args);
+    return options.webhookOnly?{...result,command:'shop webhook',why:result.why.replaceAll('shop connect','shop webhook')}:result;
+  };
   if (options.manual || options.fromClipboard) {
     const result = await shopConnectManual(root, options);
     if (result.ok) rmSync(join(receiptDir(root, options.storage ?? receiptHome()), 'test.json'), { force: true });
@@ -81,19 +85,32 @@ export async function shopConnect(root, options = {}) {
     storage = receiptHome(), wrangler = null } = options;
   const mode = live ? 'live' : 'test';
   const checked = readShop(root);
-  if (!checked.ok || checked.absent) return failure('shop', 'Create and check shop.json first: homie-studio shop init, then shop check.');
-  if (options.managed === true && checked.shop.till !== 'stripe-managed') return failure('shop-settings', 'For Managed Payments, set shop.json till to stripe-managed and deploy that choice before connecting. Stripe’s own eligibility and terms still apply.');
+  if (!checked.ok || checked.absent) return fail('shop', 'Create and check shop.json first: homie-studio shop init, then shop check.');
+  if (options.managed === true && checked.shop.till !== 'stripe-managed') return fail('shop-settings', 'For Managed Payments, set shop.json till to stripe-managed and deploy that choice before connecting. Stripe’s own eligibility and terms still apply.');
+  let catalog, mcpAccount;
+  if (options.webhookOnly) {
+    try {
+      const {saveMcpVerification} = await import('./shop-mcp.mjs');
+      const saved=JSON.parse(readFileSync(join(root,'.studio','stripe-mcp.json'),'utf8'));
+      if(!saved.result?.verifiedAt || Date.now()-Date.parse(saved.result.verifiedAt)>15*60_000) return fail('verify','Run shop verify with fresh Stripe MCP reads before installing the webhook (verification is valid for 15 minutes).');
+      const verified=await saveMcpVerification(root,saved.options);
+      if(!verified.verified || verified.local || verified.mode!==mode || verified.site!==new URL(siteUrl(root)).origin) return fail('verify','Run shop verify with fresh Stripe MCP reads for this site and mode first.');
+      mcpAccount=saved.options.account;
+      if(!/^acct_[A-Za-z0-9]+$/.test(mcpAccount??''))return fail('account','Verify with the Stripe MCP account ID first.');
+      catalog={config:verified.config,retire:verified.retire};
+    } catch { return fail('verify','Run shop verify with fresh Stripe MCP reads for this site first.'); }
+  }
   const id = hash(realpathSync(root)).slice(0, 24);
-  const profile = `homie-${id}`;
+  const profile = options.profile ?? `homie-${id}`;
   const dir = join(storage, id);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   // Reuse the toolkit’s process-aware lock, in the private receipt folder. Dead processes do not strand setup.
   const lock = lockDeploy(dir);
-  if (!lock.ok) return failure('busy', 'Stripe connection is already running for this studio. Wait for that command to finish.');
+  if (!lock.ok) return fail('busy', 'Stripe connection is already running for this studio. Wait for that command to finish.');
   try {
     const cli = (args) => exec(['--project-name', profile, ...args], { cwd: root });
     const installed = await cli(['--version']);
-    if (installed.code !== 0) return failure('stripe-cli', 'Install Stripe’s official CLI, then run shop connect again.', { next: ['npm install -g @stripe/cli@latest'] });
+    if (installed.code !== 0) return fail('stripe-cli', 'Install Stripe’s official CLI, then run shop connect again.', { next: ['npm install -g @stripe/cli@latest'] });
 
     // A read both checks existing credentials and lets Stripe refresh its OAuth session itself.
     let probe = renew ? { code: 1 } : await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
@@ -102,21 +119,25 @@ export async function shopConnect(root, options = {}) {
       const login = json(start.stdout);
       const complete = completionArgs(login?.next_step);
       if (start.code !== 0 || !stripeURL(login?.browser_url) || !complete || !/^[a-zA-Z0-9 -]{1,100}$/.test(login?.verification_code ?? '')) {
-        return failure('stripe-login', 'Stripe could not start browser approval. Update the official Stripe CLI and try shop connect again. An account administrator may need to enable CLI access in Stripe’s MCP and CLI access settings.' + stripeReason(start, 'login'));
+        return fail('stripe-login', 'Stripe could not start browser approval. Update the official Stripe CLI and try shop connect again. An account administrator may need to enable CLI access in Stripe’s MCP and CLI access settings.' + stripeReason(start, 'login'));
       }
       log(`Approve your studio’s Stripe account in your browser. Pairing code: ${login.verification_code}. ${login.browser_url}`);
       open(login.browser_url);
       const finished = await cli(complete);
-      if (finished.code !== 0) return failure('stripe-login', 'Stripe approval did not finish. Run shop connect again when ready.' + stripeReason(finished, 'login completion'));
+      if (finished.code !== 0) return fail('stripe-login', 'Stripe approval did not finish. Run shop connect again when ready.' + stripeReason(finished, 'login completion'));
 
       probe = await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
-      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return failure('stripe-access', 'Stripe is signed in but cannot read Products in the requested mode. Review the account, sandbox and permissions in Stripe, then run shop connect --renew again.' + stripeReason(probe, 'GET /v1/products'));
+      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return fail('stripe-access', 'Stripe is signed in but cannot read Products in the requested mode. Review the account, sandbox and permissions in Stripe, then run shop connect --renew again.' + stripeReason(probe, 'GET /v1/products'));
+    }
+    if (options.webhookOnly) {
+      const accountResult=await cli(['get','/v1/account',...(live?['--live']:[])]);
+      if(accountResult.code!==0 || json(accountResult.stdout)?.id!==mcpAccount) return fail('account','Stripe CLI and MCP must select the same account. Verify with the MCP account ID first.');
     }
     const site = siteUrl(root);
-    if (!site) return failure('deploy', 'Stripe is connected on this computer. Deploy the studio with studio_deploy (Cloudflare approval first if needed), then run shop connect again.', { mode, connected: true });
+    if (!site) return fail('deploy', 'Stripe is connected on this computer. Deploy the studio with studio_deploy (Cloudflare approval first if needed), then run shop connect again.', { mode, connected: true });
     let target;
-    try { target = new URL(site); } catch { return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.'); }
-    if (target.protocol !== 'https:' || target.username || target.password || /^(localhost|127\.|\[::1\])/.test(target.hostname)) return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.');
+    try { target = new URL(site); } catch { return fail('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.'); }
+    if (target.protocol !== 'https:' || target.username || target.password || /^(localhost|127\.|\[::1\])/.test(target.hostname)) return fail('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.');
     const api = async (method, path, params, idempotency) => {
       const args = [method.toLowerCase(), path, '--stripe-version', LINKS_STRIPE_VERSION, ...(live ? ['--live'] : []), ...(idempotency ? ['--idempotency', idempotency] : [])];
       for (const [k, v] of formEncode(params)) args.push('-d', `${k}=${v}`);
@@ -128,20 +149,20 @@ export async function shopConnect(root, options = {}) {
       return body;
     };
     const reason = fullerReason(checked.shop);
-    if (reason) return failure('fuller-checkout', reason, { mode, connected: true });
+    if (reason) return fail('fuller-checkout', reason, { mode, connected: true });
     const studio = readStudio(root);
     const w = wrangler ?? runner(root, studio.cloudflare?.accountId ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
     const receiptFile = join(dir, `${mode}.json`);
     const receipt = existsSync(receiptFile) ? json(readFileSync(receiptFile, 'utf8')) : null;
-    const result = await syncPaymentLinks({ root, api, shop: checked.shop, slug: studio.slug, site: target.origin, mode, w, receipt,
+    const result = await syncPaymentLinks({ catalog, root, api, shop: checked.shop, slug: studio.slug, site: target.origin, mode, w, receipt,
       bookingSlots: options.bookingSlots ?? (existsSync(join(root,'.studio','booking-slots.json')) ? JSON.parse(readFileSync(join(root,'.studio','booking-slots.json'),'utf8')) : []),
       saveReceipt: (record) => {
         writeFileSync(`${receiptFile}.tmp`, JSON.stringify(record), { mode: 0o600 });
         renameSync(`${receiptFile}.tmp`, receiptFile);
       } });
-    return { ...result, profile };
+    return { ...result, command:options.webhookOnly?'shop webhook':result.command, profile };
   } catch (e) {
     const said = e?.stripeReason ?? '';
-    return failure('stripe-setup', 'Stripe setup could not finish. Check the studio’s Stripe session and Products, Prices, Payment Links and Webhook Endpoints write permissions, and the Cloudflare login, then run shop connect again. No credentials were printed.' + said);
+    return fail('stripe-setup', 'Stripe setup could not finish. Check the studio’s Stripe session and Products, Prices, Payment Links and Webhook Endpoints write permissions, and the Cloudflare login, then run shop connect again. No credentials were printed.' + said);
   } finally { lock.release(); }
 }

package/lib/template-history.json

@@ -3708,6 +3708,93 @@
      }
     }
    }
+  },
+  "0.51.5": {
+   "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": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": [
+      "0df5a5fe1833c624",
+      "43a3556be93d1235"
+     ],
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
+  },
+  "0.51.6": {
+   "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": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/upgrade-media.mjs

@@ -0,0 +1,13 @@
+/** Retire the exact guidance shipped by Homie without opening credential files. */
+export const RETIRED_MEDIA_GUIDANCE = "### Existing provider credentials\n\nThe tools read `FAL_KEY` or `ELEVENLABS_API_KEY` first, then the plain single-line\nkey in `~/.homie/keys/fal-key` or `~/.homie/keys/elevenlabs-key`. They also accept\n`~/.homie/workspace/fal-key` and `~/.homie/workspace/elevenlabs-key` from earlier\ninstalls. Checks name the source, never the key. Keep these files private (mode\n0600); never copy them into a studio. ElevenLabs also accepts its CLI browser\nsign-in and the existing Stripe Projects connection. Run the tool\u2019s `check`\nbefore declaring a provider disconnected.\n";
+export const OFFICIAL_MEDIA_GUIDANCE = `### Official media connections
+
+Use the official fal and ElevenLabs plugins in the AI client, with their browser sign-in.
+Homie never reads provider credentials. Cloudflare deploys use Wrangler login; official
+Cloudflare MCP tools inspect logs, Workers Issues and D1. Follow the matching toolkit's
+guides/studio-setup/references/OFFICIAL-MEDIA.md. Retired Homie generation scripts have
+no compatibility path. Keep existing assets and receipts; do not migrate credential files.
+`;
+export function upgradeMediaGuidance(text) {
+  return text.replace(RETIRED_MEDIA_GUIDANCE.trimEnd(), OFFICIAL_MEDIA_GUIDANCE.trimEnd());
+}

package/lib/upgrade.mjs

@@ -1,3 +1,4 @@
+import { upgradeMediaGuidance } from './upgrade-media.mjs';
 import {appPresetChanges} from './upgrade-app-presets.mjs';
 import {refreshWorkerConfig} from './worker-config.mjs';
 /**
@@ -199,8 +200,17 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   if (Object.keys(missingScripts).length) changes.push({ file: 'package.json', kind: 'scripts', what: `add scripts: ${Object.keys(missingScripts).join(', ')}`, scripts: missingScripts });
   if (studio.homie?.studio !== STUDIO_VERSION) changes.push({ file: 'studio.json', kind: 'version', what: `homie.studio ${studio.homie?.studio ?? '(none)'} → ${STUDIO_VERSION}`, to: STUDIO_VERSION });
 
+  const mediaFiles = new Set();
+  for (const file of ['AGENTS.md', 'CLAUDE.md', 'README.md']) {
+    const from = read(root, file);
+    if (from === null) continue;
+    const text = upgradeMediaGuidance(from);
+    if (text !== from) { changes.push({ file, kind: 'update-file', what: 'replace retired Homie credential guidance with official plugin connections', from, text }); mediaFiles.add(file); }
+  }
+
   // AGENTS.md, section by section; the other template files whole.
   for (const rel of TEMPLATE_FILES) {
+    if (mediaFiles.has(rel)) continue;
     const mine = read(root, rel);
     const want = tmpl[rel];
     if (want === undefined) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.51.4",
+  "version": "0.51.6",
   "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/parts/PARTS.md

@@ -240,7 +240,7 @@ Paid releases use a **separate private R2 bucket and `PURCHASE_MEDIA` binding**.
 
 Stripe's [MPP guide](https://docs.stripe.com/payments/machine/mpp) initializes the Stripe client with a secret credential. Its [x402 guide](https://docs.stripe.com/payments/machine/x402) separates the on-chain facilitator settlement from authenticated PaymentIntent recording. **x402 itself does not require a Stripe API key**; this supported path records money into the seller's Stripe books as Stripe documents. The keyless Payment Link path uses [signed webhooks](https://docs.stripe.com/webhooks) instead of provider reads. CLI OAuth is not exported as a Worker REST credential; see [the setup research](../../../docs/stripe-connect-research.md).
 
-For a fuller connection, the AI operates Stripe's [key-creation page](https://docs.stripe.com/keys), selects the necessary permissions and clicks Copy, then runs `shop connect --from-clipboard` (`--live` for live mode). The local command privately reads the clipboard, verifies the key, makes the webhook and writes secrets to Wrangler stdin, then clears the clipboard. **The human only handles provider sign-in, verification or approval prompts**; their count is controlled by Stripe. Never ask the person to find or paste a key when browser control is available. No supported public API to mint a persistent Stripe REST credential from the CLI approval was established. On macOS this uses `pbpaste`/`pbcopy`, Windows its clipboard commands, and Linux Wayland `wl-paste`/`wl-copy`; other desktops require an equivalent private credential transport. The manual local form remains an explicit fallback, not the default instruction. Live CDP credentials likewise belong to the seller and should be transferred privately by the AI from the provider's setup; no Homie account is involved.
+Owner setup uses Stripe’s official OAuth plugin and Homie’s private webhook installation; read [SHOP.md](../shop/SHOP.md). Runtime-credential machine payment integrations are developer work, not an owner fallback. Never ask an owner to create or copy a key.
 
 Turnstile is optional. If the studio configures it, the fallback verifies its hostname and action. The per-address Worker rate limiter remains configurable flood protection. Machine payment proofs are verified by the protocol libraries.
 

package/rules/view.ts

@@ -728,6 +728,10 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     while (stepped < t) {
       stepped += 1;
       step(stepped, stepped === t);
+      // fire() can read/cache the own entity before this pump advances it.
+      // A renderer later in the same callback must see the completed step,
+      // not hold that effect's old pose until the next (possibly early) frame.
+      presentedEntity = null;
       if (stepped % sendEvery === sendEvery - 1) flush(now, stepped);
     }
   }

package/shop/SHOP.md

@@ -101,26 +101,68 @@ One order stores every line and its item snapshot. `/api/shop/mine` lists the li
 
 `homie-studio shop init --supporter` writes an example item and `SELLING.md`, without a policy, cap or refund
 window. `shop check` validates settings; the build uses the same validation.
-`shop connect` (MCP `stripe_login`) starts Stripe's official browser approval, sandbox/test first.
-If Stripe CLI is missing, the result gives `npm install -g @stripe/cli@latest` for the AI to run.
-The person never supplies a key to the AI. A studio-specific CLI profile avoids borrowing another studio's login.
-If the studio is not deployed yet, approval is retained: deploy with `studio_deploy` (and
-`cloudflare_login` first if needed), then rerun connect. Webhooks require the deployed HTTPS address.
-
-**The default is keyless.** Connect syncs one Product and Price for each shop.json item and one
-Payment Link for each paid item, adjustable-quantity menus, and one capacity-limited link per published booking slot. Tip Prices use custom amounts; free orders stay local. It creates
-an account webhook at `<site>/api/shop/hook`, captures its signing secret without displaying it,
-and installs `STRIPE_WEBHOOK_SECRET` and `STRIPE_SHOP_LINKS` through Wrangler stdin. No Stripe
-API key goes into the Worker. Repeat connect after editing shop.json: changed prices get new
-Price versions, changed links get new versions, and removed objects are archived. Old paid orders
-keep their frozen item definitions. Receipts contain no credentials. Unchanged runs create nothing.
-
-With an existing account and deployed studio, the person approves Stripe CLI once; an already
-connected profile needs zero new approvals. An MCP-only grant is separate and is never extracted.
-The AI installs tooling, creates/syncs objects and stores the secret. New account verification,
-activation, administrator access settings and Cloudflare authorization are separate prerequisites.
-`shop connect --live` requires the owner's go-live request. `--renew` retries browser authorization.
-Never request a key from the person for the default flow.
+## Default: Stripe's official plugin
+
+Use Stripe's official plugin, authenticated with its browser OAuth approval, for Products,
+Prices, Payment Links, menu links, per-slot booking links, monthly giving and the customer
+portal. Install with `stripe agent setup` if needed; the MCP URL is
+`https://mcp.stripe.com`. Current tools are `stripe_api_search`, `stripe_api_details`,
+`stripe_api_read` and `stripe_api_write`. Discover the operation and its schema before
+calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
+
+1. Create/check `shop.json`. Read the app's published slot records and supply the complete
+   slot manifest described below. Select the owner's account and sandbox in Stripe's plugin;
+   read `/v1/account` to record its account ID. Live mode only after the owner requests it.
+2. Call Homie's `stripe_shop_plan` with `account`, `mode: "test"`, `slots` and
+   `observations: []`. CLI equivalent: `homie-studio shop plan --have plan-input.json`.
+   That JSON file contains the same fields. A returned `next` is the exact operation:
+   method, API path, parameters, API version and (for creates) idempotency key. Updates set desired fields; read before retrying. Metadata
+   scopes objects to this studio and origin; prices and links have content revisions.
+3. Perform each `next` through Stripe's official MCP. For GET, append
+   `{ "path": "…", "params": {…}, "body": <Stripe response> }` to `observations`
+   and plan again. Follow every pagination request. After a write, discard observations
+   and read fresh. Replanning resolves real Stripe IDs; never invent IDs or substitute
+   a different price. Reuse the supplied idempotency key where the tool supports it;
+   otherwise read before retrying and match the stable product ID/revision metadata.
+4. When no writes remain, use fresh reads with `stripe_shop_plan` `verify: true`
+   (CLI `homie-studio shop verify --have plan-input.json`). It checks the catalog,
+   actual link fields and line items, menus, slot limits and portal settings against
+   shop.json and the slot manifest. A mismatch blocks verification. It saves only public
+   configuration to `.studio/stripe-mcp.json`; local test configuration goes to `.dev.vars`.
+5. For a deployed HTTPS studio, run `stripe_webhook` (CLI `homie-studio shop webhook`).
+   Follow `studio_job`. This uses Stripe CLI only for private webhook installation,
+   checks the same account as the MCP, and installs the signing secret and verified
+   links through Wrangler stdin. The CLI needs one separate browser approval if its
+   studio profile is not already connected. MCP approval cannot be reused or exported.
+   Cloudflare authorization and an existing deployment are prerequisites.
+6. After installation, perform the returned `retire` operations through Stripe MCP to
+   archive replaced catalog objects, then verify fresh reads again. Test a sandbox
+   purchase and its signed event, order grant, booking capacity or recurring invoice;
+   a browser return is never proof. Stripe CLI `trigger` can send a test event, and
+   `events resend <event> --webhook-endpoint <endpoint>` retries a delivery. Check the
+   endpoint's delivery result and the app's verified records. Do not type a card into
+   a page for an automated proof; use Stripe's documented test PaymentMethods/fixtures.
+
+Never create a webhook through model-visible Stripe MCP: its response exposes the signing secret.
+
+The owner never handles an API key or signing secret. No Homie backend handles payments.
+The Worker needs only public link configuration and the signing secret; buyers pay
+Stripe directly even when the AI and the owner's computer are offline. The old
+`stripe_login` / `shop connect` flow remains an alternative that syncs everything
+through Stripe CLI browser approval. `--renew` renews that approval; `--live` requires
+the owner's go-live request. Never read CLI config or print login-completion output.
+
+For local checkout, pass `url: "http://localhost:8787"` (or the private Wi-Fi address)
+and `mode: "test"` to the same plan/verify flow; the official plugin makes the links.
+Run `homie-studio shop listen --profile <sandbox-profile>` in a background terminal.
+Stripe CLI is required for forwarding; one browser approval is enough if needed.
+The command captures and saves the listener secret privately. Start/restart
+`homie-studio dev --lan` once it reports ready and keep the listener running.
+Never copy the listener's raw output into the conversation.
+
+For a faster local iteration, `homie-studio build --quick` skips generated rules play
+and the snapshot smoke-run, while retaining compilation, guards and type checks.
+Run a full build before release; quick output is not evidence that play checks passed.
 
 At purchase time, the Worker saves an opaque order reference and sends it as the link's
 `client_reference_id`. The buyer confirms quantity or tip amount on Stripe. A signed snapshot
@@ -142,17 +184,7 @@ items; failed refunds restore the financial booking. A lost dispute revokes good
 | Managed Payments | Payment Links support managed_payments.enabled; connect uses it when the studio selects Stripe as seller, subject to Stripe eligibility and terms. |
 | Currency display | Payment Links always enable Stripe Adaptive Pricing. Bookkeeping uses integration currency; presentment details describe what the customer saw. |
 
-A key alone never selects the fuller path. It requires explicit `STRIPE_CHECKOUT_MODE=sessions` as well as a Worker key. Only if requested, explain: “The optional session connection adds exact app-built carts, spending reservations, expiring holds and runtime refunds.”
-The explicit `shop connect --manual` path remains available, including `--live`, but requires the
-owner's existing Dashboard key step; it does not satisfy one approval. Never choose it automatically.
-Running default connect again saves links, removes the API key, and keeps signed-event fulfillment.
-When switching to spending restrictions, the AI must deactivate previously issued Payment Links through
-the approved CLI and resolve in-flight checkouts before relying on those restrictions; switching credentials
-does not cancel old Stripe sessions. The runtime OAuth finding and sources are in `docs/stripe-connect-research.md` in the source checkout.
-
-`shop`, `shop orders`, and `/_studio/office/shop` show readiness and sales. Stripe's optional MCP
-is useful for owner-requested refunds and analytics; honor its approval links. Do not create a
-secret-returning webhook through a conversation tool: the private connect process owns that call.
+`shop`, `shop orders`, and `/_studio/office/shop` show readiness and sales. Use Stripe's official MCP for owner-requested refunds and analytics; honor its approval links.
 
 ## Payment guarantees and schema
 
@@ -220,7 +252,7 @@ For referrals, use Stripe Connect to split payments or a Stripe-based affiliate
 
 ## Keyless menus, paid seats and monthly giving (0.51.0)
 
-Use `shop connect` by default. All objects belong to the owner's Stripe account and
+Use the official MCP plan/verify flow by default. All objects belong to the owner's Stripe account and
 are created through its approved CLI session. Homie has no platform key, OAuth
 backend, payment intermediary or cut. A desktop is needed to sync, not to take money.
 
@@ -251,7 +283,7 @@ data goes in that reference. A return URL is never proof of payment.
 collection with integer `capacity` and a server-managed `bookings` collection with
 `"booking":{"slots":"slots","item":"full-tune"}`. Publish slot records, then have
 the owner's AI write the complete manifest to `.studio/booking-slots.json` and run
-`shop connect`, or call local MCP `stripe_bookings_sync` with the same `slots` array:
+`stripe_shop_plan` with the same `slots` array (the CLI alternative is `stripe_bookings_sync`):
 
 ```json
 [{"app":"tune","collection":"bookings","slots":"slots","slot":"sat-0900","item":"full-tune","capacity":1}]
@@ -303,7 +335,7 @@ Signed `subscription.started`, `.renewed`, `.failed`, `.cancelled` events drive
 membership and giving. Membership access ends at the paid invoice line's period end;
 failed invoices cannot extend it and cancellation ends access. Unknown Prices grant
 nothing. Keyless portal configuration supports cancellation, payment-method updates
-and invoice history. `shop connect` enables `login_page.enabled` through the CLI API
+and invoice history. The official MCP plan enables `login_page.enabled` through Stripe’s API
 and stores Stripe's no-code login URL; **no Dashboard toggle is required**. Givers
 verify their email with Stripe to manage/cancel. The buyer-owned `/api/shop/portal`
 returns this URL. Plan changes require deliberate portal configuration and fulfilment
@@ -339,3 +371,47 @@ dev bindings and disposable studios when finished.
 See `apps/APPS.md`, “Real Stripe test checkout on this computer”, for the supported
 `shop connect --local` and Stripe CLI forwarding recipe. Every paid monthly cycle
 creates a paid order and `order.paid` with the subscription’s original app reference.
+
+## Preserve a local basket with keyless checkout
+
+For a venue that wants the phone's exact items and quantities, opt into a saved
+basket in `shop.json` before syncing Payment Links:
+
+```json
+"basket": {
+  "name": "Round for your table",
+  "description": "Enter the total shown on your pub basket. Any shortfall is settled at the bar."
+}
+```
+
+Use Stripe (`till: "stripe"`) and tax-inclusive menu prices (`automaticTax: false`).
+Sync creates one custom-amount Price and Payment Link per app, with one line and
+quantity one. `shop.checkout({reference: "table-7"})` saves the validated basket
+lines, quantities, total and reference in the studio's D1 before opening Stripe.
+Even a basket containing only one item keeps its exact quantity. The opaque order
+ID travels as `client_reference_id`; no Stripe API key or Homie payment relay is
+used by the Worker. Existing menus without `basket` retain their behavior.
+
+The link prefills the saved total using Stripe's documented
+[`prefilled_amount`](https://docs.stripe.com/payment-links/customize#customize-checkout-with-url-parameters)
+in minor currency units. The guest can edit it, so a preset is never payment proof.
+[`custom_unit_amount.preset`](https://docs.stripe.com/api/prices/create?query=custom_unit_amount)
+is the Price-level fallback, not a per-buyer setting. Never mutate that shared Price
+at checkout: concurrent baskets would race. Both the Price fallback and the URL
+override were verified in the Homie sandbox. Invalid overrides fall back to the
+stored preset or an empty amount; keep the expected total visible on the phone.
+
+After a signed paid session matches the frozen link, revision, mode, currency and
+order reference, `order.paid` contains the **saved basket lines**, `amount` (actual
+payment), `basketTotal` (expected total), and `settlement` (`paid` or `short`).
+Line `amount` is the saved extended amount (unit price × quantity); line `total`
+is its proportionally allocated share of the actual aggregate payment for refunds.
+A short payment emits the event so staff can resolve it, but grants no automatic
+entitlements. Apps must compare the actual payment with `basketTotal`, show a
+shortfall explicitly, and deduplicate by order ID. More than the total is paid.
+Reopening and paying the link creates another order for the same frozen basket;
+repeated delivery of the same session never creates another round.
+
+The Stripe heading is the connected Stripe account's business name. A sandbox
+account named “Homie sandbox” shows that name; a real pub's account shows the pub's
+name. The basket's product name and description use the pub's own wording.

package/worker/app-records.mjs

@@ -47,6 +47,7 @@ export async function appAccess(request, env, meta, url) {
   const caller = toolIdentity(request);
   if (caller) {
     if (caller.owner) return { ok: true, role, can: declared.can };
+    if(env.HOMIE_LOCAL_TEST_SECRET && caller.localTest && caller.roles?.[meta.id]?.includes(role))return {ok:true,role,can:declared.can};
     if (!caller.id) return { ok: false, status: 401, error: 'sign in to this studio' };
     const grant = await env.DB.prepare("SELECT player FROM app_roles WHERE app IN (?1, '*') AND role = ?2 AND player = ?3").bind(meta.id, role, caller.id).first();
     return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.51.4","sha256":"6286b3013c1ad438111eaed4338ccbffa2f85bf2a765f9f007155a809c414f71"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.51.6","sha256":"035298d6bd38bab86e0471ea08819786995a53cedb8da961b595506e5403b410"});

package/worker/event-resources.mjs

@@ -25,10 +25,16 @@ export async function readableFeed(env,cat,caller,name) {
   // Non-record events have no app read capability; they remain owner-only.
   return caller.owner===true;
 }
-export async function feedEvents(env,name,{after=0,through=Number.MAX_SAFE_INTEGER}={}) {
+export async function feedEvents(env,name,{after=0,through=Number.MAX_SAFE_INTEGER,caller}={}) {
   const feed=eventFeeds(env)[name];if(!feed)return [];
-  const rows=(await env.DB.prepare('SELECT seq,id,type,data,at FROM studio_events WHERE type=?1 AND seq>?2 AND seq<=?3 ORDER BY seq LIMIT 100').bind(feed.event,after,through).all()).results;
-  return rows.map(r=>({...r,data:JSON.parse(r.data)}));
+  const scopedApp=env.HOMIE_LOCAL_TEST_SECRET&&caller?.localTest&&caller.testScope&&feed.event==='record.changed'?`${feed.app}:check:${caller.testScope}`:null;
+  const rows=(await env.DB.prepare("SELECT seq,id,type,data,at FROM studio_events WHERE type=?1 AND seq>?2 AND seq<=?3 AND (?4 IS NULL OR json_extract(data,'$.app')=?4) ORDER BY seq LIMIT 100").bind(feed.event,after,through,scopedApp).all()).results;
+  const events=rows.map(r=>({...r,data:JSON.parse(r.data)}));
+  if(env.HOMIE_LOCAL_TEST_SECRET && caller?.localTest && caller.testScope && feed.event==='record.changed') {
+    const app=`${feed.app}:check:${caller.testScope}`;
+    return events.filter(e=>e.data.app===app).map(e=>({...e,data:{...e.data,app:feed.app}}));
+  }
+  return events;
 }
 export function matchesFeed(feed,event) {
   return feed.event===event.type && (feed.event!=='record.changed'||(event.data.app===feed.app&&event.data.collection===feed.collection));

package/worker/index.mjs

@@ -189,7 +189,11 @@ async function availableShellShop(env, cat, game, options) {
   // The shell can show a disabled catalog before payment setup is complete.
   // Checkout readiness is enforced by the shop API, separately from visibility.
   const preview = (cat.games ?? []).find(g => g.id === game)?.screen?.shopPreview === true;
-  return (preview && !shopOf(cat)?.broken || await sellingShop(env, cat)) ? shellShop(cat, game, options) : null;
+  const shop = shopOf(cat);
+  // Free services must retain their bridge in a mixed free/paid catalogue.
+  // Paid readiness, policy and atomic booking capacity remain API decisions.
+  const free = shop?.open && !shop.broken && shop.items.some(i => i.price === 0 && !i.interval && (!i.game || i.game === game));
+  return (preview && !shop?.broken || free || await sellingShop(env, cat)) ? shellShop(cat, game, options) : null;
 }
 
 async function postsOf(env, origin) {

package/worker/local-test.mjs

@@ -2,6 +2,10 @@
 const local = (request, env) => env.HOMIE_LOCAL_TEST_SECRET && ['localhost','127.0.0.1','[::1]'].includes(new URL(request.url).hostname);
 export async function localCaller(request, env) {
   if (!local(request, env) || request.headers.get('authorization') !== `Bearer ${env.HOMIE_LOCAL_TEST_SECRET}`) return null;
+  const session=await localSession(request,env);
+  // A supplied but invalid signed session must never fall back to owner.
+  if(request.headers.get('cookie')?.includes('homie_test=')&&!session)return null;
+  if(session)return {id:`local-test-${session.app}-${session.role}`,owner:session.role==='owner',client:null,localTest:true,roles:{[session.app]:[session.role]},testApp:session.app,testScope:session.scope??null};
   return {id:'local-test-owner',owner:true,client:null};
 }
 export async function localSession(request, env) {

package/worker/mcp-events.mjs

@@ -41,9 +41,9 @@ export async function pollEvents(env,cat,caller,params,now=Date.now()){
   const rows=(await env.DB.prepare(`SELECT seq,id,type,data,at FROM studio_events
     WHERE type=?1 AND seq>?2 AND seq<=?3
       AND (?4 IS NULL OR (json_extract(data,'$.app')=?4 AND json_extract(data,'$.collection')=?5))
-    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?feed.app:null,feed.collection??null,max+1).all()).results;
+    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope?`${feed.app}:check:${caller.testScope}`:feed.app):null,feed.collection??null,max+1).all()).results;
   const hasMore=rows.length>max,page=rows.slice(0,max);
-  const events=page.map(row=>occurrence(params.name,{...row,data:JSON.parse(row.data)},cursorOf(params.name,row.seq)));
+  const events=page.map(row=>{const data=JSON.parse(row.data);if(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope&&feed.event==='record.changed')data.app=feed.app;return occurrence(params.name,{...row,data},cursorOf(params.name,row.seq));});
   const after=hasMore?page.at(-1).seq:start.through;
   return {events,cursor:cursorOf(params.name,after),truncated:start.truncated,hasMore,nextPollMs:5000};
 }