@homie-rocks/studio 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -17,9 +17,65 @@ 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.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)
+
+Your studio has its own MCP server. Connect your AI with one browser approval and add tools for the work your studio does.
+
+### Added
+
+- Connect Claude, ChatGPT or Grok to your studio's own `/mcp` address. Use your existing studio account; there is no key to find or copy. Client setup and workspace policies still apply.
+- Let your AI use the office, app records, shared parts and marked guide seats in rooms. Staff keep their own app permissions. Destructive office controls still wait for your confirmation.
+- Add a typed tool with `homie-studio tool new`, test it with `tool call` and share its code as a part. Tools can also supply prompts and signed inbound integrations; readable app records are resources.
+- Review AI connections and recent tool calls in the office. Revoke a connection there. Role checks, validated input and configurable call limits apply on the server.
+
+### Changed
+
+- Worker builds keep MCP libraries in separate modules, loaded when that surface is used. Ordinary page traffic performs no MCP storage work.
+
+### Fixed
+
+- Browser input checks wait for the final touch movement to reach the game before measuring its response, including when Chrome delays delivery. Successful browser calls clear their timeout timers.
+
+- Clean installs on Node 24 include the MCP SDK required by the payment library, so purchase tools and selling builds work alongside the studio MCP server.
+- MCP integration tests close clients after failures as well as successes. The desktop check clears request timers instead of waiting an extra minute after success. Package and plugin test files have a hard timeout.
+
+### Upgrade notes
+
+- Ask your AI to upgrade and build your studio. The build writes Worker modules and the normal deploy applies the new connection and audit tables. No separate Homie service or Cloudflare resource is needed.
+- Studio tools are trusted code in your Worker. Review tools received as parts before adding them. The tool context does not expose raw credentials.
+
 ## [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/bin/homie-studio.mjs

@@ -155,6 +155,8 @@
  *   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 tool new <name> [--app <id>]
