@homie-rocks/studio 0.35.1 → 0.37.0

package/rules/types.ts

@@ -0,0 +1,63 @@
+/** The build specialises these faces from a game's declarations; the runtime still checks every write. */
+import type { Vec3, BodyDef, Fields } from './rules.ts';
+import type { math } from './math.ts';
+
+export type Point = { readonly x: number; readonly y: number; readonly z?: number };
+export type ReadonlyState<T> = T extends object ? { readonly [K in keyof T]: ReadonlyState<T[K]> } : T;
+export type WriteState<T> = T extends Vec3 ? keyof T extends keyof Vec3 ? Point : { [K in keyof T]: WriteState<T[K]> } : T extends object ? { [K in keyof T]: WriteState<T[K]> } : T;
+type Payload<T> = {} extends T ? [data?: WriteState<T>] : [data: WriteState<T>];
+type Query<T> = ReadonlyState<Omit<T, 'input'>>;
+export interface Goal { readonly goal: string; readonly args: Readonly<Record<string, unknown>>; readonly from: 'brain' | 'floor'; readonly at: number; readonly asked: boolean; readonly state: 'active' | 'done' | 'failed' }
+export interface GuideDecision { goal?: string | null; args?: Record<string, unknown>; say?: string | null; sayArgs?: Record<string, unknown> }
+export interface GuideRequest { readonly k: string; readonly args: Readonly<Record<string, unknown>>; readonly from: number; readonly at: number }
+export type GuideView<V, G = Goal, A = GuideRequest> = ReadonlyState<V> & { readonly goal: G | null; readonly asks: readonly A[] };
+export interface Player<G = Goal> { readonly seat: number; readonly owner: string; readonly driver: 'person' | 'bot' | 'ai'; readonly away: boolean; readonly goal: G | null }
+export type Self<F, M, I, K extends string, P extends boolean, G = Goal> = F & {
+  readonly id: string; readonly kind: K; readonly pos: Vec3; get vel(): Vec3; set vel(value: Point); get heading(): Vec3; set heading(value: Point); readonly grounded: boolean;
+  readonly motion: M; readonly input: ReadonlyState<I>;
+} & (P extends true ? Player<G> : {});
+export interface Hit { readonly entity?: string; readonly at: Point; readonly normal: Vec3; readonly dist?: number }
+export type Area = { sphere: { at: Point; r: number } } | { box: { min: Point; max: Point } } | { cone: { at: Point; dir: Point; r: number; angle: number } };
+export interface MapView { readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
+export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
+export interface Round { readonly n: number; readonly phase: 'live' | 'over'; readonly endsAt: number }
+export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
+  readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number;
+  readonly shared: Room extends true ? S : ReadonlyState<S>;
+  readonly round: Round & (Room extends true ? { end(): void } : {});
+  random(): number;
+  send<K extends keyof E>(target: string, event: K, ...data: Payload<E[K]>): void;
+  sendRoom<K extends keyof E>(event: K, ...data: Payload<E[K]>): void;
+  sendArea<K extends keyof E>(area: Area, event: K, ...data: Payload<E[K]>): void;
+  after<K extends keyof E>(ticks: number, event: K, ...data: Payload<E[K]>): void;
+  emit<K extends keyof F>(effect: K, at: Point | string, ...data: Payload<F[K]>): void;
+  spawn<K extends keyof C>(kind: K, at: Point, fields?: Partial<WriteState<C[K]>>): string;
+  near<K extends keyof V>(at: Point, radius: number, kind: K): readonly Query<V[K]>[];
+  near(at: Point, radius: number): readonly Query<V[keyof V]>[];
+  inBox<K extends keyof V>(box: { min: Point; max: Point }, kind: K): readonly Query<V[K]>[];
+  inBox(box: { min: Point; max: Point }): readonly Query<V[keyof V]>[];
+  ray(from: Point, direction: Point, max: number): (Hit & { readonly dist: number }) | undefined;
+  ask<K extends keyof A>(name: K, state: WriteState<A[K]>): boolean;
+} & (Room extends true ? { announce<K extends keyof E>(event: K, ...data: Payload<E[K]>): void; finish(): void } : {
+  goalDone(ok?: boolean): void;
+  despawn(self: Exclude<V[keyof V], Player>): void;
+  place(self: V[keyof V], at: Point, options?: { vel?: Point; heading?: Point }): void;
+  sweep(self: V[keyof V], delta: Point, options?: { ignore?: readonly string[] }): Hit | undefined;
+});
+export type EventData<T> = ReadonlyState<T>;
+export type Undeliverable<E> = { [K in keyof E]: { to: string; event: K; data: E[K] } }[keyof E];
+export type BuiltIns<E = Record<string, never>> = { arrive: { why: 'join' | 'spawn' }; leave: {}; takeover: {}; undeliverable: Undeliverable<E>; answer: { ask: string; by: string; picks: Readonly<Record<string, unknown>>; why?: string } };
+export type RoomEvents<E = Record<string, never>> = RoundEvents & { seatJoined: { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; owner: string; took: boolean }; seatAway: { seat: number; id: string; away: boolean }; seatLeft: { seat: number; id: string }; answer: BuiltIns['answer']; undeliverable: BuiltIns<E>['undeliverable'] };
+export type RoundEvents = { roundStart: { n: number }; roundOver: { n: number; results: readonly { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; score: number; place: number }[] } };
+type GuideWorld<W> = Pick<W, Extract<keyof W, 'tick' | 'dt' | 'ticks' | 'math' | 'map' | 'tune' | 'stage' | 'level' | 'levelMax' | 'round' | 'shared' | 'near' | 'inBox' | 'ray'>>;
+export type Entity<W, S, I, E, C, V, Answer = BuiltIns['answer'], G = Goal, A = GuideRequest, D = GuideDecision> = {
+  player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot' }; fields?: Fields; motion?: Fields; input?: Fields; body?: BodyDef;
+  tick?: (world: W, self: S) => void;
+  think?: (world: W, self: S) => Partial<I>;
+  on?: { [K in keyof (Omit<E, keyof BuiltIns> & Omit<BuiltIns<E>, 'answer'> & { answer: Answer })]?: (world: W, self: S, event: EventData<(Omit<E, keyof BuiltIns> & Omit<BuiltIns<E>, 'answer'> & { answer: Answer })[K]>) => void };
+  commands?: { [K in keyof C]?: (world: W, self: S, event: EventData<C[K]>) => void };
+  onRoom?: { [K in keyof (E & RoundEvents)]?: (world: W, self: S, event: EventData<(E & RoundEvents)[K]>) => void };
+  guide?: { view: (world: GuideWorld<W>, self: ReadonlyState<Omit<S, 'input'>>) => V; floor?: (world: W, self: S, view: GuideView<V, G, A>) => D };
+};
+export interface MoveBody<M> { get pos(): Vec3; set pos(value: Point); get vel(): Vec3; set vel(value: Point); get heading(): Vec3; set heading(value: Point); grounded: boolean; readonly motion: M }
+export type MoveContext<T, M> = Clock & { readonly tune: ReadonlyState<T>; readonly map: MapView & { sweep(body: MoveBody<M>, delta: Point): Hit | undefined } };

