@homie-rocks/studio 0.40.0 → 0.43.0

package/CHANGELOG.md

@@ -17,9 +17,62 @@ 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.43.0] - 2026-10-09
+
+**Plugin 0.43.0**
+
+Ask for a game and its rules run on your server.
+
+### Added
+
+- The game skill teaches the whole rules-and-view workflow: shared truth, immediate movement, levels, companions, saving and the checks that prove the requested game plays. Your AI chooses the engineering defaults.
+- A guided rewrite keeps an older game's look, controls and feel while moving its rules to the server. It preserves the studio's other games and existing tests; there is no automatic converter.
+
+### Changed
+
+- Apps that need a shared live screen now start with the same server rooms. A quiz, queue or turn-based app gets real actions and shared state without pretend movement or compulsory game rounds.
+- Playtests explain stationary controls and intentional freezes. Performance reports measure both players when the server hosts. Covers and trailers use a live rules room and explain when an empty spectator room is paused.
+
+### Fixed
+
+- Builds explain the exact script tag a game page needs, check rules types once, and keep guarded builds working through a temporary-directory alias.
+- Builds refuse a game with neither rules plus view nor a browser-hosted netplay contract, instead of silently calling an unconnected page multiplayer. Existing netplay games keep their compatibility path.
+
+### Upgrade notes
+
+- Existing games keep working as they are. A rewrite happens only when requested. Building a game does not ask for publication or deploy it.
+- Rooms still hold at most 32 seats. Larger rooms are a later milestone; Cloudflare capacity and billing remain unmeasured.
+
+## [0.42.0] - 2026-10-09
+
+**Plugin 0.42.0**
+
+Customers and other businesses can use a studio's tools, buy its goods and services, and trigger its own functions.
+
+### Added
+
+- Customer catalogue, cart, checkout and agent purchases through the studio MCP server, using the existing payment standards and purchase lifecycle.
+- Priced studio tools and configurable built-in audiences, with current permissions checked when listing and calling.
+- Studio functions: plain-file event handlers, local firing, durable retries and office delivery status.
+
+### Changed
+
+- MCP call rates and shop purchase/guest-buyer rates are opt-in.
+
+### Fixed
+
+- Claim refunds use the same tip, used-item and window policy as the web shop. Guest carts create usable accounts before payment.
+- Builds fully regenerate Worker configuration, remove stale generated bindings and the old default purchase limiter, and keep explicit additions in `wrangler.custom.json`.
+- New functions skip history unless explicitly replayed; indexed subscriptions and cursors avoid unused events and prune completed delivery pages.
+- Paid tools renew execution leases, return saved results on retries and automatically refund failed handlers. Unpaid quotes expire and are pruned.
+
+### Upgrade notes
+
+- Run the toolkit upgrade and build, then commit the generated Worker configuration before deploying. Move hand-added Wrangler settings to root `wrangler.custom.json`; apply migrations 0018 and 0019 with the other studio migrations. Functions add a Cloudflare cron for retries only when declared.
+
 ## [0.40.0] - 2026-10-09
 
