@homie-rocks/studio 0.51.7 → 0.52.0

package/CHANGELOG.md

@@ -17,6 +17,60 @@ 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**
+
+Run your studio across more screens with reliable shared records, clearer checks and a simpler owner connection.
+
+### Fixed
+
+- **Reliable screens and saved settings:** App screens share simultaneous record reads across tabs, queue bursts and back off after connection failures. Writes stay separate and refresh cached reads; reconnect notices use plain language. Records-only apps remember device preferences and saved references after reload while keeping their iframe sandbox.
+- **Room for your wall display:** TV join cards reserve a measured safe area for your app, stay within a bounded size and wrap long addresses. Hiding the card returns that space to your content.
+- **Checks that match what people can use:** Covered controls fail checks immediately with the blocking element identified, including overlays outside the app frame. You can also check text navigation with graphics disabled using `check --webgl-failure`; fallback notices stay in the page flow so controls remain reachable.
+- **Clean toolkit type checks:** Collision, terrain and tile-coordinate code now passes strict `build --types` checks when imported into your app or game.
+
+### Added
+
+- **Connect your owner's AI with your existing login:** `connector` uses your Wrangler sign-in to save a private MCP configuration limited to the chosen tools, studio origin and expiry. You can revoke access; the server stores only token hashes and command output contains no bearer secret.
+
+### Changed
+
+- **Safer bookings and usable text controls:** Authoring guides show server-owned capacity with atomic versioned writes, tested with six simultaneous requests and one successful reservation. They explain how to initialise text controls before graphics and keep the app usable when 3D is unavailable.
+- **Clear deploy guidance:** Wrangler remains the path for uploading your site's static assets. The guide explains why Cloudflare's official MCP request interface cannot perform the required upload authorization.
+
 ## [0.51.7] - 2026-10-14
 
 **Plugin 0.51.7**

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/bin/homie-studio.mjs

@@ -37,7 +37,9 @@
  *                                         AI guides, chat review and game decisions think with Clef on this computer
  *                                         when Ollama has clef-flash (free; dev never downloads it), else scripted;
  *                                         --remote-ai: the real Workers AI, billed)