package/rules/view.ts

@@ -1,3 +1,5 @@
+import { rulesOutput } from '../netplay/rules-output.mjs';
+import { rulesCaps, rulesRates } from '../worker/limits.mjs';
 /*
  * view.ts — what a rules game's view imports: the room, as a browser sees it.
  * =============================================================================
@@ -6,10 +8,10 @@
  *   import type rules from './rules';
  *   const room = openRoom<typeof rules>();
  *
- * A game is rules plus view. The rules run on the server; the view draws what it is told and sends what the player
+ * A game is rules plus view. The rules run in one host runtime; the view draws what it is told and sends what the player
  * presses. `openRoom` starts the netplay helper (netplay/netplay.ts), joins the room the play page names and returns
  * at once: `room.status` moves from `connecting` to `playing`. The rules are imported for their types only, so none
- * of their code is in the view's bundle; the build hands this library their declarations as data (`setGame`), and it
+ * of their code is imported by the game's view; the build supplies declarations and an optional local host loader, and it
  * unpacks every frame from them. A view never packs or unpacks state.
  *
  *   room.me                 the player's own body
@@ -39,19 +41,20 @@ import type { useAgents, Vocabulary, AskButton } from '../agents/agents.ts';
 let agentFactory: typeof useAgents | null = null;
 export function setAgentFactory(factory: typeof useAgents): void { agentFactory = factory; }
 import { createNetplay } from '../netplay/netplay.ts';
-import type { Netplay, NetplayOptions, RoundInfo, Snapshot, StepEntry } from '../netplay/netplay.ts';
+import type { Netplay, NetplayOptions, RulesHostFactory, RoundInfo, Snapshot, StepEntry } from '../netplay/netplay.ts';
+import { lab } from '../lab/lab.ts';
 import { exposePort } from '../port/probe.ts';
-import { BudgetError, G, brand } from './guard.ts';
-import { math, sweepMap } from './math.ts';
-import { coerce, coerceFields, dir, num, thawFields, unpackEntity, unpackFields, unpackVec, vec3 } from './pack.ts';
+import { BudgetError } from './guard.ts';
+import { moveContext } from './math.ts';
+import { coerce, dir, stepMove, thawFields, unpackEntity, unpackFields, unpackVec, vec3 } from './pack.ts';
 import type { Unpacked } from './pack.ts';
 import type { FieldList, MoveFn, Schema, Vec3 } from './rules.ts';
 
 /** What the build hands the view library for one game: its declarations, its public tunables and its map. No code. */
 export interface GameData { vocab?: Vocabulary; id: string; schema: Schema; tune: Record<string, unknown>; map: { name?: string; bounds: { min: unknown; max: unknown }; boxes?: unknown[]; circles?: unknown[]; spots?: Record<string, unknown[]> } }
-let current: { game: GameData; move: Record<string, MoveFn> } | null = null;
+let current: { game: GameData; move: Record<string, MoveFn>; load?: () => Promise<RulesHostFactory> } | null = null;
 /** Called by the build's own two lines at the top of a view's bundle, before the view's code runs. */
