@homie-rocks/studio 0.51.8 → 0.52.0

package/CHANGELOG.md

@@ -17,6 +17,38 @@ 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.52.0] - 2026-10-15
+
+**Plugin 0.52.0**
+
+Run your place with trusted actions across screens and AI, live business records, shared booking capacity and stronger proofs that it works for your customers.
+
+### Added
+
+- **One trusted action from any screen or AI:** App screens call the same studio tools as MCP through `createAppTools`, with strict input schemas, server role checks and versioned writes.
+- **Screens that stay in step:** Live record subscriptions and presence use the existing Lobby without polling or a dummy game room. Supported app context supplies your public address and a local proof clock; isolated proofs stay separate.
+- **Business events with useful history:** Record changes include the previous value. Trusted functions publish schema-checked business feeds with durable receipts that prevent duplicate events.
+- **Bookings that share one capacity:** App holds and Stripe session checkout use the same capacity row, including group quantities, ownership, version checks and scheduled release. Confirmations distinguish unpaid reservations from verified payments.
+- **Proofs for difficult situations:** Needs can force disabled clicks to check server refusals, race actions from separate browsers, restart local development and reload without WebGL.
+- **Time at your place:** IANA time zones support local scheduling and explicitly reject nonexistent or ambiguous wall times around clock changes.
+
+### Fixed
+
+- **Shops that survive upgrades:** Matching 0.51.6 Stripe plugin verifications remain valid; real shop, slot or site changes explain what needs verification. Unfinished setup still builds and deploys with checkout closed and a clear next step.
+- **Room for your whole catalogue:** Verified public links ship as a JSON asset instead of a size-limited Worker text binding, including catalogues with more than 100 links. Missing assets keep checkout closed.
+- **Faster Stripe setup and replanning:** Saved public observations avoid repeated discovery. Explicit refresh paginates expanded Payment Link lists, refreshes changed links and preserves verification freshness. Private webhook setup installs Stripe's official npm CLI automatically when missing, then continues to browser approval.
+
+### Changed
+
+- **Guides grounded in six real builds:** App and game guides include place patterns, security alternatives and small examples that compile against the toolkit.
+- **Cleaner upgrades:** Recognized polling workarounds and exact obsolete capability notes are retired; custom business logic remains available for review.
+
+### Upgrade notes
+
+- Apply migrations `0027_app_live.sql`, `0028_business_events.sql` and `0029_booking_holds.sql` in order.
+- Replace refresh timers with record subscriptions, and private origin, peer and clock reads with `createAppContext`.
+- Shared local booking holds require Stripe session checkout. Keyless Payment Links cannot claim those holds and are explicitly refused.
+
 ## [0.51.8] - 2026-10-15
 
 **Plugin 0.51.8**

package/apps/APPS.md

@@ -222,3 +222,120 @@ and pass a role when deliberately testing the customer experience.
 `check --shots` may capture outside the studio, but persistent needs evidence copies
 those pictures into `.studio/checks` and stores studio-relative paths. Keep that
 folder with the Codex evidence. Deploy can render it without outside-path warnings.
