@homie-rocks/studio 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -17,6 +17,78 @@ 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.
 
+## [Unreleased]
+
+### Fixed
+
+- The MCP Events workerd conformance test now parses SSE frames across HTTP chunks, including combined event/heartbeat frames and split UTF-8. Its former one-chunk-per-event assumption caused the intermittent 0.57.0 publish-gate JSON parse failure; production delivery and webhook formats are unchanged. PR CI adds a path-filtered Events/webhook gate covering protocol, push, durable delivery and signed studio events.
+
+## [0.57.0] - 2026-10-16
+
+**Plugin 0.57.0**
+
+Studios can book at each other on behalf of a person, with proven studio identity and signed events, and friends joining a browser-hosted game at the same moment always get their seat.
+
+### Fixed
+
+- Browser-hosted games retry connected players’ seat claims when the host’s roster has no player body for them. Friends joining while the host is still loading now become seated players when its world is ready, including games with older bundled netplay clients. Fixes the 0.56.0 regression where Kart Royale replicas stayed bots across rounds; the two-browser check retains its original early-join timing. Host-driven AI seats count as acknowledged; missing-seat retries use capped exponential backoff and stop after eight attempts with one diagnostic, avoiding repeated joins when a game has no available body.
+- Studio ingress now limits requests by IP before discovery; failed JWKS fetches and unknown keys share an atomic 60-second per-origin fetch bound. Authentication errors are generic, with stage details only in owner audit logs. Signed events use the exact inbound path rule, honour disabled entries and reject non-object bodies with 400. Removed the unused v1-only webhook production dependency and documented exact manual key rotation steps through stdin.
+
+- Studio-to-studio limits aggregate by proven origin, outbound destinations require explicit configuration, and remote results retain untrusted provenance. Asserted handles never identify local accounts.
+- Availability allocates from a page snapshot in three queries instead of querying per slot, option and resource.
+- Studio identity uses Ed25519 private-key JWT and origin-hosted JWKS; events use Standard Webhooks v1a with the same key. Deploy provisions private keys through stdin. Office Allow/Deny is stored in D1, denied by default, with origin/handle audit entries. Owners exchange no secrets.
+- Studio events and business feed data share an 8,192-byte limit. Discovery and tokens are cached within each request; proof scripts use deploy URLs without reading Wrangler OAuth files.
+
+### Added
+
+- Studio-to-studio tools use the official MCP SDK with bounded HTTPS transport, receiver-owned OAuth client credentials and a verified studio caller distinct from an asserted end-user handle.
+- Booking availability returns paged schema.org offers and exact booking arguments, shared by AI tools and the existing booking choices UI.
+- Signed cross-studio events reuse Standard Webhooks, per-sender allowlists and durable business-event receipts to trigger studio functions.
+- Tools can call their own custom routes with the caller's identity and share opt-in Cloudflare Rate Limiting bindings.
+
+### Upgrade notes
+
+- Studios that call or accept calls from other studios list them in studio.json (outbound) and allow them in the office (inbound); the deploy provisions each studio's signing key — nothing is exchanged between owners. Existing OAuth browser connections, booking migrations and function delivery remain in use. No version bump or new migration. See `packages/studio/docs/studio-to-studio.md`.
+
+## [0.56.0] - 2026-10-15
+
+**Plugin 0.56.0**
+
+Studios scale with hibernating rooms, add custom routes with built-in access checks, and deploy reliably with background queue handlers.
+
+### Added
+
+- Studio Worker `useRoutes` hook for custom APIs, well-known files and callbacks, after Homie's matched routes and before Worker asset fallback, with response security headers.
+- Public `isOwner(request, env)` and `hasRole(request, env, app, role)` authorization helpers using existing live session and app access checks.
+- Secret capabilities may use `self` for the runtime studio origin, with origin and redirect restrictions retained.
+
+### Changed
+
+- Renew relay sequence epochs whenever a Gate opens a link, probe the room after a missed round start, refill quiet games across all matching pools, and coalesce peak increases without writing unchanged room reports.
+- Recover Gate relay transport failures with ordered backoff and bounded output queues; remove dead sessions so players can reconnect. Keep idle heartbeats at the edge through long breaks, exclude transport telemetry from session writes, and retain only QA markers from relay user agents. Match quiet public games in one pool, spread bursts through leased shard routing, and calculate daily peaks from concurrent shard totals.
+- Close failed room restores, detect unanswered clock pings, preserve live Gate multiplexing, bound crowd session storage, and avoid unchanged idle writes. Restore watcher rate limits without replay, shard matchmaking, and paginate aggregated room summaries.
+- Add an opt-in rules-host round-idle contract: finish both scoring-settlement ticks, persist the next-round deadline, and resume without simulating idle time.
+- Store Lobby rooms as SQLite rows and deliver room summaries through Queues. Hibernate player and watch sockets, including Gates and server-rule rooms, between settled rounds. Retain logical sessions and moderation state, detach idle relay streams, and restore complete world headers without repeating admission.
+
+### Fixed
+
+- Custom studio Workers that wrap only `fetch` now inherit missing toolkit queue and scheduled handlers in the generated entry, so background queue consumers attach during deploy. Custom handlers remain intact.
+- Deploy failures retain Wrangler's real error and context with secrets redacted, instead of showing only the last six lines.
+- Custom route role checks enforce fresh app launch gates. Custom Worker asset routes preserve generated authorization paths; same-origin mutation protection is exported and documented with reserved `/api/custom/*` paths and app cookie scope.
+- Custom `assets.run_worker_first` entries cannot exclude paths with `!`; the build refuses them so private app files always stay behind their access checks.
+- Late link subscriptions no longer trigger rules-view reconnect recovery; throwing listeners still return their unsubscribe function.
+- MCP publishing and its preflight use the connector's directory. Wrangler sign-in checks stop immediately when logged out and retry refresh collisions without blocking the event loop, including CLI status.
+- Scaffold, local database and login regression tests use OS temporary directories and work from the package test command.
+- New studios leave directory listing opt-in; existing explicit directory choices are preserved.
+- Deploy and storage sign-in checks retry shared Wrangler OAuth refresh races with bounded backoff and report the original diagnostic, distinguishing authentication from temporary check failures.
+- Room-link listeners immediately receive current state, so wall UIs mounted after welcome do not stay on “Connecting to Homie.”
+- Local dev refuses to serve until migrations and function registration succeed, preserving first-notice delivery on a fresh database.
+
+### Upgrade notes
+
+- `net.on('link', listener)` now calls the listener synchronously on subscription with `why: 'subscribe'` and `prev === state`, then reports changes as before.
+- Custom routes and authorization examples are in `packages/studio/docs/custom-routes.md` (the installed package uses `docs/custom-routes.md`).
+
 ## [0.55.0] - 2026-10-15
 
 **Plugin 0.55.0**

