@homie-rocks/studio 0.54.0 → 0.56.0

package/lib/scaffold.mjs

@@ -1,4 +1,7 @@
-import {TOOL_NAMESPACE_MIGRATION,TOOL_NAMESPACE_MIGRATION_FILE,CACHE_MIGRATION,CACHE_MIGRATION_FILE,OPERATIONAL_MIGRATION,OPERATIONAL_MIGRATION_FILE} from '../worker/operational-schema.mjs';
+import {ANALYTICS_MIGRATION,ANALYTICS_MIGRATION_FILE} from '../worker/analytics.mjs';
+import {backgroundQueues} from './background-queue.mjs';
+import {WORKER_ROUTES} from './static-assets.mjs';
+import {EXTRA_RUNTIME_MIGRATIONS,RUNTIME_INDEX_MIGRATION,RUNTIME_INDEX_MIGRATION_FILE,TOOL_NAMESPACE_MIGRATION,TOOL_NAMESPACE_MIGRATION_FILE,CACHE_MIGRATION,CACHE_MIGRATION_FILE,OPERATIONAL_MIGRATION,OPERATIONAL_MIGRATION_FILE} from '../worker/operational-schema.mjs';
 import {BOOKING_RESOURCES_MIGRATION,BOOKING_RESOURCES_MIGRATION_FILE} from '../worker/booking-resources.mjs';
 import {BOOKING_HOLDS_MIGRATION,BOOKING_HOLDS_MIGRATION_FILE} from '../worker/booking-holds.mjs';
 import {BUSINESS_EVENTS_MIGRATION,BUSINESS_EVENTS_MIGRATION_FILE} from '../worker/business-events.mjs';
@@ -76,10 +79,10 @@ export function slugify(name) {
  * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
  * the binding names and keep it linked.
  */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', main = null, ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null, eventFeeds = null }) {
+export function wranglerConfig({analytics = false, workerRoutes = WORKER_ROUTES, worker, name, d1, d1Id = null, r2 = null, layout = 'root', main = null, ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null, eventFeeds = null }) {
   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' }, { name: 'GATE', class_name: 'Gate' }, { name: 'CONCENTRATOR', class_name: 'Concentrator' }];
+  const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }, { name: 'GATE', class_name: 'Gate' }, { name: 'CONCENTRATOR', class_name: 'Concentrator' }, {name:'APP_RECORDS',class_name:'AppRecordHub'}, {name:'EVENTS',class_name:'EventHub'}];
   const config = {
     $schema: `${at.schema}/wrangler/config-schema.json`,
     name: worker,
@@ -92,25 +95,27 @@ 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 * * * *'] }, ...(partsRateLimit ? { ratelimits: [partsRateLimit] } : {}) } : {}),
+    ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, ...(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
     // every deploy, and one written without them sends the studio's domain back to whatever else the zone routes
     // (lib/routes.mjs). A studio without routes gets no key at all.
     ...(routes?.length ? { routes } : {}),
-    ...(triggers ? { triggers: paidParts ? { ...triggers, crons: [...new Set([...(triggers.crons ?? []), '*/5 * * * *'])] } : triggers } : {}),
-    assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: true },
+    triggers: { crons: [...new Set([...(triggers?.crons ?? []), ...(paidParts ? ['*/5 * * * *','17 * * * *'] : []), ...(analytics ? ['17 * * * *'] : [])])] },
+    assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: workerRoutes },
+    ...(analytics ? {analytics_engine_datasets:[{binding:'STUDIO_ANALYTICS',dataset:`${worker.replace(/-/g,'_')}_visits`}],analytics:{binding:'ANALYTICS_SQL'}} : {}),
+    queues:{producers:[{binding:'BACKGROUND',queue:backgroundQueues(worker).work},{binding:'BACKGROUND_DLQ',queue:backgroundQueues(worker).dead}],consumers:[{queue:backgroundQueues(worker).work,max_batch_size:100,max_batch_timeout:1,max_retries:5,dead_letter_queue:backgroundQueues(worker).dead}]},
     durable_objects: { bindings: rooms },
-    migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }, { tag: 'v2-gates', new_sqlite_classes: ['Gate', 'Concentrator'] }],
+    migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }, { tag: 'v2-gates', new_sqlite_classes: ['Gate', 'Concentrator'] }, {tag:'v3-streams',new_sqlite_classes:['AppRecordHub','EventHub']}],
     d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: at.migrations }],
     ...(r2 ? { r2_buckets: [{ binding: 'MEDIA', bucket_name: r2 }, ...(paidParts ? [{ binding: 'PURCHASE_MEDIA', bucket_name: `${r2.slice(0, 52)}-purchases` }] : [])] } : {}),
     // Workers AI, only when a server's AI guides think with it (agents_brain workers-ai; deploy adds it, 0.17.0).
     // Never in Previews: they do not inherit it, so a Preview's guides answer from the game's script.
     ...(ai ? { ai: { binding: 'AI' } } : {}),