+
+## Screens and AI share tools
+
+Import `createAppTools` from `@homie-rocks/studio/apps`, then call
+`await tools.call('place_book', {slot, request})`. It runs the studio's `defineTool`
+handler, with its strict input schema, audience checks, rate policy and versioned
+`context.database`. The shell supplies identity; message fields cannot grant a
+role. Only studio-defined tools are exposed. Priced tools still use MCP's payment
+approval flow. Dispose the client on unmount. Use a stable request ID across
+retries; a lost response does not mean the write failed. Keep rules in a shared
+`domain.ts`, but only the server handler commits them.
+
+## Live records and frame context
+
+`records.subscribe(() => void refresh())` returns an unsubscribe function. It
+notifies on connection/reconnection and when the collection changes; `refresh`
+calls `records.list()` to obtain currently authorized data. Do an initial read as
+well. Coalesce overlapping refreshes in a busy screen. This uses the existing
+Lobby, without a rules file or a dummy map. Notifications contain collection names,
+not records or private IDs. A 15-second server heartbeat repairs missed wakes;
+screens do not poll. Closing the page closes its stream. Apply `0027_app_live.sql`
+on upgrade before starting the new Worker.
+
+`createAppContext()` provides `ready`, `current`, `subscribe`, `now()` and `dispose`.
+After `await context.ready`, `current` has `app`, `origin`, public `url`, and
+`presence` (connected screens in this app/room and isolated proof scope, including
+the current screen). Presence is screens, not unique people or paid customers.
+The public address excludes role grants and booking credentials. Do not inspect
+`HOMIE_NET` or cast room internals to read peers.
+
+For a signed local proof session, the shell supports
+`window.homieApp.setTestClock(epochMilliseconds)` and `null` to restore wall time;
+frame code reads `context.now()`. Production shells refuse the setter. This is a
+view clock, never authority for capacity, payment or server deadlines. Scheduled
+needs supply their own explicit `scheduledTime`.
+
+See `guides/app/PLACES.md` for the six-build recipe and small typed examples.
+
+## One capacity budget for holds and Stripe
+
+A collection with `booking: {slots:'slots', item:'ticket'}` uses the same
+`shop_bookings` row from hold through payment. A trusted tool can call:
+
+```ts
+const held = await context.bookings.hold({
+  app: 'place', collection: 'bookings', slot: 'morning', quantity: 2,
+  id: input.request, expiresAt: Date.now() + 60_000 // choose the hold window on the server
+});
+```
+
+Require a signed-in caller, or pass a private, random 32–128 hex-character `token`
+for a guest. Keep the request ID stable on retries; a retry returns the original expiry and never extends it. The returned `id` is
+scoped by app/collection/proof; it is public identification, never authorization.
+Only the owner (or holder of that private token) can `get`, `confirm` or `release`.
+Confirm/release take `{id, version, token?}`. Another owner's ID is not permission.
+The entire group quantity reserves atomically or fails; there is no partial group.
+Slot reads report availability including held and confirmed quantities.
+
+Use `shop.book('ticket', {collection:'bookings', slot:'morning', hold:held.id,
+token}, 2)` to pay for that same row. Session checkout claims it once, in the order
+transaction. A second checkout cannot take it; verified payment updates it.
+`confirmed` means a capacity commitment; only `paid:true` means payment was
+verified. Do not label a confirmation as a paid receipt.
+
+A scheduled owner function calls
+`context.bookings.releaseExpired({app:'place',collection:'bookings',now:event.data.scheduledTime})`.
+Only unconfirmed local holds expire this way. After checkout claims a hold,
+Stripe's verified payment/expiry/refund owns its lifecycle; a local timer cannot
+release a possibly paid seat. Keyless Payment Links cannot safely claim local
+holds: configure session checkout, or keep using their existing pending-to-paid
+path. The toolkit refuses to mix active keyless links with new local holds.
+Apply `0029_booking_holds.sql`; public projections never include actors or tokens.
+
+## Adversarial needs
+
+Actions inside `concurrent` start together on separate browser contexts:
+
+```json
+{"concurrent":[{"surface":"phone","selector":"#book","click":true},{"surface":"phone-two","selector":"#book","click":true}]}
+```
+
+Assert exactly one saved booking afterwards. `{"surface":"staff","selector":"#close","forceClick":true}`
+temporarily bypasses the disabled attribute, clicks, and restores it: assert the
+server refusal and unchanged data. It is not a permission grant.
+`{"surface":"phone","capabilities":{"webgl":false}}` installs a WebGL blocker
+before reloading that surface, leaving ordinary controls functional. Set `true`
+to restore WebGL on another reload. `{"surface":"phone","clock":1792800000000}`
+sets the supported local frame clock.
+
+`{"restart":true}` asks the authenticated local dev controller to restart its own
+Wrangler child, keeps disk state and proof sessions, and waits for readiness.
+It never kills a PID discovered by port. Start the current toolkit's dev server;
+remote URLs and old servers without this controller refuse or time out. Put
+restart/capability steps outside concurrent groups, then assert saved state.
+
+## Place time and upgrades
+
+```ts
+import {placeTime} from '@homie-rocks/studio/links';
+const startsAt = placeTime('2027-03-20', '09:30', 'America/Vancouver');
+```
+
+Store the occurrence's local date/time and IANA zone in place config; derive epoch
+milliseconds with the runtime's zone database. Never append `-07:00`. Invalid dates
+and spring gaps are refused; repeated autumn times require explicit
+`{disambiguation:'earlier'}` or `'later'`. Generate future occurrence dates from the
+calendar rule, not a constant “next Saturday”. Update runtime zone data with the
+runtime itself.
+
+`upgrade --diff` includes recognized obsolete capability notes and standalone
+2–3-second named refresh timers over `createAppRecords` clients. `upgrade --apply`
+replaces those timers with subscriptions and corrects exact stale notes without
+marking old needs passed. Timer conversion uses the studio’s installed TypeScript
+compiler; run `npm install` in the studio first if it is missing. Review the diff and rerun the affected needs. Custom
+combined timer/jobs, hand-written routes and business-event mirrors need a semantic
+migration to the APIs above; they are not automatically deleted. The owner's
+words, historical evidence and unresolved integration work remain intact.