- *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio check <id> [--url <site>] [--shots <dir>] [--webgl-failure]
+ *   homie-studio connector --tools <name,...> --out <private-config.json> [--days 30]
+ *   homie-studio connector --revoke <id>
  *   homie-studio shoot <id> [--url <site> | --preview] [--frames 60] [--fps 30] [--device computer|phone]
  *                      [--out <dir>] [--hold <key code>] [--no-smoke] [--timeout 180]
  *                                         pictures of the game on a clock this command steps (one frame = 1/fps s
@@ -380,14 +382,14 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 const argv = process.argv.slice(2);
 const flags = new Map();
 // build --quick keeps compilation and type checks, skips rules generated play/smoke checks.
-const BOOL_FLAGS = ['quick', 'public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+const BOOL_FLAGS = ['webgl-failure', 'quick', 'public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a.startsWith('--')) {
     const [k, v] = a.slice(2).split(/=(.*)/s, 2);
     if (v !== undefined) flags.set(k, v);
-    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && (!BOOL_FLAGS.includes(k) || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && (!BOOL_FLAGS.includes(k) || k === 'revoke' && argv[0] === 'connector' || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
@@ -407,6 +409,7 @@ function print(result) {
   if (/^(style|assets|cast|anim)( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${artLines(result).join('\n')}\n`); return; }
   if (/^collision /.test(String(result.command ?? '')) && result.lines) { process.stdout.write(`${result.lines.join('\n')}\n`); return; }
   switch (result.command) {
+    case 'connector': lines.push(JSON.stringify(result,null,2)); break;
     case 'new':
       lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`), '', result.online);
       break;
@@ -831,6 +834,7 @@ const OUTWARD_FLAGS = {
   'setup attach': ['homie', 'client'],
   handoff: ['homie', 'client'],
   'players owner': ['url', 'revoke'],
+  'connector': ['url','tools','out','days','revoke'],
   'stats key': ['url', 'hours'], 'stats link': ['url'], 'stats revoke': ['url'], 'stats share': [],
   'office link': ['url', 'to'], 'office key': ['url', 'hours'], 'office announce': ['url', 'game', 'room', 'seconds'],
   'office invite': ['url', 'label', 'uses', 'count', 'days', 'server'], 'office launch': ['url', 'max'],
@@ -914,6 +918,7 @@ async function main() {
   }
   if (cmd === 'events') return (await import('../lib/events-cli.mjs')).eventsCommand(root, sub, positional, flags, { log });
   if (cmd === 'function' || cmd === 'functions') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
+  if (cmd === 'connector') return (await import('../lib/connector-token.mjs')).connectorToken(root,{url:flags.get('url'),tools:typeof flags.get('tools')==='string'?flags.get('tools').split(','):[],out:flags.get('out'),days:flags.has('days')?Number(flags.get('days')):30,revoke:flags.get('revoke')});
   if (cmd === 'tool') return (await import('../lib/tools-cli.mjs')).toolCommand(root, sub, positional, flags, { log });
   // A trailer is the plugin's video skill; this hands the words after the id over to it (lib/trailer.mjs).
   if (cmd === 'trailer') return trailerCommand(root, sub, argv.slice(argv.indexOf(sub) + 1), { skills: flags.get('skills') ?? null, slug: flags.get('slug') ?? null });
@@ -995,7 +1000,7 @@ async function main() {
       const results = [];
       for (const game of games) {
         const shots = flags.get('shots') ? resolve(flags.get('shots'), ...(games.length > 1 ? [game] : [])) : null;
-        const r = await tracked(root, 'checks', (report) => check({ root, url: site.url, game, shots, log, report, isolate:!flags.has('no-isolate') }), 'check');
+        const r = await tracked(root, 'checks', (report) => check({ webglFailure:flags.has('webgl-failure'), root, url: site.url, game, shots, log, report, isolate:!flags.has('no-isolate') }), 'check');
         results.push({ ...r, game, site: site.url, local: site.local });
         const receiptDir = join(root, '.studio', 'checks');
         mkdirSync(receiptDir, { recursive: true });

package/docs/toolkit-place-patterns.md

@@ -0,0 +1,68 @@
+# 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.
+
+Reserve an entire strip on either occupied axis, with a gap:
+
+```css
+.status { position: fixed; right: 20px;
+  bottom: calc(var(--homie-join-inset-bottom, 0px) + 20px); }
+.tee-sheet { position: fixed; left: 20px; bottom: 20px;
+  right: calc(var(--homie-join-inset-right, 0px) + 20px); }
+```
+
+For top/left join corners, use the corresponding top/left insets. Never position critical controls underneath the card merely because it ignores pointer events. Regression coverage measures actual rectangles at 1920×1080, 1280×720 and 3840×2160.
+
+## Authoritative capacity
+
+Bookings and inventory belong to server-side `defineTool` mutations, with strict schemas (`additionalProperties: false`) and atomic versioned writes. A client-writable generic ledger is not an inventory authority: six browsers can all read one remaining place and overwrite one another. Clients may display availability and request a reservation; they cannot supply remaining capacity, identity or a new inventory total.
+
+The executable [reservation example](../guides/app/examples/reserve.mjs) accepts only a slot ID. An owner-only action seeds `ctx.database.put('tee-0900', {remaining: 1, bookings: []}, {version: 0})`. `reserve` reads that row, derives the booking identity from `ctx.caller`, and writes with `{version: row.version}`. One SQLite statement checks the version and updates the entire row; a conflict is a failed reservation, never a success. Six simultaneous requests produce one winner and five conflicts. Do not expose this namespace through a generic client record mutation. Read availability through a separate read-only action. For retryable purchases add a server-owned idempotency key and settlement handling before charging.
+
+## Text first, graphics optional
+
+Bind navigation and text controls before creating a renderer. A failed WebGL context must not prevent those handlers from being installed:
+
+```ts
+renderTextControls();
+bindNavigation();
+try {
+  const renderer = new THREE.WebGLRenderer({canvas});
+  startScene(renderer);
+} catch {
+  canvas.hidden = true;
+  fallback.hidden = false; // a normal-flow status inside the scene section
+}
+```
+
+Keep the fallback inside the scene section, outside navigation; never use a fullscreen or fixed overlay. The shell's automatic fallback is a normal-flow status beside the canvas and does not intercept input. Author a Codex need that clicks navigation and asserts the resulting text; then run `homie-studio check <id> --webgl-failure --shots .checks/no-webgl`. This disables WebGL context creation before scripts run in every app frame and executes the same UI needs. A passing rendering check alone does not establish usable text controls.
+
+## Action diagnostics and types
+
+`check` tests whether the action target is covered before dispatch. An obstruction reports the surface, target selector and covering element immediately; remove the overlay or repair its layout before retrying. Navigation/detachment handling does not replay an ambiguous dispatched action.
+
+`build --types` checks imported toolkit sources too. Collision/terrain closure narrowing and tile-coordinate narrowing are fixed in the toolkit; fresh studios need no local suppressions or edits to `node_modules`.
+
+## Connect another studio without another approval page
+
+Use the new studio's directory and the owner's existing Wrangler login (the same Cloudflare account must have D1 access). One command writes a connector config, never its bearer to stdout:
+
+```sh
+homie-studio connector --tools studio_stats --out /private/path/studio-connector.json
+```
+
+Load that file directly into the AI client's connector configuration using its local configuration/import mechanism. Do not paste, print or include the file in chat or commit it. The file is created exclusively with mode 0600; existing files are never overwritten. Only the file path, token ID, scopes and expiry are reported. The config targets this studio's `/mcp/auth` endpoint. No browser approval is needed when Wrangler is already authenticated; this command does not deploy anything.
+
+Tokens are bound to this origin, limited to the exact named tools, expire after 30 days by default (`--days 1` through `--days 90`), and cannot read MCP resources or subscriptions. D1 stores only the token hash and its scope metadata. Revoke with `homie-studio connector --revoke <id>` from the same studio. Every dispatch rechecks expiry and revocation. A login to a different studio alone does not grant authority over this database.
+
+## 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.

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
@@ -354,3 +357,11 @@ 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.
+
+### Places: capacity, TV space and failed graphics
+
+Authoritative bookings/inventory are server-side `defineTool` actions with strict schemas and atomic versioned writes, never a client-writable generic ledger. Use [the capacity example](examples/reserve.mjs): seed one place through an owner action; six simultaneous reservation requests must yield exactly one winner. Derive identity from the caller; expose neither inventory totals nor the authoritative namespace as client mutations.
+
+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.

package/guides/app/examples/reserve.mjs

@@ -0,0 +1,13 @@
+import {defineTool} from '@homie-rocks/studio/tools';
+export default defineTool({
+ name:'reserve',description:'Reserve one place in a server-owned slot',audience:'signed-in',namespace:'capacity',
+ inputSchema:{type:'object',properties:{slot:{type:'string',pattern:'^tee-[0-9]{4}$'}},required:['slot'],additionalProperties:false},
+ async handler({slot},ctx){
+  const row=await ctx.database.getVersioned(slot);
+  if(!row)return {ok:false,reason:'Unknown slot'};
+  const value=row.value;
+  if(value.remaining<1)return {ok:false,reason:'Full'};
+  const result=await ctx.database.put(slot,{remaining:value.remaining-1,bookings:[...value.bookings,ctx.caller.id]},{version:row.version});
+  return result.ok?{ok:true}:{ok:false,reason:'Taken; refresh availability'};
+ }
+});

package/guides/functions/SKILL.md

@@ -28,3 +28,5 @@ isolated records. Assert actual sound/haptic/notification triggers where request
 Check waits through reload readiness and reports dialogs and named timeout conditions.
 Do not weaken a need to obtain a green result; inspect captures and complete the
 owner's workflow. Do not deploy merely to prove a local handler.
+
+For authoritative bookings/inventory use strict `defineTool` actions and `database.put(key, next, {version: row.version})`; a conflict is a failed reservation. Never make the inventory a client-writable generic ledger. The [capacity example](../app/examples/reserve.mjs) proves one winner from six simultaneous requests for one place; initialise capacity through an owner-only action.

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.