@homie-rocks/studio 0.55.0 → 0.57.0

package/lib/cloudflare.mjs

@@ -1,3 +1,5 @@
+import {ensureStudioSigningKey} from './studios-keys.mjs';
+import {redactText} from './redact.mjs';
 import {enableReadReplication} from './read-replication.mjs';
 import {ensureBackgroundQueues,backgroundQueues} from './background-queue.mjs';
 import { directoryUrl } from '../worker/directory-choice.mjs';
@@ -53,6 +55,13 @@ import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layou
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
+/** Keep Wrangler's error and its context; progress/footer lines must not hide it. */
+export function wranglerDeployError(out) {
+  const clean = redactText(String(out ?? '').replace(ANSI, '')).text;
+  const error = clean.search(/(?:^|\n)[^\n]*\[ERROR\]/);
+  return (error >= 0 ? clean.slice(error) : clean).trim();
+}
+
 export function experienceAddresses(root, id, url) {
   const app = listGames(root).find(g => g.id === id)?.kind === 'app';
   return { [app ? 'open' : 'play']: url ? `${url}/${id}/${app ? 'open' : 'play'}` : null, wall: url ? `${url}/${id}/tv` : null };
@@ -67,24 +76,41 @@ export function wranglerBin(root) {
 export function runner(root, env) {
   const bin = wranglerBin(root);
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
-  return (args, { cwd = workerDir(root), input } = {}) => {
+  return (args, { cwd = workerDir(root), input, timeout = 10 * 60_000 } = {}) => {
     const dev = join(workerDir(root), '.wrangler', 'homie-dev.wrangler.json');
     if (args.includes('--local') && !args.includes('--config') && existsSync(dev)) args = [...args, '--config', dev, '--persist-to', join(workerDir(root), '.wrangler', 'state')];
     const res = spawnSync(bin, args, {
       cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
-      input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
+      input, maxBuffer: 64 * 1024 * 1024, timeout,
     });
-    const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.replace(ANSI, '');
+    const out = `${res.stdout ?? ''}${res.stderr ?? ''}${res.error ? '\n' + res.error.message : ''}`.replace(ANSI, '');
     return { code: res.status ?? 1, out, stdout: (res.stdout ?? '').replace(ANSI, '') };
   };
 }
 
+/** Retry with fresh Wrangler processes: another studio may be rotating shared OAuth credentials. */
+export async function checkWranglerLogin(root, env = {}, {run = null, sleep = ms => new Promise(resolve => setTimeout(resolve, ms))} = {}) {
+  const bin = run ? null : wranglerBin(root);
+  if (!run && !bin) return {ok:false, needs:'cloudflare-login', why:'Wrangler is not installed in this studio yet: run `npm install` first.'};
+  const w = run ?? (args => wranglerRun(bin, args, {cwd:root, env:{...process.env,...env,WRANGLER_SEND_METRICS:'false',CI:'1'}, timeout:25_000}));
+  let res, data;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt) await sleep([200, 600, 1400][attempt - 1] + Math.floor(Math.random() * 100));
+    res = await w(['whoami', '--json'], {cwd: root, timeout: 25_000});
+    try { data = JSON.parse(res.stdout ?? ''); } catch { data = null; }
+    if (res.code === 0 && data?.loggedIn === false) return {ok:false, needs:'cloudflare-login', why:'Wrangler is not signed in. Run `npx wrangler login` and approve once in your browser, then retry.'};
+    if (res.code === 0 && data?.loggedIn === true) return {ok:true, who:{accounts:(data.accounts ?? []).map(a => ({id:a.id,name:a.name})),authType:data.authType}};
+  }
+  const detail = String(res.out ?? '').trim();
+  const expired = data?.loggedIn === false || /(?:refresh token.*(?:expired|invalid)|invalid_grant|not (?:logged|signed) in|authentication error|authenticate request)/i.test(detail);
+  return {ok:false, needs:expired ? 'cloudflare-login' : 'cloudflare-auth-check', why: (expired
+    ? 'Wrangler could not authenticate after four attempts. Run `npx wrangler login`, then retry.'
+    : 'Wrangler could not check sign-in after four attempts. Another process may be refreshing credentials, or Cloudflare may be unreachable. Retry shortly.') + (detail ? '\nWrangler: '+detail : '')};
+}
+
 /** Who Wrangler is signed in as, or null. Never prints a token. */
-export function whoami(root, env = {}) {
-  const w = runner(root, env);
-  const res = w(['whoami', '--json'], { cwd: root });
-  if (res.code !== 0) return null;
-  try { const d = JSON.parse(res.stdout); return d.loggedIn ? { accounts: (d.accounts ?? []).map((a) => ({ id: a.id, name: a.name })), authType: d.authType } : null; } catch { return null; }
+export async function whoami(root, env = {}) {
+  return (await checkWranglerLogin(root, env)).who ?? null;
 }
 
 function parseJson(text) {
@@ -262,12 +288,13 @@ 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 who = whoami(root);
-  if (!who) {
-    if (cf.auth === 'stripe-projects') {
-      return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler did not accept the Cloudflare token Stripe Projects keeps for this studio (studio.json "auth": "stripe-projects"). Run `stripe projects env --pull` in the studio folder (it rewrites the git-ignored .env from Projects\' vault), then `npm run deploy` again; or sign in the usual way (`npx wrangler login`) and remove "auth" from studio.json.' };
+  const login = await checkWranglerLogin(root);
+  const who = login.who;
+  if (!login.ok) {
+    if (cf.auth === 'stripe-projects' && login.needs === 'cloudflare-login') {
+      return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: login.why + '\nWrangler did not accept the Cloudflare token Stripe Projects keeps for this studio (studio.json "auth": "stripe-projects"). Run `stripe projects env --pull` in the studio folder (it rewrites the git-ignored .env from Projects\' vault), then `npm run deploy` again; or sign in the usual way (`npx wrangler login`) and remove "auth" from studio.json.' };
     }
-    return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` in the studio folder: it opens Cloudflare in the browser and the person approves once (a free account works, no payment method). Then run `npm run deploy` again.' };
+    return { ...login, command: 'deploy' };
   }
   const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
   if (!accountId) {
@@ -413,7 +440,8 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     step(address.created ? 'registered the account’s workers.dev address automatically' : 'kept the account’s existing workers.dev address');
     dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
   }
-  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
+  try{await ensureStudioSigningKey(readStudio(root),w);}catch(error){return refuse(error.message);}
   if (paidReleases(root).length) {
     const bin = wranglerBin(root);
     const uploadOptions = { cwd: workerDir(root), env: { ...process.env, CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
@@ -637,7 +665,8 @@ export async function ciDeploy(root, { log = () => {}, wrangler = null } = {}) {
   }
   const started = Date.now();
   const dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
-  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${wranglerDeployError(dep.out)}`, dep.out);
+  try{await ensureStudioSigningKey(readStudio(root),w);}catch(error){return refuse(error.message);}
   step(`deployed ${names.worker ?? 'the Worker'} in ${Math.round((Date.now() - started) / 1000)} s`);
   const repo = repoOf(root);
   step(repo ? `the live site knows its GitHub repository (${repo}), for the Claude app's hand-off` : 'no GitHub repository found here (no HOMIE_REPO, studio.json "github" or git remote): the Claude app\'s card asks the person which it is');
@@ -683,8 +712,9 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   if (created.has(`r2:${bucket}`)) {
     return { ok: true, command: 'storage add', bucket, already: true, next: ['npm run deploy   (binds it as MEDIA if the live site does not have it yet)'] };
   }
-  const who = whoami(root);
-  if (!who) return { ok: false, command: 'storage add', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` first (one approval in the browser).' };
+  const login = await checkWranglerLogin(root);
+  if (!login.ok) return {...login, command:'storage add'};
+  const who = login.who;
   const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
   if (!accountId) return { ok: false, command: 'storage add', needs: 'cloudflare-account', why: 'This login reaches several Cloudflare accounts; put the studio\'s in studio.json (cloudflare.accountId) first.', accounts: who.accounts };
   const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
@@ -718,15 +748,15 @@ export async function storageAdd(root, { log = () => {} } = {}) {
 }
 
 /** One Wrangler command, run without blocking (an upload of a music video takes a while); the last of its words kept. */
-function wranglerRun(bin, args, { cwd, env }) {
+function wranglerRun(bin, args, { cwd, env, timeout }) {
   return new Promise((done) => {
-    const p = spawn(bin, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '';
+    const p = spawn(bin, args, { cwd, env, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', stdout = '';
     const keep = (d) => { out = `${out}${d}`.slice(-8000); };
-    p.stdout.on('data', keep);
+    p.stdout.on('data', data => {stdout = `${stdout}${data}`.slice(-65536); keep(data);});
     p.stderr.on('data', keep);
     p.on('error', (e) => done({ code: 1, out: String(e.message) }));
-    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, '') }));
+    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, ''), stdout: stdout.replace(ANSI, '') }));
   });
 }
 

package/lib/dev.mjs

@@ -347,17 +347,15 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1', ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}) };
   for (const added of ensureMigrations(root)) log(`added ${added} (${migrationWord(added)})`);
-  await new Promise((done) => {
-    const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
-    m.on('close', done);
-    m.on('error', done);
-  });
   const {functionDeploymentSQL}=await import('./functions-build.mjs');
-  const registerFunctions=()=>new Promise(resolve=>{
-    const child=spawn(bin,['d1','execute','DB','--local','--command',functionDeploymentSQL(root)],{cwd:workerDir(root),env,stdio:['ignore','ignore','inherit']});
+  const {prepareLocalDatabase}=await import('./local-database-start.mjs');
+  const runLocal=args=>new Promise(resolve=>{
+    const child=spawn(bin,args,{cwd:workerDir(root),env,stdio:['ignore','ignore','inherit']});
     child.on('close',code=>resolve(code===0));child.on('error',()=>resolve(false));
   });
-  if(!await registerFunctions())return {ok:false,command:'dev',why:'Local function registration failed; fix the D1 error above before serving requests.'};
+  const registerFunctions=()=>runLocal(['d1','execute','DB','--local','--command',functionDeploymentSQL(root)]);
+  const failure=await prepareLocalDatabase({migrate:()=>runLocal(['d1','migrations','apply','DB','--local']),register:registerFunctions});
+  if(failure)return {ok:false,command:'dev',why:failure};
   const origin = `http://127.0.0.1:${port}`;
   const printedOrigin = `http://localhost:${port}`;
   log(`Local site: ${printedOrigin}/  (each game: ${printedOrigin}/<id>/play — open it in two browsers)`);

package/lib/local-database-start.mjs

@@ -0,0 +1,6 @@
+/** Complete local schema and subscriptions before any request can emit an event. */
+export async function prepareLocalDatabase({migrate,register}) {
+  if(!await migrate())return 'Local database migration failed; fix the D1 error above before serving requests.';
+  if(!await register())return 'Local function registration failed; fix the D1 error above before serving requests.';
+  return null;
+}

package/lib/mcp-tools.mjs

@@ -843,7 +843,7 @@ export function toolDefs(ctx, avail = {}) {
         let at = dir;
         if (existsSync(at) && readdirSync(at).some((f) => !['.DS_Store', '.git'].includes(f)) && !existsSync(join(at, 'studio.json'))) at = `${dir}-studio`;
         let made;
-        try { made = newStudio(at, { name, kind: a.kind ?? 'game', install: false, ...(ctx.directory ? { homie: ctx.directory } : {}) }); } catch (error) { return fail(error.message); }
+        try { made = newStudio(at, { name, kind: a.kind ?? 'game', install: false }); } catch (error) { return fail(error.message); }
         ctx.current = made.dir;
         ctx.note(made.dir).earlier = earlier.map((e) => e.path);
         let install = null;
@@ -1258,10 +1258,10 @@ export function toolDefs(ctx, avail = {}) {
         // the directory's read-only count for this site, the parts' lines, and nothing published. Run here, by THIS
         // toolkit, never handed to the studio's pinned one: a 0.31.0 toolkit reads `publish --before` as `publish`.
         if (a.before === true) {
-          const b = await publishBefore(root, { site: a.site ? String(a.site) : undefined });
+          const b = await publishBefore(root, { homie: ctx.directory ?? undefined, site: a.site ? String(a.site) : undefined });
           return ok(b.lines.join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...b });
         }
-        const r = await cli(ctx, root, 'publish', ['publish', ...(a.site ? ['--site', String(a.site)] : [])]);
+        const r = await cli(ctx, root, 'publish', ['publish', ...(ctx.directory ? ['--homie', ctx.directory] : []), ...(a.site ? ['--site', String(a.site)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'Listing');
         if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`, r.result?.publishes ? { kind: 'publish', ok: false, needs: r.result.needs ?? null, publishes: r.result.publishes } : undefined);
         return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}${r.result?.publishes?.line ? `\n${r.result.publishes.line}` : ''}${partsSaid.length ? `\n${partsSaid.join('\n')}` : ''}`, { kind: 'publish', ...r.result });

package/lib/needs-headless.mjs

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

package/lib/port-check.mjs

@@ -628,12 +628,13 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
       }
     }
 
-    /* ---- two fresh browsers meet through the lobby and finish a round */
+    /* ---- a public join and an invited browser finish a round */
     if (want.has('round') && await gate('round')) {
       try {
         const A = await launch('desk');
         const B = await launch('phone');
-        const [oa, ob] = [await open(A, `${base}/${game}/play?name=Desk`), await open(B, `${base}/${game}/play?name=Phone`)];
+        const oa = await open(A, `${base}/${game}/play?name=Desk`);
+        const ob = await open(B, `${base}/${game}/play?name=Phone${oa.shell?.room ? `&room=${encodeURIComponent(oa.shell.room)}` : ''}`);
         if (!oa.ok || !ob.ok) row('round', false, { why: `a browser was never seated (${!oa.ok ? `computer: ${oa.why}` : ''} ${!ob.ok ? `phone: ${ob.why}` : ''})` });
         else if (oa.shell.room !== ob.shell.room) row('round', false, { why: `the two browsers landed in different rooms (${oa.shell.room}, ${ob.shell.room})` });
         else {

package/lib/scaffold.mjs

@@ -152,6 +152,8 @@ the Table/Lobby Durable Objects, on the studio's Cloudflare account), built
 from \`@homie-rocks/studio\`, pinned in \`package.json\`. The homie.rocks
 directory lists its games; homie.rocks does not host them.
 
+For studio-owned HTTP endpoints, read \`node_modules/@homie-rocks/studio/docs/custom-routes.md\` before editing \`site/src/worker.mjs\`. Use the reserved \`/api/custom/*\` namespace and the documented authorization and cookie scopes.
+
 ## Version-matched authoring guides
 
 Before authoring or rewriting a game, read \`node_modules/@homie-rocks/studio/guides/game/SKILL.md\`,

package/lib/studios-keys.mjs

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

package/lib/template-history.json

@@ -4020,7 +4020,94 @@
    },
    "sections": {
     "AGENTS.md": {
-     "(intro)": "394cbbe934e80722",
+     "(intro)": [
+      "394cbbe934e80722",
+      "af7f2f732505d379"
+     ],
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
+  },
+  "0.56.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
+  },
+  "0.57.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
      "## Version-matched authoring guides": "f6261a0e5801b96b",
      "## Layout": "f3a280b8c96cd068",
      "## Apps: one screen, roles and parts": "c10aa0441ea89702",

package/lib/worker-build.mjs

@@ -20,7 +20,10 @@ export async function buildWorker(root,esbuild,metadata=null) {
   // classes in the generated bundle without rewriting the studio's source/customizations.
   const standardRooms=/export\s*\{[^}]*\bTable\b[^}]*\bLobby\b[^}]*\}\s*from\s*['"]@homie-rocks\/studio\/worker['"]/.test(readFileSync(source,'utf8'));
   const lazyRooms=standardRooms?`export {Table,Lobby} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`:'';
-  const contents=`${lazyRooms}export * from ${JSON.stringify(source)};\nexport { default } from ${JSON.stringify(source)};\nexport { Gate, Concentrator } from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\nexport {AppRecordHub, EventHub} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`;
+  // A custom fetch wrapper may predate background delivery. Complete the event
+  // boundary here, preserving explicit studio handlers and leaving source alone.
+  const toolkitEntry=alias['@homie-rocks/studio/worker']==='@homie-rocks/studio/worker/selling'?'worker/selling/index.mjs':'worker/index.mjs';
+  const contents=`${lazyRooms}export * from ${JSON.stringify(source)};\nimport studioWorker from ${JSON.stringify(source)};\nimport toolkitWorker from ${JSON.stringify(join(PACKAGE_ROOT,toolkitEntry))};\nexport default { ...studioWorker, queue: studioWorker.queue ?? toolkitWorker.queue, scheduled: studioWorker.scheduled ?? toolkitWorker.scheduled };\nexport { Gate, Concentrator } from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\nexport {AppRecordHub, EventHub} from ${JSON.stringify(join(PACKAGE_ROOT,'worker/lazy-objects.mjs'))};\n`;
   const result=await esbuild.build({stdin:{contents,resolveDir:root,sourcefile:'worker.mjs'},entryNames:'worker',absWorkingDir:root,alias,outdir:out,bundle:true,splitting:true,format:'esm',platform:'browser',mainFields:['module','main'],conditions:['workerd','worker','browser'],external:['node:*','cloudflare:*'],target:'es2022',write:false,minify:true,metafile:true,logLevel:'silent',plugins:[{name:'studio-runtime',setup(build){
     if(metadata)build.onLoad({filter:/[/\\]worker[/\\]built-metadata\.mjs$/},()=>({contents:'export default '+JSON.stringify(metadata),loader:'js'}));
     // Merely overriding entry exports still evaluates the barrel's dependencies.

package/lib/worker-config.mjs

@@ -28,6 +28,13 @@ export function updateWorkerConfig(root,generated) {
     writeFileSync(join(root,'wrangler.custom.json'),JSON.stringify(custom,null,2)+'\n');
   }
   const next=merge(base,custom);
+  // Authorization paths are additive: custom assets must never bypass toolkit gates.
+  const requiredRoutes=base.assets?.run_worker_first, customRoutes=custom.assets?.run_worker_first;
+  // A "!" pattern excludes paths from the Worker. Only Homie writes those (static-assets.mjs): a custom one
+  // could take /games/*, /_studio/* or an app's files out from behind their access checks.
+  const exclusions=Array.isArray(customRoutes)?customRoutes.filter(p=>String(p).startsWith('!')):[];
+  if(exclusions.length)throw new Error(`wrangler.custom.json assets.run_worker_first cannot exclude paths (${exclusions.join(', ')}): list only the extra paths your own routes need`);
+  next.assets={...next.assets,run_worker_first:requiredRoutes===true || customRoutes===true ? true : [...new Set([...(Array.isArray(requiredRoutes)?requiredRoutes:[]),...(Array.isArray(customRoutes)?customRoutes:[])])]};
   if(readStudio(root).concept===true)next.assets={...next.assets,run_worker_first:true};
   next.vars={...next.vars,HOMIE_CONCEPT:readStudio(root).concept===true?'1':'0'};
   verifiedMcpConfig(root);

package/netplay/NETPLAY.md

@@ -290,6 +290,13 @@ at once, with bots filling the slots (Gem Rush: 1 human + 2 bots).
 - A human who leaves turns back into a bot in the same body.
 - `trim()` removes surplus bots between rounds.
 - After every change the host calls `net.roster(slots)`.
+- A browser host may receive `join` before its world is ready. Once it publishes a roster,
+  snapshot traffic makes the relay retry any connected replica seat missing from that roster,
+  with delays doubling from 1 second to a 30-second cap, for at most eight retries per peer
+  and host. A roster seat (including `agent.seat` for host-driven AI) acknowledges the claim.
+  If still unacknowledged after the final wait, the relay logs once and stops retrying. Treat a repeated `join` for an
+  already claimed seat as idempotent; keep its body and score. This uses the existing wire
+  message, including for older bundled clients. Rules hosts reconcile seats separately.
 
 **Join in progress.**
 1. The `welcome` carries the last snapshot, round, roster and **all keyed state**. The
@@ -1591,7 +1598,11 @@ A page stands in one of six places with its room, and the helper says which:
 - **`net.offline` means "not in a room"**, not "no network": it is true for `alone` and `offline`.
   **`net.connected`** is true only while the socket is up and welcomed. The state between them
   (`!net.offline && !net.connected`) is `reconnecting`.
-- **`on('link', (e) => …)`** fires on every change with `{ state, prev, why, hosting, downMs }`.
+- **`on('link', (e) => …)`** immediately calls the listener with the current state
+  (`prev === state`, `why: 'subscribe'`), then fires on every change with `{ state, prev, why, hosting, downMs }`.
+  Ignore `why === 'subscribe'` when triggering reconnect recovery; it initializes
+  UI and does not signal a new connection. Listener errors are isolated, including
+  this immediate call, and `on()` always returns the unsubscribe function.
   `hosting` says this page is running the rules right now. Two pages can both say so for a
   moment: a host that was cut off keeps simulating until its welcome tells it the room moved on,
   and a page that is `alone` hosts its own private round. Before revision 9 neither said

package/netplay/netplay.ts

@@ -170,7 +170,7 @@ export type LinkState = 'connecting' | 'online' | 'reconnecting' | 'alone' | 'of
 export interface LinkChange {
   state: LinkState;
   prev: LinkState;
-  /** Why it changed: `welcome`, `lost` (the socket closed), `stale` (it went silent), `relay-timeout` (the room never answered), `reconnect-timeout` (it was in the room and the room did not come back in `reconnectMaxMs`), `no-shell`, or a refusal's code. */
+  /** `subscribe` is the current state delivered immediately on subscription (prev equals state). Otherwise, why it changed: `welcome`, `lost` (the socket closed), `stale` (it went silent), `relay-timeout` (the room never answered), `reconnect-timeout` (it was in the room and the room did not come back in `reconnectMaxMs`), `no-shell`, or a refusal's code. */
   why: string;
   /** This browser is running the rules right now (alone, or as the room's host): two browsers can both say so while one is cut off. */
   hosting: boolean;
@@ -749,7 +749,7 @@ export interface NetHandlers<S, A, C> {
   unchat: (e: { ids: string[] }) => void;
   /** Revision 8: a message of mine was not sent (slow mode, sign in to type, a word, the studio's filter…). */
   held: (h: ChatHeld) => void;
-  /** Revision 9: where this browser stands with its room changed (online, reconnecting, alone, closed). */
+  /** Current link on subscription (why: subscribe), then changes (online, reconnecting, alone, closed). */
   link: (e: LinkChange) => void;
   /** Revision 9: a newer build of the game is live; this tab should reload (section 23). */
   stale: (e: StaleNotice) => void;
@@ -797,7 +797,7 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
    * THE LINK (revision 9, NETPLAY.md section 22). `offline` is true when this browser is NOT in a room: there is no
    * shell at all, or the room never answered and it plays alone (`link === 'alone'`). `connected` is true only while
    * the socket is up and welcomed. Between the two (`!offline && !connected`) the browser was in a room and is
-   * knocking again: `link === 'reconnecting'`. `link` says which in one word, and `on('link')` when it changes.
+   * knocking again: `link === 'reconnecting'`. `link` says which in one word, and `on('link')` immediately reports the current state, then each change.
    */
   readonly link: LinkState;
   /** Times the helper has scheduled another knock at the relay (the same number as `stats().reconnects`). 0: never interrupted. */
@@ -1713,6 +1713,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   const peers = new Map<string, Peer>();
   let heldPeers: Peer[] = [];
   let roundInfo: RoundInfo | null = null;
+  let idlePing = false, lastClockPing = -Infinity;
   let slots: Slot[] | null = null;
   let lastCkpt: Checkpoint<C> | null = null;
 
@@ -2352,12 +2353,13 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
 
   // ---------------------------------------------------------------- wire in
   function onMessage(data: unknown): void {
-    lastMsgAt = wall();
+    if (data === 'homie-pong' && idlePing) { lastMsgAt = wall(); return; }
     const text = typeof data === 'string' ? data : String(data);
     countBytes(bytesIn, text.length);
     let m: Record<string, unknown>;
     try { m = JSON.parse(text) as Record<string, unknown>; } catch { return; }
     if (!m || typeof m['t'] !== 'string') return;
+    lastMsgAt = wall();
     switch (m['t']) {
       case 'welcome': return onWelcome(m);
       case 'snap': return onSnap(m, text.length);
@@ -2583,6 +2585,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   }
 
   function onWelcome(m: Record<string, unknown>): void {
+    idlePing = m.idlePing === true; lastClockPing = -Infinity;
     post?.({ what: 'build', ver: version });
     clearTimeout(connectTimer);
     const next = m['role'] as Role;
@@ -2810,7 +2813,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     const st = Number(m['st']);
     const sent = pingsOut.get(c);
     if (sent === undefined || !Number.isFinite(st)) return;
-    pingsOut.delete(c);
+    for (const key of pingsOut.keys()) if (key <= c) pingsOut.delete(key);
     const recv = Date.now();
     const r = recv - sent;
     const off = st + r / 2 - recv;
@@ -2869,7 +2872,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   }
 
   function hidden(): boolean { try { return Boolean(g.document?.hidden); } catch { return false; } }
-  function ping(): void {
+  function ping(force = false): void {
     // This runs every two seconds at least. A gap of more than three and a half means the page itself was held.
     const beat = wall();
     const pingHeld = beat - lastPingTick > 2000 + 1500;
@@ -2885,12 +2888,22 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     // the word of a timer that itself ran seconds late: the page was blocked (a heavy boot, shaders compiling) and
     // could not have heard anything, and what the relay sent meanwhile is still queued behind this very timer.
     // Dropping a healthy socket there turned every long hitch into a reconnect.
-    if (ws && lastMsgAt && wall() - lastMsgAt > staleMs) {
+    const oldestPing = pingsOut.values().next().value;
+    if (ws && oldestPing !== undefined && Date.now() - oldestPing >= 30_000 && !pingHeld) { lost(ws, 'stale'); return; }
+    const silence = idlePing && (roundInfo?.phase !== 'live' || wall() - lastClockPing > staleMs) ? Math.max(staleMs, 60_000) : staleMs;
+    if (ws && lastMsgAt && wall() - lastMsgAt > silence) {
       if (!pingHeld) { lost(ws, 'stale'); return; }
       // Two and a half seconds to be heard from (a pong answers the ping below): a socket that is really dead is
       // still dropped, two beats from now.
       lastMsgAt = wall() - staleMs + 2500;
     }
+    // An idle hibernatable room can answer this at the edge. Keep a regular
+    // clock/visibility sample on visibility changes, and every heartbeat during play.
+    if (idlePing && roundInfo?.phase !== 'live' && !(roundInfo?.phase === 'over' && now() >= roundInfo.endsAt) && !force) {
+      try { ws?.send('homie-ping'); } catch { if(ws)lost(ws,'send'); }
+      return;
+    }
+    lastClockPing = wall();
     const c = Date.now();
     pingsOut.set(c, c);
     if (pingsOut.size > 16) { const first = pingsOut.keys().next().value; if (first !== undefined) pingsOut.delete(first); }
@@ -3026,6 +3039,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     ws = sock; socketStartedAt = wall();
     sock.onopen = () => {
       lastMsgAt = wall();
+      pingsOut.clear();
       raw({
         t: 'hello', rules: rulesGame, v: NETPLAY_VERSION, rev: NETPLAY_REVISION, token, name: name || undefined, device, want, canHost: asAgent && asAgent.hands === 'host' ? false : canHost, game: opts.game, max: opts.maxPlayers,
         ...(rulesGame ? { coast: 1 } : {}),
@@ -3101,8 +3115,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       if (hidden()) {
         // A hidden phone tab loses its timers and rAF: hand the round on before it stalls.
         if (role === 'host' && peers.size > 1) yieldHost();
-        ping();
-      } else ping();
+        ping(true);
+      } else ping(true);
     });
     g.addEventListener?.('online', () => { if (!closed && !connected && rulesGame) { if (ws) lost(ws, 'online'); if (retryTimer !== null) clearTimeout(retryTimer); retryTimer = null; attempt = 0; open(); } });
     g.addEventListener?.('pagehide', () => { if (role === 'host') { sendCheckpoint(); rulesSender?.leave(); } raw({ t: 'bye' }); });
@@ -3353,6 +3367,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     on(kind, fn) {
       (handlers[kind] as Set<unknown>).add(fn);
       if (kind === 'view') markFollows();
+      if (kind === 'link') try { (fn as NetHandlers<S, A, C>['link'])({state:link,prev:link,why:'subscribe',hosting:roleKnown && role === 'host',downMs:connected || !downSince ? 0 : Math.round(wall() - downSince)}); } catch { /* A failed UI listener must still be removable. */ }
       return () => { (handlers[kind] as Set<unknown>).delete(fn); };
     },
     now,

package/package.json

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

package/rules/core.ts

@@ -173,6 +173,8 @@ export interface Core {
   shared(): unknown[];
   /** The current round, for a host rebasing wall-clock deadlines after a pause or restore. */
   round(): Extract<CoreOut, { t: 'round' }>;
+  /** End a settled wall-clock break without simulating its idle ticks. */
+  resumeRound(): boolean;
   bodies(): Body[];
   /** Every person's body with where it stands: who an effect with an audience reaches (0.46.3). */
   listeners(): { seat: number; id: string; pos: Vec3 }[];
@@ -1537,6 +1539,13 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   }
   return {
     round: () => ({ t: 'round', ...round, ...(round.phase === 'over' && !overAt ? { results: results() } : {}) }),
+    resumeRound() {
+      if (round.phase !== 'over' || overAt) return false;
+      // Preserve queued events and their simulation-time deadlines. Nothing
+      // moves during the wall-clock break; the next step delivers them.
+      if (playing) startRound(); else restartAt = tick;
+      return true;
+    },
     get tick() { return tick; },
     reviseMovement,
     get epoch() { return epoch; },