package/apps/apps.ts

@@ -4,7 +4,9 @@ export interface AppRecord<T> { id: string; data: T; version: number; updatedAt:
 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> }>();
+  const listeners = new Set<() => void>();
   const receive = (e: MessageEvent) => {
+    if(e.source === parent && e.data?.type === 'homie-app-changed' && e.data.collections?.includes(collection)) { for(const listener of listeners) listener(); return; }
     if (e.source !== parent || e.data?.type !== 'homie-app-result') return;
     const p = pending.get(e.data.id); if (!p) return;
     pending.delete(e.data.id); clearTimeout(p.timer);
@@ -18,11 +20,59 @@ export function createAppRecords<T extends Record<string, unknown>>({ collection
     parent.postMessage({ type: 'homie-app', id, collection, method, record, data, version }, '*');
   });
   return {
+    subscribe(listener: () => void) { listeners.add(listener); parent.postMessage({type:'homie-app-subscribe',collections:[collection]}, '*'); return () => {listeners.delete(listener);}; },
     async list(): Promise<AppRecord<T>[]> { return (await ask('GET')).records; },
     async get(id: string): Promise<AppRecord<T> | null> { return (await ask('GET', id)).records[0] ?? null; },
     create: (data: T, id = randomId()) => ask('POST', id, data),
     update: (record: AppRecord<T>, data: T) => ask('PUT', record.id, data, record.version),
     remove: (record: AppRecord<T>) => ask('DELETE', record.id, undefined, record.version),
-    dispose() { removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); },
+    dispose() { listeners.clear(); removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); },
+  };
+}
+
+/** Call the same trusted studio definition used by MCP. The shell supplies identity. */
+export function createAppTools() {
+  const pending = new Map<string, {resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>}>();
+  const receive = (e: MessageEvent) => {
+    if (e.source !== parent || e.data?.type !== 'homie-app-result') return;
+    const p = pending.get(e.data.id); if (!p) return;
+    pending.delete(e.data.id); clearTimeout(p.timer);
+    if (e.data.result?.ok) p.resolve(e.data.result.data); else p.reject(new Error(e.data.result?.error ?? 'tool failed'));
+  };
+  addEventListener('message', receive);
+  return {
+    call<T = unknown>(name: string, input: Record<string, unknown> = {}): Promise<T> {
+      return new Promise((resolve, reject) => {
+        const id = randomId();
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error('app shell did not answer')); }, 15000);
+        pending.set(id, {resolve: value => resolve(value as T), reject, timer});
+        parent.postMessage({type:'homie-app-tool', id, name, input}, '*');
+      });
+    },
+    dispose() { removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); }
+  };
+}
+
+export interface AppContext { app: string; origin: string; url: string; presence: number; now: number | null }
+/** Public self address and live presence supplied by the authenticated shell. */
+export function createAppContext() {
+  let value: AppContext | null = null;
+  const listeners = new Set<(context: AppContext) => void>();
+  let resolve!: (context: AppContext) => void;
+  const ready = new Promise<AppContext>(r => {resolve = r;});
+  const receive = (e: MessageEvent) => {
+    if(e.source !== parent || e.data?.type !== 'homie-app-context') return;
+    value = Object.freeze(e.data.context) as AppContext;
+    resolve(value); for(const listener of listeners) listener(value);
+  };
+  addEventListener('message', receive);
+  parent.postMessage({type:'homie-app-context'}, '*');
+  parent.postMessage({type:'homie-app-subscribe',collections:[]}, '*');
+  return {
+    ready,
+    get current() {return value;},
+    now: () => value?.now ?? Date.now(),
+    subscribe(listener: (context: AppContext) => void) {listeners.add(listener); if(value)listener(value); return () => {listeners.delete(listener);};},
+    dispose() {removeEventListener('message',receive);listeners.clear();}
   };
 }

