@homie-rocks/studio 0.39.0 → 0.42.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.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**
+
+New 3D games keep their matches on the server and answer your controls immediately.
+
+### Added
+
+- Rules games can move and face in three dimensions, jump and land, and collide with boxes, spheres, upright capsules and sloped height tiles. Declared level data reaches the server and the browser together and is checked with the game's save and restore.
+- Prediction follows vertical movement and facing, eases corrections, and draws other players' poses and animation state smoothly. The build reports the completed local room-capacity trial separately from its generated game check.
+
+### Changed
+
+- Gem Rush 3D, Hero Rush 3D and Ember Vale now use rules plus view with the server keeping the match, including bots, companions, pickups and combat. Ember Vale keeps its saved hero. All five game starters now use the rules runtime; Ember Vale keeps its two-dimensional play.
+
+### Fixed
+
+- Predicted movement respects the server's floor and ceiling, and catch-up animation follows the pose being drawn.
+- Knockback no longer stores blocked travel and bursts around obstacles. A jump or direction change partway through a tick preserves the current drawn position before advancing.
+- Phone control checks start measuring with the first directional touch movement, so slow browser automation cannot cross the arena before measurement begins.
+- Gem Rush keeps sliding along arena walls under thumb input, and a delayed animation frame cannot give a newly arrived effect a negative radius.
+
+### Upgrade notes
+
+- Existing games keep their source and their hosting choice. The game skill is unchanged; its authoring update is the next slice.
+- Capacity measurements in this release are local. Cloudflare capacity and billing have not been measured.
+
 ## [0.39.0] - 2026-10-09
 
 **Plugin 0.39.0** · [#78](https://github.com/homie-rocks/homie/pull/78)
@@ -48,7 +102,7 @@ Your studio has its own MCP server. Connect your AI with one browser approval an
 
 ## [0.38.0] - 2026-10-09
 
-**Plugin 0.39.0**
+**Plugin 0.39.0** · [#77](https://github.com/homie-rocks/homie/pull/77)
 
 Your own character answers as soon as you press, even when the room runs on the server.
 

package/README.md

@@ -44,6 +44,17 @@ asks (`game new <id> --from gem-rush`, or `--from ember-vale` for a hero who las
 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

package/bin/homie-studio.mjs

@@ -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]
@@ -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

@@ -492,6 +492,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');
@@ -544,6 +545,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     if (seats.asked > SEAT_MAX) log(`warning: games/${g.id} asks for ${seats.asked} players; a room holds at most ${SEAT_MAX}, so its rooms have ${SEAT_MAX} seats`);
     built.push({
       id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings, seats: seats.max,
+      ...(rules ? { capacityTrial: rules.check.capacityTrial } : {}),
       ...(bundle ? { bundle } : {}), ...(chunks.length ? { chunks: chunks.length, chunkBytes: later } : {}),
     });
     log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} additional ${chunks.length === 1 ? 'chunk' : 'chunks'}, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import { refreshWorkerConfig } from './worker-config.mjs';
 import { paidReleases, uploadPaidParts } from './parts-upload.mjs';
 /**
  * `homie-studio deploy` — the studio's site on the studio's OWN Cloudflare
@@ -41,7 +42,7 @@ import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File,
 import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
 import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
-import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
+import { ensureLocalIgnored, ensureMigrations, migrationWord } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listExperiences as listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
@@ -240,7 +241,6 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
   let routes = keptRoutes(root, studio);
-  const triggers = readConfig(root)?.triggers;
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -277,6 +277,9 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   if (zone) {
     if (ownRoute && zone.state === 'foreign') {
       routes = [...(routes ?? []), zone.route];
+      const customFile=join(root,'wrangler.custom.json');
+      const custom=existsSync(customFile)?JSON.parse(readFileSync(customFile,'utf8')):{};
+      writeFileSync(customFile,JSON.stringify({...custom,routes},null,2)+'\n');
       step(`added the studio's own exact-host route to "routes" in wrangler.jsonc: ${zone.line}. It covers ${zone.host} only, and every deploy keeps it; the other site's route was not touched.`, { route: zone.route });
       const config = readConfig(root) ?? {};
       zone = await zoneCheck(root, { studio, accountId, fetchFn, config: { ...config, routes: [...routesOf(config), zone.route] } });
@@ -368,17 +371,14 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes, triggers }));
+  refreshWorkerConfig(root, {d1Id: db.uuid});
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
-  // Workers AI (0.17.0): bound only when a server's AI guides think with it.
-  if (needsWorkersAi(root, w, cf.d1)) {
-    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes, triggers }));
-    step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
-  }
+  const subscriptions=w(['d1','execute',cf.d1,'--remote','--command',(await import('./functions-build.mjs')).functionDeploymentSQL(root)]);
+  if(subscriptions.code!==0)return refuse('Could not register studio functions',subscriptions.out);
 
   const started = Date.now();
   let dep = w(['deploy', ...repoVar(root)]);
@@ -680,7 +680,7 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
     // The studio's own routes stay through this rewrite too (lib/routes.mjs).
-    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root), routes: keptRoutes(root, studio) }));
+    refreshWorkerConfig(root);
   }
   log(`created R2 ${bucket}`);
   return { ok: true, command: 'storage add', bucket, account: accountId, cost: R2_COST, next: ['npx --no-install homie-studio media move --dry-run   (which songs and videos go to R2: over 1 MiB, or left out of git)', 'npm run deploy   (binds the bucket as MEDIA, moves them, checks each by SHA-256, and serves them from R2 at the same addresses; the files stay in this folder)'] };

package/lib/dev.mjs

@@ -459,8 +459,9 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
       return;
     }
   };
+  const { functionFiles } = await import('./functions-build.mjs');
   const { toolFiles } = await import('./tools-build.mjs');
-  const toolsStamp = () => toolFiles(root).map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
+  const toolsStamp = () => [...toolFiles(root),...functionFiles(root)].map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
   let lastTools = toolsStamp();
   const toolsLook = async () => {
     if (rebuilding || ending) return;

package/lib/functions-build.mjs

@@ -0,0 +1,36 @@
+import {existsSync,readdirSync,mkdirSync,writeFileSync,readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {createRequire} from 'node:module';
+const require=createRequire(import.meta.url);
+export function functionFiles(root) { const dir=join(root,'functions');return existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]; }
+export async function buildFunctions(root,esbuild) {
+  const files=functionFiles(root),dir=join(root,'site/src/functions');mkdirSync(dir,{recursive:true});
+  if(files.length) {
+    const ts=require('typescript'),options={target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,moduleResolution:ts.ModuleResolutionKind.Bundler,strict:true,noEmit:true,skipLibCheck:true};
+    const errors=ts.getPreEmitDiagnostics(ts.createProgram(files,options));
+    if(errors.length)throw new Error(ts.formatDiagnosticsWithColorAndContext(errors,{getCurrentDirectory:()=>root,getCanonicalFileName:f=>f,getNewLine:()=> '\n'}));
+  }
+  const contents=files.map((f,i)=>`import f${i} from ${JSON.stringify(f)};`).join('\n')+`\nexport default [${files.map((_,i)=>'f'+i).join(',')}];`;
+  const built=await esbuild.build({stdin:{contents,resolveDir:root},bundle:true,format:'esm',platform:'neutral',write:false,logLevel:'silent'});
+  const file=join(dir,'index.mjs');writeFileSync(file,built.outputFiles[0].text);
+  const definitions=(await import(pathToFileURL(file).href+'?build='+Date.now())).default;
+  const names=new Set();
+  for(const fn of definitions) {
+    if(!/^[a-z][a-z0-9-]*$/.test(fn.name)||names.has(fn.name)||typeof fn.handler!=='function'||typeof fn.event!=='string'||!fn.event.trim())throw new Error('Function needs a unique name, event and handler');
+    if(fn.schedule && (typeof fn.schedule!=='string'||fn.schedule.trim().split(/\s+/).length!==5))throw new Error('Function schedule needs a Cloudflare cron expression');
+    names.add(fn.name);
+  }
+  const worker=join(root,'site/src/worker.mjs');
+  if(existsSync(worker)) {let text=readFileSync(worker,'utf8');if(!text.includes('useFunctions(')){text+="\nimport { useFunctions } from '@homie-rocks/studio/worker';\nuseFunctions(async () => (await import('./functions/index.mjs')).default);\n";writeFileSync(worker,text);}}
+  writeFileSync(join(dir,'declarations.json'),JSON.stringify(definitions.map(({name,event,schedule,replay})=>({name,event,schedule,replay})),null,2)+'\n');
+  (await import('./worker-config.mjs')).refreshWorkerConfig(root);
+  return definitions;
+}
+/** Install subscriptions before the new Worker can produce its first event. */
+export function functionDeploymentSQL(root) {
+  const file=join(root,'site/src/functions/declarations.json');
+  const definitions=existsSync(file)?JSON.parse(readFileSync(file,'utf8')):[];
+  const literal=value=>"'"+String(value).replaceAll("'","''")+"'";
+  return [...definitions.map(fn=>`INSERT INTO function_subscriptions(name,type,cursor,started) VALUES(${literal(fn.name)},${literal(fn.event)},(SELECT COALESCE(MAX(seq),0) FROM studio_events),unixepoch()*1000) ON CONFLICT(name) DO UPDATE SET type=excluded.type,cursor=excluded.cursor,started=excluded.started WHERE type!=excluded.type;`),`DELETE FROM function_subscriptions WHERE name NOT IN (${definitions.map(fn=>literal(fn.name)).join(',')||"''"});`,"INSERT INTO meta(key,value) VALUES('function-registry-deployed','1') ON CONFLICT(key) DO UPDATE SET value='1';"].join(' ');
+}

package/lib/functions-cli.mjs

@@ -0,0 +1,23 @@
+import {existsSync,mkdirSync,writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {connectToolClient} from './tools-cli.mjs';
+export async function functionCommand(root,sub,positional,flags,{log=()=>{}}={}) {
+  if(sub==='new') {
+    const name=positional[2],event=flags.get('event')??'order.paid';
+    if(!/^[a-z][a-z0-9-]*$/.test(name??''))throw new Error('Use a lowercase function name');
+    const file=join(root,'functions',name+'.ts');if(existsSync(file))throw new Error('Function already exists');
+    mkdirSync(join(root,'functions'),{recursive:true});
+    writeFileSync(file,`import { defineFunction } from '@homie-rocks/studio/functions';\nexport default defineFunction({\n  name: ${JSON.stringify(name)}, event: ${JSON.stringify(event)},\n  async handler(event, context) {\n    // Deduplicate external side effects with event.id (for example an API idempotency key).\n    await context.database.put(event.id, event.data);\n  },\n});\n`);
+    return {ok:true,command:'function new',file,next:'Edit your function, then run homie-studio dev.'};
+  }
+  if(sub==='replay') {
+    if(!flags.has('replay'))throw new Error('Pass --replay to explicitly request retained history');
+    const client=await connectToolClient(root,new URL(flags.get('url')??'http://localhost:8787'),{log});
+    try {const result=await client.callTool({name:'studio_function_replay',arguments:{name:positional[2]}});return {ok:!result.isError,command:'function replay',result};}finally{await client.close();}
+  }
+  if(sub!=='fire')throw new Error('Use function new <name> --event <event>, or function fire <event> --input <JSON>');
+  const url=new URL(flags.get('url')??'http://localhost:8787');
+  if(!['localhost','127.0.0.1','[::1]'].includes(url.hostname))throw new Error('Fire is local testing only');
+  const client=await connectToolClient(root,url,{log});
+  try {const result=await client.callTool({name:'studio_function_fire',arguments:{event:positional[2],data:JSON.parse(flags.get('input')??'{}'),...(flags.has('id')?{id:flags.get('id')}: {})}});return {ok:!result.isError,command:'function fire',result};}finally{await client.close();}
+}

package/lib/port-check.mjs

@@ -314,10 +314,10 @@ async function focusGame(h) {
 async function holdKey(h, code, ms, ready) { await h.page.keyboard.down(code); if (ready) await ready(); await sleep(ms); await h.page.keyboard.up(code); }
 
 function thumbAt(h, i) { const t = i?.thumb ?? [0.24, 0.74]; return [Math.round(h.vp.width * t[0]), Math.round(h.vp.height * t[1])]; }
-async function touchDrag(h, from, dir, reach, holdMs, ready) {
+async function touchDrag(h, from, dir, reach, holdMs, ready, steps = 8) {
   const [x0, y0] = from; const u = DIRV[dir];
   await h.touch('touchStart', [{ id: 1, x: x0, y: y0 }]);
-  for (let k = 1; k <= 8; k++) { await h.touch('touchMove', [{ id: 1, x: Math.round(x0 + (u[0] * reach * k) / 8), y: Math.round(y0 + (u[1] * reach * k) / 8) }]); await sleep(12); }
+  for (let k = 1; k <= steps; k++) { await h.touch('touchMove', [{ id: 1, x: Math.round(x0 + (u[0] * reach * k) / steps), y: Math.round(y0 + (u[1] * reach * k) / steps) }]); await sleep(12); }
   if (ready) await ready();
   const end = Date.now() + holdMs;
   let w = 0;
@@ -369,7 +369,10 @@ export async function measuredPress(h, how, code, from, dir) {
     b = await frameNow(h);
   };
   if (how === 'keys') await holdKey(h, code, 0, ready);
-  else await touchDrag(h, from, dir, 70, 0, ready);
+  // One real move establishes the measured direction. An eight-event ramp can
+  // take seconds on software Chrome and drive all the way into a wall before
+  // its final-point receipt starts the measurement. Holds still exercise ramps.
+  else await touchDrag(h, from, dir, 70, 0, ready, 1);
   return { dir, a, b };
 }
 

package/lib/purchase-links.mjs

@@ -1,3 +1,5 @@
+import {pathToFileURL} from 'node:url';
+import {serviceTerms} from '../worker/service-terms.mjs';
 /** Uses the shop's authorized Stripe API transport; no API credential goes to the Worker. */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -13,6 +15,12 @@ export async function syncPurchaseLinks({ root, api, slug, site, mode, list, til
     const p = readPart(packedDir(root,id,version)), config = settings[id], selected = config?.releases?.[version];
     return p.sale && config?.active !== false && selected?.active !== false && (version === versions.at(-1) || selected?.keepOnSale === true) ? [{kind:'part',resource:id,version,name:part.name,sale:{...p.sale,...config?.price}}] : [];
   }));
+  const {toolFiles,buildTools}=await import('./tools-build.mjs');
+  if(toolFiles(root).length){
+    await buildTools(root,await import('esbuild'));
+    const definitions=(await import(pathToFileURL(join(root,'site/src/tools/index.mjs')).href+'?links='+Date.now())).default;
+    offers.push(...definitions.filter(t=>t.price).map(t=>({kind:'service',resource:t.name,version:'1.0.0',name:t.description,sale:serviceTerms(t.price)})));
+  }
   const configured = offers.flatMap(o => {
     const quantities = settings[o.resource]?.quantities ?? [1];
     if (!Array.isArray(quantities) || !quantities.length || quantities.some(q=>!Number.isSafeInteger(q) || q<1 || !Number.isSafeInteger(q*o.sale.amount))) throw new Error(`Invalid Payment Link quantities for ${o.resource}`);

package/lib/rules-build.mjs

@@ -33,6 +33,10 @@ import { typecheckRules } from './typecheck.mjs';
 export { isRulesGame };
 export { stateHash } from './rules-check.mjs';
 
+// A reference workload, not a promise about every game's rules or a Cloudflare measurement.
+// Receipt and method: docs/rooms-slice-7-notes.md, "Budget measurements".
+export const RULES_CAPACITY_TRIAL = Object.freeze({ game: 'hero-rush-3d', seats: 32, tickHz: 30, minutes: 20, host: 'Node', platform: 'macOS arm64', cloudflare: false });
+
 const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
 const RULES_FILES = { [RULES_MODULE]: 'rules.ts', [GUARD_MODULE]: 'guard.ts', [`${RULES_MODULE}/view`]: 'view.ts', [`${RULES_MODULE}/host`]: 'host.ts' };
 
@@ -150,6 +154,9 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   for (const p of checked.problems) log(`warning: games/${g.id}/game.json: ${p}`);
   for (const line of checked.information) log(`info: ${line}`);
   const { settings, schema, publicTune, rounds, stateHash } = checked;
+  const trial = RULES_CAPACITY_TRIAL;
+  log(`info: rules runtime reference trial: ${trial.game}, ${trial.seats} players at ${trial.tickHz} Hz for ${trial.minutes} minutes on ${trial.host} (${trial.platform}). Cloudflare capacity and billing are unmeasured.`);
+  if (settings.tickHz > trial.tickHz) log(`info: games/${g.id} asks for ${settings.tickHz} Hz, above the completed local reference trial's ${trial.tickHz} Hz. This game's generated check does not establish live room capacity.`);
   const { def, R, H } = await loadRules(esbuild, root, g.id, guarded.code);
   const compiled = R.compileRules(def, { tune, map: R.compileMap(map, map.name), settings, seats });
   const stats = smokeRun(H, compiled, g.id, { timer: () => 0, vocab: data.vocab });
@@ -171,7 +178,7 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
     build: createHash('sha256').update(guarded.code).update(JSON.stringify(built)).digest('hex'),
     snapshotCap, checkpointCap, snapshotBytes: stats.snapshotBytes, checkpointBytes: stats.checkpointBytes,
     units: checked.maxUnits, tickUnits: checked.maxTickUnits,
-    check: { information: checked.information, plays: checked.plays, ticks: checked.ticks, rounds: checked.roundsPlayed, restores: checked.restores, units: checked.units, largestSaveBytes: checked.largestSaveBytes },
+    check: { information: checked.information, capacityTrial: trial, plays: checked.plays, ticks: checked.ticks, rounds: checked.roundsPlayed, restores: checked.restores, units: checked.units, largestSaveBytes: checked.largestSaveBytes },
   };
 }
 

package/lib/rules-check-worker.mjs

@@ -236,7 +236,7 @@ function play(c, companions, allow) {
   const ends = (fd) => (fd.t === 'bit' || fd.t === 'press' ? [false, true] : fd.t === 'fix' ? [-1, 1] : [L.P.coerce(fd, -Infinity, c.dims), L.P.coerce(fd, Infinity, c.dims)]);
   const steering = new Map();
   let moveTick = 0;
-  const moveCtx = new Map(c.kinds.filter((k) => k.move && k.body).map((k) => [k.name, L.M.moveContext({ tick: () => moveTick, tickHz, tune: c.publicTune, map: c.map, name: c.map.name, spots: c.map.spots, radius: () => k.body.radius, dims: c.dims })]));
+  const moveCtx = new Map(c.kinds.filter((k) => k.move && k.body).map((k) => [k.name, L.M.moveContext({ tick: () => moveTick, tickHz, tune: c.publicTune, map: c.map, name: c.map.name, spots: c.map.spots, radius: () => k.body.radius, shape: () => k.body, dims: c.dims })]));
   /**
    * An owner-moved body's own browser, for one tick: the game's `move` from where the last snapshot has the body, by
    * the step a browser takes (pack.ts `stepMove`), and the claim of where that leaves it. Its units are the play's.
@@ -350,8 +350,8 @@ function play(c, companions, allow) {
       const result = L.P.stepMove(kind.move, before, input, moveCtx.get(name), Math.max(1, Math.floor(budget / 4)), kind.motion, c.dims,
         error => { fault ??= `${siteOf(name, 'move')} ${name}.move: prediction failed: ${error.message}.${when()}`; });
       units += result.used;
-      const r = kind.body.radius, bounds = c.map.bounds;
-      result.pos = L.P.vec3({ x: Math.max(bounds.min.x + r, Math.min(bounds.max.x - r, result.pos.x)), y: Math.max(bounds.min.y + r, Math.min(bounds.max.y - r, result.pos.y)), z: result.pos.z }, c.dims);
+      const r = kind.body.radius, height = kind.body.height || 2 * r, bounds = c.map.bounds;
+      result.pos = L.P.vec3({ x: Math.max(bounds.min.x + r, Math.min(bounds.max.x - r, result.pos.x)), y: Math.max(bounds.min.y + r, Math.min(bounds.max.y - r, result.pos.y)), z: c.dims === 3 ? Math.max(bounds.min.z, Math.min(bounds.max.z - height, result.pos.z)) : 0 }, c.dims);
       delete result.used;
       if (JSON.stringify(result) !== JSON.stringify(after)) fault ??= `${siteOf(name, 'move')} ${name}.move: prediction and the server produced different bodies from the same input.${when()}`;
     }

package/lib/rules-check.mjs

@@ -28,7 +28,9 @@ export const LONG_ALLOWANCE = Object.freeze({ ...ALLOWANCE, ticks: 8 * ALLOWANCE
 
 /** The ordered declarations a save depends on. Functions contribute their presence, never their implementation. */
 export function stateHash(c) {
-  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, save } = c;
+  const { kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map: geometry, dims, contract, seats, save } = c;
+  // Keep existing 2D save compatibility hashes when the 3D map vocabulary grows.
+  const map = dims === 2 ? { name: geometry.name, bounds: geometry.bounds, boxes: geometry.boxes, circles: geometry.circles, spots: geometry.spots } : geometry;
   return createHash('sha256').update(JSON.stringify({ kinds, events, commands, effects, shared, rounds, bots, roomOn, asks, map, dims, contract, seats, tickHz: c.settings.tickHz, save }, (k, v) => typeof v === 'function' ? true : v)).digest('hex').slice(0, 32);
 }
 

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
 import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
@@ -83,7 +84,7 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // later). A game's rules run in this Worker (NETPLAY.md section 29), and nothing in them is ever made from text.
     no_bundle: true, find_additional_modules: true, rules: [{ type: 'ESModule', globs: ['**/*.js'], fallthrough: true }],
     compatibility_flags: ['nodejs_compat', 'global_fetch_strictly_public', 'disallow_eval_during_startup'],
-    ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, triggers: { crons: ['*/5 * * * *'] }, ratelimits: [partsRateLimit ?? { name: 'PURCHASE_RATE_LIMITER', namespace_id: '1001', simple: { limit: 60, period: 60 } }] } : {}),
+    ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, triggers: { crons: ['*/5 * * * *'] }, ...(partsRateLimit ? { ratelimits: [partsRateLimit] } : {}) } : {}),
     workers_dev: true,
     preview_urls: true,
     // The studio's own custom-domain and exact-host routes, as its owner wrote them: this file is written again by