package/README.md

@@ -8,6 +8,8 @@ to its own Cloudflare account with Wrangler. The homie.rocks directory lists the
 
 Apps are one morphing screen, its roles and its parts: a customer phone, a staff tablet and a wall can share a 3D scene without rounds or scores. `homie-studio app new welcome` creates a working welcome queue in `apps/welcome/`; install its declared dependencies, build, then use `dev --lan` and the printed Wi-Fi address. `check welcome --url <origin>` proves a shared action and reconnect across three screens. Staff permissions, lasting D1 records, public QR/link helpers and customer standalone builds use the existing studio machinery. See [the app guide](apps/APPS.md).
 
+For studio-specific JSON APIs, well-known files and OAuth callbacks, see [custom Worker routes and authorization](docs/custom-routes.md).
+
 Most people never run this by hand: the Homie plugin for Claude Code, Codex and Grok does,
 and the person approves Cloudflare once in their browser.
 

package/apps/APPS.md

@@ -339,3 +339,12 @@ compiler; run `npm install` in the studio first if it is missing. Review the dif
 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.
+
+## Availability shared with an AI
+
+`studio_availability` and `context.bookings.availability` return paged offers with
+valid booking arguments, checking the existing slots, holds, options and resources.
+Pass that result to `createBookingChoices({container,availability})`; `value()`
+returns the selected offer's booking arguments for the same booking tool an AI
+uses. Availability is a snapshot; authoritative holds still recheck capacity.
+See [the convention](../docs/studio-to-studio.md#availability-convention-v).

package/apps/apps.ts

@@ -78,7 +78,25 @@ export function createAppContext() {
 }
 
 /** Native accessible choices; submit value() to the same booking tool used by an AI. */
-export function createBookingChoices({container,options=[],resources=[]}:{container:HTMLElement;options?:Array<{id:string;name:string}>;resources?:Array<{id:string;name:string}>}) {
+export interface BookingAvailability {
+  convention: 'studio.booking-availability/1';
+  bookingTool: string;
+  items: Array<{identifier: string; name?: string; availabilityStarts?: string; booking: {app: string; collection: string; slot: string; quantity: number; option?: string; resource?: string; addons?: Record<string,number>}}>;
+  next: string|null;
+}
+export function createBookingChoices({container,options=[],resources=[],availability}:{container:HTMLElement;options?:Array<{id:string;name:string}>;resources?:Array<{id:string;name:string}>;availability?:BookingAvailability}) {
+  if(availability){
+    if(availability.convention!=='studio.booking-availability/1')throw new Error('Unsupported booking availability convention');
+    const label=document.createElement('label');label.textContent='Available bookings';
+    const select=document.createElement('select');select.name='booking';
+    const empty=document.createElement('option');empty.value='';empty.textContent='Choose a booking';select.append(empty);
+    const bookings=availability.items.map(item=>structuredClone(item.booking));
+    for(const [index,item] of availability.items.entries()){
+      const option=document.createElement('option');option.value=String(index);option.textContent=[item.name??item.booking.slot,item.availabilityStarts].filter(Boolean).join(' · ');select.append(option);
+    }
+    label.append(select);container.append(label);
+    return {value:():Partial<BookingAvailability['items'][number]['booking']>=>select.value===''?{}:structuredClone(bookings[Number(select.value)]),dispose:()=>label.remove()};
+  }
   const fields=new Map<string,HTMLSelectElement>();
   const group=document.createElement('fieldset');
   const legend=document.createElement('legend');legend.textContent='Choose an option';group.append(legend);

package/bin/homie-studio.mjs

@@ -973,7 +973,7 @@ async function main() {
   }
   if (cmd === 'status') {
     const studio = readStudio(root);
-    return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
+    return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && await whoami(root)) };
   }
   if (cmd === 'upgrade') {
     const plan = upgradePlan(root);

package/docs/custom-routes.md

@@ -0,0 +1,72 @@
+# Studio Worker routes
+
+In `site/src/worker.mjs`, register one handler at module evaluation. Keep the
+existing exports and registrations. Do not wrap the default export's `fetch`.
+
+```js
+import {useRoutes, isOwner, hasRole, requireSameOrigin} from '@homie-rocks/studio/worker';
+
+useRoutes(async (request, env, ctx) => {
+  const url = new URL(request.url);
+  if (url.pathname === '/.well-known/example.json') {
+    return Response.json({name: 'My studio'});
+  }
+  if (url.pathname === '/api/custom/refresh') {
+    if (request.method !== 'POST') return new Response('POST required', {status:405});
+    const refused = requireSameOrigin(request);
+    if (refused) return refused;
+    if (!(await isOwner(request, env))) return new Response('Unauthorized', {status: 401});
+    // Validate input, then perform the owner-authorized mutation here.
+    return Response.json({ok: true});
+  }
+  // Return undefined or null to continue to the studio's static assets / 404.
+});
+```
+
+Homie's matched routes always take precedence, including its office, OAuth,
+MCP, discovery, app and game routes, and their authorization refusals. Use a
+separate namespace under `/api/custom/`, such as `/api/custom/callbacks/provider` for your OAuth callback;
+`/oauth/*` belongs to Homie. Unmatched requests reach your handler before static
+assets inside the Worker. Cloudflare normally serves existing public static files
+without invoking the Worker. If a custom route must override such a file, put
+`{"assets":{"run_worker_first":true}}` in the studio's `wrangler.custom.json`;
+build/deploy preserves that setting. To intercept only selected files, use
+`{"assets":{"run_worker_first":["/feed.json"]}}`. These paths are unioned with
+Homie's generated `/games/*`, `/_studio/*`, `/_site/*` and per-app paths. Those
+paths must reach the Worker to enforce private app authorization; custom arrays
+(including empty arrays) or `false` cannot remove them. Exclusion patterns (starting with `!`) are refused at build, because they would take those paths out from behind their access checks. A second `useRoutes` call replaces the handler; `useRoutes(null)` removes
+it. Register configuration only, never request data, at module scope.
+
+The handler may return a `Response`, `null` or `undefined`. Errors propagate as
+Worker errors. Responses keep streaming and pass through Homie's normal HTML
+security headers, concept-mode handling and database change delivery. Custom
+responses also receive `X-Content-Type-Options: nosniff` and a default
+`Referrer-Policy: strict-origin-when-cross-origin`. WebSocket upgrades are preserved.
+Use `ctx.waitUntil(promise)` for work that must finish after the response.
+
+`await isOwner(request, env)` recognizes the live owner session issued by passkey
+sign-in (including expiry and revocation), configured owner player accounts, and
+trusted owner tool identity. Read/office bearer keys alone do not make a browser
+the owner. `await hasRole(request, env, appId, roleName)` uses the app's declared
+role and existing access checks: public roles permit visitors; private roles
+require the same private link or handoff session and live grants as the app.
+Unknown apps and roles return false. The explicit role argument takes precedence
+over query parameters. These helpers authorize identity; custom mutations must
+also validate the request method, Origin/CSRF protection, input and OAuth state.
+
+`requireSameOrigin(request)` reuses the studio's browser Origin checks and returns
+`null` on success or a 403 `Response` to return immediately. Use it with an explicit
+POST (or other mutation method) check before cookie-authorized changes.
+
+Use `/api/custom/*` for studio-owned endpoints: `api` is reserved from game and app
+IDs, so future experiences cannot take over that namespace. An app handoff cookie
+is scoped to `/<app>/`; the browser does **not** send it to `/custom-api/...` or
+`/api/custom/...`. For app role mutations, use the built-in `/<app>/api/app/records/*`
+endpoints or an app tool with its existing grant checks. A studio-wide custom
+endpoint can use the owner session; do not broaden app cookies or assume a handoff
+cookie will authorize `hasRole` outside its app path. Private/invite launches
+also require launch access even for a declared anonymous visitor role.
+
+For function HTTP calls whose destination is `self`, use direct `/api/` endpoints
+such as `/api/custom/refresh`, not page URLs that redirect. Self calls use
+`redirect:'error'`; a redirect fails instead of forwarding credentials.

package/docs/studio-to-studio.md

@@ -0,0 +1,248 @@
+# One studio acting at another
+
+A concierge can discover a venue, select a visit, reserve it for a person and tell
+its host when they will arrive. Each studio runs its own tools, OAuth, database and
+functions. The same mechanisms apply to a resort stay or any other collaboration.
+
+## Client (t)
+
+Tools and functions receive `context.studios`:
+
+```ts
+const origin = 'https://venue.example';
+const page = await ctx.studios.listTools(origin); // pass {cursor: page.nextCursor}
+const available = await ctx.studios.call(origin, 'studio_availability', {
+  app: 'venue', collection: 'bookings'
+});
+if (available.isError) throw new Error('Availability could not be read');
+// Inspect available.data.items, choose an offer, then:
+const booked = await ctx.studios.call(origin, 'studio_book', {
+  ...chosenOffer.booking, id: stableBookingId, expiresAt: Date.now() + 600000
+}, {assertedHandle: 'guest-42'});
+if (booked.isError) throw new Error('Reservation was refused');
+```
+
+The official MCP TypeScript client owns initialization, Streamable HTTP/SSE,
+OAuth discovery, client authentication, schema validation and protocol errors.
+`call` returns `{source:{origin,authenticated},untrusted:true,isError,data?,content}`. Structured content is preserved; the
+kit's legacy `untrusted-tool-data` envelope is decoded while retaining the untrusted marker and provenance. `listTools` and each description are also labelled untrusted. Before any `ctx.ai` call, wrap remote data and descriptions as untrusted input, preserving `source` and `untrusted`; never concatenate them into system instructions. Content and
+`data` remain untrusted business data, never instructions or verified claims.
+Transport failures reject; tool failures return `isError:true`. No automatic
+booking or payment retries are introduced. Use stable business IDs for retries.
+
+Each operation has a ten-second deadline including discovery, a 1 MiB response
+limit before SDK parsing, and a 64 KiB argument limit. Origins must be bare HTTPS
+origins on port 443 with public DNS names. IP literals (including IPv6, mapped and integer forms), localhost, .localhost, .local and .internal are refused unless that exact outbound entry explicitly sets `allowPrivate:true`. Config keys are normalized; duplicate normalized keys or mismatched `origin` fields fail. Never take an origin from model or user input without checking it against a list of permitted origins. All redirects are refused. Every fetch, including OAuth metadata and token
+requests, must stay on the chosen origin. Credentials are issuer-pinned. A client
+and its transport close after each operation; discovery and tokens are cached per origin within the request; tool listing is cursor-paged.
+Keep the toolkit's `global_fetch_strictly_public` compatibility flag for
+Worker-to-Worker HTTP calls. Every destination must be configured and delegated to the calling tool. Public anonymous calls require `anonymous:true` on that exact outbound entry. An unknown origin never falls back to anonymous. Studio code is trusted Worker
+code: these safeguards are not a sandbox for imported JavaScript. Choose trusted
+remote operators; this does not implement DNS address pinning.
+
+## Studio identity and allowlists (u)
+
+Each studio deploy generates its own Ed25519 key into the `STUDIO_SIGNING_KEY`
+Worker secret via stdin. Private keys never appear in model output, source or
+studio.json. Existing keys survive redeploys. Owners exchange nothing.
+The caller publishes only public keys at `https://<origin>/.well-known/jwks.json`.
+The receiver fetches that exact origin with bounded responses and no redirects.
+
+B declares permitted capabilities:
+
+```json
+{"mcp":{"studios":{"inbound":{"concierge":{
+  "origin":"https://concierge.example",
+  "tools":["studio_availability","studio_book"]
+}}}}}
+```
+
+A delegates the outbound destination:
+
+```json
+{"mcp":{"studios":{"outbound":{"https://venue.example":{
+  "tools":["plan_drive"]
+}}}}}
+```
+
+B's owner opens **Office → AI connections** and clicks **Allow** for the
+configured calling origin. All start denied. Allow/Deny is stored in D1 and takes
+effect on every dispatch without redeploying, including existing tokens. Tool and
+event capability declarations remain in configuration. Audit entries show the
+calling origin and the asserted handle, not a misleading local account name.
+
+`/oauth/token` accepts `client_credentials` with RFC 7523 `private_key_jwt`,
+`scope=studio`, and the receiver's `/mcp` resource. The client ID, issuer and subject
+are the caller's canonical origin; audience is the exact receiver token endpoint.
+Assertions have short expiry, `kid`, and a one-use `jti` checked atomically in D1.
+The receiver accepts Ed25519/EdDSA keys. Five-minute opaque access tokens are hashed
+in D1. Browser OAuth continues using the existing provider.
+
+JWKS cache lifetime is five minutes. Failed fetches are cached for 60 seconds;
+unknown `kid` refreshes are limited to once per origin per 60 seconds, including
+concurrent requests. Token and studio-hook requests share a mandatory limit of
+60 requests per IP per minute before key discovery. Throttled requests return
+429 with `Retry-After: 60`. Authentication failures return the same generic 401;
+only the owner-visible audit log records the failed stage.
+
+### Manual key rotation
+
+Rotation is manual today. From the studio's `site/` directory (the directory with
+its deployed `wrangler.jsonc`), run the following with the deployed origin in
+`STUDIO_ORIGIN`. These commands fetch only public keys; the new private key stays
+in the Node process and Wrangler stdin. Do not enable shell tracing or print the
+bulk input. Use the same Wrangler environment/account as the existing deployment.
+
+```sh
+export STUDIO_ORIGIN=https://your-studio.example
+node --input-type=module <<'NODE' | npx wrangler secret bulk
+import {generateKeyPairSync, randomUUID} from 'node:crypto';
+const response = await fetch(new URL('/.well-known/jwks.json', process.env.STUDIO_ORIGIN), {redirect:'error'});
+if (!response.ok) throw new Error('Cannot read existing public keys; rotation aborted');
+const jwks = await response.json();
+if (!Array.isArray(jwks.keys) || !jwks.keys.length || jwks.keys.length > 7 ||
+    jwks.keys.some(k => !k || k.d || k.kty !== 'OKP' || k.crv !== 'Ed25519' || !k.x || !k.kid))
+  throw new Error('Invalid or too many retained public keys; rotation aborted');
+const previous = jwks.keys.map(({kty,crv,x,kid}) => ({kty,crv,x,kid,alg:'EdDSA',use:'sig'}));
+const {privateKey} = generateKeyPairSync('ed25519');
+const next = {...privateKey.export({format:'jwk'}), kid:randomUUID()};
+process.stdout.write(JSON.stringify({
+  STUDIO_PREVIOUS_PUBLIC_KEYS: JSON.stringify(previous),
+  STUDIO_SIGNING_KEY: JSON.stringify(next)
+}));
+NODE
+```
+
+1. Confirm Wrangler reports that **both** secrets were updated. If the command
+   fails, inspect the public JWKS and Wrangler deployment status before retrying.
+2. Check `curl --fail "$STUDIO_ORIGIN/.well-known/jwks.json"`: it must publish the
+   new `kid` and the previous public keys, with no `d` field. Peer caches may take
+   up to 60 seconds to refresh for the new `kid`; retry failed operations with
+   their original stable business/event IDs.
+3. Retain the old public keys for at least ten minutes after successful rotation.
+   Then, provided no other rotation is still in its overlap period, remove them:
+   `printf '%s' '[]' | npx wrangler secret put STUDIO_PREVIOUS_PUBLIC_KEYS`.
+4. Check the public JWKS again: only the new public key should remain. Existing
+   signing keys survive future normal deploys. Deny the origin immediately if a
+   key is compromised; rotation overlap is not emergency revocation.
+
+```ts
+ctx.caller.studio // {origin:'https://concierge.example', verified:true,
+                  //  method:'private_key_jwt'}
+ctx.caller.actingFor // {assertedHandle:'guest-42', verified:false,
+                     //  assertedBy:'https://concierge.example'}
+```
+
+Verified means the caller proved possession of a key published by that HTTPS
+origin. It does not verify any person. `assertedHandle` permits only
+`[A-Za-z0-9._@-]`, 1–128 characters. Never match it to a local account or grant
+roles from it. It only separates bookings within the calling studio. A studio can
+assert any handle within its own origin; all handles share origin-level rate
+limits. Studio callers use only allowlisted public tools, never signed-in roles.
+
+References: [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523) and the
+[MCP client credentials extension](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx).
+
+## Availability convention (v)
+
+`studio_availability({app,collection,after?,quantity?,option?,resource?,addons?})`
+and `ctx.bookings.availability(...)` return:
+
+```json
+{"convention":"studio.booking-availability/1","bookingTool":"studio_book",
+ "items":[{"@type":"Offer","identifier":"[\"morning\",null]",
+   "availability":"https://schema.org/InStock","remaining":2,
+   "availabilityStarts":"2030-10-15T10:00:00Z",
+   "availabilityEnds":"2030-10-15T11:00:00Z",
+   "booking":{"app":"venue","collection":"bookings","slot":"morning","quantity":1}}],
+ "next":null}
+```
+
+The snapshot loads a page of slots, resource records and active allocations in three queries regardless of slot × option count (plus access-policy checks), and uses the same
+resource/option allocator as `studio_book`. It checks app visibility and slot-read
+grants. A page scans at most 50 slots and supports at most 64 alternatives per
+slot; `next` can be non-null even when no offers on this page are available.
+Only feasible options are returned. Add-ons and preferred resources can be checked
+as query inputs. No booking is taken during discovery. Holds still enforce capacity
+atomically; concurrent clients may see the same offer and only one may book.
+Expired holds continue occupying capacity until the existing expiry function
+releases them, matching the authoritative hold path.
+
+The existing `createBookingChoices({container,availability})` UI part accepts this
+same result and returns the selected offer's exact booking arguments from `value()`.
+Its existing explicit `options`/`resources` mode remains available. Share custom
+booking parts with an availability tool returning this convention and name their
+booking tool in `bookingTool`.
+
+[Schema.org Offer](https://schema.org/Offer) supplies `availability`, `identifier`
+and availability dates. A successful hold corresponds to a
+[Reservation](https://schema.org/Reservation): its `id` maps to `reservationId`,
+`state` to reservation status, and the chosen slot to `reservationFor`. The
+kit keeps its existing versioned hold response and payment lifecycle. Local
+`booking`, `remaining`, pagination and convention fields are explicit extensions;
+this is not a claim that schema.org defines a booking API.
+
+The [Agentic Commerce Protocol](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol)
+standardizes commerce/checkout interactions. Its separation of available offers
+from authoritative checkout is compatible with this convention, but it does not
+supply this toolkit's time-slot and multi-resource allocation schema. Availability
+does not invent checkout, represent a payment approval, or claim ACP conformance.
+
+## Signed arrival events (o)
+
+Use Standard Webhooks asymmetric `v1a` Ed25519 signatures with the same studio key and the envelope `{eventId,name,timestamp,source,data}`. On A's outbound destination, add:
+
+```json
+{"eventPath":"/hooks/studios/concierge","events":["arrival"]}
+```
+
+On B's inbound `concierge` entry, add
+`"events":{"arrival":"arrivals"}`. No shared event secret is needed. B's `mcp.events.arrivals` declares `event:"guest.arriving"`, an audience,
+and a schema for `{sender:{origin,verified:true},data:{booking,minutes}}`.
+Only mapped names can publish to local feeds. Define a function with
+`event:'guest.arriving'` to consume `event.data.data` and its verified
+`event.data.sender`. The sender cannot select an arbitrary local event type.
+
+```ts
+await ctx.studios.send('https://venue.example', 'arrival', {
+  id: stableArrivalId, data: {booking: bookingId, minutes: 10}
+});
+```
+
+The JavaScript `standardwebhooks` package currently supports HMAC `v1` only, so
+studio `v1a` uses Web Crypto directly, with fixed cryptographic and spec-framing
+regression vectors. The receiver verifies Standard Webhooks `id.timestamp.body` signatures with Web Crypto Ed25519, including a five-minute timestamp window. Both studio event envelopes and business-feed data are limited to **8,192 UTF-8 bytes**; oversized events return a clear 413 error. `webhook-key-id` selects the origin JWKS key; `webhook-origin` must match the configured sender and signed body. IDs are 1–128 letters,
+digits, underscores or hyphens. A receipt is committed atomically with the event
+using existing business-event publication. Identical retries return 204 without
+running the function again; a signed changed payload under the same ID returns
+409. Receipts survive event pruning. Function execution remains at least once:
+handlers must deduplicate external effects by event ID. If acceptance fails, the
+sender gets an error and can retry the same ID. Calls to `send` do not create an
+outbound retry queue; call from an existing durable function for automatic retries.
+The existing configured-feed/MCP Events subscription dispatcher remains available
+for subscription delivery. No new event bus or MCP method is introduced.
+
+## Friend routes and rate limits (p, q)
+
+`await ctx.fetchSelf('/api/friend-action', {method:'POST', body:...})` invokes the
+studio's registered `useRoutes` handler in-process. It carries the caller through
+the existing internal identity mechanism. `isOwner`, `hasRole`, and the studio's
+player lookup still perform their normal checks. Explicit cookies/Authorization
+headers, URL credentials and other origins are refused. A missing custom route
+returns 404. `fetchSelf` sets `Origin` to the local studio origin, so a custom route’s same-origin/CSRF check will pass; that check is not authorization. Routes must still check the propagated identity and roles. It does not borrow `fetchWithSecret` or mint an owner credential.
+
+`await ctx.rateLimit('friends')` uses a declared Cloudflare Rate Limiting binding,
+sharing the same namespace and account key between delegated tools:
+
+```json
+{"mcp":{"rateLimits":{"friends":{"binding":"FRIEND_RATE","tools":["join","reserve"]}}}}
+```
+
+In wrangler.jsonc, configure `ratelimits` with a stable `namespace_id`, name
+`FRIEND_RATE` and `simple:{limit:30,period:60}`. The helper returns `{success}`;
+the tool chooses its refusal response. No policy is enabled by default. Signed-in
+callers default to their identity key; studio callers default to `studio:<origin>` regardless of asserted handle. Public MCP callers expose `ctx.caller.clientAddressKey` and use that address-based key by default. Do not let customers select keys to bypass your policy.
+[Cloudflare's binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/)
+is an approximate per-location limiter, not a globally strict quota or booking
+capacity mechanism. Existing authoritative booking/database checks remain necessary.
+

package/functions/FUNCTIONS.md

@@ -424,3 +424,12 @@ 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.
+
+## Events from another studio
+
+An explicitly allowed studio can send a Standard Webhooks arrival event to
+`/hooks/studios/<connection>`. The receiver maps allowed names to declared business
+feeds and commits their existing durable receipt before acknowledging. Functions
+receive the verified sender origin separately from the sender's untrusted data.
+Use `context.studios.send` inside a durable function when sending needs retries.
+See [studio-to-studio](../docs/studio-to-studio.md) for setup and replay semantics.

package/guides/app/SKILL.md

@@ -365,3 +365,10 @@ Authoritative bookings/inventory are server-side `defineTool` actions with stric
 Initialise text controls and navigation before 3D rendering. Catch renderer creation failures inside the scene section; keep fallback text in normal flow, never over navigation. Add a navigation need and run `homie-studio check <id> --webgl-failure --shots .checks/no-webgl` to prove the controls work without WebGL.
 
 On TV, reserve `--homie-join-inset-bottom/right` (or the configured corner's top/left) plus a gap; `body.homie-join-visible` and `--homie-join-x/y/width/height` describe the shell card in the app frame too. See `node_modules/@homie-rocks/studio/docs/toolkit-place-patterns.md` for layout and text-first examples, connector setup and diagnostics.
+
+For studio-owned HTTP routes, read
+`node_modules/@homie-rocks/studio/docs/custom-routes.md`. Register with `useRoutes`
+and use `/api/custom/*` (game/app IDs cannot claim `api`). App handoff cookies are
+scoped to `/<app>/` and do not reach `/custom-api/...`; use built-in app record
+endpoints or app tools for role-authorized mutations. Use direct `/api/` endpoints
+for function `self` calls, which use `redirect:'error'`.

package/guides/playtest/scripts/playtest.mjs

@@ -542,17 +542,19 @@ async function soundSession(base, game, out, seconds, gameJson) {
   } finally { await close(h); }
 }
 
-/** A round with one person playing hard (a computer) and one doing nothing (a phone), both strangers in the public room. */
+/** A round with one person playing hard (a computer) and one doing nothing (a phone), in the same public room. */
 async function playSession(base, game, out, roundSeconds, gameJson) {
   const profile = actionProfile(gameJson, 'desk');
   const actions = newActions(profile);
   const active = await launch('desk', `${base}/${game}/play`);
-  const idle = await launch('phone', `${base}/${game}/play`);
+  let idle;
   try {
     const seat = async (h) => { const until = Date.now() + 45_000; while (Date.now() < until) { const s = await shell(h); if (s?.room && s.seat !== null && s.seat !== undefined && s.role) return s; await sleep(300); } return null; };
-    const [sa, si] = await Promise.all([seat(active), seat(idle)]);
+    const sa = await seat(active);
+    idle = await launch('phone', `${base}/${game}/play${sa?.room ? `?room=${encodeURIComponent(sa.room)}` : ''}`);
+    const si = await seat(idle);
     if (!sa || !si) { row('play', 'FAIL', { why: 'a browser never got a seat in 45 s' }); return; }
-    if (sa.room !== si.room) { row('play', 'FAIL', { why: `the two browsers landed in different rooms (${sa.room}, ${si.room}): two strangers who press Play must meet` }); return; }
+    if (sa.room !== si.room) { row('play', 'FAIL', { why: `the two browsers landed in different rooms (${sa.room}, ${si.room}): the invitation must join the same room` }); return; }
     const since = Date.now();
     // Only a round that STARTS after both are seated counts: a newcomer takes a bot's place mid-round and inherits
     // its body and score, so the round already running says nothing about how these two played.
@@ -597,7 +599,7 @@ async function playSession(base, game, out, roundSeconds, gameJson) {
       results: rowsR.map((x) => ({ place: x.place, score: x.score, bot: x.bot, who: x.seat === sa.seat ? 'the active player' : x.seat === si.seat ? 'the idle player' : x.bot ? 'a bot' : 'another person' })),
       scoreSamples: scores.filter((_, k) => k % 5 === 0).slice(0, 40), shot: 'play-round-over.png',
     });
-  } finally { await close(active); await close(idle); }
+  } finally { await close(active); if (idle) await close(idle); }
 }
 
 /** The studio's own checks, run as the creator would: the owner tests (port check) and the two-stranger round. */

package/lib/check.mjs

@@ -203,7 +203,14 @@ export async function check({ webglFailure = false, isolate = true, root = null,
       const ua = await browser.userAgent();
       await page.setUserAgent(`${ua} ${userAgentTag}`);
       const t0 = Date.now();
-      try { await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 90_000 }); } catch (error) {
+      let target = play;
+      if (players.length) {
+        const first = players[0].page;
+        await first.waitForFunction(() => Boolean(window.__shell?.room), {timeout: 90_000});
+        const room = await first.evaluate(() => window.__shell.room);
+        target = `${play}?room=${encodeURIComponent(room)}`;
+      }
+      try { await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 90_000 }); } catch (error) {
         if (cannotAsk) return { ...cannotAsk, play, why: `${cannotAsk.why} (The ${kind.name} browser could not open it either: ${String(error?.message ?? error).split('\n')[0].slice(0, 120)}.)` };
         throw error;
       }