@homie-rocks/studio 0.57.0 → 0.58.1

package/rules/rules.ts

@@ -214,6 +214,19 @@ export interface RoomSettings {
   predict: { idleHold?: boolean; catchM: number | null; catchUp: number; snapM: number | null; blendMs: number; interpMs: number | null };
   /** The studio's own pace on what one player sends, messages a second by frame kind (`in`, `ev`, ...). Absent: none. */
   rates?: Record<string, number>;
+  /**
+   * When a room with people in it rests (rules/host.ts): its clock stops, its people keep their sockets and seats, and
+   * the first input, command, AI command or returning page starts it again where it stopped.
+   *   'quiet' (absent): nobody has played for `restSeconds`, and the world has nothing of its own to do: no round clock
+   *                     running, no event, timer, spawn or ask waiting, nothing moving (bots, physics, tick handlers).
+   *   'idle':           nobody has played for `restSeconds`, whatever the world is doing: round clocks, timers, bots
+   *                     and AI pause with it (an away-from-keyboard pause, for arcade games where that is right).
+   *   'never':          never rests while somebody is here.
+   * Every page in the background counts as nobody playing after ten seconds. A lasting world never rests.
+   */
+  rest?: 'quiet' | 'idle' | 'never';
+  /** How long nobody plays before a room rests (`rest`). Absent: 60. 0: never rests. */
+  restSeconds?: number;
 }
 /**
  * The default `budget.tick`: 500,000 units at 20 ticks a second or fewer, and less at a faster rate, so a second of
@@ -247,8 +260,8 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
     if (!Number.isFinite(n) || n < 0) { problems.push(`"room.${name}" is a number, zero or more; using its default`); return d; }
     return n;
   };
-  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view', 'lifetime', 'characters', 'rates']);
-  for (const key of Object.keys(r)) if (!known.has(key)) problems.push(`"room.${key}" is not a setting (host, offline, tickHz, inputHz, durability, budget, predict, view, rates)`);
+  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view', 'lifetime', 'characters', 'rates', 'rest', 'restSeconds']);
+  for (const key of Object.keys(r)) if (!known.has(key)) problems.push(`"room.${key}" is not a setting (host, offline, tickHz, inputHz, durability, budget, predict, view, rates, rest, restSeconds)`);
   let rates: Record<string, number> | undefined;
   if (r.rates !== undefined) {
     if (!r.rates || typeof r.rates !== 'object' || Array.isArray(r.rates)) problems.push('"room.rates" is an object of messages a second per player by kind ({ "in": 60 }); using none');
@@ -275,7 +288,7 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
   const p = r.predict && typeof r.predict === 'object' ? r.predict : {};
   return {
     settings: {
-      host, offline, tickHz, inputHz, ...(rates ? { rates } : {}), ...(r.lifetime === 'persistent' ? { lifetime: 'persistent' as const } : {}), ...(r.characters === true ? { characters: true } : {}),
+      host, offline, tickHz, inputHz, ...(rates ? { rates } : {}), ...(r.rest !== undefined ? { rest: ['quiet', 'idle', 'never'].includes(r.rest) ? r.rest : (problems.push('"room.rest" is "quiet", "idle" or "never"; using "quiet"'), 'quiet') } : {}), ...(r.restSeconds !== undefined ? { restSeconds: whole('restSeconds', r.restSeconds, 0, 3600, 60) } : {}), ...(r.lifetime === 'persistent' ? { lifetime: 'persistent' as const } : {}), ...(r.characters === true ? { characters: true } : {}),
       view: { radiusM: r.view?.radiusM === null ? null : num('view.radiusM', r.view?.radiusM, null), ...(r.view?.precisionM !== undefined ? { precisionM: num('view.precisionM', r.view.precisionM, 0) as number } : {}), ...(r.view?.nearM !== undefined ? { nearM: num('view.nearM', r.view.nearM, null) } : {}), ...(r.view?.farHz !== undefined ? { farHz: whole('view.farHz', r.view.farHz, 1, tickHz, tickHz) } : {}) },
       durability: { movementSeconds: whole('durability.movementSeconds', r.durability?.movementSeconds, 1, 60, r.lifetime === 'persistent' ? 30 : 1) },
       budget: { tick: Math.max(1, Math.floor(num('budget.tick', r.budget?.tick, budgetFor(tickHz)) as number)) },

package/rules/view.ts

@@ -294,6 +294,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   let controlChanges: number[][] = [];
   let sentHistory: { t: number; row: number[] }[] = [];
   let hiddenSent = false;
+  /** The room rests (net.resting): when this page last sent the change that wakes it, and whether its clock is held. */
+  let restWokeAt = -Infinity;
+  let restHeld = false;
   const history = new Map<number, Mine>();
   let pending: { seq?: number; applied?: number; t: number; input: Readonly<Record<string, unknown>>; pulses?: Record<string, number>; pulseTicks?: Record<string, number> }[] = [];
   /** Valued pulses sent, numbered: the server's control row names the newest it has acted on (0.46.3). */