-    vars: { STUDIO_NAME: name, ...(eventFeeds&&Object.keys(eventFeeds).length?{STUDIO_EVENT_FEEDS:JSON.stringify(eventFeeds)}:{}) },
+    vars: { STUDIO_NAME: name, ...(analytics ? {STUDIO_ANALYTICS_DATASET: `${worker.replace(/-/g,'_')}_visits`} : {}), ...(eventFeeds&&Object.keys(eventFeeds).length?{STUDIO_EVENT_FEEDS:JSON.stringify(eventFeeds)}:{}) },
     observability: { enabled: true },
-    previews: { vars: { STUDIO_NAME: name, HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
+    previews: { vars: { STUDIO_NAME: name, ...(analytics ? {STUDIO_ANALYTICS_DATASET: `${worker.replace(/-/g,'_')}_visits`} : {}), HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
   };
   return `// This studio's site on its own Cloudflare account (written by homie-studio). Everything here runs on
 // the studio's Cloudflare Workers account. \`npm run deploy\` (on this computer, or in Workers Builds) puts it live;
@@ -147,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\`,
@@ -833,6 +840,9 @@ export { default, Table, Lobby, Gate, Concentrator } from '@homie-rocks/studio/w
     [`site/migrations/${OPERATIONAL_MIGRATION_FILE}`]: OPERATIONAL_MIGRATION,
     [`site/migrations/${CACHE_MIGRATION_FILE}`]: CACHE_MIGRATION,
     [`site/migrations/${TOOL_NAMESPACE_MIGRATION_FILE}`]: TOOL_NAMESPACE_MIGRATION,
+    [`site/migrations/${ANALYTICS_MIGRATION_FILE}`]: ANALYTICS_MIGRATION,
+    [`site/migrations/${RUNTIME_INDEX_MIGRATION_FILE}`]: RUNTIME_INDEX_MIGRATION,
+    ...Object.fromEntries(Object.entries(EXTRA_RUNTIME_MIGRATIONS).sort(([a],[b])=>a.localeCompare(b)).map(([name,sql])=>[`site/migrations/${name}`,sql])),
     [`site/migrations/${BOOKING_HOLDS_MIGRATION_FILE}`]: BOOKING_HOLDS_MIGRATION,
     [`site/migrations/${APP_LIVE_MIGRATION_FILE}`]: APP_LIVE_MIGRATION,
     [`site/migrations/${TOOL_DATABASE_MIGRATION_FILE}`]: TOOL_DATABASE_MIGRATION,
@@ -1095,8 +1105,18 @@ function ensureOperational(root) {
  if(existsSync(file))return null;
  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,OPERATIONAL_MIGRATION);return `site/migrations/${OPERATIONAL_MIGRATION_FILE}`;
 }
+function ensureRuntimeIndexes(root) {
+ const file=join(root,'site','migrations',RUNTIME_INDEX_MIGRATION_FILE);
+ if(existsSync(file))return null;
+ mkdirSync(dirname(file),{recursive:true});writeFileSync(file,RUNTIME_INDEX_MIGRATION);return `site/migrations/${RUNTIME_INDEX_MIGRATION_FILE}`;
+}
+function ensureAnalytics(root) {
+ const file=join(root,'site','migrations',ANALYTICS_MIGRATION_FILE);
+ if(existsSync(file))return null;
+ mkdirSync(dirname(file),{recursive:true});writeFileSync(file,ANALYTICS_MIGRATION);return `site/migrations/${ANALYTICS_MIGRATION_FILE}`;
+}
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root), ensureFunctionRuns(root), ensureToolDatabase(root), ensureBookings(root), ensureSubscriptions(root), ensureAppLive(root), ensureBusinessEvents(root), ensureBookingHolds(root),ensureBookingResources(root),ensureOperational(root),ensureCache(root),ensureToolNamespaces(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root), ensureFunctionRuns(root), ensureToolDatabase(root), ensureBookings(root), ensureSubscriptions(root), ensureAppLive(root), ensureBusinessEvents(root), ensureBookingHolds(root),ensureBookingResources(root),ensureOperational(root),ensureCache(root),ensureToolNamespaces(root),ensureRuntimeIndexes(root),...Object.entries(EXTRA_RUNTIME_MIGRATIONS).sort(([a],[b])=>a.localeCompare(b)).map(([name,sql])=>{const file=join(root,'site','migrations',name);if(existsSync(file))return null;mkdirSync(dirname(file),{recursive:true});writeFileSync(file,sql);return `site/migrations/${name}`;}),ensureAnalytics(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

@@ -50,6 +50,8 @@ export const HOOK_EVENTS = Object.freeze([
 ]);
 /** The restricted key's permissions, as Stripe's key page names them. Nothing else. */
 export const KEY_PERMISSIONS = Object.freeze([
+  ['Products', 'Read', 'read expanded products on checkout and subscription lines'],
+  ['Prices', 'Read', 'read prices on checkout and subscription lines'],
   ['Checkout Sessions', 'Write', 'open Stripe\'s checkout page for one item'],
   ['Charges', 'Write', 'refunds (Stripe keeps refunds under Charges)'],
   ['PaymentIntents', 'Write', 'verify, create and cancel machine payments as well as read purchase receipts'],
@@ -70,6 +72,11 @@ export const SHOP_HOOK_EVENTS = Object.freeze([
 ]);
 /** The restricted key's permissions, as Stripe's key page names them. Nothing else. */
 export const SHOP_KEY_PERMISSIONS = Object.freeze([
+  ['Subscriptions', 'Read', 'verify current subscription items and paid periods'],
+  ['Invoices', 'Read', 'verify subscription renewal payments'],
+  ['Customer portal', 'Write', 'let shop buyers manage their subscription'],
+  ['Products', 'Read', 'read expanded products on checkout and subscription lines'],
+  ['Prices', 'Read', 'read prices on checkout and subscription lines'],
   ['Checkout Sessions', 'Write', 'open Stripe\'s checkout page for one item'],
   ['Charges', 'Write', 'refunds (Stripe keeps refunds under Charges)'],
   ['PaymentIntents', 'Read', 'which payment an order was'],

package/lib/static-assets.mjs

@@ -0,0 +1,27 @@
+/** Assets matching a protected namespace must pass through runtime authorization. */
+export const WORKER_ROUTES = [
+  '/', '/index.html', '/api/*', '/_studio/*', '/mcp', '/mcp/*', '/oauth/*', '/hooks/*',
+  '/.well-known/*', '/_site/*', '/parts/*', '/games/*', '/account', '/account/*',
+  '/shop', '/shop/*', '/lounge', '/lounge/*', '/_homie/*', '/media/*',
+  '/robots.txt', '/sitemap.xml', '/llms.txt', '/llms-full.txt',
+];
+export function staticWorkerRoutes(catalogue) {
+  if (catalogue?.studio?.concept === true) return true;
+  return [...WORKER_ROUTES, ...(catalogue?.games ?? []).flatMap(game =>
+    [`/${game.id}`, `/${game.id}/*`, ...(game.kind === 'app' ? [] : [`!/games/${game.id}/assets/*`, `!/games/${game.id}/_landing/*`])])];
+}
+/** Keep the owner's header rules last. Worker responses attach their own headers. */
+export function staticHeaders(custom = '', {concept = false} = {}) {
+  custom = custom.replace(/# BEGIN HOMIE HEADERS[\s\S]*?# END HOMIE HEADERS\n?/g, '');
+  return `# BEGIN HOMIE HEADERS
+# Studio defaults: public static assets are served without a Worker invocation.
+/*
+  Cache-Control: public, max-age=0, must-revalidate, no-transform
+  X-Frame-Options: DENY${concept ? "\n  X-Robots-Tag: noindex, nofollow" : ""}
+/games/*
+  ! X-Frame-Options
+/parts/*
+  ! X-Frame-Options
+# END HOMIE HEADERS
+${custom}`;
+}

package/lib/template-history.json

@@ -4005,6 +4005,93 @@
      }
     }
    }
+  },
+  "0.55.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)": [
+      "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"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/worker-build.mjs

@@ -1,3 +1,4 @@
+import {staticWorkerRoutes} from './static-assets.mjs';
 import {createHash} from 'node:crypto';
 import {refreshWorkerConfig} from './worker-config.mjs';
 import {pathToFileURL} from 'node:url';
@@ -7,7 +8,7 @@ import {readConfig} from './routes.mjs';
 import {PACKAGE_ROOT,workerDir} from './studio.mjs';
 import {paidReleases} from './parts-upload.mjs';
 /** Preserve dynamic imports as real Worker modules: page startup never evaluates MCP libraries. */
-export async function buildWorker(root,esbuild) {
+export async function buildWorker(root,esbuild,metadata=null) {
   const source=join(root,'site/src/worker.mjs');if(!existsSync(source))return;
   const out=join(root,'site/src/runtime');
 
@@ -17,8 +18,19 @@ export async function buildWorker(root,esbuild) {
   if(paidReleases(root).length || existsSync(join(root,'shop.json')) || pricedTools)alias['@homie-rocks/studio/worker']='@homie-rocks/studio/worker/selling';
   // Older studio entries export only Table and Lobby. Supply the new toolkit-owned
   // classes in the generated bundle without rewriting the studio's source/customizations.
-  const contents=`export * from ${JSON.stringify(source)};\nexport { default } from ${JSON.stringify(source)};\nexport { Gate, Concentrator } from ${JSON.stringify(join(PACKAGE_ROOT,'worker/gate.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'});
+  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`:'';
+  // 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.
+    // Standard generated rooms use lazy exports at that barrel as well; a studio
+    // with custom subclasses retains the original class constructors.
+    if(standardRooms)build.onLoad({filter:/[/\\]worker[/\\]index\.mjs$/},({path})=>path===join(PACKAGE_ROOT,'worker/index.mjs')?{contents:readFileSync(path,'utf8').replace("export {Table} from './table.mjs';","export {Table} from './lazy-objects.mjs';").replace("export {Lobby} from './lobby.mjs';","export {Lobby} from './lazy-objects.mjs';").replace("export { Gate, Concentrator } from './gate.mjs';","export { Gate, Concentrator } from './lazy-objects.mjs';").replace("export {AppRecordHub, EventHub} from './stream-objects.mjs';","export {AppRecordHub, EventHub} from './lazy-objects.mjs';"),loader:'js'}:undefined);
+  }}]});
   // A watcher may already have read the previous entry while this build is
   // publishing. Keep its entire graph available. Publish immutable modules first,
   // then switch the single entry atomically; never remove a running graph.