package/docs/toolkit-place-patterns.md

@@ -1,5 +1,11 @@
 # Building places: layout, authority and recovery
 
+Start with [the six-build place recipe](../guides/app/PLACES.md) and
+[the app contracts](../apps/APPS.md) for screen-to-tool calls, live records,
+shared booking holds, named events, IANA time and adversarial needs. The small
+CAS example below teaches authority; paid inventory uses `context.bookings` so
+checkout and app capacity remain one system.
+
 ## TV join safe area
 
 On `/<id>/tv`, the shell sets `body.homie-join-visible` while the join card is present. It publishes CSS pixel values on the document root in both the shell and the sandboxed app: `--homie-join-x`, `--homie-join-y`, `--homie-join-width`, `--homie-join-height`, and `--homie-join-inset-top/right/bottom/left`. The insets include the card's distance from its configured screen edge. Inactive edges are zero; no card means all values are zero and the body class is absent. Measurements update on resize and iframe navigation. The card is at most 480 × 280 CSS pixels; its address wraps within that box.

package/functions/FUNCTIONS.md

@@ -383,3 +383,30 @@ A booking payment can be tested with:
 Create any records the handler reads first. First fire registers subscriptions
 before writing the event, so the first event is delivered too. No Stripe checkout
 or browser approval is needed for this explicitly synthetic local event.
+
+## Previous records and named business events
+
+`record.changed` data includes `previous`: `null` for insert, the old data for
+update/delete. `data` remains the new value for update and the deleted value for
+delete. Both are captured by the same database transaction as the write. Import
+`RecordChanged<T>` and `ScheduledEvent` from `@homie-rocks/studio/functions`;
+scheduled time is `event.data.scheduledTime` (epoch milliseconds), not `event.at`.
+
+Declare a feed in `studio.json` and its allowed payload:
+
+```json
+{"mcp":{"events":{"arrivals":{"event":"place.arrived","audience":"owner","schema":{"type":"object","properties":{"booking":{"type":"string"}},"required":["booking"],"additionalProperties":false}}}}}
+```
+
+A function declares `publish: ['arrivals']`, then calls
+`await context.events.publish({feed:'arrivals', id:event.id, data:{booking:'...'}})`.
+Use the source event ID, or a stable business request ID; repeats with the same
+payload are no-ops, and changed payloads under the same ID are refused. Publication
+and its deduplication receipt commit atomically. Receipts survive feed pruning.
+Do not mirror every record or build a sleep-and-retry log. Keep contact details
+out of operational events. Owner AIs use the existing feed cursor, MCP subscription
+or declared webhook; functions never send email/SMS themselves.
+
+Apply `0028_business_events.sql` on upgrade. Local proof publications carry their
+scope and do not appear in production feed reads. Event feeds retain their declared
+type; give different business feeds distinct types when their content differs.

package/functions/functions.ts

@@ -8,6 +8,10 @@ export interface StudioFunction<Data = unknown> {
   /** Permit an explicit owner replay command to consume retained history. */
   replay?: boolean;
   events?: StudioTool['events'];
+  publish?: string[];
   handler(event: StudioEvent<Data>, context: ToolContext): unknown | Promise<unknown>;
 }
 export function defineFunction<Data = unknown>(definition: StudioFunction<Data>): StudioFunction<Data> { return definition; }
+
+export interface RecordChanged<T = Record<string, unknown>> { app: string; collection: string; record: string; version: number; operation: "insert" | "update" | "delete"; data: T; previous: T | null }
+export interface ScheduledEvent { function: string; cron: string; scheduledTime: number }

package/guides/app/PLACES.md