-export function setGame(game: GameData, move: Record<string, MoveFn> = {}): void { current = { game, move }; }
+export function setGame(game: GameData, move: Record<string, MoveFn> = {}, load?: () => Promise<RulesHostFactory>): void { current = { game, move, load }; }
 
 /** An entity as a view reads it: the built-in fields, the kind's declared fields by name, and its `motion`. */
 export interface Entity {
@@ -82,7 +85,7 @@ export interface Room<R = unknown> {
   follow(id: string | null): void;
   /** Extra values for the testing tools' receipts (`window.__homiePort`). */
   probe(extra: Record<string, () => unknown>): void;
-  /** A guide's ask buttons and a person's ask (today's relay frames; guides are driven by the server in a later release). */
+  /** A guide's ask buttons and a person's ask, handled by the room's rules host. */
   ask(id: string, askId: string, args?: Record<string, unknown>): void;
   askButtons(id: string, offer?: Record<string, unknown>): AskButton[];
   readonly tune: Readonly<Record<string, unknown>>;
@@ -110,8 +113,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const period = 1000 / tickHz;
   const sendEvery = Math.ceil(tickHz / Math.max(1, schema.settings.inputHz));
   const clock = opts.now ?? ((): number => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
-  const net = createNetplay<unknown, unknown, unknown>({ game: game.id, maxPlayers: schema.seats, snapshotHz: tickHz, ...opts.net, rules: true });
-  const agents = game.vocab && agentFactory ? agentFactory(net, game.vocab, { roles: ['guide', 'party'], view: () => ({}), manual: true }) : null;
+  const net = createNetplay<unknown, unknown, unknown>({ game: game.id, maxPlayers: schema.seats, snapshotHz: tickHz, heartbeatMs: 0, rulesHost: { mode: schema.settings.host, offline: schema.settings.offline, load: current?.load }, ...opts.net, rules: true, rulesLimits: { output: rulesOutput, bytes: rulesCaps(schema.seats), rates: rulesRates(tickHz, schema.seats) } });
+  const agents = game.vocab && agentFactory ? agentFactory(net, game.vocab, { roles: ['guide', 'party'], view: () => ({}), manual: true, viewOnly: true }) : null;
   const kindOf = new Map(schema.kinds.map((k) => [k.name, k]));
   const listeners = new Map<string, Set<(e: any) => void>>();
   const emit = (name: string, e: unknown): void => { for (const fn of listeners.get(name) ?? []) { try { fn(e); } catch (err) { console.warn(`[room] on('${name}')`, err); } } };
@@ -119,7 +122,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const map = { bounds: { min: vecOf(game.map.bounds.min), max: vecOf(game.map.bounds.max) }, boxes: (game.map.boxes ?? []).map((b: any) => ({ min: vecOf(b.min), max: vecOf(b.max) })), circles: (game.map.circles ?? []).map((c: any) => ({ at: vecOf(c.at), r: Number(c.r) })) };
   const spots: Record<string, readonly Vec3[]> = {};
   for (const [key, list] of Object.entries(game.map.spots ?? {})) spots[key] = Object.freeze(list.map(vecOf));
-  const tune = Object.freeze({ ...game.tune });
+  const tune = Object.freeze({ ...(lab.rulesTune({ public: game.tune }).public as Record<string, unknown>) });
 
   let status: RoomStatus = 'connecting';
   let latest: Frame | null = null;
@@ -167,12 +170,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const tickAt = (now: number): number => (base ? base.tick + (now - base.at) / period : 0);
   /** The tick `move` is being run for: the step just taken, or the one after it while the own body is drawn between ticks. */
   let moveTick = 0;
-  const moveCtx = brand(Object.freeze({
-    get tick() { return moveTick; }, dt: 1 / tickHz, tune, math,
-    // As the server's `ctx.ticks` reads it: a plain number, or nothing.
-    ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
-    map: brand(Object.freeze({ name: game.map.name ?? 'main', spot: (name: string) => spots[name]?.[0], spots: (name: string) => spots[name] ?? Object.freeze([]), sweep: (body: any, delta: unknown) => sweepMap(map, body, delta, myKind()?.radius ?? 0, dims) })),
-  }));
+  const moveCtx = moveContext({ tick: () => moveTick, tickHz, tune, map, name: game.map.name ?? 'main', spots, radius: () => myKind()?.radius ?? 0, dims });
   function rebase(k: number): void {
     const rtt = net.stats().rtt ?? 100;
     base = { tick: k + Math.ceil(rtt / period + TARGET_LEAD) + sendEvery - 1, at: clock() };
@@ -190,12 +188,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     const fn = moves[kindName];
     if (!fn) return body;
     moveTick = t;
-    G.left = Math.max(1, Math.floor(schema.settings.budget.tick / 4));
-    try { fn(body, input, moveCtx); } catch (err) { if (!(err instanceof BudgetError)) console.warn('[room] move', err); }
-    G.left = Infinity;
-    // Rounded to 32-bit floats and held to the declared shapes, as the server does it: both hold the same numbers.
-    const list = kindOf.get(kindName)?.motion ?? [];
-    return { pos: vec3(body.pos, dims), vel: vec3(body.vel, dims), heading: dir(body.heading, dims), grounded: body.grounded === true, motion: thawFields(list, coerceFields(list, body.motion, dims)) };
+    return stepMove(fn, body, input, moveCtx, Math.max(1, Math.floor(schema.settings.budget.tick / 4)), kindOf.get(kindName)?.motion ?? [], dims, (err) => { if (!(err instanceof BudgetError)) console.warn('[room] move', err); });
   }
   /** The input values the last step held (a press is never held). */
   let held: Readonly<Record<string, unknown>> = Object.freeze({});
@@ -243,12 +236,12 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   }
   function pump(): void {
     if (closed) return;
-    if (net.offline) setStatus(net.closedWhy ? 'closed' : 'offline');
+    if (net.offline && !net.rulesHosting) setStatus(net.closedWhy ? 'closed' : 'offline');
     const now = clock();
     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) return;
+    if (!mine || !base || net.seat === null || (!net.connected && !net.rulesHosting)) 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.
@@ -306,7 +299,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   function roundNow(): RoomRound | null {
     if (!round || !latest) return null;
     // The room's clock now, from the newest snapshot: a view never turns a tick into time itself.
-    const serverTick = latest.k + (net.connected ? (clock() - latest.at) / period : 0);
+    const serverTick = latest.k + ((net.connected || net.rulesHosting) ? (clock() - latest.at) / period : 0);
     return { ...round, secondsLeft: round.endsAt ? Math.max(0, (round.endsAt - serverTick) / tickHz) : Infinity, ...(results ? { results } : {}) };
   }
   /** Effects wait for the tick they were emitted on to be drawn (an effect on the player's own body plays at once). */
@@ -323,7 +316,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) setStatus(net.closedWhy ? 'closed' : 'offline'); });
+  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.state === 'online') { base = null; if (status !== 'playing') setStatus('connecting'); } else if (e.state === 'closed') setStatus('closed'); else if (e.state === 'alone' || e.state === 'offline') setStatus('offline');
   });