@@ -41,7 +53,7 @@ export async function buildWorker(root,esbuild) {
   }
   // Wrangler's module root is the immutable generation, so old generations are
   // retained locally for in-flight reloads but are never added to a deployment.
-  refreshWorkerConfig(root);
+  refreshWorkerConfig(root, metadata ? {workerRoutes: staticWorkerRoutes(metadata.catalogue)} : {});
   const current=join(out,'current.json'), pending=`${current}.${process.pid}.tmp`;
   writeFileSync(pending,JSON.stringify({main:join(dir,'worker.js')})+'\n');renameSync(pending,current);
   // Dev sometimes watches a copy with routes/remote AI removed. Publish its

package/lib/worker-config.mjs

@@ -1,3 +1,4 @@
+import {staticWorkerRoutes} from './static-assets.mjs';
 import {verifiedMcpConfig,publicMcpSetup} from './shop-mcp.mjs';
 import {readFileSync,writeFileSync,existsSync,renameSync} from 'node:fs';
 import {join} from 'node:path';
@@ -27,6 +28,14 @@ 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);
   if(publicMcpSetup(root)) {
@@ -48,5 +57,5 @@ export function refreshWorkerConfig(root,overrides={}) {
   const tools=read(join(root,'site/src/tools/declarations.json'));
   const ai=cf.ai??listExperiences(root).some(g=>g.decide===true || g.chat!==false && (g.chat?.mode??'text')==='text' && g.chat?.ai!==false);
   const paid=paidReleases(root).length>0||existsSync(join(root,'shop.json'))||tools.paid===true;
-  updateWorkerConfig(root,wranglerConfig({worker:cf.worker,name:studio.name,d1:cf.d1,d1Id:cf.d1Id,r2:cf.r2,layout:layoutOf(root),ai,paidParts:paid,partsRateLimit:cf.purchaseRateLimit??null,routes:cf.routes??null,eventFeeds:studio.mcp?.events,triggers:{crons:[scheduleTrigger(functions,{eventFeeds:Object.keys(studio.mcp?.events??{}).length>0})].filter(Boolean)},...overrides}));
+  updateWorkerConfig(root,wranglerConfig({analytics:studio.stats?.analytics===true,workerRoutes:staticWorkerRoutes(read(join(root,'site/dist/games.json'))),worker:cf.worker,name:studio.name,d1:cf.d1,d1Id:cf.d1Id,r2:cf.r2,layout:layoutOf(root),ai,paidParts:paid,partsRateLimit:cf.purchaseRateLimit??null,routes:cf.routes??null,eventFeeds:studio.mcp?.events,triggers:{crons:[scheduleTrigger(functions,{eventFeeds:Object.keys(studio.mcp?.events??{}).length>0})].filter(Boolean)},...overrides}));
 }

package/netplay/NETPLAY.md

@@ -1591,7 +1591,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.54.0",
+  "version": "0.56.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; },