@@ -423,7 +426,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     leadAfter = clock() + 2 * rtt + period;
     base = { tick: continuousTick ?? k + Math.min(tickHz, Math.ceil(rtt / period + target) + sendEvery - 1), at: clock() };
     stepped = Math.max(k, Math.floor(base.tick) - (continuousTick === null ? 1 : 0));
-    entries = []; sentHistory = []; controlChanges = []; pending = []; history.clear(); replayHeld = {}; serverHeld = {}; held = {}; lastSent = ''; leads.length = 0; leadTarget = .5; leadMedian = 0; pressed = new Map(); pulseNumber = new Map(); heldTrack.clear(); if (reason !== 'lead') dropPredictions();
+    entries = []; sentHistory = []; controlChanges = []; pending = []; history.clear(); replayHeld = {}; serverHeld = {}; held = {}; lastSent = ''; leads.length = 0; leadTarget = .5; leadMedian = 0; pressed = new Map(); pulseNumber = new Map(); heldTrack.clear(); if (reason !== 'lead' && reason !== 'rest') dropPredictions();
     speed = 1; phases.length = 0; phases.push({ ...base, rate: 1 }); catchTick = null; offsets = []; headingBlend = null; correction.rebases += 1;
     const u = mine && latest?.ents.get(mine.id); if (u) adopt(u);
     if (mine) {
@@ -637,14 +640,16 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   /**
    * The end of a send period (`sendEvery` ticks, counted from tick 0): one frame with the entries made in it, `k` the
    * period's first tick. A period with no entry sends nothing; after 250 ms without a frame the held values are sent
-   * again as an ordinary entry on the current tick.
+   * again as an ordinary entry on the current tick. A resting room (nobody played for a while) is sent nothing until
+   * an entry changes: that first change is what wakes it.
    */
   function flush(now: number, t: number): void {
     if (!mine) { entries = []; return; }
-    if (!entries.length && now - lastSendAt >= 250) keepalive(t);
+    const resting = net.resting();
+    if (!entries.length && now - lastSendAt >= 250 && !resting) keepalive(t);
     const marker = myKind()!.input.length + (myKind()!.owner ? 9 : 0);
     // A newer tick's acknowledgement cannot acknowledge a hole in the history.
-    if (!entries.length && !sentHistory.some(e => !applications.has(e.row[marker + 1]))) return;
+    if (!entries.length && (resting || !sentHistory.some(e => !applications.has(e.row[marker + 1])))) return;
     const k = Math.min(entries[0]?.t ?? t, t - (t % sendEvery));
     for (const entry of entries) {
       const old = sentHistory.findIndex(e => e.t === entry.t);
@@ -710,7 +715,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     const hidden = typeof document !== 'undefined' && document.hidden === true;
     // Effects play for everyone who draws the room: a watcher has no body and still sees them.
     fire();
-    if (!mine || !base || net.seat === null || (!net.connected && !net.rulesHosting)) return;
+    if (!mine || net.seat === null || (!net.connected && !net.rulesHosting)) return;
+    if (!hidden && net.resting()) { restPump(now); return; }
+    if (!base) return;
     if (hidden) {
       // A hidden tab's timers are too slow to keep input alive, and a body must not run on without its player:
       // one neutral entry at once (every field at its init, no press), then no more steps until the tab shows again.
@@ -736,6 +743,28 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     }
   }
 
+  /**
+   * A resting room (nothing is simulated until somebody plays): this page's input clock stops with it, so what it
+   * sends next is stamped on the tick the room rested on, never seconds ahead of it. Nothing is stepped or sent until
+   * a control is held or pressed; then that input goes at once, as one entry on the next tick (again a second later
+   * if the room has not woken yet), and it wakes the room. The first snapshot after the room wakes sets the clock
+   * again (applySnapshot: no base), keeping what is predicted.
+   */
+  function restPump(now: number): void {
+    const kind = myKind();
+    base = null; restHeld = true;
+    if (!kind || now - restWokeAt < 1000) return;
+    const engaged = pressed.size > 0 || pulseQueue.length > 0 || kind.input.some(([name, fd]) => fd.t !== 'press' && fd.t !== 'pulse' && Number(coerce(fd, fd.t === 'held' ? heldNumber(sample[name], fd.init) : sample[name] ?? fd.init, dims)) !== Number(coerce(fd, fd.init, dims)));
+    if (!engaged) return;
+    restWokeAt = now;
+    const t = stepped + 1;
+    const values = kind.input.map(([name, fd]) => fd.t === 'press' ? (pressed.get(name) ? 1 : 0) : fd.t === 'pulse' ? 0 : fd.t === 'held' ? Number(coerce(fd, heldNumber(sample[name], fd.init), dims)) : Number(coerce(fd, sample[name] ?? fd.init, dims)));
+    pressed = new Map();
+    const claim = kind.owner ? [mine!.pos.x, mine!.pos.y, mine!.pos.z, mine!.vel.x, mine!.vel.y, mine!.vel.z, mine!.heading.x, mine!.heading.y, mine!.heading.z] : [];
+    entries = [{ t, row: [...values, ...claim, -471, ++inputSequence, 0] }]; lastSent = JSON.stringify([values, claim]);
+    lastSendAt = 0; flush(now, t);
+  }
+
   function onSnapshot(s: Snapshot<unknown>): void {
     const wasPumping = pumping;
     pumping = true;
@@ -780,7 +809,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         returningUntil = 0;
       }
       if (placed || !base) {
-        adopt(me); rebase(f.k, changedEpoch ? 'epoch' : 'placement');
+        const rested = restHeld && !placed; restHeld = false;
+        adopt(me); rebase(f.k, changedEpoch ? 'epoch' : rested ? 'rest' : 'placement');
         if (placed) emit('placed', entityOf(me, true));
       } else if (kindOf.get(me.kind)?.owner) {
         mine!.motion = motionOf(me.kind, me.motion);
@@ -886,7 +916,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         }
       }
       if (!latencyCalibrated && authorityRtt() > calibratedRtt + period && !Object.values(sample).some(Boolean) && !pending.some(e=>Object.values(e.input).some(Boolean))) { rebase(f.k, 'lead'); latencyCalibrated = true; }
-      if (row && row[3] !== -128 && base && clock() >= leadAfter) {
+      // The furthest lead there is: this clock is more than a second ahead of the room (its input is being dropped).
+      if (row && row[3] >= 126 && base && clock() >= leadAfter) rebase(f.k, 'lead');
+      else if (row && row[3] !== -128 && base && clock() >= leadAfter) {
         const now = clock(), rtt = authorityRtt();
         // A reported lead describes an input sent roughly one authority round trip ago. Remove that
         // clock's phase before measuring jitter; project the control median onto today's phase. Otherwise

package/starters/coin-dash/game.json

@@ -9,7 +9,8 @@
   "entry": "src/view.ts",
   "example": true,
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   },
   "landing": {
     "pitch": "Run for the coins. First one there takes it.",

package/starters/ember-vale/game.json

@@ -24,6 +24,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/gem-rush/game.json

@@ -16,6 +16,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/gem-rush-3d/game.json

@@ -21,6 +21,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/hero-rush-3d/game.json

@@ -21,6 +21,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/tools/tools.ts

@@ -16,7 +16,7 @@ export interface ToolContext {
   };
   bookings: {
     availability(args: {app: string; collection: string; after?: string; quantity?: number; option?: string; resource?: string; addons?: Record<string,number>}): Promise<BookingAvailability>;
-    calendar(args: {app:string;startDate:string;endDate:string;timeZone?:string;time?:string;days?:number;durationMinutes?:number;capacity?:number;weekdays?:number[];resources?:string[];options?:unknown[];prefix?:string}): Array<{id:string;start:string;end:string;capacity:number;date:string;timeZone:string}>;
+    calendar(args: {app:string;startDate:string;endDate:string;timeZone?:string;time?:string;days?:number;durationMinutes?:number;capacity?:number;weekdays?:number[];resources?:string[];options?:unknown[];prefix?:string;exceptions?:Record<string,null|{time?:string;capacity?:number;durationMinutes?:number}>}): Array<{id:string;start:string;end:string;capacity:number;date:string;timeZone:string}>;
     hold(args: {app: string; collection: string; slot?: string; time?: string; option?: string; resource?: string; preferredResource?: string; addons?: string[] | Record<string,number>; addOns?: string[] | Record<string,number>; quantity?: number; id: string; token?: string; expiresAt: number}): Promise<BookingHold>;
     get(args: {id: string; token?: string}): Promise<BookingHold>;
     confirm(args: {id: string; token?: string; version: number}): Promise<BookingHold>;

package/worker/agents.mjs

@@ -363,6 +363,7 @@ export class HouseAgents {
     this.agents = [];
     this.decisions = [];
     this.alarmAt = null;
+    this.resting = false;
     this.lastAlarmAt = -Infinity;
     this.backoffUntil = 0;
     /** pass id → until: a guide the owner kicked stays out until its hold ends. */
@@ -423,7 +424,7 @@ export class HouseAgents {
     };
     this.agents.push(a);
     a.h = this.room.attach(a.conn);
-    a.h.onMessage(JSON.stringify({ t: 'hello', v: 1, rev: 7, device: 'desk', want: 'play', canHost: false, agent: { hands: 'host', role: 'guide' } }));
+    a.h.onMessage(JSON.stringify({ t: 'hello', v: 1, rev: 7, device: 'desk', want: 'play', canHost: false, rest: 1, agent: { hands: 'host', role: 'guide' } }));
     return !a.closed;
   }
 
@@ -449,7 +450,8 @@ export class HouseAgents {
     try { m = JSON.parse(text); } catch { return; }
     const now = this.now();
     switch (m.t) {
-      case 'welcome': a.seat = m.seat; if (typeof m.name === 'string') a.name = m.name; return;
+      case 'welcome': a.seat = m.seat; if (typeof m.name === 'string') a.name = m.name; if (m.rest === true) this.rest(true); return;
+      case 'rest': this.rest(m.on === true); return;
       case 'error':
         if (m.code === 'kicked') this.held.set(a.pass, Number(m.until) || now + 10 * 60_000);
         else if (['agents-off', 'agents-unsupported', 'agent-pass', 'room-closed', 'room-full', 'too-many'].includes(m.code)) this.backoffUntil = now + 60_000;
@@ -524,8 +526,19 @@ export class HouseAgents {
     return Math.max(a.lastCallAt + BRAIN_CADENCE.gapMs, cap);
   }
 
+  /**
+   * The room rested, or woke. While it rests, no guide thinks and none keeps an alarm: a think would be a command,
+   * and a command would wake the room. The next decision waits until somebody plays.
+   */
+  rest(on) {
+    this.resting = on === true;
+    if (this.resting) { this.alarmAt = null; return; }
+    this.schedule();
+  }
+
   /** One alarm for the room: the earliest due guide, never sooner than 3 s after the last alarm. */
   schedule() {
+    if (this.resting) return null;
     const now = this.now();
     let next = Infinity;
     for (const a of this.live()) if (a.seat !== null && a.dueAt !== Infinity && !a.inFlight) next = Math.min(next, Math.max(a.dueAt, this.readyAt(a, now)));
@@ -539,6 +552,7 @@ export class HouseAgents {
 
   /** The Durable Object's alarm: every guide due by now (or within 1.5 s) decides, then the next alarm is set. */
   async onAlarm() {
+    if (this.resting) { this.alarmAt = null; return 0; }
     const now = this.now();
     this.lastAlarmAt = now;
     this.alarmAt = null;
@@ -568,7 +582,7 @@ export class HouseAgents {
     const goalNow = a.view?.goal && typeof a.view.goal === 'object' ? a.view.goal : null;
     if (!asks.length && a.carry && now < a.carry.until && (!goalNow || (goalNow.goal === a.carry.goal && goalNow.state === 'active'))) {
       a.inFlight = false;
-      if (this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
+      if (!this.resting && this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
       return null;
     }
     if (a.carry && (now >= a.carry.until || (goalNow && (goalNow.goal !== a.carry.goal || goalNow.state !== 'active')))) a.carry = null;
@@ -584,6 +598,8 @@ export class HouseAgents {
     const newHere = [...a.seen].filter(([seat, at]) => now - at < 20_000 && players.includes(seat)).map(([seat]) => seat);
     const ctx = { view: a.view, me: { seat: a.seat }, goal: a.view?.goal ?? null, asks, party: a.party, speech: this.room.policy.speech, kids: this.room.policy.kids, quiet, players, avoid, said, newHere };
     const t = await think(vocab, { mode, brain: p, ctx, ms: BRAIN_CADENCE.timeoutMs, now: this.now });
+    // The room rested while the brain was thinking: drop the decision. Sending it would wake the room.
+    if (this.resting || a.closed) { a.inFlight = false; return null; }
     const { decision, provider, why, ms, cost } = t;
     if (t.engine) {
       this.calls += 1;
@@ -606,7 +622,7 @@ export class HouseAgents {
       ...(t.own && /\+floor$/.test(provider) ? { own: { goal: t.own.goal, args: t.own.args } } : {}), ...(t.p ? { p: t.p } : {}), ...(t.model ? { model: t.model } : {}),
     }].slice(-LOG_MAX);
     a.inFlight = false;
-    if (this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
+    if (!this.resting && this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
     return decision;
   }
 

package/worker/booking-calendar.mjs

@@ -11,15 +11,28 @@ function instant(day,time,format) {
  return matches[0];
 }
 /** Inclusive season dates; each returned slot may span several local calendar days. */
-export function calendarSlots({startDate,endDate,timeZone,time='09:00',days,durationMinutes=60,capacity=1,weekdays,resources,options,prefix='slot'}) {
+export function calendarSlots({startDate,endDate,timeZone,time='09:00',days,durationMinutes=60,capacity=1,weekdays,resources,options,prefix='slot',exceptions={}}) {
  const start=date(startDate),end=date(endDate);
+ if(!exceptions||Array.isArray(exceptions)||typeof exceptions!=='object')throw new Error('Invalid calendar exceptions');
+ for(const [day,change] of Object.entries(exceptions)){
+  const at=date(day);
+  if(at<start||at>end||weekdays&&!weekdays.includes(new Date(at).getUTCDay()))throw new Error('Exception is outside the series');
+  if(change!==null&&(!change||typeof change!=='object'||Array.isArray(change)||Object.keys(change).some(k=>!['time','capacity','durationMinutes'].includes(k)||change[k]===undefined)))throw new Error('Invalid calendar exception');
+ }
  if(end<start||end-start>3660*dayMs||!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)||!Number.isSafeInteger(capacity)||capacity<1||days!==undefined&&(!Number.isSafeInteger(days)||days<1)||!Number.isSafeInteger(durationMinutes)||durationMinutes<1)throw new Error('Invalid calendar range, time, duration or capacity');
  if(weekdays&&(!Array.isArray(weekdays)||weekdays.some(n=>!Number.isInteger(n)||n<0||n>6)))throw new Error('weekdays uses 0 (Sunday) through 6 (Saturday)');
  if(typeof timeZone!=='string'||!timeZone)throw new Error('Declare the place timeZone');
  const format=new Intl.DateTimeFormat('en-CA',{timeZone,year:'numeric',month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',hourCycle:'h23'}),slots=[];
  for(let at=start;at<=end;at+=dayMs) {
   if(weekdays&&!weekdays.includes(new Date(at).getUTCDay()))continue;
-  const day=new Date(at).toISOString().slice(0,10),from=instant(day,time,format),to=days?instant(new Date(at+days*dayMs).toISOString().slice(0,10),time,format):from+durationMinutes*60000;
+  const day=new Date(at).toISOString().slice(0,10);
+  if(Object.hasOwn(exceptions,day)){
+   const change=exceptions[day];if(change===null)continue;
+   const [slot]=calendarSlots({startDate:day,endDate:day,timeZone,time,days:Object.hasOwn(change,'durationMinutes')?undefined:days,durationMinutes,capacity,resources,options,prefix,...change});
+   // Identity follows the series occurrence, even when its wall time changes.
+   slots.push({...slot,id:`${prefix}-${day}-${time.replace(':','')}`});continue;
+  }
+  const from=instant(day,time,format),to=days?instant(new Date(at+days*dayMs).toISOString().slice(0,10),time,format):from+durationMinutes*60000;
   slots.push({id:`${prefix}-${day}-${time.replace(':','')}`,date:day,timeZone,start:new Date(from).toISOString(),end:new Date(to).toISOString(),capacity,...(resources?{resources}:{}),...(options?{options}:{})});
  }
  return slots;

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.57.0","sha256":"0a84d357448b7257ee97cac637957a6fe5bb46323de76625644d88e80a684a87"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.58.1","sha256":"b3944d94ae64b4e7755614a9801c54216f14fcb741e9598bd5c4eab117deae50"});

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');