@@ -0,0 +1,123 @@
+# Build a place people recognize
+
+Use this with APPS.md and TOOLS.md. Six place builds exposed the same rule:
+make the owner's dream visible, with one trusted operation behind every action.
+
+1. **Start with their paragraph.** Quote the owner's actual words in CODEX.md,
+   including sensory details and operating rules. Write one executable need per
+   clause. Describe Scene as data: “held = white ball; confirmed = gold; mine =
+   gold ring; empty capacity = empty pegs.” List phone, wall, signed-in staff,
+   customer AI and owner AI with their addresses and actions. Record what is
+   simulated, evidence viewports and who reviewed it. Local review is not independent.
+2. **Make records visible.** Give each meaningful record an object, each state a
+   material, and the visitor's object a clear marker. Arrivals pop and chime;
+   outcomes become bags, cups or flags. Empty capacity can be negative space.
+3. **Spend geometry where it reads.** Use one layout curve for paths, trees and
+   objects. Add a gradient sky shader and sun, fog matching the horizon, terrain
+   vertex colours by zone, and seeded low-poly local vegetation. Animate water
+   and a flag in vertex shaders; avoid recomputing a large mesh's normals every
+   frame. Ease role-specific cameras with `1 - Math.exp(-dt * 4)`. Cap pixel
+   ratio on phones, pause hidden frames, respect reduced motion. Generate a
+   filtered noise ambient bed after the first sound opt-in; its gain follows the
+   scene. Compose a share card from the live scene and actual outcome.
+4. **One set of rules.** Put validation and transitions in `domain.ts`; the view
+   may preview them, but a `defineTool` handler decides and saves. Screens call
+   `createAppTools().call`, AIs call the same definition over MCP. Use strict
+   schemas, bounded inputs, versioned writes with revalidation on conflict, and
+   a caller-generated request ID. A repeated ID with different data is refused.
+   Do not rebuild the operation with browser record writes or a custom route.
+5. **Plan the AI's whole visit.** Provide `place_info` (“Call this first”: rules,
+   availability, prices, notice), `place_book` (all choices in one call, bounded
+   enums from config, a private management credential and a `next` sentence),
+   and `place_booking` (owner-authorized lookup/change/cancel). Never expose
+   management credentials in public records. Owner tools read an outbox, mark
+   messages sent, consume event feeds, and repeat next month by a calendar rule.
+   Homie composes; the owner's AI sends through its own connector. A repeat
+   invites past visitors; it never silently enrols them.
+6. **Operate from one config.** Put the place's IANA zone, schedule rule, capacity,
+   prices, add-ons and notice in one config. Derive UI, tools and `shop.json` from
+   it during build. Do not maintain a second price list. Model holds → confirm →
+   scheduled release, with fixed spot IDs and version checks on reuse. Group
+   allocation must be atomic, never a loop that reports partial success. Use the
+   toolkit's booking capacity for paid inventory. HANDOVER.md says what runs
+   where, the monthly rhythm, how to connect an AI, what to do when the owner
+   leaves, and which integrations are still unproven.
+
+## Small working boundaries
+
+The examples use the installed toolkit's exports. Declare `reserve` in `tools/`;
+this small example reserves one whole slot for a signed-in account. Keep the
+public collection a projection without account IDs or secrets. A production
+paid slot uses the shop booking system, not a second ledger.
+
+```ts
+import { defineTool } from '@homie-rocks/studio/tools';
+export default defineTool<{ slot: string; request: string }>({
+  name: 'reserve', description: 'Reserve one slot; repeat the same request safely.',
+  audience: 'signed-in',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['slot', 'request'],
+    properties: {
+      slot: { type: 'string', enum: ['morning', 'afternoon'] },
+      request: { type: 'string', pattern: '^[a-f0-9]{32}$' }
+    }
+  },
+  async handler(input, ctx) {
+    const owner = ctx.caller.id;
+    const key = 'slot:' + input.slot;
+    const old = await ctx.database.getVersioned(key);
+    if (old) {
+      const saved = old.value as { owner: string; request: string };
+      if (saved.owner === owner && saved.request === input.request) return { booked: true };
+      return { booked: false, next: 'That slot is full. No place has been taken.' };
+    }
+    const result = await ctx.database.put(key, { owner, request: input.request }, { version: 0 });
+    return { booked: result.ok, next: result.ok ? 'Your place is reserved.' : 'That slot filled. Choose another.' };
+  }
+});
+```
+
+```ts
+import { createAppTools, createAppContext, createAppRecords } from '@homie-rocks/studio/apps';
+const tools = createAppTools();
+const context = createAppContext();
+const self = await context.ready; // self.url is public; it contains no private access link
+const records = createAppRecords<{ status: string }>({ collection: 'spots' });
+const refresh = async () => {
+  const rows = await records.list();
+  document.querySelector('output')!.textContent = `${rows.length} places · ${self.url}`;
+};
+const stop = records.subscribe(() => { void refresh(); });
+await refresh();
+// In the visitor's click handler, preserve request across network retries:
+const request = crypto.randomUUID().replaceAll('-', '');
+await tools.call('reserve', { slot: 'morning', request });
+// On unmount: stop(); records.dispose(); context.dispose(); tools.dispose();
+```
+
+Build the controls first: an area menu is the primary navigation, and tapping a
+3D object selects the same area. Catch renderer creation failure and context loss;
+keep every booking/control usable without WebGL. Refusals are human sentences
+that say what happened. Prove refusals by bypassing disabled controls, race two
+browsers for the last seat, reload and restart, and run with WebGL unavailable.
+Document the exact commands and results; an empty assertion list is not proof.
+
+## Do not teach the mistakes
+
+- No booking codes in public collections or anonymous edits of arbitrary bookings.
+  Bind tickets to their account/seat, or verify a secret only the booker holds.
+- No public staff console. Use a signed-in role and check it on the server.
+  Label an intentionally public simulator in both UI and Codex.
+- Never interpolate visitor text into `innerHTML`: a stored XSS reached a staff
+  tablet in the study. Use `textContent` for names, contacts, notices and outbox text.
+- Never issue an “official receipt” for an unpaid donation. Record a pledge as a
+  pledge; count a paid gift only after a verified, deduplicated `order.paid` event,
+  with the gift's ID as its reference.
+- No fixed UTC offsets or one hard-coded event date. Use IANA zones and recurring
+  calendar rules; carry the same occurrence into site copy and all screens.
+- No sleep-and-retry event arrays or staff-device cron jobs. Use durable functions,
+  version checks, declared feeds and the server scheduler.
+- No live-only assets. Commit every asset the site serves, with its provenance,
+  and verify a clean checkout can build it. Declare only packages actually used.
+- No invented reviews, impact figures or verification. Label estimates and test
+  payments honestly; remove stale workaround claims when upgrading.

