@homie-rocks/studio 0.58.0 → 0.58.2

package/worker/app-records.mjs

@@ -19,7 +19,7 @@ CREATE TABLE IF NOT EXISTS app_roles (
   PRIMARY KEY (app, role, player)
 );
 CREATE TABLE IF NOT EXISTS app_role_links (
-  app TEXT NOT NULL, role TEXT NOT NULL, token TEXT NOT NULL,
+  app TEXT NOT NULL, role TEXT NOT NULL, token TEXT NOT NULL, expires_at INTEGER,
   PRIMARY KEY (app, role)
 );
 `;
@@ -35,8 +35,37 @@ async function bodyOf(request) {
   for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
   return JSON.parse(new TextDecoder().decode(bytes) || '{}');
 }
+const ROLE_LINK_YEAR = 366 * 24 * 60 * 60 * 1000;
+const roleLinkReady = new WeakSet();
+/** Old studios have no expires_at. One ALTER per database; a duplicate column is the column already being there. */
+async function ensureRoleLinkExpiry(db) {
+  if (!db || roleLinkReady.has(db)) return true;
+  try {
+    await db.prepare('ALTER TABLE app_role_links ADD COLUMN expires_at INTEGER').run();
+    roleLinkReady.add(db);
+    return true;
+  } catch (error) {
+    if (/duplicate column/i.test(String(error?.message ?? error))) { roleLinkReady.add(db); return true; }
+    return false;
+  }
+}
+async function roleLink(env, app, role) {
+  if (await ensureRoleLinkExpiry(env.DB)) {
+    try { return await env.DB.prepare('SELECT token, expires_at FROM app_role_links WHERE app = ?1 AND role = ?2').bind(app, role).first(); } catch { /* column still absent */ }
+  }
+  const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(app, role).first();
+  return row ? { token: row.token, expires_at: null } : null;
+}
+const linkLive = (row) => !!row && (row.expires_at == null || Number(row.expires_at) > Date.now());
+const linkUrl = (url, meta, role, token) => `${url.origin.replace('127.0.0.1', 'localhost')}/${meta.id}/open?role=${role}&access=${token}`;
+function expiryOf(value) {
+  if (value == null) return null;
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isSafeInteger(n) || n <= Date.now() || n > Date.now() + ROLE_LINK_YEAR) return undefined;
+  return n;
+}
 /** Private links conceal staff addresses; a signed-in grant is still required on every request. */
-export async function appAccess(request, env, meta, url) {
+export async function appAccess(request, env, meta, url, options = {}) {
   const role = appRole(meta, url);
   const declared = Object.hasOwn(meta.roles ?? {}, role) ? meta.roles[role] : null;
   if (!declared) return { ok: false, status: 404, error: 'unknown role' };
@@ -54,8 +83,10 @@ export async function appAccess(request, env, meta, url) {
   }
   const handoff=cookieValues(request,`studio_app_${meta.id}_${role}`)[0];
   if(handoff&&await appAssetTicket(env,meta.id,handoff,{meta,purpose:'handoff',expectedRole:role,launch:launchOf(meta,await settingsOf(env),env)}))return {ok:true,role,can:declared.can};
-  const link = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, role).first();
-  if (!link || link.token !== url.searchParams.get('access')) return { ok: false, status: 404, error: 'private role link required' };
+  // Opening the app: the signed-in studio owner needs no link. hasRole passes owner:false so a custom route still requires that role's own link.
+  if (options.owner !== false && await isOwner(request, env)) return { ok: true, role, can: declared.can };
+  const link = await roleLink(env, meta.id, role);
+  if (!linkLive(link) || link.token !== url.searchParams.get('access')) return { ok: false, status: 404, error: 'private role link required' };
   if (await isOwner(request, env)) return { ok: true, role, can: declared.can };
   const person = await players.of(request, env);
   if (!person || person.guest) return { ok: false, status: 401, error: 'sign in to this studio' };
@@ -72,6 +103,17 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
       if (request.method !== 'POST') return fail(405, 'POST required');
       if (!key && !sameOrigin(request, url)) return fail(403, 'same origin required');
       const b = await bodyOf(request);
+      await ensureRoleLinkExpiry(env.DB);
+      if (b.list === true) {
+        const roles = [];
+        for (const [role, declared] of Object.entries(meta.roles ?? {})) {
+          if (!declared?.signIn) continue;
+          const row = await roleLink(env, meta.id, role);
+          const live = linkLive(row);
+          roles.push({ role, expiresAt: row?.expires_at == null ? null : Number(row.expires_at), link: live ? linkUrl(url, meta, role, row.token) : null });
+        }
+        return json({ ok: true, roles });
+      }
       if (!Object.hasOwn(meta.roles, b.role) || !meta.roles[b.role].signIn) return fail(400, 'name a sign-in role');
       if (b.player !== undefined) {
         if (!ID.test(b.player)) return fail(400, 'invalid account');
@@ -79,11 +121,21 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
         if (!p || p.guest) return fail(400, 'role grants require an existing signed-in account');
         await env.DB.prepare(b.revoke === true ? 'DELETE FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3' : 'INSERT OR IGNORE INTO app_roles (app, role, player) VALUES (?1, ?2, ?3)').bind(b.studio === true ? '*' : meta.id, b.role, b.player).run();
       }
+      if (b.revokeLink === true) {
+        await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
+        return json({ ok: true, role: b.role, revoked: true });
+      }
+      let expires;
+      if (Object.hasOwn(b, 'expires')) {
+        expires = expiryOf(b.expires);
+        if (expires === undefined) return fail(400, 'expiry must be a future time within 366 days');
+      }
       const token = crypto.randomUUID().replaceAll('-', '');
       if (b.rotate === true) await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
       await env.DB.prepare('INSERT OR IGNORE INTO app_role_links (app, role, token) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, token).run();
-      const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).first();
-      return json({ ok: true, link: `${url.origin.replace('127.0.0.1','localhost')}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
+      if (expires !== undefined) await env.DB.prepare('UPDATE app_role_links SET expires_at = ?3 WHERE app = ?1 AND role = ?2').bind(meta.id, b.role, expires).run();
+      const row = await roleLink(env, meta.id, b.role);
+      return json({ ok: true, link: linkUrl(url, meta, b.role, row.token), role: b.role, expiresAt: row.expires_at == null ? null : Number(row.expires_at) });
     }
     const match = /^api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(sub);
     if(!match && /^api\/app\/records\/[^/]+\//.test(sub))return fail(400,'record id: 1–64 letters, digits, underscore or hyphen');

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.58.0","sha256":"c8953383f91877ce12a615ce9c730f7d5fd4859acf285efe5132404ef70c8895"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.58.2","sha256":"5186ba06317a7de1677209dbbba72ee69d4e1cf79a08b46c74e9c20bd92e74a7"});

