@homie-rocks/studio 0.55.0 → 0.56.0

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.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; },

package/rules/host.ts

@@ -87,6 +87,8 @@ export interface HostOptions {
   restoreEpoch?: number;
   startDelayMs?: number;
   onTick?(): void;
+  /** Suspend settled round breaks; the owner persists and wakes this deadline. */
+  onRoundIdle?(until: number): void;
   /** Only the shared server isolate can attribute timer lateness to another tick. */
   enforceOverrun?: boolean;
   log?(line: Record<string, unknown>): void;
@@ -111,6 +113,8 @@ export interface Host {
   readonly epoch: number;
   readonly running: boolean;
   readonly paused: boolean;
+  readonly roundIdleUntil: number | null;
+  wakeRound(): void;
   readonly people: number;
   readonly viewRadiusM: number | null;
   readonly privateDelivery: boolean;
@@ -199,13 +203,14 @@ export function createHost(o: HostOptions): Host {
   // A log that throws takes nothing down with it.
   const log = (line: Record<string, unknown>): void => { try { o.log?.(line); } catch { /* nothing to say it with */ } };
   const random = o.random ?? Math.random;
-  const saved = o.restore ? fromBytes(o.restore) as { v: number; characters?: CharacterLease[]; core: SavedCore; names: [number, string][]; agents?: AgentsSaved; guideViews?: [number, { id: string; at: number; value: Record<string, unknown> }][]; queues: [number, Record<string, unknown>, StepInput['claim'], number, number][]; inputs?: [number, SeatIn][] } : null;
+  const saved = o.restore ? fromBytes(o.restore) as { v: number; roundIdleUntil?: number; characters?: CharacterLease[]; core: SavedCore; names: [number, string][]; agents?: AgentsSaved; guideViews?: [number, { id: string; at: number; value: Record<string, unknown> }][]; queues: [number, Record<string, unknown>, StepInput['claim'], number, number][]; inputs?: [number, SeatIn][] } : null;
   if (o.restore && (!saved || typeof saved !== 'object' || Array.isArray(saved))) throw new Error('saved host is not an object');
   if (saved) {
     const check = (ok: unknown): void => { if (!ok) throw new Error('saved host inputs are invalid'); };
     const uint = (n: unknown): boolean => Number.isSafeInteger(n) && (n as number) >= 0;
-    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs', 'characters'].includes(k)));
+    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs', 'characters', 'roundIdleUntil'].includes(k)));
     check(saved.core && Array.isArray(saved.names) && Array.isArray(saved.queues));
+    if (saved.roundIdleUntil !== undefined) check(Number.isFinite(saved.roundIdleUntil) && saved.roundIdleUntil >= 0 && saved.core.round[1] === 0 && !saved.core.overAt);
     if (saved.characters !== undefined) {
       check(c.settings.characters && Array.isArray(saved.characters));
       check(new Set(saved.characters.map(c => c.account)).size === saved.characters.length);
@@ -396,6 +401,7 @@ export function createHost(o: HostOptions): Host {
       core.goal(b.seat, g?.state === 'active' ? { goal: g.goal, args: g.args, from: g.from, at: Math.round(g.at / period), asked: g.asked === true } : null);
     }
   }
+  let roundIdleUntil: number | null = o.onRoundIdle && Number.isFinite(saved?.roundIdleUntil) ? saved!.roundIdleUntil! : null;
   let running = false;
   let paused = Boolean(saved && (o.startPaused ?? o.restoreEpoch !== undefined));
   let ended = false;
@@ -594,7 +600,7 @@ export function createHost(o: HostOptions): Host {
           core.seatLeave(held.seat);
           tick(o.clock.now());
         } else core.seatAway(m.seat as number, true);
-        if (running && people() === 0) pause();
+        if ((running || roundIdleUntil !== null) && people() === 0) pause();
         return;
       }
       case 'free': {
@@ -832,7 +838,17 @@ export function createHost(o: HostOptions): Host {
     }
     timing.record('tick', tickAt);
     if (ended) return;
-    if (!faulted && core.stats.ticksCut === cut) { failingSince = null; return; }
+    if (!faulted && core.stats.ticksCut === cut) {
+      failingSince = null;
+      const round = core.round();
+      if (o.onRoundIdle && running && round.phase === 'over' && round.results && round.endsAt > core.tick) {
+        roundIdleUntil = now + (round.endsAt - core.tick) * period;
+        running = false; disarm();
+        try { o.store?.save(save()); o.onRoundIdle(roundIdleUntil); }
+        catch (error) { fault('round-idle', error); stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); }
+      }
+      return;
+    }
     if (failingSince === null) failingSince = now;
     if (now - failingSince < FAIL_MS) return;
     if (faulted) end('fault', { error: stats.lastFault, faults: stats.faults });
@@ -913,7 +929,7 @@ export function createHost(o: HostOptions): Host {
   const self = { blame: (): void => { blamed = true; } };
 
   function start(): void {
-    if (running || ended) return;
+    if (running || ended || roundIdleUntil !== null) return;
     running = true; paused = false;
     try {
       base = { ms: o.clock.now() + (firstTick ? o.startDelayMs ?? 0 : 0), tick: core.tick };
@@ -926,26 +942,37 @@ export function createHost(o: HostOptions): Host {
     } catch (error) { fault('start', error); } finally { keepTime(); }
   }
   function pause(): void {
-    if (!running) return;
+    if (!running) {
+      if (roundIdleUntil !== null && !paused) { paused = true; checkpoint(true); o.onPause?.(); }
+      return;
+    }
     running = false; paused = true;
     // A pending timer would keep the object in memory and billed: the pause clears it.
     disarm();
     log({ ev: 'host-pause', game: o.game, tick: core.tick });
     try { checkpoint(true); o.onPause?.(); } catch (error) { fault('onPause', error); if (persistent) { stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); } }
   }
-  function resume(): void {
-    if (running || ended || !paused) return;
+  function resume(announceRound = true): void {
+    if (running || ended || !paused || roundIdleUntil !== null) return;
     running = true; paused = false;
     try {
       // The room resumes at the tick it paused on: no tick is skipped and no timer fires for the gap.
       base = { ms: o.clock.now() + (firstTick ? o.startDelayMs ?? 0 : 0), tick: core.tick };
       overSince = null; blamed = false; failingSince = null; lastStart = base.ms;
-      handle([core.round()], base.ms);
+      if (announceRound) handle([core.round()], base.ms);
       for (const q of queues.values()) q.lastFrameTick = core.tick;
       log({ ev: 'host-resume', game: o.game, tick: core.tick });
       o.onResume?.();
     } catch (error) { fault('resume', error); } finally { keepTime(); }
   }
+  function wakeRound(): void {
+    if (roundIdleUntil === null || o.clock.now() < roundIdleUntil || ended) return;
+    if (!core.resumeRound()) throw new Error('Round is not settled');
+    roundIdleUntil = null;
+    handle(core.drain(), o.clock.now());
+    if (people() > 0) { paused = true; resume(false); }
+    else { paused = true; checkpoint(true); }
+  }
   /** What a relay keeps for whoever joins next, said again: the round with its results, the roster, the shared state, the capabilities. */
   function announce(): void {
     if (ended) return;
@@ -975,7 +1002,7 @@ export function createHost(o: HostOptions): Host {
 
   function save(): Uint8Array {
     const reserved = new Set(core.bodies().filter(b => b.owner === 'reserved').map(b => b.seat));
-    return toBytes({ v: 1, ...(characters.size ? { characters: [...characters.values()] } : {}), core: core.save(), guideViews: [...guideViews], ...(agents ? { agents: agents.save() } : savedAgents ? { agents: savedAgents } : {}), names: [...names].filter(([seat]) => !reserved.has(seat)), queues: [...queues].map(([seat, q]) => [seat, q.held, q.claim, q.newest, q.ack]), inputs: [...queues] });
+    return toBytes({ v: 1, ...(roundIdleUntil !== null ? { roundIdleUntil } : {}), ...(characters.size ? { characters: [...characters.values()] } : {}), core: core.save(), guideViews: [...guideViews], ...(agents ? { agents: agents.save() } : savedAgents ? { agents: savedAgents } : {}), names: [...names].filter(([seat]) => !reserved.has(seat)), queues: [...queues].map(([seat, q]) => [seat, q.held, q.claim, q.newest, q.ack]), inputs: [...queues] });
   }
   function checkpoint(force = false): void {
     if (persistent) {
@@ -1022,7 +1049,7 @@ export function createHost(o: HostOptions): Host {
       held.character = core.character(held.seat) ?? held.character; held.returning = true;
       present.delete(held.seat); queues.delete(held.seat); names.delete(held.seat);
       if (held.seat >= 0) core.seatLeave(held.seat); tick(o.clock.now());
-      if (running && people() === 0) pause();
+      if ((running || roundIdleUntil !== null) && people() === 0) pause();
     },
     characterReturned(account, lease) { if (characters.get(account)?.returning && characters.get(account)?.lease === lease) characters.delete(account); },
     get viewSettings() { return c.settings.view; },
@@ -1032,6 +1059,8 @@ export function createHost(o: HostOptions): Host {
     get epoch() { return epoch; },
     get running() { return running; },
     get paused() { return paused; },
+    get roundIdleUntil() { return roundIdleUntil; },
+    wakeRound,
     get people() { return people(); },
     frame, start, pause, resume, announce,
     // An orderly stop of a lasting world folds what moved since the last checkpoint. One that follows a failed write, or arrives during one, writes nothing.

package/rules/view.ts

@@ -941,6 +941,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   net.on('snapshot', onSnapshot);
   net.on('role', (e) => { if (e.snap) onSnapshot(e.snap); if (net.offline && !net.rulesHosting) setStatus(net.closedWhy ? 'closed' : 'offline'); });
   net.on('link', (e) => {
+    if (e.why === 'subscribe') return;
     if (e.state === 'online') { returningUntil = clock() + 3000; base = null; if (status !== 'playing') setStatus('connecting'); } else if (e.state === 'closed') setStatus('closed'); else if (e.state === 'alone' || e.state === 'offline') setStatus('offline');
   });
   net.on('round', (r) => { if (r.results) { results = r.results; if (round) { round = { ...round, results }; emit('round', roundNow()); } } });

package/tools/TOOLS.md

@@ -53,7 +53,12 @@ Workers AI requires the studio's own binding and owner authority, or an explicit
 never exposes the environment or raw credentials. A named secret capability in
 `studio.json` (`mcp.secrets.NAME: { origin, header, prefix, tools }`) lets an owner tool
 make an HTTPS request to one declared origin; `tools` can explicitly delegate this capability to named staff tools; redirects and credential echoes are
-refused. The studio’s AI can generate an integration secret and place it in Cloudflare and the sender through their authorized APIs. Never ask the person to find or paste a key, and never put a secret in source files.
+refused. Use `origin: 'self'` for the studio's own API: the capability resolves to
+ the current Worker request origin (or the configured studio origin for scheduled
+ functions), so a workers.dev address need not be known at build time. Calls may
+ use a relative URL such as `ctx.fetchWithSecret('API_TOKEN', '/api/sync')`.
+ HTTPS is still required; credentials in URLs and cross-origin targets are refused.
+ The studio’s AI can generate an integration secret and place it in Cloudflare and the sender through their authorized APIs. Never ask the person to find or paste a key, and never put a secret in source files.
 
 Studio handlers and imported parts are trusted Worker code, not sandboxed plugins.
 Review shared code before adding it: JavaScript wrappers cannot confine malicious

package/worker/background-queue.mjs

@@ -22,6 +22,7 @@ export async function consumeBackground(batch, env) {
   }
   for(const message of batch.messages)if(!changes.includes(message)) {
     try {
+      if(message.body?.v===1&&message.body.type==='lobby.snapshot'){await (await import('./lobby-summary.mjs')).storeLobbySummary(env,message.body);message.ack();continue;}
       if(message.body?.v!==1||message.body.type!=='stripe.event')throw new Error('Unknown background message type');
       await (await import('./stripe-intake.mjs')).reconcileStripeEvent(env,message.body.id,await catalogue(env));
       message.ack();

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.55.0","sha256":"597d65592bde7e9519b8184bc2db2502a88ef37cfc31dd6ba3b1c9a4ece30132"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.56.0","sha256":"9b000afecb22ce5781d6499a02f44ffcc255c61907e9f7d469dd63d0bd9f35d1"});

package/worker/custom-routes.mjs

@@ -0,0 +1,16 @@
+/** Studio configuration only: register once at module evaluation, never per request. */
+let handler = null;
+export function useRoutes(routes) {
+  if (routes !== null && typeof routes !== 'function') throw new TypeError('useRoutes expects a function or null');
+  handler = routes;
+}
+export async function customRoute(request, env, ctx) {
+  const response = await handler?.(request, env, ctx);
+  if (response == null) return null;
+  if (!(response instanceof Response)) throw new TypeError('A custom route must return a Response, null, or undefined');
+  if (response.status === 101 || response.webSocket) return response;
+  const headers = new Headers(response.headers);
+  headers.set('x-content-type-options', 'nosniff');
+  if (!headers.has('referrer-policy')) headers.set('referrer-policy', 'strict-origin-when-cross-origin');
+  return new Response(response.body, {status:response.status,statusText:response.statusText,headers});
+}