@@ -335,10 +328,20 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
       return;
     }
     // A player's speech and emotes, and a guide's lines and goals, as the relay carries them today.
-    if (/^(?:say|chat|emote)/i.test(e.k) && !(agents && (e.d as { ai?: boolean })?.ai)) emit('say', { kind: e.k, seat: e.from, ...(e.d && typeof e.d === 'object' ? e.d as object : { text: e.d }) });
-    else if (e.k === 'agent:goal' && e.from === net.host?.seat) emit('goal', e.d);
-    else if (e.k === 'agent:ask' && e.from === net.host?.seat) emit('ask', e.d);
-    else if (/^ask:/.test(e.k)) emit('ask', { ask: e.k.slice(4), ...(e.d && typeof e.d === 'object' ? e.d as object : {}) });
+    if (/^(?:say|chat|emote)/i.test(e.k) && !(agents && (e.d as { ai?: boolean })?.ai)) {
+      const data = e.d && typeof e.d === 'object' ? e.d as Record<string, unknown> : { text: e.d };
+      emit('say', { ...data, kind: e.k, seat: e.from, slot: -1, line: typeof data.line === 'string' ? data.line : undefined, text: typeof data.text === 'string' ? data.text : '', args: {} });
+    }
+    else if (e.k === 'agent:goal' && e.from === null) {
+      const data = e.d as import('../agents/agents.ts').GoalEvent;
+      const goal = (g: import('../agents/agents.ts').Goal) => ({ ...g, asked: g.asked === true });
+      emit('goal', { ...data, goal: goal(data.goal), prev: data.prev ? goal(data.prev) : null });
+    }
+    else if (e.k === 'agent:ask' && e.from === null) emit('ask', e.d);
+    else if (/^ask:/.test(e.k)) {
+      const data = e.d && typeof e.d === 'object' ? e.d as Record<string, unknown> : {};
+      emit('ask', { ...data, ask: e.k.slice(4), k: e.k.slice(4), slot: typeof data.slot === 'number' ? data.slot : -1, from: e.from, at: clock(), args: data.args && typeof data.args === 'object' ? data.args : {} });
+    }
   });
 
   agents?.on('say', (e) => emit('say', e));
@@ -406,7 +409,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     self: () => { const m = meNow(); return m ? { x: m.pos.x, y: m.pos.y, z: m.pos.z } : null; },
     peer: (seat: number) => { if (!latest) return null; for (const u of latest.ents.values()) if (u.seat === seat) return { x: u.pos.x, y: u.pos.y, z: u.pos.z }; return null; },
     scores: () => roster().map((r) => ({ seat: r.seat, score: r.score })),
