@homie-rocks/studio 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -17,9 +17,63 @@ 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]
+
+## [0.58.0] - 2026-10-16
+
+**Plugin 0.58.0**
+
+Two new shared parts — an owner action checklist and a 3D terrain route map — and booking calendars that can skip or change single dates in a weekly series.
+
+### Added
+
+- Two Apache-2.0 shared building blocks: an owner action checklist with visible consequences, one-tap confirmation, server-authorized undo and existing studio role/origin checks; and a three.js terrain route map with a local heightmap coastline, route tube, markers and phone/TV camera controls. Both include standard part manifests, catalogue entries, AI integration docs, self-contained previews and fast logic checks. No tile service is required.
+- Weekly booking calendars can omit individual dates or override an occurrence's time, capacity and duration. Occurrence IDs stay stable when a start time changes; undefined overrides, off-series or invalid dates and ambiguous DST times are refused, and a date that already has reservations cannot be silently removed.
+
+### Changed
+
+- Shared terrain map: smooth high-resolution coast, lit terrain with cavity shading, animated depth-coloured water and foam, sky/haze, flowing elevated route, collision-aware leader labels, intro camera and measured-frame lite fallback. Owner checklist distinguishes pending, confirming, done and undone, announces actual consequences, labels irreversible actions and restores fresh pending actions after undo.
+
+### Fixed
+
+- Public checklist proposals require per-action staff authorization, validate tokens, retain retry keys and use separate expiring undo grants. Terrain heightmaps restrict origins and PNG types and enforce byte/dimension budgets before decoding.
+- The MCP Events workerd conformance test parses SSE frames across HTTP chunks, including combined event/heartbeat frames and split UTF-8 (the intermittent 0.57.0 publish-gate failure); production delivery and webhook formats are unchanged. PR CI adds a path-filtered Events/webhook gate.
+- CI Chrome launches keep each caller's protocol timeout.
+
+### Upgrade notes
+
+- No migration and nothing to change. Studios use the new parts by asking their AI to add them from the catalogue; existing weekly calendars keep working, and dated exceptions are optional (see "Weekly calendar exceptions" in `packages/studio/docs/toolkit-place-patterns.md`).
+
+## [0.57.0] - 2026-10-16
+
+**Plugin 0.57.0** · [release-2026-10-16-studio-0.57.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-16-studio-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**
+**Plugin 0.56.0** · [release-2026-10-15-studio-0.56.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-15-studio-0.56.0)
 
 Studios scale with hibernating rooms, add custom routes with built-in access checks, and deploy reliably with background queue handlers.
 

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/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/docs/toolkit-place-patterns.md

@@ -66,3 +66,19 @@ Tokens are bound to this origin, limited to the exact named tools, expire after
 ## Deployment
 
 Cloudflare's official MCP request interface cannot authorize new static-asset uploads with an upload JWT; deploy with Wrangler, Cloudflare's own CLI using browser OAuth.
+
+## Weekly calendar exceptions
+
+`calendarSlots` (also exposed by `ctx.bookings.calendar`) accepts `exceptions`,
+keyed by local `YYYY-MM-DD`. Use `null` to omit a holiday or an object containing
+`time`, `capacity` and/or `durationMinutes` to override that occurrence. Dates
+must belong to the declared range and weekdays. The occurrence ID remains based
+on the original series time when an exception changes its start time. DST gaps
+and ambiguous times refuse rather than silently changing the booking. Publishing
+new calendar data does not itself move existing reservations or change payments.
+
+A `durationMinutes` exception replaces the series `days` duration for that date.
+Explicit `undefined` override values are invalid. Removing a published slot with
+active reservations is refused by the database (`slot has active bookings`).
+Release or cancel those reservations through the payment-aware booking flow before
+deleting the slot; omitting a generated date alone does not delete a published row.

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/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import {ensureStudioSigningKey} from './studios-keys.mjs';
 import {redactText} from './redact.mjs';
 import {enableReadReplication} from './read-replication.mjs';
 import {ensureBackgroundQueues,backgroundQueues} from './background-queue.mjs';
@@ -440,6 +441,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
   }
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
+  try{await ensureStudioSigningKey(readStudio(root),w);}catch(error){return refuse(error.message);}
   if (paidReleases(root).length) {
     const bin = wranglerBin(root);
     const uploadOptions = { cwd: workerDir(root), env: { ...process.env, CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
@@ -664,6 +666,7 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   const started = Date.now();
   const dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
+  try{await ensureStudioSigningKey(readStudio(root),w);}catch(error){return refuse(error.message);}
   step(`deployed ${names.worker ?? 'the Worker'} in ${Math.round((Date.now() - started) / 1000)} s`);
   const repo = repoOf(root);
   step(repo ? `the live site knows its GitHub repository (${repo}), for the Claude app's hand-off` : 'no GitHub repository found here (no HOMIE_REPO, studio.json "github" or git remote): the Claude app\'s card asks the person which it is');

package/lib/needs-headless.mjs

@@ -26,7 +26,7 @@ export function needsHeadless({url,secret,app,meta,scope,sessionFor}) {
       if(!call?.tool)throw new Error('MCP step requires tool and optional arguments');
       const result=await client.callTool({name:call.tool,arguments:call.arguments??{}},undefined,{timeout:item.schedule?15000:10000});
       if(result.isError)throw new Error(result.content?.filter(c=>c.type==='text').map(c=>c.text).join('; ')||'MCP tool failed');
-      if(result.structuredContent!==undefined)return result.structuredContent;
+      if(result.structuredContent!==undefined){const value=result.structuredContent;return value?.kind==='untrusted-tool-data'?value.data:value;}
       const content=result.content?.filter(c=>c.type==='text');
       if(content?.length===1) {try {const parsed=JSON.parse(content[0].text);return parsed.kind==='untrusted-tool-data'?parsed.data:parsed;}catch{}}
       return result;

package/lib/studios-keys.mjs

@@ -0,0 +1,13 @@
+import {generateKeyPairSync,randomUUID} from 'node:crypto';
+/** Key material travels only in memory and Wrangler stdin. Never return it or include command output in errors. */
+export async function ensureStudioSigningKey(studio,w){
+ if(!studio.mcp?.studios)return;
+ const result=await w(['secret','list']);
+ if(result.code!==0)throw new Error('Cannot inspect studio signing key bindings');
+ let names;try{names=JSON.parse(result.stdout??result.out);}catch{throw new Error('Cannot inspect studio signing key bindings');}
+ if(names.some(entry=>entry.name==='STUDIO_SIGNING_KEY'))return;
+ const {privateKey}=generateKeyPairSync('ed25519');
+ const key={...privateKey.export({format:'jwk'}),kid:randomUUID()};
+ const saved=await w(['secret','bulk'],{input:JSON.stringify({STUDIO_SIGNING_KEY:JSON.stringify(key)})});
+ if(saved.code!==0)throw new Error('Cannot provision studio signing key');
+}

package/lib/template-history.json

@@ -4092,6 +4092,90 @@
      }
     }
    }
+  },
+  "0.57.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## 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"
+      }
+     }
+    }
+   }
+  },
+  "0.58.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## 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/netplay/NETPLAY.md