-**Plugin 0.40.0**
+**Plugin 0.40.0** · [#79](https://github.com/homie-rocks/homie/pull/79)
 
 New 3D games keep their matches on the server and answer your controls immediately.
 

package/README.md

@@ -38,12 +38,31 @@ A new studio has no game: its home page says "First game coming soon" until the
 `homie-studio demo` names a live game on Homie Arcade to try meanwhile. A starter is copied in only when the person
 asks (`game new <id> --from gem-rush`, or `--from ember-vale` for a hero who lasts, with cloud saves).
 
+New games are rules plus view: `src/rules.ts` declares state and server decisions,
+`src/move.ts` supplies shared movement and local prediction, and `src/view.ts` draws
+and sends input through `openRoom`. All five starters declare `room.host: server`.
+Follow the game skill and `RULES.md`; `build` checks rules, movement and view types
+and refuses a game with neither rules nor a browser-hosted netplay contract.
+The same rules support browser hosting for offline, local and private play.
+Existing browser-hosted games remain supported; rewriting one is an explicit task.
+
 ## In one chat: `homie-studio mcp`
 
 ```sh
 npx -y @homie-rocks/studio mcp --studios "<the folder the studios live in>"   # the toolkit as a local MCP server (stdio)
 ```
 
+Every studio also has its own customer-facing `/mcp`. Customers can browse, quote a cart,
+and pay through the same MPP/x402 purchase engine used for paid parts, or open the studio's
+Stripe checkout for human approval. Studio tools choose `public`, `signed-in`, an app staff
+role, or `owner`; a tool can sell its service with `price`. See [Studio tools](tools/TOOLS.md).
+
+[Studio functions](functions/FUNCTIONS.md) run your code when an order is paid or refunded,
+a player joins, a room closes, an app record changes, a tool is called, or a schedule fires.
+Add one with `homie-studio function new paid-order --event order.paid`; fire an event locally
+with `homie-studio function fire order.paid --input '{"order":"example"}'`. Deliveries persist,
+retry with the same event ID, and show failures in the office. Policies and rate limits are opt-in.
+
 The toolkit as MCP tools, so the chat that shows Homie's cards also does the work: the setup status, a new studio,
 the live demo, make / port / plan a game and its Game Codex, build, run it here, the two-browser check, a
 playtest, deploy, publish, the progress feed, the studio's files, and the music, sound, art and video scripts where
@@ -132,7 +151,7 @@ Anyone can **watch** a live room from any player's view at `/<game>/watch?room=<
 Join on every room): the game itself, drawn by the watcher's own browser as a watcher that never takes a seat,
 with a strip of the players to switch between (a tap, keys 1-9, Auto, the whole room). A game draws the followed
 player's camera and HUD from `net.viewSeat` (Gem Rush and Ember Vale do; a game that does not is watched as its
-overview), and game.json `"watch": "overview"` or `false` keeps hidden hands hidden. Private and invite-only games
+overview), and game.json `"watch": "overview"` or `false` changes the watch UI. Rules state is public to replicas; these settings do not secure hidden hands. Private and invite-only games
 are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
 
 ## Upgrading a studio
@@ -187,12 +206,16 @@ game its studio chooses to share, each with its own licence ("Game parts", below
 Every room of a game has the seats its netplay manifest names: game.json's `netplay`
 block (`maxPlayers`), or a `netplay.json` beside game.json or in the game's build
 (`maxPlayers` or `players.max`), else game.json's `players.max`, else 8; at most 32.
-Bots, a late joiner taking a bot's body and a new host after the old one leaves work
-the same at 32 as at 4. One address may hold every seat plus four sockets, so a party
+Bots and a late joiner taking a bot's body work the same at 32 as at 4.
+Server rules keep running when a browser leaves; older browser-hosted games elect a new host. One address may hold every seat plus four sockets, so a party
 on one Wi-Fi (or strangers behind one carrier's address) fills a room with a TV beside it.
 
 ## A game's netplay manifest
 
+For rules games the build derives the revision from the rules and view; do not bump
+`netplay.version` or tune browser host election. `room` sets hosting and tick rate.
+The version and stall settings below describe existing browser-hosted games.
+
 game.json `"netplay"` says more than the room's size. All of it is optional, and `homie-studio build`
 writes it to the catalogue for the site's rooms (`netplay/NETPLAY.md` sections 22 to 24):
 
@@ -353,7 +376,8 @@ npx homie-studio agents pass night-rush --label Claude
   account) or invite (`office invite <id> --server <server>`).
 - **AI is always marked AI**, by the room's relay, not the game: every agent is named "<label> · AI", and the
   relay rewrites a host's roster and results so a game cannot hide one.
-- **The skill dial:** 1 Rookie to 5 Maxed (`{ reactionMs, aimNoise, aggression, positioning }`). The party votes it
+- **Rules authoring:** use `world.level`, `world.guideLevel`, `world.guideSeats` and `world.kids`; declare `guide.view`, `guide.floor`, `think` and `world.goalDone` for companions, and `asks` with `world.ask` / `on.answer` for decisions. The following `net.skillOf`, `BotBrain`, `useAgents` and `net.decide` recipes apply to existing browser-hosted games.
+- **The skill dial (browser-hosted games):** 1 Rookie to 5 Maxed (`{ reactionMs, aimNoise, aggression, positioning }`). The party votes it
   on a card in the play page (the middle vote wins); `net.skillOf(slot)` is what a bot reads (`NETPLAY.md` section
   17), and `BotBrain` reads it with a rebuild. In the starters, Gem Rush's Rookie bots collect far fewer gems than
   its Maxed ones.
@@ -361,7 +385,7 @@ npx homie-studio agents pass night-rush --label Claude
   (humans-only, a stricter door), closing it, removing a member, and the first time AI guides may talk are asked
   for, and the owner confirms with one tap.
 - **AI guides that talk** (0.17.0): a game's `agents.json` is its guides' vocabulary (goals, lines, the asks a
-  player taps), and `useAgents` from `@homie-rocks/studio/agents` its host side (Ember Vale is the reference). The
+  player taps), and `useAgents` from `@homie-rocks/studio/agents` its browser-host side (the pre-rules Ember Vale is the reference). The
   brain is the server's: `agents brain night-rush first-light workers-ai` (the studio's own Workers AI; deploy binds
   it; 8,000 neurons a day by default) or `owner-key` (the owner's own key, `agents brain key`, capped in dollars a
   day); with none, the game's scripted floor. The local MCP's `agent_sit` puts the owner's own Claude in a guide's