+ *   homie-studio tool call <name> --input <JSON> [--url <site>] [--public]
  *   homie-studio servers set <game> <server> [the same flags]
  *   homie-studio servers close <game> <server> [--reopen]
  *   homie-studio servers level <game> <room> <1-5>   (the AI's level in one room: Rookie, Steady, Fair, Strong, Maxed)
@@ -377,7 +379,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['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', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+const BOOL_FLAGS = ['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', '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];
@@ -487,7 +489,15 @@ 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 'tool new':
+      lines.push(result.file, result.next);
+      break;
+    case 'tool call':
+    case 'tool list':
+      lines.push(JSON.stringify(result.result, null, 2));
+      break;
     case 'deploy':
+      if (result.mcp) lines.push(`Connect your AI: ${result.mcp} (approve in your studio's browser page; no key)`);
       if (result.ci) {
         lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}${g.hash ? `  [${deployWords(g)}]` : ''}`));
         break;
@@ -823,6 +833,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'],
+  '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'],
 };
@@ -883,6 +894,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 === '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 });
   if (cmd === 'style') return styleCommand(root, sub, positional, flags, { log });

package/lib/build.mjs

@@ -491,6 +491,7 @@ export function orderGames(games, order, log = () => {}) {
 export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false, beforePublish = async () => {}, longCheck = false } = {}) {
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
+  await (await import('./tools-build.mjs')).buildTools(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');
@@ -543,6 +544,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` : ''})`);
@@ -689,6 +691,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       ...(audienceOf(studio) !== 'general' ? { audience: audienceOf(studio) } : {}),
       ...(studio.referrals === false ? { referrals: false } : {}),
       ...(lounge ? { lounge } : {}),
+      ...(studio.mcp ? { mcp: studio.mcp } : {}),
       build: buildInfo(root),
     },
     games: rows,
@@ -723,6 +726,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // site, never before: a game that did not build has left both as they were.
   await beforePublish();
   const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.get(g.id)?.host === 'server').map((g) => g.id));
+  await (await import('./worker-build.mjs')).buildWorker(root, esbuild);
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);
   return {

package/lib/cloudflare.mjs

@@ -466,7 +466,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const next = { ...kept, ...(cf.url && !isWorkersDev(cf.url) ? { url: cf.url } : {}), accountId, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort() };
   writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
-    ok: true, command: 'deploy', url, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
+    ok: true, command: 'deploy', url, mcp: url ? `${url}/mcp` : null, connectAI: url ? `${url}/_studio/office/connections` : null, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
     ...(media ? { media: { moved: media.moved ?? [], failed: media.failed ?? [], inR2: media.inR2 ?? null } } : {}),
     games: b.catalogue.map((id) => { const g = delta.games.find((x) => x.id === id); return { id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: g?.hash ?? null, change: delta.first ? 'first deploy from this computer' : g?.change ?? null }; }),
     ...(delta.removed.length ? { removed: delta.removed } : {}),
@@ -628,7 +628,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const hashes = builtGames(root, games);
   for (const id of games) if (hashes[id]?.hash) step(`${id}: ${deployWords(hashes[id])}`);
   return {
-    ok: true, command: 'deploy', ci: true, url, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
+    ok: true, command: 'deploy', ci: true, url, mcp: url ? `${url}/mcp` : null, connectAI: url ? `${url}/_studio/office/connections` : null, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
     commit: process.env.WORKERS_CI_COMMIT_SHA ?? null, branch: process.env.WORKERS_CI_BRANCH ?? null,
     // A CI checkout has no earlier deploy to compare with: each game's content hash only (lib/deploy-state.mjs).
     games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: hashes[id]?.hash ?? null })), songs: [], videos: [],

package/lib/dev.mjs

@@ -459,7 +459,18 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
       return;
     }
   };
-  const timer = setInterval(() => { look().catch(() => {}); rulesLook().catch(() => {}); }, watchMs);
+  const { toolFiles } = await import('./tools-build.mjs');
+  const toolsStamp = () => toolFiles(root).map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
+  let lastTools = toolsStamp();
+  const toolsLook = async () => {
+    if (rebuilding || ending) return;
+    const stamp = toolsStamp(); if (stamp === lastTools) return;
+    lastTools = stamp; rebuilding = true;
+    try { log('Studio tools changed: type-checking and rebuilding…'); await build(root, { log }); }
+    catch (error) { log(`Studio tools did not build: ${error.message}`); }
+    finally { rebuilding = false; }
+  };
+  const timer = setInterval(() => { look().catch(() => {}); rulesLook().catch(() => {}); toolsLook().catch(() => {}); }, watchMs);
   timer.unref?.();
 
   /** Wait for the local site, then hold it to its own address (socketOriginProblem); a mismatch ends dev. */

package/lib/mcp-tools.mjs

@@ -782,6 +782,16 @@ export function toolDefs(ctx, avail = {}) {
         return r.ok ? ok('Node and npm are ready. AI: continue studio_scaffold.', r) : fail(r.next, r);
       },
     },
+    {
+      name: 'studio_connect_ai', title: 'Connect your AI to the studio',
+      description: 'Give the person this studio’s own remote MCP address and connection page. Their AI connects directly with browser approval and their existing studio account; no key or local server.',
+      inputSchema: { type: 'object', properties: { ...STUDIO_ARG } },
+      annotations: { title: 'Connect your AI', ...RO },
+      run: async (a) => {
+        const root = ctx.root(a.studio), site = siteUrl(root);
+        return site ? ok(`Connect your AI to ${site}/mcp. Approve with your studio account in the browser. Manage connections at ${site}/_studio/office/connections. Client setup varies; do not promise a one-click import a client does not support.`, { mcp: `${site}/mcp`, connections: `${site}/_studio/office/connections` }) : fail('This studio has no published address yet. Local tools can be tested with homie-studio dev.');
+      },
+    },
     {
       name: 'studio_domain', title: 'Set the studio domain',
       description: 'Prepare a requested custom hostname for deployment. Cloudflare creates DNS and TLS using its existing browser sign-in. The AI handles configuration; never ask for an account id, zone id or DNS value. Does not deploy or change the domain registrar.',

package/lib/port-check.mjs

@@ -44,7 +44,11 @@ const GPU = [
 const TAG = 'homie-studio-check';
 const ANDROID_UA = 'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Mobile Safari/537.36';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const T = (p, ms, v = null) => Promise.race([Promise.resolve(p).catch(() => v), sleep(ms).then(() => v)]);
+const T = async (p, ms, v = null) => {
+  let timer;
+  try { return await Promise.race([Promise.resolve(p).catch(() => v), new Promise(resolve => { timer = setTimeout(() => resolve(v), ms); })]); }
+  finally { clearTimeout(timer); }
+};
 const DIRV = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] };
 const ALL = ['owner-desk', 'owner-phone', 'owner-iphone', 'round', 'life', 'tv'];
 
@@ -310,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;
@@ -328,17 +332,36 @@ async function touchDrag(h, from, dir, reach, holdMs, ready) {
 /** Timestamp real input delivery, then keep it held until four frames can judge its direction.
  * The response limit stays 600 ms; slow automation delivery and the thumb's ramp are not game latency. */
 export async function measuredPress(h, how, code, from, dir) {
+  // CDP points use page coordinates; DOM touch receipts use frame coordinates.
+  let offset = { x: 0, y: 0 };
+  if (how !== 'keys') {
+    const element = await frameOf(h)?.frameElement();
+    if (element) {
+      try { offset = await element.boundingBox() ?? offset; }
+      finally { await element.dispose(); }
+    }
+  }
   await inFrame(h, `(() => {
     if (!window.__homieCheckInput) {
       const state = window.__homieCheckInput = {};
       addEventListener('keydown', e => { if (state.code === e.code && state.key === null) state.key = performance.now(); }, true);
-      addEventListener('touchmove', () => { state.touch = performance.now(); }, { capture: true, passive: true });
+      addEventListener('touchmove', e => {
+        const touch = e.touches[0];
+        if (state.touch === null && touch && touch.clientX === state.touchX && touch.clientY === state.touchY) state.touch = performance.now();
+      }, { capture: true, passive: true });
     }
-    Object.assign(window.__homieCheckInput, { code: ${JSON.stringify(code)}, key: null, touch: null });
+    Object.assign(window.__homieCheckInput, { code: ${JSON.stringify(code)}, key: null, touch: null, touchX: ${Math.round(from[0] + DIRV[dir][0] * 70) - offset.x}, touchY: ${Math.round(from[1] + DIRV[dir][1] * 70) - offset.y} });
   })()`);
   let a = null, b = null;
   const ready = async () => {
-    a = await inFrame(h, `window.__homieCheckInput.${how === 'keys' ? 'key' : 'touch'}`);
+    // CDP acknowledgement is not DOM delivery. Wait for the final ramp point,
+    // then latch that receipt so later/coalesced moves cannot change it.
+    const deliveryDeadline = Date.now() + 3000;
+    do {
+      a = await inFrame(h, `window.__homieCheckInput.${how === 'keys' ? 'key' : 'touch'}`);
+      if (Number.isFinite(a)) break;
+      await sleep(20);
+    } while (Date.now() < deliveryDeadline);
     if (!Number.isFinite(a)) throw new Error('the game frame did not receive the measured input');
     await sleep(420);
     const until = Date.now() + 3000;
@@ -346,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/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 { 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';
 /**
@@ -67,8 +68,8 @@ export function slugify(name) {
  * the binding names and keep it linked.
  */
 export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null }) {
-  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
-    : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
+  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/runtime/worker.js', dist: './dist', migrations: 'migrations' }
+    : { schema: 'node_modules', main: 'site/src/runtime/worker.js', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
   const config = {
     $schema: `${at.schema}/wrangler/config-schema.json`,
@@ -80,7 +81,8 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // subdomain) reaches it instead of failing with 1042.
     // `disallow_eval_during_startup`: no code is made from a string while the Worker loads (Cloudflare never allows it
     // later). A game's rules run in this Worker (NETPLAY.md section 29), and nothing in them is ever made from text.
-    compatibility_flags: ['global_fetch_strictly_public', 'disallow_eval_during_startup', ...(paidParts ? ['nodejs_compat'] : [])],
+    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 } }] } : {}),
     workers_dev: true,
     preview_urls: true,
@@ -152,6 +154,8 @@ 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.
+
 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\`.
 
 ## Commands (all through the pinned CLI in node_modules)
@@ -645,6 +649,8 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 `;
 
 const GITIGNORE = `node_modules/
+site/src/runtime/
+site/src/tools/
 # This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
 .studio/
 # This person's own Claude Code settings for this studio (the status line, for one).
@@ -734,11 +740,12 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'site/README.md': SITE_README,
     'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
-import { hostRules } from '@homie-rocks/studio/worker';
+import { hostRules, useTools } from '@homie-rocks/studio/worker';
 // The rules of this studio's games that run on the server (written by homie-studio build; empty until a game has some).
 import rules from './rules/index.mjs';
 
 hostRules(rules);
+useTools(async () => (await import('./tools/index.mjs')).default);
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/src/rules/index.mjs': rulesIndex([]),
@@ -755,6 +762,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_STATEMENTS_FILE}`]: SHOP_STATEMENTS,
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
+    [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_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': '',
@@ -926,13 +934,18 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_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)].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)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
 export function migrationWord(file) {
-  return /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
+  return /studio_mcp/.test(file) ? 'AI connections and tool call history' : /studio_apps/.test(file) ? 'apps: lasting records and signed-in role grants' : /lounge/.test(file) ? 'the Lounge and kept chat: play nights, moderators, and what was said only where an owner turns history on' : /shop/.test(file) ? 'the shop: orders, what players own, refunds and referral books (paid sales wait until shop.json and the studio\'s Stripe connection are ready)' : /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'apps', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
+const RESERVED_IDS = new Set(['mcp', 'oauth', 'hooks', 'api', 'media', 'games', 'apps', 'assets', '_homie', '_site', '_studio', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts', 'rooms', 'feed', 'account']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);

package/lib/template-history.json

@@ -2156,6 +2156,88 @@
      }
     }
    }