@@ -290,6 +290,13 @@ at once, with bots filling the slots (Gem Rush: 1 human + 2 bots).
 - A human who leaves turns back into a bot in the same body.
 - `trim()` removes surplus bots between rounds.
 - After every change the host calls `net.roster(slots)`.
+- A browser host may receive `join` before its world is ready. Once it publishes a roster,
+  snapshot traffic makes the relay retry any connected replica seat missing from that roster,
+  with delays doubling from 1 second to a 30-second cap, for at most eight retries per peer
+  and host. A roster seat (including `agent.seat` for host-driven AI) acknowledges the claim.
+  If still unacknowledged after the final wait, the relay logs once and stops retrying. Treat a repeated `join` for an
+  already claimed seat as idempotent; keep its body and score. This uses the existing wire
+  message, including for older bundled clients. Rules hosts reconcile seats separately.
 
 **Join in progress.**
 1. The `welcome` carries the last snapshot, round, roster and **all keyed state**. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/parts/README.md

@@ -0,0 +1,28 @@
+# Toolkit parts catalogue
+
+These are reusable files, not new npm packages or complete apps. The catalogue entries
+are the standard `part.json` records, also collected in `catalogue.json` for local browsing.
+
+| Part | What it supplies | Source | Licence |
+| --- | --- | --- | --- |
+| [Owner action checklist](owner-action-checklist/README.md) | Consequence-first owner/staff action UI, server integration boundary, optional undo | Owner action checklist / Homie toolkit | Apache-2.0 |
+| [Terrain route map](terrain-route-map/README.md) | Local heightmap coast, draped route, markers and phone/TV camera controls | Terrain route map / Homie toolkit | Apache-2.0 (three.js MIT) |
+
+Each folder includes its licence, attribution, AI integration contract, tunables and small
+working preview. Ryan Campbell authored both. To preview locally, serve this directory with
+a static HTTP server, then open `<id>/preview/index.html`.
+
+These public source parts are explicitly shared in their manifests. This checkout is not
+a deployed studio and does not invent a catalogue host or claim a live directory listing.
+To distribute from a studio, retain the original provenance/credit, place these original
+source folders under that studio's `parts/`, run the existing `parts share` checks/packing,
+and deploy. The standard well-known catalogue then advertises exact immutable releases;
+consuming studios use `parts_find` / `part_add`, never copy another studio's release by hand.
+Follow [PARTS.md](PARTS.md) for hashes, licence checks, packing and delivery. Do not serve
+unpacked source as an immutable release. Later changes to a shared release need a new part
+version. These initial parts are 1.0.0; no toolkit version is changed.
+
+Maintainers: `node scripts/build-shared-parts.mjs` builds the local map preview and rewrites
+hashes with `writeHashes`. `node --test packages/studio/test/shared-parts.test.mjs` checks
+logic, licences and real pack/catalogue/integrity paths. Run
+`node scripts/check-shared-parts.mjs` for one short browser check and 4× CPU measurements.