package/guides/app/SKILL.md

@@ -6,6 +6,9 @@ compatibility: Node 22 and Chrome; the studio's pinned toolkit and Wrangler.
 
 # Make an app
 
+For place-based builds, read [the six-build patterns](../app/PLACES.md): owner words to needs, records as objects, a local scene and ambience, one trusted operation for screens and AI, graceful graphics, and adversarial proof. Apply the same authority and honest-evidence rules to game economies and tickets.
+
+
 For the installed version’s payment, records and local-check contracts, start with
 `node_modules/@homie-rocks/studio/apps/APPS.md`. Its “Real Stripe test checkout on
 this computer” section is the supported offline-hosting path: real Stripe test

package/guides/game/SKILL.md

@@ -25,6 +25,9 @@ cover, doors and platforms, use declared entity `collider` state and movement's
 
 # Make a game
 
+For place-based builds, read [the six-build patterns](../app/PLACES.md): owner words to needs, records as objects, a local scene and ambience, one trusted operation for screens and AI, graceful graphics, and adversarial proof. Apply the same authority and honest-evidence rules to game economies and tickets.
+
+
 You are in a Homie studio when the folder (or one above it) has `studio.json`. If there
 is none, use the `studio-setup` skill first.
 

package/guides/shop/SKILL.md

@@ -49,27 +49,34 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
 3. Append `{ "method": "POST", "path": "…", "params": {…}, "body": <Stripe response> }`
    for **writes as well as reads**. Keep this setup's observations across batches.
    Product creation includes its default Price; link creation expands line items.
-   Product and Price Search use studio/origin metadata. Existing links are fetched by
-   IDs from the verified configuration; Stripe has no Payment Link metadata search.
-   Keep `.studio/stripe-mcp.json` when moving the studio to another computer. Without
-   it, repeat creates use their idempotency keys; outside Stripe's idempotency retention
-   window, recover the studio's existing link IDs before setup to avoid duplicates.
-   Follow search `next_page` cursors. Search is eventually consistent: write responses
-   are the immediate evidence. On an uncertain write, retry its exact idempotency key;
-   never discard successful responses or invent IDs. Start a new read set when checking
-   later external edits, changing accounts, or changing mode.
+   Product and Price Search use studio/origin metadata. Payment Links use paginated
+   list reads with `expand[]=data.line_items`, then filter studio/origin metadata locally;
+   Stripe has no Payment Link metadata search. There is no per-link read loop.
+   The planner saves public observations in `.studio/stripe-mcp-observations.json` and
+   reuses them on the next call; send only new responses. Keep that file and
+   `.studio/stripe-mcp.json` when moving computers. Changed shop/slot settings refresh
+   mutable links while retaining product/price discovery. Account, mode and origin
+   changes start separate reads. Pass `refresh: true` for Dashboard changes or a fresh
+   verification before webhook installation (CLI: include it in `--have` input).
+   Follow search `next_page` and list `starting_after` cursors. On an uncertain write,
+   retry its exact idempotency key; never discard successful responses or invent IDs.
 4. Call `stripe_shop_plan` with `verify: true` using those observations (CLI
    `homie-studio shop verify --have plan-input.json`). Verification checks real fields,
    line items, menus, slot limits and portal settings. It saves compact public Worker
    configuration and provenance to `.studio/stripe-mcp.json`, never API response history.