@@ -379,7 +403,7 @@ npx homie-studio agents pass night-rush --label Claude
 - **A game's own decisions** (0.24.4, NETPLAY.md section 20): `net.decide(state, questions, { floor })` on the host,
   for a game whose game.json says `"decide": true`: tactics for its opponents, an NPC's reaction, a director's call,
   a turn's move, answered by Clef in the room in about a quarter of a second, per beat (never per frame), within the
-  AI brains' day; the floor answers whenever it cannot. Ember Vale's slimes pick their tactics this way (opt-in).
+  AI brains' day; the floor answers whenever it cannot. Rules-based Ember Vale declares asks instead (opt-in).
 - Everything is in the studio's own Worker and D1 (migration `0006_studio_servers.sql`). The site's side is in
   [site/SITE.md](site/SITE.md); the room's in [netplay/NETPLAY.md](netplay/NETPLAY.md) sections 17, 18 and 20.
 
@@ -734,11 +758,10 @@ Web Workers, a live server) and what a game must do for its sound to be in the f
 ```sh
 npx homie-studio perf crown-thief --url http://127.0.0.1:8787 [--device computer,phone] [--runs 3] [--profile]
 npx homie-studio perf sizes crown-thief                     # every built file, raw and gzipped; with build --maps, the bundle's modules
-npx homie-studio perf compare .perf/crown-thief/<before> .perf/crown-thief/<after> --goal phone.host.frame.p95
+npx homie-studio perf compare .perf/crown-thief/<before> .perf/crown-thief/<after> --goal phone.replica.frame.p95
 ```
 
-One run is two headless Chromes on this computer's GPU in a fresh room of their own (`?room=perf-…`): the host (the
-rules, the bots, the snapshots) and a replica, both a computer (1280x800 at 2x) or both an emulated phone (390x844 at
+One run is two headless Chromes on this computer's GPU in a fresh room of their own (`?room=perf-…`): two replicas for server rules, or a host and replica for older browser-hosted games, both a computer (1280x800 at 2x) or both an emulated phone (390x844 at
 3x, touch, Chrome's CPU throttle at 4x with `--cpu`, 4G; each run records the slow-down the throttle really gave, which
 on a fast computer is less than its rate). They play the same seeded presses through a warm-up and a measured
 window, and each run's JSON says, per browser: the time between animation frames (median, p95, p99, the share over 33

package/app-starters/welcome/app.json

@@ -2,7 +2,7 @@
   "id": "welcome",
   "name": "Welcome together",
   "blurb": "A little place to gather. Join the queue, keep your ticket, and see when it is your turn.",
-  "entry": "src/main.ts",
+  "entry": "src/view.ts",
   "roles": {
     "customer": {
       "signIn": false,
@@ -102,5 +102,12 @@
       "phone": "Join once and keep your ticket.",
       "computer": "Staff call the next person from their signed-in tablet."
     }
+  },
+  "room": {
+    "host": "server"
+  },
+  "players": {
+    "min": 1,
+    "max": 32
   }
 }

package/app-starters/welcome/map/main.json

@@ -0,0 +1 @@
+{"bounds":{"min":[-1,-1],"max":[1,1]},"boxes":[],"spots":{"start":[[0,0]]}}

package/app-starters/welcome/src/move.ts

@@ -0,0 +1,3 @@
+// The current rules contract requires a move for a participant, even without an avatar.
+import { defineMove } from '@homie-rocks/studio/rules';
+export const move = defineMove({ participant() {} });

package/app-starters/welcome/src/rules.ts