@@ -154,7 +155,7 @@ An app is ONE screen that morphs with context: camera moves, panels unfold, its
 
 Declare roles, surfaces, words and lasting record collections in app.json. Netplay's host is not a staff permission. Use \`@homie-rocks/studio/apps\` for authorized lasting records and \`@homie-rocks/studio/links\` for ticket links, QR and HTTP-safe IDs. Staff use private role links plus existing account grants; keep private records out of public collections. Look for engine mechanisms and shared parts before writing a component. Credit licences; sharing is optional and separate from selling.
 
-Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
+Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Customers can browse and buy through this same endpoint, and tools may declare a price using the studio's existing payments. Add event handlers with \`homie-studio function new <name> --event order.paid\`; read \`node_modules/@homie-rocks/studio/functions/FUNCTIONS.md\`. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
 
 Build normally, run \`homie-studio dev --lan\`, then \`homie-studio check <id> --url <origin>\`: the app check proves an actual action across a wall and two phones plus reconnect. The public screen is \`/<id>/open\`, the wall \`/<id>/tv\`. Customer apps use the same \`standalone\` build for desktop/iOS/Android; its existing sign-in and store limitations still apply. See \`node_modules/@homie-rocks/studio/apps/APPS.md\`.
 
@@ -763,6 +764,8 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
     [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_MIGRATION,
+    [`site/migrations/${FUNCTIONS_MIGRATION_FILE}`]: FUNCTIONS_MIGRATION,
+    [`site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`]: FUNCTIONS_CURSOR_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -934,13 +937,23 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureFunctionCursors(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_CURSOR_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_CURSOR_MIGRATION);return `site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`;
+}
+function ensureFunctionsMigration(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_MIGRATION);return `site/migrations/${FUNCTIONS_MIGRATION_FILE}`;
+}
 function ensureMcpMigration(root) {
   const file=join(root,'site','migrations',MCP_MIGRATION_FILE);
   if(existsSync(file))return null;
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
 }
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/shop.mjs

@@ -287,7 +287,7 @@ export async function shopConnectManual(root, { fromClipboard = false, clipboard
   const shopNow = readShop(root);
   const till = managed === true ? 'stripe-managed' : managed === false ? 'stripe' : shopNow.shop?.till ?? 'stripe';
   const nonce = randomBytes(16).toString('hex');
-  const paidParts = paidReleases(root).length > 0;
+  const paidParts = paidReleases(root).length > 0 || (shopNow.shop?.items?.length??0)>0 || (await import('./tools-build.mjs')).toolFiles(root).length>0;
   const page = connectPage({ paidParts, nonce, site, studio: studio.name ?? 'Your studio', till, test: !live });
   return await new Promise((done) => {
     let finished = false;