-    score: myScore, tick: () => latest?.k ?? 0, epoch: () => epoch, hosted: () => 'server', status: () => status,
+    score: myScore, tick: () => latest?.k ?? 0, epoch: () => epoch, hosted: () => net.rulesHosting ? 'browser' : schema.settings.host, status: () => status,
   });
   if (typeof window !== 'undefined') {
     exposePort(net as Netplay<unknown, unknown, unknown>, {

package/shop/SHOP.md

@@ -201,3 +201,16 @@ Game and TV checkout use the same tab if a new tab is unavailable, then return t
 During rollback, the released Worker grants only a cart’s first item until the new Worker repairs it; it
 allows whole-cart player refunds even when a tip is included, and counts partially refunded carts at
 the full amount toward a cap. The additive schema preserves its original rows and entitlement keys.
+
+## Shop button on the screen
+
+An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to hide this button (merge with any existing screen settings). The room panel and your own shop buttons still work. Closed shops, kids policies and an empty selection show no button.
+
+```ts
+import { createShop } from '@homie-rocks/studio/shop';
+const shop = createShop();
+shopButton.onclick = () => shop.open();
+itemButton.onclick = () => shop.open('supporter');
+```
+
+These calls open the same shop in games and apps. Inside a player card, purchases leave for the studio's shop; ordinary play/open pages start Stripe checkout. The studio's TV and kids policies still apply.

package/site/SITE.md

@@ -398,7 +398,7 @@ A studio with a `shop.json` ([../shop/SHOP.md](../shop/SHOP.md)) has `/shop/` (i
 one neutral age question, Buy on Stripe's own page, or a link for a parent), `/shop/thanks`, `/shop/refunds/` (the
 refund policy every seller publishes) and `/shop/parent/<link>` (what a parent opens). The account page lists the
 player's purchases and badges, with the self-serve refund of an unused item. A play page whose game the studio
-sells something for carries the store sheet (the game's `shop.open()`, and Shop in the room sheet); the protective shop policy hides it on kids servers and sends big-screen shoppers to a phone. The studio can edit these policies in shop.json. With a `shop.json`, `/shop/` belongs to the
+sells something for carries the store sheet, and play/open screens show a visible Shop button in a reserved strip above the content. `screen.shop: false` in game.json or app.json hides this button; `createShop().open()` or `.open(item)` opens the same sheet from the experience's own button. Closed shops and experiences without items show no button; the protective shop policy hides it on kids servers and sends big-screen shoppers to a phone. The studio can edit these policies in shop.json. With a `shop.json`, `/shop/` belongs to the
 shop (a `site/pages/shop/` is not served); without one it is the studio's own. The directory manifest says only
 whether the shop is open and its till.
 

package/standalone/shell/shell.js

@@ -84,20 +84,22 @@
   /** The room's address on the studio's site: a friend opens it in any browser and lands in this room. */
   function linkOf(room) { return site + '/' + game + '/play?room=' + encodeURIComponent(room); }
 
+  var canOffline = !app.room || app.room.host === 'browser' || app.room.offline !== false;
+  noticeEl.querySelector('[data-notice-offline]').hidden = !canOffline;
   // What the button and its sheet say: the room, or plainly that this copy plays offline.
   function paint() {
     var alone = !state.online || (state.link && state.link.state === 'alone');
-    var word = !state.starts ? 'Finding a room…' : alone ? 'Playing offline · Try again' : state.link && state.link.state === 'reconnecting' ? 'Reconnecting…' : labelOf(state.room);
+    var word = !state.starts ? 'Finding a room…' : alone ? (canOffline ? 'Playing offline · Try again' : 'Connection needed · Try again') : state.link && state.link.state === 'reconnecting' ? 'Reconnecting…' : labelOf(state.room);
     ui.querySelector('[data-room-code]').textContent = word;
     ui.querySelector('[data-room-label]').textContent = state.online ? labelOf(state.room) : 'Offline';
     ui.querySelector('[data-room-state]').textContent = !site ? 'This copy has no online address' : alone ? 'No room answered' : '';
     // A copy the site has outgrown cannot invite anybody: a friend's browser would land on the newer version, which
     // this copy cannot join. The line about updating stands where the invite was.
-    ui.querySelector('[data-room-link]').textContent = state.outdated ? STALE : state.online ? linkOf(state.room).replace(/^https?:\/\//, '') : 'Your game and its bots are on this device.';
+    ui.querySelector('[data-room-link]').textContent = state.outdated ? STALE : state.online ? linkOf(state.room).replace(/^https?:\/\//, '') : (canOffline ? 'Your game and its bots are on this device.' : 'This game needs a connection.');
     ui.querySelector('[data-invite]').hidden = !state.online || state.outdated;
     ui.querySelector('[data-quick]').textContent = alone ? 'Try again' : 'Quick play';
     if (alone) ui.querySelector('[data-quick]').classList.add('primary'); else ui.querySelector('[data-quick]').classList.remove('primary');
-    ui.querySelector('[data-offline]').hidden = !state.online;
+    ui.querySelector('[data-offline]').hidden = !state.online || !canOffline;
     wake();
     tellRects();
   }
@@ -113,7 +115,7 @@
     try { if (typeof AbortController === 'function') { var ac = new AbortController(); opts.signal = ac.signal; setTimeout(function () { try { ac.abort(); } catch (e) {} }, 6000); } } catch (e) {}
     return fetch(site + '/' + game + '/api/lobby' + (q.length ? '?' + q.join('&') : ''), opts)
       .then(function (r) { return r.json(); })
-      .then(function (j) { return j && typeof j.room === 'string' && ROOM.test(j.room) ? j.room : null; })
+      .then(function (j) { if (j && j.error === 'stale') { state.outdated = true; flash(STALE); } return j && typeof j.room === 'string' && ROOM.test(j.room) ? j.room : null; })
       .catch(function () { return null; });
   }
 
@@ -165,7 +167,7 @@
       lobby().then(function (room) {
         state.finding = false;
         if (state.starts !== asked) return;
-        if (room) start(room); else { flash('No room answered: still playing offline.'); paint(); }
+        if (room) start(room); else { flash(state.outdated ? STALE : canOffline ? 'No room answered: still playing offline.' : 'This game needs a connection.'); paint(); }
       });
       return;
     }
@@ -184,7 +186,7 @@
   function go() { if (state.finding) return; var kept = remembered(); hide(); if (kept && site) start(kept); else find(); }
   function join(code) {
     if (!ROOM.test(code)) { flash('A room code is 1 to 32 letters, digits, - or _.'); return false; }
-    if (!site) { flash('This copy has no online address: it plays offline.'); return false; }
+    if (!site) { flash(canOffline ? 'This copy has no online address: it plays offline.' : 'This game needs an online address and a connection.'); return false; }
     remember(code); hide(); open(false); start(code);
     return true;
   }

package/worker/account-page.mjs

@@ -108,11 +108,12 @@ export function accountPage(cat, { origin = '', next = '/account/', owner = null
   const studio = cat?.studio?.name ?? 'Studio';
   const boot = { next, owner, link, mode, features, studio };
   const games = (cat?.games ?? []).filter((g) => g.saves).map((g) => g.name);
-  const back = next !== '/account/' ? `<p class="back"><a class="ghost" href="${esc(next)}" data-back>Back to the game</a></p>` : '';
+  const app = (cat.games ?? []).some((g) => g.kind === 'app' && next.startsWith(`/${g.id}/`));
+  const back = next !== '/account/' ? `<p class="back"><a class="ghost" href="${esc(next)}" data-back>Back to the ${app ? 'app' : 'game'}</a></p>` : '';
   const main = `<section class="acct" data-account>
 <p class="kicker">${esc(studio)}</p>
-<h1>Your player account</h1>
-<p class="lead">Keep your characters and progress on every device you play on. It is an account on ${esc(studio)} only, made with a passkey: Face ID, a fingerprint or your device's PIN. No password, and no email needed.</p>
+<h1>${app ? 'Your account' : 'Your player account'}</h1>
+<p class="lead">${app ? 'Sign in for your role in this app.' : 'Keep your characters and progress on every device you play on.'} It is an account on ${esc(studio)} only, made with a passkey: Face ID, a fingerprint or your device's PIN. No password, and no email needed.</p>
 <noscript><p class="lead">This page needs JavaScript for passkeys.</p></noscript>
 <div class="card" data-view="loading"><p>Looking for your account…</p></div>
 

package/worker/app-format.mjs

@@ -0,0 +1,42 @@
+/** App metadata shared by the build and the Worker. No browser role grants authority. */
+export const APP_SURFACES = ['phone', 'wall', 'kiosk', 'tablet'];
+export const APP_WORDS = Object.freeze({ open: 'Open', join: 'Scan to join', one: 'person', many: 'people' });
+const key = /^[a-z][a-z0-9-]{0,39}$/;
+const object = (x) => x && typeof x === 'object' && !Array.isArray(x);
+export function appProblems(meta) {
+  const bad = [];
+  if (!object(meta)) return ['app.json must be an object'];
+  const roles = object(meta.roles) ? meta.roles : {};
+  const collections = object(meta.records?.collections) ? meta.records.collections : {};
+  if (!object(meta.roles) || !Object.keys(meta.roles).length) bad.push('roles must declare at least one role');
+  for (const [id, role] of Object.entries(roles)) {
+    if (!key.test(id) || !object(role) || typeof role.signIn !== 'boolean' || !Array.isArray(role.can) || role.can.some((s) => !/^(read|create|update|delete):[a-z][a-z0-9-]{0,39}$/.test(s))) bad.push(`role ${id}: declare signIn and can (read/create/update/delete:collection)`);
+  }
+  if (!Object.values(roles).some((r) => r?.signIn === false)) bad.push('declare a public role');
+  if (!object(meta.surfaces) || !Object.keys(meta.surfaces).length) bad.push('declare surfaces');
+  for (const [surface, role] of Object.entries(meta.surfaces ?? {})) if (!APP_SURFACES.includes(surface) || !Object.hasOwn(meta.roles ?? {}, role)) bad.push(`surface ${surface}: name a declared role`);
+  if (!object(meta.records) || typeof meta.records.persist !== 'boolean' || !object(meta.records.collections)) bad.push('records declares persist and collections');
+  for (const [id, c] of Object.entries(collections)) {
+    if (!key.test(id) || !object(c) || !object(c.fields)) { bad.push(`collection ${id}: declare fields`); continue; }
+    for (const [field, spec] of Object.entries(c.fields)) if (!key.test(field) || !object(spec) || !['string', 'number', 'boolean'].includes(spec.type) || (spec.enum && (!Array.isArray(spec.enum) || !spec.enum.length))) bad.push(`collection ${id}.${field}: invalid field`);
+  }
+  for (const r of Object.values(roles)) for (const cap of Array.isArray(r?.can) ? r.can : []) if (!Object.hasOwn(meta.records?.collections ?? {}, String(cap).split(':')[1])) bad.push(`unknown collection in ${cap}`);
+  for (const [k, v] of Object.entries(meta.words ?? {})) if (!Object.hasOwn(APP_WORDS, k) || typeof v !== 'string' || !v.trim() || v.length > 60) bad.push(`words.${k}: use a short label`);
+  return bad;
+}
+export const appWords = (g) => g?.kind === 'app' ? { ...APP_WORDS, ...g.words } : { open: 'Play', join: 'Scan to play', one: 'player', many: 'players' };
+export const openPath = (g) => `/${g.id}/${g.kind === 'app' ? 'open' : 'play'}`;
+export function appRole(meta, url) {
+  const surface = url.searchParams.get('surface') ?? ((url.pathname.endsWith('/tv') || url.pathname.endsWith('/watch')) || url.searchParams.get('want') === 'screen' ? 'wall' : 'phone');
+  return url.searchParams.get('role') ?? meta.surfaces?.[surface] ?? Object.keys(meta.roles ?? {}).find((r) => !meta.roles[r].signIn);
+}
+export function recordProblem(collection, data, { create = false } = {}) {
+  if (!object(data) || JSON.stringify(data).length > 8192) return 'record must be an object below 8 KB';
+  for (const k of Object.keys(data)) if (!Object.hasOwn(collection.fields, k)) return `unknown field ${k}`;
+  for (const [k, s] of Object.entries(collection.fields)) {
+    const v = data[k];
+    if (v === undefined) { if (s.required) return `missing ${k}`; continue; }
+    if (typeof v !== s.type || (s.type === 'number' && !Number.isFinite(v)) || (typeof v === 'string' && v.length > (s.maxLength ?? 256)) || (s.enum && !s.enum.includes(v)) || (create && s.initial !== undefined && v !== s.initial)) return `invalid ${k}`;
+  }
+  return null;
+}

package/worker/app-records.mjs

@@ -0,0 +1,100 @@
+/** Lasting app records in the studio's own D1. Room hosts never authorize writes. */
+import { appRole, recordProblem } from './app-format.mjs';
+import { isOwner, sameOrigin } from './office.mjs';
+import { players } from './players.mjs';
+import { ownerAllowed } from './stats.mjs';
+import { appOriginOf } from './standalone.mjs';
+export const APPS_MIGRATION_FILE = '0014_studio_apps.sql';
+export const APPS_MIGRATION = `CREATE TABLE IF NOT EXISTS app_records (
+  app TEXT NOT NULL, collection TEXT NOT NULL, id TEXT NOT NULL, value TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1, updated_at INTEGER NOT NULL,
+  PRIMARY KEY (app, collection, id)
+);
+CREATE TABLE IF NOT EXISTS app_roles (
+  app TEXT NOT NULL, role TEXT NOT NULL, player TEXT NOT NULL,
+  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,
+  PRIMARY KEY (app, role)
+);
+`;
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+const fail = (status, error) => json({ ok: false, error }, status);
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+async function bodyOf(request) {
+  const reader = request.body?.getReader();
+  if (!reader) return {};
+  let size = 0; const chunks = [];
+  for (;;) { const { done, value } = await reader.read(); if (done) break; size += value.length; if (size > 12_288) { await reader.cancel(); throw new Error('body too large'); } chunks.push(value); }
+  const bytes = new Uint8Array(size); let at = 0;
+  for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
+  return JSON.parse(new TextDecoder().decode(bytes) || '{}');
+}
+/** Private links conceal staff addresses; a signed-in grant is still required on every request. */
+export async function appAccess(request, env, meta, url) {
+  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' };
+  if (!declared.signIn) return { ok: true, role, can: declared.can };
+  if (!env.DB) return { ok: false, status: 503, error: 'app roles need the studio database' };
+  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' };
+  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' };
+  const grant = await env.DB.prepare('SELECT player FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3').bind(meta.id, role, person.id).first();
+  return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };
+}
+export async function appRecordsRoute(request, env, meta, url, sub) {
+  if (!sub.startsWith('api/app/')) return null;
+  if (!env.DB) return fail(503, 'app records need the studio database');
+  try {
+    if (sub === 'api/app/roles') {
+      const key = await ownerAllowed(request, env, { kinds: ['office'] });
+      if (!key && !(await isOwner(request, env))) return fail(403, 'owner only');
+      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);
+      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');
+        const p = await players.get(b.player, env);
+        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(meta.id, b.role, b.player).run();
+      }
+      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}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
+    }
+    const match = /^api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(sub);
+    if (!match || !Object.hasOwn(meta.records?.collections ?? {}, match[1])) return fail(404, 'unknown collection');
+    if (meta.records.persist !== true) return fail(409, 'use netplay state for transient records, or enable records.persist');
+    const access = await appAccess(request, env, meta, url);
+    if (!access.ok) return fail(access.status, access.error);
+    const [, collection, id] = match;
+    const op = ({ GET: 'read', POST: 'create', PUT: 'update', DELETE: 'delete' })[request.method];
+    if (!op || !access.can.includes(`${op}:${collection}`)) return fail(403, 'role cannot perform this operation');
+    if (op !== 'read' && !sameOrigin(request, url) && !(appOriginOf(request) && !meta.roles[access.role].signIn)) return fail(403, 'same origin required');
+    if (op === 'read') {
+      const rows = id ? [await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3').bind(meta.id, collection, id).first()].filter(Boolean)
+        : (await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 ORDER BY updated_at, id LIMIT 1000').bind(meta.id, collection).all()).results;
+      return json({ ok: true, records: rows.map((r) => ({ id: r.id, data: JSON.parse(r.value), version: r.version, updatedAt: r.updated_at })) });
+    }
+    if (!id) return fail(400, 'record id required');
+    const body = await bodyOf(request);
+    if (op !== 'delete') { const bad = recordProblem(meta.records.collections[collection], body.data, { create: op === 'create' }); if (bad) return fail(400, bad); }
+    if (op !== 'create' && (!Number.isSafeInteger(body.version) || body.version < 1)) return fail(400, 'record version required');
+    const stmt = op === 'create'
+      ? env.DB.prepare('INSERT OR IGNORE INTO app_records (app, collection, id, value, version, updated_at) SELECT ?1, ?2, ?3, ?4, 1, ?5 WHERE (SELECT COUNT(*) FROM app_records WHERE app = ?1 AND collection = ?2) < 1000').bind(meta.id, collection, id, JSON.stringify(body.data), Date.now())
+      : op === 'update' ? env.DB.prepare('UPDATE app_records SET value = ?4, version = version + 1, updated_at = ?5 WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?6').bind(meta.id, collection, id, JSON.stringify(body.data), Date.now(), body.version)
+      : env.DB.prepare('DELETE FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?4').bind(meta.id, collection, id, body.version);
+    const result = await stmt.run();
+    return result.meta.changes ? json({ ok: true, id, version: op === 'create' ? 1 : body.version + 1 }) : fail(409, 'record changed, already exists, or collection full; reload');
+  } catch (error) {
+    if (error instanceof SyntaxError || error.message === 'body too large') return fail(400, error.message);
+    return fail(503, 'app database unavailable; apply studio migrations');
+  }
+}

package/worker/app-shell.mjs

@@ -0,0 +1,29 @@
+/** Only the shell's own frame can ask; role and access come from the shell, never the message. */
+export const APP_SHELL_JS = String.raw`(function () {
+  var boot = window.__HOMIE_PLAY || window.__HOMIE_APP || window.__HOMIE_WATCH;
+  if (!boot || boot.kind !== 'app') return;
+  var frame = document.querySelector('iframe.game') || document.querySelector('iframe');
+  var params = new URLSearchParams(location.search);
+  var inflight = 0;
+  addEventListener('message', async function (e) {
+    var m = e.data;
+    if (frame && e.source === frame.contentWindow && m?.type === 'homie-app-ticket' && /^[a-f0-9]{32}$/.test(m.ticket)) { params.set('ticket', m.ticket); history.replaceState(null, '', location.pathname + '?' + params); return; }
+    if (!frame || e.source !== frame.contentWindow || !m || m.type !== 'homie-app' || !/^[a-f0-9]{32}$/.test(m.id || '')) return;
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(m.collection || '') || !['GET','POST','PUT','DELETE'].includes(m.method) || (m.record !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(m.record))) return;
+    var result;
+    if (inflight >= 8) result = { ok: false, error: 'too many requests' };
+    else {
+      inflight++;
+      try {
+        var q = new URLSearchParams();
+        ['role','surface','access'].forEach(function (k) { var v = params.get(k); if (v) q.set(k, v); });
+        if (boot.screen && !q.has('role')) q.set('surface', 'wall');
+        var path = (boot.site || '') + '/' + boot.game + '/api/app/records/' + m.collection + (m.record ? '/' + m.record : '') + '?' + q;
+        var res = await fetch(path, { method: m.method, headers: { 'content-type': 'application/json' }, body: m.method === 'GET' ? undefined : JSON.stringify({ data: m.data, version: m.version }) });
+        result = await res.json();
+      } catch (err) { result = { ok: false, error: 'records unavailable; reconnect and retry' }; }
+      finally { inflight--; }
+    }
+    e.source.postMessage({ type: 'homie-app-result', id: m.id, result: result }, '*');
+  });
+})();`;

package/worker/brain.mjs

@@ -1,3 +1,4 @@
+import { LIMITS } from './limits.mjs';
 /**
  * BRAINS (@homie-rocks/studio 0.17.0, NETPLAY.md section 18): what an AI guide decides, a few seconds at a time, and
  * only ever in the game's own words. Pure: no Worker import and no Node built-in, so the relay (room.mjs), the Table's
@@ -649,7 +650,7 @@ export async function clefDecide(env, { vocab, ctx = {}, model, ms = 8000, local
  *                                   8 questions; Choice 2 to 26 options, Score 2 to 10 levels, a yes/no; short words
  *   picksOf(answers, questions)     the answers as the game uses them: { tactic: 'surround', wave: false, pressure: 2.6 }
  */
-export const DECIDE = Object.freeze({ questions: 8, options: 26, levels: 10, words: 160, option: 40, stateBytes: 2048, bytes: 6144, gapMs: 3000, perMinute: 20, inFlight: 2, ms: 2500 });
+export const DECIDE = Object.freeze({ questions: 8, options: 26, levels: 10, words: 160, option: 40, stateBytes: 2048, bytes: LIMITS.decide, gapMs: 3000, perMinute: 20, inFlight: 2, ms: 2500 });
 const QID = /^[A-Za-z][A-Za-z0-9_.-]{0,39}$/;
 const OPT = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$/;
 

package/worker/embed.mjs

@@ -1,3 +1,4 @@
+import { appWords, openPath } from './app-format.mjs';
 /**
  * Player cards. X's reference: developer.x.com, "Cards: player card" (archived)
  * (redirects to docs.x.com/overview as checked 2026-10-08). Surviving official sample:
@@ -71,7 +72,8 @@ export function httpsAddress(value, origin) {
   try { const u = new URL(value, origin); return u.protocol === 'https:' && !u.username && !u.password ? u.href : null; } catch { return null; }
 }
 export function playerProperties(cat, game, { origin = '', title = game?.name, description = game?.blurb } = {}) {
-  const player = httpsAddress(`/${game?.id}/play/embed`, origin);
+  if (!game) return {};
+  const player = httpsAddress(`${openPath(game)}/embed`, origin);
   const measured = game?.playerImage;
   const picture = measured && httpsAddress(measured.src, origin);
   // twitter:site goes out when the studio has set its handle; a card is never withheld for the lack of one
@@ -80,7 +82,7 @@ export function playerProperties(cat, game, { origin = '', title = game?.name, d
   if (!playerEnabled(cat, game) || !player || !picture || playerImageRule(measured)) return {};
   return { ...(handle ? { 'twitter:site': handle } : {}), 'twitter:card': 'player', 'twitter:player': player, 'twitter:player:width': PLAYER_SIZE.width,
     'twitter:player:height': PLAYER_SIZE.height, 'twitter:image': picture, 'twitter:title': title,
-    'twitter:description': String(description || `Play ${game.name} in your browser.`).slice(0, 200) };
+    'twitter:description': String(description || `${appWords(game).open} ${game.name} in your browser.`).slice(0, 200) };
 }
 
 /** Browser restrictions belong to the outer host; failures must not kill a game's input loop.

package/worker/hosted.mjs

@@ -49,7 +49,7 @@ export function compiledFor(id) {
  */
 export function startHost(game, { send, log, onPause, onResume, onEnd, ...recovery }) {
   return createHost({
-    game, build: games.get(game)?.build ?? undefined, compiled: compiledFor(game), send, log, onPause, onResume, onEnd,
+    enforceOverrun: true, game, build: games.get(game)?.build ?? undefined, compiled: compiledFor(game), send, log, onPause, onResume, onEnd,
     clock: { now: () => Date.now(), setTimer: (fn, ms) => setTimeout(fn, ms), clearTimer: (h) => clearTimeout(h) },
     ...recovery,
   });