@@ -0,0 +1,21 @@
+// Transient scene truth lives in the room; authorized queue records live in AppRecords.
+// A phone has a logical stationary seat anchor. The wall watches without a seat.
+import { defineRules, f } from '@homie-rocks/studio/rules';
+import { move } from './move';
+export default defineRules({
+  contract: 2, space: { dims: 2 }, move,
+  shared: { revision: f.u32() },
+  shapes: { events: { refresh: {} }, commands: { refresh: {} }, effects: { refresh: {} } },
+  entities: {
+    participant: {
+      player: true,
+      body: { shape: 'circle', radius: 0.1, maxSpeed: 0 },
+      commands: { refresh(world, self) { world.sendRoom('refresh', {}); } },
+    },
+  },
+  room: {
+    rounds: { seconds: 0, breakSeconds: 0 }, bots: { keep: 0 },
+    join() { return { kind: 'participant', at: { x: 0, y: 0 } }; },
+    on: { refresh(world) { world.shared.revision += 1; world.emit('refresh', { x: 0, y: 0 }, {}); } },
+  },
+});

package/app-starters/welcome/src/{main.ts → view.ts}

@@ -1,12 +1,14 @@
 import * as THREE from 'three';
 import { damp1 } from '@homie-rocks/camera/spring.js';
 import { chamferBox } from '@homie-rocks/geom/chamfer.js';
-import { createNetplay } from '@homie-rocks/studio/netplay';
+import { openRoom } from '@homie-rocks/studio/rules/view';
+import type rules from './rules';
 import { createAppRecords, type AppRecord } from '@homie-rocks/studio/apps';
 import { appLink, qrSvg, randomId } from '@homie-rocks/studio/links';
 
 type Ticket = { label: string; status: string };
-const net = createNetplay<{ light: number }>({ game: 'welcome', maxPlayers: 32, snapshotHz: 2 });
+const room = openRoom<typeof rules>();
+const net = room.net;
 const role = net.params.role ?? 'customer';
 document.body.className = role;
 const $ = <T extends HTMLElement = HTMLElement>(s: string) => document.querySelector<T>(s)!;
@@ -42,7 +44,7 @@ async function refresh() {
 }
 async function action(fn: () => Promise<unknown>) {
   pending = true; paint();
-  try { await fn(); net.send('records-changed'); await refresh(); }
+  try { await fn(); room.command('refresh', {}); await refresh(); }
   catch (e) { $('#status').textContent = (e as Error).message; }
   finally { pending = false; paint(); }
 }
@@ -61,10 +63,9 @@ next.onclick = () => action(async () => {
   if (first) await records.update(first, { ...first.data, status: 'called' });
 });
 // The room carries scene state and change notices; records always come from the authorized database.
-net.on('event', (e) => { if (e.k === 'records-changed') { if (net.role === 'host') net.send('records-changed'); void refresh(); } });
-net.on('snapshot', (s) => { light = s.d.light; });
+room.on('refresh', () => { void refresh(); });
 net.on('link', () => { void refresh(); });
-setInterval(() => { if (net.role === 'host') { light = net.now() / 1000; net.snapshot({ light }); } $('#connection').textContent = net.link === 'online' ? 'Here together · live' : 'Reconnecting…'; }, 500);
+setInterval(() => { $('#connection').textContent = net.link === 'online' ? 'Here together · live' : 'Reconnecting…'; }, 500);
 setInterval(() => void refresh(), 2000); // recover a missed notice; no dependency on a trusted browser host
 void refresh(); paint();
 
@@ -100,6 +101,7 @@ function draw(now: number) {
   const phone = innerWidth < 600;
   camera.position.set(phone ? 7 : 6, phone ? 6 : 5, distance); camera.lookAt(phone ? 1 : -.4, .6, 0);
   stage.position.x = phone ? 1.8 : 2.4;
+  light = net.now() / 1000;
   stage.rotation.y = reduced.matches ? 0 : Math.sin(light * .12) * .09;
   lanterns.forEach((g, i) => { const target = i < waiting ? 1 : .28; g.scale.y += (target - g.scale.y) * (1 - Math.exp(-dt * 5)); g.position.y = .18 + (reduced.matches ? 0 : Math.sin(now / 1000 + i) * .05); });
   renderer.render(scene, camera);

package/bin/homie-studio.mjs

@@ -57,8 +57,8 @@
  *                                          emulated (a --cpu times slower CPU, 4G) on this computer's GPU. The plugin's perf
  *                                          skill runs the whole measure, change, compare, keep-or-revert loop)
  *   homie-studio trailer <id> [--url <site>] [--seconds 40] [--length 20] [--title "…"] [--end "…"] [--skills <folder>]