-   Deploy installs those links. Checkout then reports only `webhook-secret` missing;
+   Build writes public links to `site/dist/_site/stripe-shop-links.json`; deploy ships
+   that asset, with only its path in Wrangler vars. Large catalogues never use a text
+   binding. Deploy after verifying, including when setup began on an already-live site. Checkout then reports only `webhook-secret` missing;
    it cannot open until signed payment events can confirm orders. Changing shop.json,
    the slot manifest or origin requires verification again. 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
+   checks the same account as the MCP, and installs only the signing secret through
+   Wrangler stdin. If Stripe CLI is missing, the tool installs the official
+   `@stripe/cli@latest` npm package automatically, checks the executable, then continues.
+   An installation failure reports npm permissions/PATH and a retry command. 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
@@ -80,6 +87,14 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
    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.
 
+Upgrades accept 0.51.6 verifications without a source fingerprint only when their
+saved content fingerprint still matches the current shop, slots, site and mode.
+Actual changes name the affected settings and require verification. An unfinished
+setup still builds and deploys with checkout closed and one next step: finish
+`stripe_shop_plan` with `verify: true`. Missing/unreadable assets also close checkout;
+old link secrets cannot reopen it. Cached observations never renew the verification
+time; use fresh reads if the private webhook tool requests them.
+
 Never create a webhook through model-visible Stripe MCP: its response exposes the signing secret.
 
 **Why the separate approval (checked 2026-10-14).** Stripe's

package/lib/app-needs.mjs

@@ -23,7 +23,7 @@ export function readAppNeeds(root, id) {
 }
 
 /** Run real UI actions. A failed or absent flow stays visible; continue collecting other needs. */
-export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {}, root, headless }) {
+export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {}, root, headless, restart }) {
   const results = [];
   const appBarrier=ready;
   ready=async (s,options)=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s,options);};
@@ -31,7 +31,7 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
   const surface = name => { const s = surfaces.find(s => s.name === name && (!activeRole || s.role === activeRole)) ?? surfaces.find(s => s.name === name); if (!s) throw new Error(`unknown surface ${name}`); return s; };
   for (const need of plan.needs) {
     activeRole = need.role;
-    const names = [...new Set([...(need.steps ?? []), ...(need.assertions ?? [])].map(s => s.surface).filter(Boolean))];
+    const names = [...new Set([...needSteps(need.steps), ...(need.assertions ?? [])].map(s => s.surface).filter(Boolean))];
     const saved = new Map();
     const run = async item => { if (!headless) throw new Error('headless MCP proof requires local dev and its test credential'); return headless(item,item.role ?? need.role); };
     let waiting = 'validating assertions';
@@ -41,19 +41,34 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
       const popupNames=new Set((need.steps??[]).map(s=>s.popup).filter(Boolean));
       for (const name of names) { if(popupNames.has(name))continue; const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
       for (const name of new Set(need.assertions.filter(a => a.effect).map(a => a.surface))) await surface(name).frame.evaluate(() => { window.__homieNeedsEffects = []; });
-      for (const rawStep of need.steps ?? []) {
+      const perform = async rawStep => {
         const step=resolveNeedResults(rawStep,saved);
+        if(step.concurrent){
+          if(!Array.isArray(step.concurrent)||step.concurrent.length<2)throw new Error('concurrent needs at least two steps');
+          if(needSteps(step.concurrent).some(s=>s.restart||s.capabilities))throw new Error('Restart and capabilities changes must be outside a race');
+          const results=await Promise.allSettled(step.concurrent.map(perform));
+          const failed=results.find(r=>r.status==='rejected');if(failed)throw failed.reason;return;
+        }
+        if(step.restart){if(!restart)throw new Error('Restart requires the local dev controller');await restart();for(const s of surfaces)await ready(s);return;}
+
         if (step.mcp || step.schedule) {
           waiting = step.mcp ? `MCP ${step.mcp.tool ?? step.mcp.method} as ${step.role ?? need.role ?? 'unspecified'}` : `schedule ${step.schedule.name}`;
           const value = await run(step);
           if (step.save) { if(saved.has(step.save))throw new Error(`duplicate saved result ${step.save}`); saved.set(step.save,value); }
-          continue;
+          return;
         }
         const target=surface(step.surface);
         if(!step.reload)await ready(target);
         const { page } = target;
+        if(step.capabilities){
+          if(typeof step.capabilities.webgl!=='boolean')throw new Error('capabilities.webgl must be boolean');
+          await page.evaluateOnNewDocument(configureWebGL,step.capabilities.webgl);
+          await page.reload({waitUntil:'domcontentloaded'});await ready(target);return;
+        }
+        if(Object.hasOwn(step,'clock')){await page.evaluate(value=>window.homieApp.setTestClock(value),step.clock);return;}
+
         waiting = `${step.surface}: ${step.reload ? 'reload and arrival readiness' : step.selector}`;
-        if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); continue; }
+        if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); return; }
         const act = fn => actInApp(target,step.selector,fn,{ready});
         if (step.click && step.popup) {
           let listener,timer;
@@ -67,11 +82,15 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
             await page.bringToFront();
           } finally {clearTimeout(timer);page.off('popup',listener);}
         }