+  },
+  "0.39.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "34444a6ca4b14437"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "c18362ed28975d81",
+     "## Apps: one screen, roles and parts": "be6f8fa45f93211a",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
+  },
+  "0.40.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "34444a6ca4b14437"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "c18362ed28975d81",
+     "## Apps: one screen, roles and parts": "be6f8fa45f93211a",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/tools-build.mjs

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import { partsPlugin, resolvePartImport } from './parts-build.mjs';
+const require=createRequire(import.meta.url);
+export function toolFiles(root) {
+  const dirs=[join(root,'tools')];
+  const apps=join(root,'apps');if(existsSync(apps))for(const app of readdirSync(apps,{withFileTypes:true}))if(app.isDirectory())dirs.push(join(apps,app.name,'tools'));
+  return dirs.flatMap(dir=>existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]);
+}
+export async function buildTools(root,esbuild) {
+  const files=toolFiles(root),dir=join(root,'site/src/tools');
+  mkdirSync(dir,{recursive:true});
+  if(files.length){
+    const ts=require('typescript');
+    const options={target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,moduleResolution:ts.ModuleResolutionKind.Bundler,strict:true,noEmit:true,skipLibCheck:true,allowImportingTsExtensions:true};
+    const host=ts.createCompilerHost(options);
+    host.resolveModuleNames=(names,containing)=>names.map(name=>{
+      if(name.startsWith('@parts/')){const part=resolvePartImport(root,name);if(part.path)return {resolvedFileName:part.path,extension:part.path.endsWith('.ts')?ts.Extension.Ts:ts.Extension.Js};}
+      return ts.resolveModuleName(name,containing,options,host).resolvedModule;
+    });
+    const program=ts.createProgram(files,options,host);
+    const errors=ts.getPreEmitDiagnostics(program);
+    if(errors.length)throw new Error(ts.formatDiagnosticsWithColorAndContext(errors,{getCurrentDirectory:()=>root,getCanonicalFileName:f=>f,getNewLine:()=> '\n'}));
+  }
+  const contents=files.map((f,i)=>`import t${i} from ${JSON.stringify(f)};`).join('\n')+`\nexport default [${files.map((_,i)=>'t'+i).join(',')}];\n`;
+  const result=await esbuild.build({stdin:{contents,resolveDir:root},bundle:true,format:'esm',platform:'neutral',target:'es2022',write:false,plugins:[partsPlugin(root)],logLevel:'silent'});
+  const temp=join(dir,'index.mjs');writeFileSync(temp,result.outputFiles[0].text);
+  // Trusted studio code, as with the existing build command. No Worker bindings exist during build.
+  const defs=(await import(pathToFileURL(temp).href+'?build='+Date.now())).default;
+  const { CfWorkerJsonSchemaValidator }=await import('@modelcontextprotocol/server/validators/cf-worker');
+  const validator=new CfWorkerJsonSchemaValidator(),seen=new Set();
+  for(const t of defs){
+    if(!/^[a-z][a-z0-9_]{0,63}$/.test(t.name)||/^(studio_|app_|agent_|room_|shop_)/.test(t.name)||seen.has(t.name))throw new Error(`tool name is invalid, reserved or duplicated: ${t.name}`);
+    seen.add(t.name);
+    if(typeof t.description!=='string'||!t.description.trim()||typeof t.handler!=='function')throw new Error(`tool ${t.name} needs description and handler`);
+    if(!['owner','signed-in','public'].includes(t.audience)&&!(t.audience&&typeof t.audience.app==='string'&&typeof t.audience.role==='string'))throw new Error(`tool ${t.name} needs an audience`);
+    if(t.inputSchema?.type!=='object')throw new Error(`tool ${t.name} input schema must be an object`);
+    validator.getValidator(t.inputSchema);
+    if(t.kind!==undefined&&!['tool','prompt'].includes(t.kind))throw new Error(`tool ${t.name}: invalid kind`);
+    if(t.webhook&&(!/^[A-Z][A-Z0-9_]{0,63}$/.test(t.webhook.secret)||typeof t.webhook.person!=='string'||!t.webhook.person))throw new Error(`tool ${t.name}: webhook needs a named secret and account`);
+    for(const [name,event] of Object.entries(t.events??{})){
+      if(!/^external:[a-z][a-z0-9_-]{0,40}$/.test(name)||!event.game||!event.schema)throw new Error(`tool ${t.name}: invalid external event`);
+      validator.getValidator(event.schema);
+    }
+  }
+  // Existing studios retain their Worker customization; install the small registry hook once.
+  const worker=join(root,'site/src/worker.mjs');
+  if(existsSync(worker)){
+    let text=readFileSync(worker,'utf8');
+    if(!text.includes('useTools(')){text += "\nimport { useTools } from '@homie-rocks/studio/worker';\nuseTools(async () => (await import('./tools/index.mjs')).default);\n";writeFileSync(worker,text);}
+  }
+  return defs.map(t=>t.name);
+}