- *                                         (a trailer in one command, by the plugin's video skill: the game rendered frame by
- *                                          frame on a virtual clock, its sound rebuilt from its own files and what it played,
+ *                                         (a trailer in one command, by the plugin's video skill: live footage for server rules,
+ *                                          or a virtual clock and rebuilt sound for older browser games,
  *                                          the highlights picked, an end card, 16:9, 1:1 and 9:16 in videos/<id>-trailer/)
  *   homie-studio perf sizes <id>          (what a player downloads: every built file, raw and gzipped, the biggest first; with
  *                                          build --maps, which modules make up the bundle; each big script read for whether it
@@ -155,6 +155,9 @@
  *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>]
  *                                        [--kids] [--door open|accounts|invite] [--level 1-5] [--level-max 1-5]
  *                                        [--speech game|lines|off] [--bots fill|off] [--rooms <n>] [--listed on|off]
+ *   homie-studio function new <name> [--event order.paid]
+ *   homie-studio function replay <name> --replay [--url <studio-site>]
+ *   homie-studio function fire <event> [--input <JSON>] [--id <event-id>] [--url <local-site>]
  *   homie-studio tool new <name> [--app <id>]
  *   homie-studio tool call <name> --input <JSON> [--url <site>] [--public]
  *   homie-studio servers set <game> <server> [the same flags]
@@ -409,7 +412,7 @@ function print(result) {
       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;
     case 'game new':
-      lines.push(`games/${result.id} is a new game from the ${result.from} starter. Change it in games/${result.id}/src/, then: npx homie-studio dev`);
+      lines.push(`games/${result.id} is a new game from the ${result.from} starter. Its server rules are src/rules.ts, shared movement src/move.ts, and browser view src/view.ts. Read the game skill and RULES.md, change the mechanic, then build and run: npx --no-install homie-studio dev`);
       if (result.installNeeded) lines.push(`It needs ${result.needsAdded.map((n) => `${n.name} ${n.version}`).join(', ')}, now in the studio's package.json: run npm install first.`);
       for (const h of result.needsHeld ?? []) lines.push(`It was written against ${h.name} ${h.want}; this studio pins ${h.have}, which stays.`);
       if (result.models) {
@@ -489,9 +492,12 @@ function print(result) {
       lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media. ${result.cost}`, ...(result.warning ? [`Warning: ${result.warning}`] : []));
       break;
     }
+    case 'function new':
     case 'tool new':
       lines.push(result.file, result.next);
       break;
+    case 'function replay':
+    case 'function fire':
     case 'tool call':
     case 'tool list':
       lines.push(JSON.stringify(result.result, null, 2));
@@ -833,6 +839,7 @@ const OUTWARD_FLAGS = {
   'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'], 'shop statements': ['url', 'period', 'send', 'cursor'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+  'function replay': ['url','replay'], 'function new': ['event'], 'function fire': ['url','input','id'],
   'tool new': ['app'], 'tool call': ['url', 'input', 'public'], 'tool list': ['url', 'public'],
   // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
   'standalone run': ['for', 'device', 'site'],
@@ -894,6 +901,7 @@ async function main() {
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
   const root = requireStudio();
+  if (cmd === 'function') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
   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 });

package/functions/FUNCTIONS.md

@@ -0,0 +1,99 @@
+# Studio functions: when this happens, run that
+
+A function is your trusted code in your own Worker. Run:
+
+```sh
+homie-studio function new prepare-order --event order.paid
+homie-studio dev
+homie-studio function fire order.paid --id local-order-1 --input '{"order":"example"}'
+```
+
+The fire command connects to the local studio through the existing browser OAuth
+approval. It is an owner tool and refuses remote hosts. It records an event in the
+same durable dispatcher as real events; firing the same ID again is a duplicate.
+
+```ts
+import { defineFunction } from '@homie-rocks/studio/functions';
+export default defineFunction<{ order: string }>({
+  name: 'prepare-order',
+  event: 'order.paid',
+  async handler(event, context) {
+    // For an external API, send event.id as its idempotency key.
+    await context.database.put(event.id, { order: event.data.order });
+  },
+});
+```
+
+Build discovers and type-checks `functions/*.ts`. Handlers have the studio tool
+context and run with the studio's authority. They can change records, send a
+room event through declared capabilities, call an external service, or implement
+another business workflow. Treat event data as data, not instructions.
+
+| Event | Data |
+| --- | --- |
+| `order.paid` | `order`, `source`, `amount`, `currency`, `mode` |
+| `payment.refunded` | `refund`, `payment`, `amount`, `currency` (each successful Stripe refund, including partial refunds) |
+| `order.refunded` | `order`, `source`, `refund`, `mode` (full refund) |
+| `player.joined` | `game`, `room`, `player` (nullable), `seat` |
+| `room.closed` | `game`, `room`, closing/ending facts |
+| `record.changed` | `app`, `collection`, `record`, `version`, `operation`, `data` |
+| `tool.called` | `tool`, `person`, `client` (successful call, no arguments) |
+
+For a scheduled function, add `schedule: '0 9 * * *'` and a chosen event name,
+for example `event: 'morning.open'`. Schedules use Cloudflare cron syntax and UTC.
+The event includes the function name, cron and scheduled time. Its ID remains the
+same if Cloudflare delivers the same tick again. Only that scheduled function
+receives its tick. Build reads custom crons from `wrangler.custom.json` and adds a minute tick
+for pending delivery retries while functions exist. Commit build changes before
+deploying. Cloudflare's own plan limits apply; Homie sets no attempt or event cap.
+
+Order, refund, record and tool events use database triggers: the source change
+and event either both commit or both roll back. Room events first enter the room's
+durable SQLite outbox; its alarm retries transfer to D1. Delivery is **at least
+once**, including after a worker dies between an external effect and its local
+acknowledgement. `event.id` is the de-duplication key and `event.attempt` is the
+attempt number. Completed deliveries do not run again. Failed/crashed deliveries
+retry after a one-minute lease. Make effects idempotent; a database marker written
+before an external request is not proof that the external request completed.
+
+Open **Office → Functions** for event IDs, states, attempt counts and failures.
+Use its Retry button, or an authenticated same-origin POST to `/_studio/office/functions` with
+`{"retry":"event-id"}` retries a failed event immediately. Failure text is generic
+so a thrown credential is never rendered in the office. Inspect the function's
+code and the studio's own provider logs to diagnose its failure.
+
+Existing signed inbound tool webhooks remain the external integration door. Their
+successful calls produce `tool.called`; record changes they make also produce
+`record.changed`. Use functions for durable downstream work instead of expecting
+a webhook sender to orchestrate the studio's internal actions. New declarations start at deployment and skip past events. To replay retained
+history, explicitly add `replay: true` to the declaration, then run
+`homie-studio function replay <name> --replay --url https://your-studio.example`.
+The owner OAuth connection is required. Merely adding `replay: true` does not run
+history. Fully delivered events are pruned; replay cannot recover pruned events.
+Only declared event types are recorded. Each function has an indexed sequence
+cursor; dispatch and maintenance use pages of 100, with no event or retry cap.
+
+
+Worker configuration is generated at build and upgrade time from `studio.json`,
+shop and tool declarations, game files, and function declarations. Commit the
+build before deploy. Put custom bindings, variables, aliases, routes, crons or
+observability settings in root `wrangler.custom.json` (plain JSON); objects merge
+recursively and arrays replace generated arrays. Do not hand-edit the generated
+`wrangler.jsonc`. Move existing manual additions into that file before upgrading.
+`studio.json.cloudflare.ai` explicitly enables/disables AI; otherwise game
+chat/decision declarations determine it. Set `cloudflare.routes` for routes and
+`cloudflare.purchaseRateLimit` for an explicitly chosen Wrangler rate-limit
+binding. An old generated purchase limiter is removed unless explicitly set.
+
+Machine cart quotes bind an account before payment. Anonymous buyers receive
+`account.player` and private `account.cookies`; retain the cookie and send its
+name/value as the Cookie header to this studio to use the grants. These credentials
+are returned only to the quoting caller, never embedded in the public offer.
+Guest limits are checked at quote time using the incoming request address.
+Quotes expire after 24 hours; paid orders retain their independent snapshots.
+
+Paid handlers renew their execution lease while running. Retries share the first
+result and never rerun an abandoned handler. A failed or abandoned run requests an
+automatic Stripe refund; retries report completion or continue refund recovery.
+Paid services require the studio's refundable Stripe connection; chain settlement
+is not offered for services. Handler errors never expose their private contents.

package/functions/functions.ts

@@ -0,0 +1,13 @@
+import type { ToolContext, StudioTool } from '../tools/tools';
+export interface StudioEvent<Data = unknown> { readonly id: string; readonly type: string; readonly at: number; readonly data: Data; readonly attempt: number }
+export interface StudioFunction<Data = unknown> {
+  name: string;
+  event: string;
+  /** Cloudflare cron expression; scheduled events are named by this function. */
+  schedule?: string;
+  /** Permit an explicit owner replay command to consume retained history. */
+  replay?: boolean;
+  events?: StudioTool['events'];
+  handler(event: StudioEvent<Data>, context: ToolContext): unknown | Promise<unknown>;
+}
+export function defineFunction<Data = unknown>(definition: StudioFunction<Data>): StudioFunction<Data> { return definition; }

package/lib/build.mjs

@@ -210,11 +210,12 @@ export function genreOf(g, log = () => {}) {
  * bundle (netplay/netplay.ts NETPLAY_MARK). A build without it is revision 5 or older: it plays on every server, but
  * reserved AI seats stay empty and its bots do not read the dial, and the office says so. Null when nothing says.
  */
-export function netplayRevOf(out) {
+export function netplayRevOf(out, { skipPort = false } = {}) {
   const files = [];
   const walk = (dir, depth) => {
     if (depth > 3 || !existsSync(dir)) return;
     for (const name of readdirSync(dir)) {
+      if (skipPort && name === 'homie-port.js') continue;
       const f = join(dir, name);
       let st;
       try { st = statSync(f); } catch { continue; }
@@ -381,6 +382,8 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
   rmSync(out, { recursive: true, force: true });
   mkdirSync(join(out, 'assets'), { recursive: true });
   const mode = g.build?.mode ?? 'bundle';
+  const label = `${g.kind === 'app' ? 'apps' : 'games'}/${g.id}`;
+  const manifest = g.kind === 'app' ? 'app.json' : 'game.json';
   let warnings = 0;
   let metafile = null;
   let bundled = null;
@@ -391,14 +394,22 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
   // browser exactly as before, and cannot ask for the server.
   const ruled = isRulesGame(g);
   if (!ruled && g.room?.host === 'server') {
-    throw new Error(`games/${g.id}/game.json asks for "room": { "host": "server" }, but ${mode === 'bundle' ? 'this game has no src/rules.ts: its rules are inside its own code and run in a player\'s browser. Ask for it to be rewritten as rules plus view' : 'a ported game is someone else\'s browser code, which the server cannot run. It stays hosted by a player\'s browser'}.`);
+    throw new Error(`${label}/${manifest} asks for "room": { "host": "server" }, but ${mode === 'bundle' ? 'this game has no src/rules.ts: its rules are inside its own code and run in a player\'s browser. Ask for it to be rewritten as rules plus view' : 'a ported game is someone else\'s browser code, which the server cannot run. It stays hosted by a player\'s browser'}.`);
+  }
+  if (ruled && mode !== 'bundle') throw new Error(`${label} has a src/rules.ts and ${manifest} "build": { "mode": "${mode}" }. A game written as rules plus view is built by Homie itself: take the "build" setting out.`);
+  if (ruled) {
+    const file = join(g.dir, 'index.html');
+    const html = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const scripts = html.match(/<script\b[^>]*>/gi) ?? [];
+    if (!scripts.some((tag) => /\btype\s*=\s*["']module["']/i.test(tag) && /\bsrc\s*=\s*(["'])(?:\.\/)?assets\/main\.js(?:[?#][^"']*)?\1/i.test(tag))) {
+      throw new Error(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id}/index.html: load the built view with <script type="module" src="./assets/main.js"></script>. The manifest entry names src/view.ts; HTML loads the bundle, not /src/view.ts. Keep the path relative so it works inside the game frame.`);
+    }
   }
-  if (ruled && mode !== 'bundle') throw new Error(`games/${g.id} has a src/rules.ts and game.json "build": { "mode": "${mode}" }. A game written as rules plus view is built by Homie itself: take the "build" setting out.`);
   const { prepareRules, viewPlugin } = ruled ? await rulesBuild() : {};
   const rules = ruled ? await prepareRules(esbuild, root, g, { log, longCheck }) : null;
   const bundle = async (entryRel) => {
     const entry = join(g.dir, entryRel);
-    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
+    if (!existsSync(entry)) throw new Error(`${label}: entry ${entryRel} not found`);
     const options = {
       entryPoints: [rules ? 'homie:view' : entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: sourcemap ?? false,
       outdir: join(out, 'assets'), splitting: true, entryNames: hashed ? 'main-[hash]' : 'main', chunkNames: 'chunk-[hash]',
@@ -411,14 +422,14 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     };
     const failed = (error) => {
       const first = error.errors?.[0];
-      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+      throw new Error(`${label} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
     };
     const result = await esbuild.build(options).catch(failed);
     warnings += result.warnings.length;
     metafile = result.metafile;
     const outputs = Object.entries(result.metafile.outputs).filter(([k]) => k.endsWith('.js'));
     const main = outputs.find(([, v]) => rules ? v.entryPoint === 'homie-view:homie:view' : Boolean(v.entryPoint))?.[0];
-    if (!main) throw new Error(`games/${g.id} did not build: esbuild wrote no bundle for ${entryRel}`);
+    if (!main) throw new Error(`${label} did not build: esbuild wrote no bundle for ${entryRel}`);
     bundled = `assets/${basename(main)}`;
     chunks = outputs.filter(([k]) => k !== main).map(([k]) => `assets/${basename(k)}`).sort();
     if (maps) {
@@ -442,25 +453,30 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
     if (g.entry) await bundle(g.entry);
     const html = readFileSync(join(out, 'index.html'), 'utf8');
-    if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
+    if (!/homie-port\.js/.test(html)) log(`warning: ${label}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
     if (hashed && bundled) writeFileSync(join(out, 'index.html'), pointAtBundle(html, bundled));
   } else if (mode === 'command') {
     const command = String(g.build.command ?? 'npm run build');
     const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
-    if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
+    if (res.status !== 0) throw new Error(`${label}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
     const built = join(g.dir, String(g.build.out ?? 'dist'));
-    if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
+    if (!existsSync(join(built, 'index.html'))) throw new Error(`${label}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
     cpSync(built, out, { recursive: true });
     writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
   } else {
     await bundle(g.entry ?? (rules ? 'src/view.ts' : 'src/main.ts'));
     const html = join(g.dir, 'index.html');
-    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+    if (!existsSync(html)) throw new Error(`${label}/index.html is missing`);
     const text = readFileSync(html, 'utf8');
     writeFileSync(join(out, 'index.html'), hashed ? pointAtBundle(text, bundled) : text);
   }
   if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
-  if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+  if (!existsSync(join(out, 'index.html'))) throw new Error(`${label}/index.html is missing`);
+  // Older games declare netplay v1 or carry the helper's revision marker. A plain
+  // browser bundle is not automatically a multiplayer game. Apps may be local-only.
+  if (!rules && g.kind !== 'app' && netplayOf(g, out).v !== 1 && netplayRevOf(out, { skipPort: true }) === null) {
+    throw new Error(`${label}/${manifest}: this game is neither rules plus view nor a browser-hosted netplay game. Start with game new, src/rules.ts, src/view.ts and "room": { "host": "server" }. Existing browser-hosted games must retain their netplay v1 manifest or netplay helper.`);
+  }
   if (rules) {
     // Only this game's executable view and rules data: buildInfo, the site and other games cannot reload its players.
     const digest = createHash('sha256').update(rules.build);
@@ -492,6 +508,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   await (await import('./tools-build.mjs')).buildTools(root, esbuild);
+  await (await import('./functions-build.mjs')).buildFunctions(root, esbuild);
   // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
   const shop = shopForBuild(root, { log });
   const live = join(root, 'site', 'dist');
@@ -500,7 +517,10 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   for (const g of games) if (g.kind === 'app') { const bad = appProblems(g); if (bad.length) throw new Error(`apps/${g.id}/app.json: ${bad.join('; ')}`); }
   // `--types`: the games' TypeScript is checked first (esbuild only strips types, it never reads them), and a type
   // error stops the build before anything is built.
-  const typed = types ? typecheck(root, games, { log }) : null;
+  // Rules always use their generated capability types, including the view. The legacy
+  // compiler sees broad source types and can falsely reject valid rules callbacks.
+  const legacy = games.filter((g) => !isRulesGame(g));
+  const typed = types && legacy.length ? typecheck(root, legacy, { log }) : null;
   // What the build before this one made, to say which games changed.
   const before = readJson(join(live, '_site', 'build.json'))?.games ?? {};
   // Everything is built in a folder of its own and put in place only when all of it is there (lib/stage.mjs): a