+        else if(step.forceClick){await act(frame=>frame.$eval(step.selector,el=>{
+          const disabled=el.disabled;try{el.disabled=false;el.click();}finally{el.disabled=disabled;}
+        }));}
         else if (step.click) {await act(frame=>frame.click(step.selector));await page.bringToFront?.();}
         else if (step.fill !== undefined) { await act(async frame=>{ await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }); }
         else if (step.select !== undefined) await act(frame=>frame.select(step.selector, String(step.select)));
         else throw new Error('step needs click, fill, select or reload');
-      }
+      };
+      for(const step of need.steps??[])await perform(step);
       for (const rawAssertion of need.assertions) {
         const assertion=resolveNeedResults(rawAssertion,saved);
         if (assertion.result || assertion.records || assertion.file || assertion.mcp) {
@@ -170,3 +189,19 @@ export function resolveNeedResults(value,saved) {
   }
   return value;
 }
+
+/** Flatten only action groups; used for browser/role discovery before a race starts. */
+export function needSteps(steps = []) { return steps.flatMap(s => s.concurrent ? needSteps(s.concurrent) : [s]); }
+export function configureWebGL(enabled) {
+  window.__homieWebGLDisabled = !enabled;
+  if(window.__homieWebGLWrapped)return;
+  window.__homieWebGLWrapped = true;
+  for(const proto of [globalThis.HTMLCanvasElement?.prototype,globalThis.OffscreenCanvas?.prototype]) {
+    if(!proto)continue;
+    const original = proto.getContext;
+    proto.getContext = function(kind, ...args) {
+      if(window.__homieWebGLDisabled && /^(webgl2?|experimental-webgl)$/.test(kind))return null;
+      return Reflect.apply(original,this,[kind,...args]);
+    };
+  }
+}

package/lib/build.mjs

@@ -1,3 +1,4 @@
+import {verifiedMcpConfig,publicMcpSetup} from './shop-mcp.mjs';
 import { directoryUrl } from '../worker/directory-choice.mjs';
 import { domainOrigin } from './studio.mjs';
 import { appProblems } from '../worker/app-format.mjs';
@@ -686,6 +687,10 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // GAME PARTS: every packed version of every SHARED part into dist/parts/, and its index; a private part is never copied.
   const partsBuilt = buildParts(root, dist, { studio, log });
   mkdirSync(join(dist, '_site'), { recursive: true });
+  if(publicMcpSetup(root)) {
+    const verified=verifiedMcpConfig(root);
+    writeFileSync(join(dist,'_site','stripe-shop-links.json'),JSON.stringify({config:verified?.result.config??null,next:verified?null:'Ask your AI to finish stripe_shop_plan with verify:true.'}));
+  }
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const studioExtras = schemaExtras(s.schema, { where: 'studio.json site', types: 'Organization', log });
   // The Lounge (0.29.0): studio.json "lounge", checked; off when a game already has /lounge/.