package/worker/limits.mjs

@@ -20,13 +20,15 @@ export const EV_RATES = Object.freeze({ host: 30, replica: 10, screen: 2 });
 /** The keyed state channel: at most this many keys and bytes per room. */
 export const STATE_CAPS = Object.freeze({ keys: 64, bytes: 65536 });
 /** Runtime output only. Player allowances above remain unchanged. */
-export const RULES_FRAMES = Object.freeze(['snap', 'ckpt', 'state', 'ev', 'round', 'roster', 'decide', 'caps', 'rules-end']);
+export const RULES_FRAMES = Object.freeze(['snap', 'ckpt', 'state', 'ev', 'round', 'roster', 'decide', 'caps', 'rules-end', 'rest']);
 export const rulesRates = (tickHz = 20, seats = 8) => ({
   // A snapshot a tick, as the server sends, and a quarter over for the ticks a late timer runs together.
   snap: Math.max(30, Math.ceil(tickHz * 1.25)), ckpt: 4, state: tickHz + 64,
   ev: Math.ceil((tickHz + seats * EV_RATES.replica + 32) / 0.8), round: 8,
   // A decision a tick is what one declared ask can make (the next waits for the answer), as on a server host.
   roster: seats * 2 + 8, decide: Math.ceil((tickHz + seats * 5 + 8) / 0.8), caps: 4, 'rules-end': 4,
+  // A browser host rests its room and wakes it: at most a few times a second.
+  rest: 4,
 });
 export const rulesCaps = seats => Object.fromEntries(RULES_FRAMES.map(t => [t, capOf(t, seats)]));
 /** Two seconds of headroom absorb timer stalls and transport batching. */

package/worker/room-sessions.mjs

@@ -3,7 +3,7 @@
  */
 // Only protocol identity, admission, controls and round deadlines survive here.
 // World snapshots/checkpoints belong to the existing host/room save, not sessions.
-const fields = new Set(`rawVocab vocab snapAt rates agentsAloneMs voteMs voteCooldownMs autoVoteMs policy level levelBy caps vote lastVoteOpen lastAutoVote lastHumanAt agentsOut officeDirty endedMatch code rules tickHz seatCap maxPlayers maxScreens perIp stallMs silentMs idleMs holdMs forgetMs persistMs gameVer currentVer occSeq seats hostId hostSince lastJoinAt lastRound lastRoster emptySince preferHost seatsDirty persistDirty lastPersistAt bans mutes announcement closedUntil closedWhy openedAt askedMax regate decideTimes defaultChat`.split(' '));
+const fields = new Set(`rawVocab vocab snapAt rates agentsAloneMs voteMs voteCooldownMs autoVoteMs policy level levelBy caps vote lastVoteOpen lastAutoVote lastHumanAt agentsOut officeDirty endedMatch code rules tickHz seatCap maxPlayers maxScreens perIp stallMs silentMs idleMs holdMs forgetMs persistMs gameVer currentVer occSeq seats hostId hostSince lastJoinAt lastRound lastRoster emptySince preferHost seatsDirty persistDirty lastPersistAt bans mutes announcement closedUntil closedWhy openedAt askedMax regate decideTimes defaultChat resting`.split(' '));
 function urlDelta(base, value) {
   const a=new URL(base),b=new URL(value),changes=[];
   for(const key of new Set([...a.searchParams.keys(),...b.searchParams.keys()])) {

package/worker/room.mjs

@@ -154,6 +154,10 @@ export class NetRoom {
      * room forgets everything (`onForget`: it ends the host runtime).
      */
     this.server = null;
+    /** The room's host has rested it (rules/host.ts): nobody is playing, its clock is stopped and it sends nothing. */
+    this.resting = false;
+    /** The Table hears a rest too (its house guides share the object's alarm). Null where nothing is listening. */
+    this.onRest = null;
     this.hosted = new Map();
     this.hostFailed = null;
     this.onForget = null;
@@ -162,7 +166,7 @@ export class NetRoom {
   /* ------------------------------------------------------------ the server as host (revision 10, section 29) */
 
   /** The host runtime of a server-hosted room (`{ frame(m), facts() }`), or null. Seats already here are said as joins. */
-  setServerHost(h) {
+  setServerHost(h, { restored = false } = {}) {
     this.server = h;
     if (h?.rates) this.rates = h.rates;
     this.hostFailed = null;
@@ -175,7 +179,7 @@ export class NetRoom {
     for (const [seat, s] of this.seats) this.hosted.set(seat, s.occ ?? null);
     this.toServer({ t: 'policy', policy: this.policyOut() });
     if (this.rawVocab) this.toServer({ t: 'vocabulary', vocab: this.rawVocab });
-    for (const c of this.live()) if (c.seat !== null && !c.watch) this.joinServer(c);
+    for (const c of this.live()) if (c.seat !== null && !c.watch) this.joinServer(c, restored);
   }
 
   /** The rules could not start: the room refuses joins and says why. It never falls back to a browser by itself. */
@@ -191,9 +195,26 @@ export class NetRoom {
     try { this.server.frame(m); } catch (error) { this.stats.failed = (this.stats.failed ?? 0) + 1; this.log({ ev: 'failed', room: this.code, op: 'host-frame', frame: m.t, error: errorLine(error) }); }
   }
 
-  joinServer(c) {
+  /** `restored`: the same socket, back after the room hibernated (a resting room rests on), not somebody arriving. */
+  joinServer(c, restored = false) {
     this.hosted.set(c.seat, this.seats.get(c.seat)?.occ ?? null);
-    this.toServer({ t: 'join', peer: this.peer(c) });
+    this.toServer({ t: 'join', peer: this.peer(c), ...(c.rest ? { rest: true } : {}), ...(c.hidden ? { hidden: true } : {}), ...(restored ? { restored: true } : {}) });
+  }
+
+  /**
+   * The host (the server's, or a browser host `c`) rested the room or woke it. Everybody hears it, and a page that
+   * arrives meanwhile is told in its welcome; browsers then ping the edge and send nothing until somebody plays. A
+   * browser host's snapshots stop while it rests, so its silence is not a stall.
+   */
+  rest(c, on) {
+    if (on === this.resting) return;
+    this.resting = on;
+    if (c && !on) c.lastSnapAt = this.now();
+    const line = JSON.stringify({ t: 'rest', on });
+    for (const o of this.live()) if (o !== c) this.sendText(o.conn, line);
+    // A browser host rests in the page, so the Table's own `onRest` (the server host) never runs. The guides still
+    // have to stop: their think alarm would wake the object, and the command it sent would wake the room.
+    try { this.onRest?.(on); } catch { /* a listener that throws does not keep the room awake */ }
   }
 
   /** A seat the host runtime knows that is no longer held (its hold ran out, the owner removed its player): its body's seat is given up. */
@@ -220,6 +241,7 @@ export class NetRoom {
       case 'roster': return this.hostRoster(null, m);
       case 'caps': return this.hostCaps(null, m);
       case 'decide': return this.onDecide(null, m, true);
+      case 'rest': return this.rest(null, m.on === true);
       case 'ev': {
         const kind = String(m.k ?? '').slice(0, 64);
         if (SPEECH.test(kind) && (this.policy.speech === 'off' || (this.policy.speech === 'lines' && /^chat/i.test(kind)))) { this.stats.speechDrops += 1; return; }
@@ -535,7 +557,7 @@ export class NetRoom {
   peer(c) {
     // Revision 9: which stay in the seat this is (`occ`), the peer's game revision and what its build can do.
     const occ = c.seat !== null ? this.seats.get(c.seat)?.occ : undefined;
-    return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}), ...(c.badge && !c.agent ? { badge: c.badge } : {}), ...(Number.isInteger(occ) ? { occ } : {}), ...(c.ver ? { ver: c.ver } : {}), ...(c.feat.length ? { feat: [...c.feat] } : {}) };
+    return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}), ...(c.badge && !c.agent ? { badge: c.badge } : {}), ...(Number.isInteger(occ) ? { occ } : {}), ...(c.ver ? { ver: c.ver } : {}), ...(c.feat.length ? { feat: [...c.feat] } : {}), ...(c.rest ? { rest: true } : {}) };
   }
   /** A hands-`host` agent (section 17): no game client of its own, so no snapshots, checkpoints or state. */
   lite(c) { return Boolean(c.agent && c.agent.hands === 'host'); }
@@ -809,11 +831,22 @@ export class NetRoom {
         const wasHidden = c.hidden;
         c.hidden = m.hid === true;
         this.send(c, { t: 'pong', c: m.c, st: now });
+        // The server's host rests a room whose pages are all in the background, and wakes it when one comes back.
+        if (c.seat !== null && c.hidden !== Boolean(wasHidden)) {
+          if (this.server) this.toServer({ t: 'hidden', seat: c.seat, on: c.hidden });
+          else if (this.rules && this.host()?.rules && this.host() !== c) this.send(this.host(), { t: 'hidden', seat: c.seat, on: c.hidden });
+        }
         if(this.server && (!c.probe || now-c.probe.at>10000)){c.probe={n:crypto.randomUUID(),at:now};this.send(c,{t:'probe',n:c.probe.n});}
-        // A host whose tab went to the background will stop ticking: hand the round on now.
+        // A host whose tab went to the background will stop running: hand the round on now. A rest goes with
+        // the checkpoint, so the next host stays asleep until somebody plays.
         if (c.id === this.hostId && c.hidden && !wasHidden) this.yieldHost(c, 'host-hidden');
         return;
       }
+      case 'rest': {
+        // A browser host rested its room, or woke it (rules/host.ts, run in the page).
+        if (!this.server && this.rules && c.rules && c.id === this.hostId) this.rest(c, m.on === true);
+        return;
+      }
       case 'yield': {
         if (c.id === this.hostId && this.rules && c.rules && m.slow === true) {
           c.rulesSpeed = Math.max(0, Math.min(1, Number(m.speed) || 0));
@@ -918,6 +951,9 @@ export class NetRoom {
     if (this.perIp && c.ip && live.filter((o) => o.ip === c.ip).length >= this.perIp) return refuse('too-many', `at most ${this.perIp} sockets per address in one room`);
     if (live.length >= this.maxPlayers + this.maxScreens) return refuse('room-full', 'this room is full; try another');
     c.rules = m.rules === true;
+    // A browser that understands a resting room (rules/host.ts): only a room of them rests.
+    // A rules browser, or an agent, that says it understands resting. An older socket keeps its own pings, and the bill.
+    c.rest = m.rest === 1 && (c.rules || Boolean(c.agent));
     c.device = m.device === 'phone' || m.device === 'tv' ? m.device : 'desk';
     // A watcher is a screen that never takes a seat, whatever else its hello says. An agent always plays.
     c.watch = watching;
@@ -971,6 +1007,11 @@ export class NetRoom {
     let role = c.seat === null ? 'screen' : 'replica';
     let why = 'joined';
     let deposed = null;
+    // An edge ping is answered without a message, so lastSeen lags it between ticks. A fresh ping is the host still here.
+    for (const o of live) {
+      const ping = o.conn.lastPing?.() ?? 0;
+      if (ping > 0) o.lastSeen = Math.max(o.lastSeen, ping);
+    }
     const h = this.host();
     const preferred = this.preferHost && now < this.preferHost.until ? this.preferHost.seat : undefined;
     // A watcher hosts only a room nobody else can host (a player who can is elected first), and never deposes one;
@@ -995,6 +1036,8 @@ export class NetRoom {
       }
     }
     if (role === 'host') {
+      // A rest with no rest checkpoint would leave this host running and everyone else holding their clock.
+      if (this.resting && !this.restSaved(this.lastCkpt)) this.rest(null, false);
       // Welcome contains the current holders; old occupancy notices must precede it.
       this.hosted = new Map([...this.seats].map(([seat, s]) => [seat, s.occ ?? null]));
       this.hostId = c.id;
@@ -1009,7 +1052,7 @@ export class NetRoom {
     const behind = !lite && this.currentVer !== undefined && c.ver !== this.currentVer;
     if (behind) c.staleTold = true;
     this.send(c, {
-      t: 'welcome', v: NET_VERSION, rev: NET_REVISION, ...(c.conn.idlePing ? {idlePing:true} : {}), id: c.id, room: this.code, seat: c.seat, token: c.token, name: c.name, colour: c.colour,
+      t: 'welcome', v: NET_VERSION, rev: NET_REVISION, ...(c.conn.idlePing ? {idlePing:true} : {}), ...(this.resting ? { rest: true } : {}), id: c.id, room: this.code, seat: c.seat, token: c.token, name: c.name, colour: c.colour,
       ...(this.gameVer ? { ver: this.gameVer } : {}), ...(behind ? { stale: { ver: this.currentVer } } : {}), stall: this.stallMs,
       role, why, host: this.hostRef(), peers: this.peers(), ...(this.rules ? { held: this.heldPeers() } : {}), st: now, max: this.maxPlayers,
       round: this.lastRound, roster: this.lastRoster, snap: lite ? null : this.playerSnapshot(c, this.lastSnap, true), state: lite ? {} : this.stateObject(),
@@ -1322,6 +1365,15 @@ export class NetRoom {
       Math.min(candidate.rulesSpeed ?? 1, candidate.readySpeed ?? 0) > (current?.rulesSpeed ?? 0) * 1.5 + 0.1;
   }
 
+  /** The checkpoint a browser host sent while resting: its save says `rest.on`. */
+  restSaved(ckpt) {
+    const d = ckpt?.d;
+    if (!d || typeof d !== 'object') return false;
+    const data = d.data && typeof d.data === 'object' ? d.data : d;
+    const rest = data.rest;
+    return Boolean(rest && typeof rest === 'object' && rest.on === true);
+  }
+
   /**
    * Choose a host. Visible and responsive first; then tenure in 30 s steps (a newcomer cannot jump the queue by
    * calling itself a desktop); then desk > tv > phone as a tie-break; then whoever came first. The chosen browser
@@ -1357,6 +1409,9 @@ export class NetRoom {
     // What the room's game reads (the dial, agent bodies) is what its new host's build says.
     this.caps = new Set(next.caps);
     next.lastSnapAt = 0;
+    // A rest stays with the room when the checkpoint the new host restores is that rest: it stays asleep.
+    // With no such save the new host would run while everyone else still holds their clock, so the rest ends.
+    if (this.resting && !this.restSaved(this.lastCkpt)) this.rest(null, false);
     this.stats.promotions += 1;
     this.stats.elections.push({ at: now, id: next.id, seat: next.seat, why });
     if (this.stats.elections.length > 32) this.stats.elections.shift();
@@ -1390,9 +1445,9 @@ export class NetRoom {
       // A loopback (the Table's own house agent) cannot be half-open: it is never closed for silence.
       if (now - c.lastSeen > this.idleMs && !c.conn.loopback) this.kick(c, 'silent', 4000);
     }
-    // A host that stopped sending snapshots while others are present.
+    // A host that stopped sending snapshots while others are present. A resting host sends none on purpose.
     const h = this.host();
-    if (!idle && h && this.live().length > 1) {
+    if (!idle && !this.resting && h && this.live().length > 1) {
       const since = Math.max(h.lastSnapAt, this.hostSince, this.lastJoinAt);
       if (now - since > this.stallMs) {
         const next = this.elect(h.id, 'host-stalled');

package/worker/route-auth.mjs

@@ -13,7 +13,7 @@ export async function hasRole(request, env, app, role) {
   const launch = launchOf(meta, await settingsOf(env, {fresh:true}), env);
   if (launch !== 'public' && !(await accessOf(request, env, app, launch)).ok) return false;
   url.searchParams.set('role', role);
-  return (await (await import('./app-records.mjs')).appAccess(request, env, meta, url)).ok === true;
+  return (await (await import('./app-records.mjs')).appAccess(request, env, meta, url, { owner: false })).ok === true;
 }
 
 /** Return a refusal response, or null when the browser supplied same-origin evidence. */

package/worker/table.mjs

@@ -71,6 +71,8 @@ export class Table {
     this.gateHeld = new Map();
     this.gatePromised = new Map();
     this.roomAlarmAt = 0;
+    /** The alarm a house guide asked for. A rest replaces it with the room's own deadline, or the guide would wake the object every few seconds. */
+    this.guideAlarmAt = 0;
     this.durable = null;
     this.roomSave = null;
     this.endedRoom = null;
@@ -175,6 +177,8 @@ export class Table {
     this.room.onUnsaid = (ids) => this.keptQueue(() => forgetLines(this.env, this.game, this.code, ids));
     // A game's own decisions (section 20): the host's typed questions, for a game whose game.json opts in.
     this.room.decider = (state, questions, opts) => this.decide(state, questions, opts);
+    // Server and browser hosts both rest through the relay. Guides stop here, including when the host is a page.
+    this.room.onRest = (on) => { this.house?.rest(on); };
     // A server-hosted room that forgets everything (nobody came back, or the owner closed it) ends its host runtime.
     this.room.onForget = () => { if (this.hostRt) this.finishRoom('forgotten'); };
     if (this.isPersistent()) this.room.forgetMs = Infinity;
@@ -216,7 +220,9 @@ export class Table {
       // A restore's provisional pause is not a recorded departure. A stored alarm,
       // even one now due, has not yet confirmed expiry. The alarm handler owns that decision.
       const restorePause = saved?.pauseFromRestore === true && Date.now() >= saved.pausedAt + ROOM_PAUSE_MS && this.recoveredAlarmAt !== null ? null : saved?.pausedAt;
-      const restoredEnd = saved ? roomEndAt({ people: 0, pausedAt: restorePause, restoredAt: Date.now(), savedAt: saved.at, alarmAt: this.recoveredAlarmAt }) : Infinity;
+      // A resting room was saved with its people still here, and hibernated on purpose: its age is no absence.
+      const rested = saved?.resting === true && saved.pausedAt === null;
+      const restoredEnd = saved ? roomEndAt({ people: 0, pausedAt: restorePause, restoredAt: Date.now(), savedAt: saved.at, alarmAt: rested ? Date.now() : this.recoveredAlarmAt }) : Infinity;
       const expired = Date.now() >= restoredEnd;
       if (saved && persistent && saved.stateHash !== build.stateHash) throw new Error('This lasting world needs its previous state schema. Restore the compatible build; the saved world has been retained.');
       if (saved && !persistent && (saved.stateHash !== build.stateHash || boot.count >= 2 || expired)) {
@@ -234,14 +240,21 @@ export class Table {
         // The seat map and the world came from one transaction. No unrelated net write can take a body from its token.
         room.seats.clear(); room.state.clear(); room.stateBytes = 0;
         room.restore({ ...saved.net, savedAt: Date.now(), durable: true });
-        this.pausedAt = persistent ? Date.now() : restoredEnd - ROOM_PAUSE_MS;
-        this.pauseFromRestore = saved.pauseFromRestore = saved.pausedAt === null || saved.pauseFromRestore === true;
-        saved.pausedAt = this.pausedAt;
-        // A failed pause write must never be mistaken for an invalid host save.
-        try { this.durable.write(saved); } catch (error) { if (persistent) throw error; pauseWriteFailed = true; this.storageProblem(error); }
+        if (rested) {
+          // Rebuilt after hibernating on purpose: this save is exactly the world every browser holds. It comes back under
+          // the same epoch, so the input that wakes it applies, and nothing is written (the room wakes about once a minute).
+          this.pausedAt = null; this.pauseFromRestore = false;
+        } else {
+          this.pausedAt = persistent ? Date.now() : restoredEnd - ROOM_PAUSE_MS;
+          this.pauseFromRestore = saved.pauseFromRestore = saved.pausedAt === null || saved.pauseFromRestore === true;
+          saved.pausedAt = this.pausedAt;
+          // A failed pause write must never be mistaken for an invalid host save.
+          try { this.durable.write(saved); } catch (error) { if (persistent) throw error; pauseWriteFailed = true; this.storageProblem(error); }
+        }
       }
-      const epoch = saved ? Math.max(saved.host.core.epoch, boot.epoch) + 1 : undefined;
-      if (saved) this.durable.boot({ epoch, count: boot.count });
+      // A rested save is replayed under its own epoch; any other restore (a crash, a deploy) takes a new one.
+      const epoch = saved ? (rested ? saved.host.core.epoch : Math.max(saved.host.core.epoch, boot.epoch) + 1) : undefined;
+      if (saved && !rested) this.durable.boot({ epoch, count: boot.count });
       this.hostCreatedAt = Date.now();
       let ticks = 0;
       this.hostRt = startHost(this.game, {
@@ -257,8 +270,17 @@ export class Table {
         // Alarm-driven suspension requires the native hibernation lifecycle.
         // Legacy adapters keep their host clock, as browser hosts do.
         ...(this.ctx.acceptWebSocket ? { onRoundIdle: until => { room.tellWatchers(); this.report(); this.recordRound(); this.armRoom(until); this.ctx.waitUntil(this.sleepRoom()); } } : {}),
+        // A room nobody is playing rests with its people connected (rules/host.ts), and hibernates like a round break.
+        // A deliberate rest is a clean stop: the restore-loop count starts again, so waking it is never a crash.
+        ...(this.ctx.acceptWebSocket && this.ctx.storage.sql ? { onRest: on => {
+          // Guides stop with the room: a think alarm would wake the object, and the command it sent would wake the sim.
+          this.house?.rest(on);
+          if (!on) { this.armRoom(Date.now() + ROOM_ALARM_MS); this.start(); return; }
+          try { this.durable?.boot({ epoch: this.hostRt?.epoch ?? epoch, count: 0 }); this.pendingBoot = null; } catch (error) { this.storageProblem(error); }
+          room.tellWatchers(); this.report(); this.ctx.waitUntil(this.sleepRoom());
+        } } : {}),
         onTick: () => {
-          if (!saved) return;
+          if (!saved || rested) return;
           ticks += 1;
           if (ticks === 1) this.pendingBoot = { epoch, count: saved.buildHash !== build.build ? 0 : boot.count + 1 };
           if (ticks === 10 * build.settings.tickHz) this.pendingBoot = { epoch, count: 0 };
@@ -315,7 +337,7 @@ export class Table {
         const tokens = new Set((net.seats ?? []).map(seat => seat[1]));
         for (const [account, token] of Object.entries(this.accountTokens)) if (!tokens.has(token)) delete this.accountTokens[account];
       }
-      const saved = { ...(build.settings.characters ? { accountTokens: { ...this.accountTokens } } : {}), v: 1, game: this.game, room: this.code, at: now, pauseFromRestore: this.hostRt?.paused === true && this.pauseFromRestore === true, pausedAt: this.hostRt?.paused ? this.pausedAt ?? now : null, stateHash: build.stateHash, buildHash: build.build, host, net };
+      const saved = { ...(build.settings.characters ? { accountTokens: { ...this.accountTokens } } : {}), v: 1, game: this.game, room: this.code, at: now, pauseFromRestore: this.hostRt?.paused === true && this.pauseFromRestore === true, pausedAt: this.hostRt?.paused ? this.pausedAt ?? now : null, ...(this.hostRt?.resting ? { resting: true } : {}), stateHash: build.stateHash, buildHash: build.build, host, net };
       const clearing = this.cleanupPending;
       if (clearing) this.durable.clear();
       if (this.isPersistent()) {
@@ -370,7 +392,7 @@ export class Table {
       if (saved.v !== 1 || typeof saved.game !== 'string' || typeof saved.room !== 'string' ||
           this.game && saved.game !== this.game || this.code && saved.room !== this.code ||
           !Number.isFinite(saved.at) || saved.at < 0 || saved.at > Date.now() + 5000 || saved.pausedAt !== null && (!Number.isFinite(saved.pausedAt) || saved.pausedAt < 0 || saved.pausedAt > Date.now() + 5000) ||
-          saved.pauseFromRestore !== undefined && typeof saved.pauseFromRestore !== 'boolean' ||
+          saved.pauseFromRestore !== undefined && typeof saved.pauseFromRestore !== 'boolean' || saved.resting !== undefined && saved.resting !== true ||
           saved.host?.v !== 1 || !saved.net || typeof saved.stateHash !== 'string' || typeof saved.buildHash !== 'string') throw new Error('save envelope does not fit this room');
       saved.at = Math.min(saved.at, Date.now());
       if (saved.pausedAt !== null) saved.pausedAt = Math.min(saved.pausedAt, Date.now());
@@ -796,7 +818,10 @@ export class Table {
       this.house = new HouseAgents({
         room, env: this.env,
         // The room's own alarm (a paused server-hosted room ends on it) is never pushed back by a guide's.
-        setAlarm: (at) => { this.ctx.storage.setAlarm(this.roomAlarmAt > Date.now() ? Math.min(at, this.roomAlarmAt) : at).catch(error => this.say({ev:'background-failed',error:errorLine(error)})); },
+        setAlarm: (at) => {
+          this.guideAlarmAt = at;
+          this.ctx.storage.setAlarm(this.roomAlarmAt > Date.now() ? Math.min(at, this.roomAlarmAt) : at).catch(error => this.say({ev:'background-failed',error:errorLine(error)}));
+        },
         budget: { left: (kind) => this.brainCap[kind] - this.brainUsed[kind], spend: (c) => this.brainSpend(c) },
         log: (line) => { try { console.log(JSON.stringify(line)); } catch { /* no console */ } },
       });
@@ -1191,7 +1216,7 @@ export class Table {
     } else {
       const h = room.attach(conn,server.resume);
       server.remember?.(h.id);
-      if (server.resume && room.server) room.joinServer(room.clients.get(h.id));
+      if (server.resume && room.server) room.joinServer(room.clients.get(h.id), true);
       // A room is OPENED when the first seat is taken in an empty one (a room restored after a deploy keeps its
       // seats, so it is not counted twice). One counter write per room.
       const fresh = room.seats.size === 0;
@@ -1281,7 +1306,8 @@ export class Table {
     // Older ports publish snapshots without a round protocol. Once play starts,
     // treat them as active until empty: persisting every frame would turn their
     // ordinary network traffic into a stream of SQLite writes.
-    const active = this.hostRt ? this.hostRt.running : this.room?.lastRound?.phase === 'live' || (!this.room?.lastRound && this.room?.lastSnap != null && this.room?.clients.size > 0);
+    // A browser host that rested its room (rules/host.ts in the page) sends nothing until somebody plays: it sleeps.
+    const active = this.hostRt ? this.hostRt.running : !this.room?.resting && (this.room?.lastRound?.phase === 'live' || (!this.room?.lastRound && this.room?.lastSnap != null && this.room?.clients.size > 0));
     return this.room && this.hibernationReady && this.sessionStore && this.ctx.storage.sql && this.ctx.acceptWebSocket && (!this.relayed || this.relays.size > 0) && (!this.hostRt || this.hostRt.roundIdleUntil !== null || !this.hostRt.running) && !active && !this.restoringSockets;
   }
   async sleepRoom() {
@@ -1304,12 +1330,19 @@ export class Table {
     }
     this.saveSessions();
     for(const relay of this.relays.values()){relay.session.flush();relay.socket.sleep();}
-    // Edge-answered heartbeats need only a minute's liveness sweep. A legacy
-    // client still keeps its original hello/heartbeat deadline.
-    const due=[...(this.hostRt?.roundIdleUntil != null ? [this.hostRt.roundIdleUntil] : []),now+(room.officeDirty?1000:60000),...[...room.clients.values()].map(c=>{const ping=c.conn.lastPing?.()??0;return c.helloed?Math.max(c.lastSeen,ping)+(ping?Math.max(room.idleMs,60000):room.idleMs):c.joinedAt+5000;})];
+    // Edge-answered heartbeats need only a minute's liveness sweep: a browser that has pinged the edge, or one that
+    // understands a resting room (it pings the edge from the moment it rests). A legacy client still keeps its
+    // original hello/heartbeat deadline.
+    const due=[...(this.hostRt?.roundIdleUntil != null ? [this.hostRt.roundIdleUntil] : []),now+(room.officeDirty?1000:60000),...[...room.clients.values()].map(c=>{const ping=c.conn.lastPing?.()??0;return c.helloed?Math.max(c.lastSeen,ping)+(ping||c.rest&&c.conn.idlePing?Math.max(room.idleMs,60000):room.idleMs):c.joinedAt+5000;})];
     for(const control of [room.vote?.open?room.vote:null,room.regate,room.agentsOut])if(control?.until)due.push(control.until);
     const at=Math.max(now+1,Math.min(...due)),alarm=await this.ctx.storage.getAlarm();
-    if(alarm==null||alarm>at)await this.ctx.storage.setAlarm(at);
+    // A guide's think is sooner than the liveness sweep, and sleep only moves an alarm earlier. While the host rests,
+    // that think must not survive: it would wake the object every few seconds and its command would start the room.
+    // A spectator's own shorter deadline stays, because `at` is already the soonest real one.
+    const roomResting=this.hostRt?.resting===true||this.room?.resting===true;
+    const guideSoon=roomResting && this.guideAlarmAt && alarm!=null && alarm<=this.guideAlarmAt+1000;
+    if(alarm==null||alarm>at||guideSoon)await this.ctx.storage.setAlarm(at);
+    if(guideSoon)this.guideAlarmAt=0;
   }
   start() {
     if(this.restoringSockets)return;

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.58.0';
+export const STUDIO_VERSION_TAG = '0.58.2';