@origingame/engine 0.2.0 → 0.4.0

package/src/ui-kit/store.ts

@@ -4,7 +4,7 @@
 
 import type * as Api from "@origingame/engine";
 import { kit } from "./bind.ts";
-import { capsule, fit, fmt, frame, grow, iconOr, px, token } from "./util.ts";
+import { hudBox, fit, fmt, frame, grow, iconOr, px, token } from "./util.ts";
 
 /** A screen panel: a dialog over the game, wide on desktop, full width on a phone. With `scrim` a press on the backdrop closes it too. */
 function screen(id: string, title: string, width: number, build: () => void, scrim = false): boolean {
@@ -16,7 +16,7 @@ function screen(id: string, title: string, width: number, build: () => void, scr
 /** An item's picture: its icon, else its initial on the slot. */
 function picture(id: string, icon: string | undefined, name: string, size: number): void {
   if (icon && kit.hasIcon(icon)) kit.icon(id, icon, { size });
-  else kit.label(id, name.slice(0, 1).toUpperCase(), { step: "xl2", font: "display", color: token("fgMuted"), nowrap: true });
+  else kit.label(id, name.slice(0, 1).toUpperCase(), { step: "xl2", font: "display", color: token("inkMuted"), nowrap: true });
 }
 
 export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult {
@@ -37,10 +37,10 @@ export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult
       } else {
         kit.spacer("Gap", null);
       }
-      capsule("Balance", () => {
-        if (desc.currencyIcon) iconOr("Icon", desc.currencyIcon, 18, token("accent"));
+      hudBox("Balance", () => {
+        if (desc.currencyIcon) iconOr("Icon", desc.currencyIcon, 18, token("gold"));
         kit.counter("Amount", balance, { font: "mono", step: "base" });
-        kit.label("Unit", desc.currency ?? "coins", { step: "base", color: token("fgMuted"), nowrap: true });
+        kit.label("Unit", desc.currency ?? "coins", { step: "base", color: token("inkMuted"), nowrap: true });
       });
     });
     const body = (): void => {
@@ -49,17 +49,17 @@ export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult
         picture("Picture", it.icon, it.name ?? "", 36);
         kit.label("Name", it.name ?? "", { step: "base", nowrap: true });
         if (it.owned) kit.badge("Owned", desc.ownedLabel ?? "Owned", "success");
-        else kit.label("Price", fmt(it.price ?? 0), { step: "meta", font: "mono", color: token(balance >= (it.price ?? 0) ? "accentInk" : "fgSubtle"), nowrap: true });
+        else kit.label("Price", fmt(it.price ?? 0), { step: "meta", font: "mono", color: token(balance >= (it.price ?? 0) ? "highlight" : "inkFaint"), nowrap: true });
       });
       if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
       const it = items[sel];
       kit.column("Detail", { width: phone ? grow() : px(220), gap: t.sm }, () => {
         if (!it) {
-          kit.label("Empty", desc.emptyLabel ?? "Nothing for sale here", { color: token("fgMuted") });
+          kit.label("Empty", desc.emptyLabel ?? "Nothing for sale here", { color: token("inkMuted") });
           return;
         }
         kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
-        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("inkMuted"), width: grow() });
         kit.keyValue("Price", desc.priceLabel ?? "Price", `${fmt(it.price ?? 0)} ${desc.currency ?? "coins"}`, true);
         const short = balance < (it.price ?? 0);
         // Short of the price, Buy still answers: it refuses, shaking with the error sound.
@@ -101,7 +101,7 @@ export function inventoryScreen(id: string, desc: Api.InventoryDesc = {}): Api.I
         const it = bySlot.get(i);
         if (!it) return;
         picture("Picture", it.icon, it.name ?? "", cell * 0.5);
-        if ((it.count ?? 0) > 1) kit.label("Count", `${it.count}`, { step: "xs", font: "mono", color: token("fgMuted"), nowrap: true });
+        if ((it.count ?? 0) > 1) kit.label("Count", `${it.count}`, { step: "xs", font: "mono", color: token("inkMuted"), nowrap: true });
       });
       if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
       if (g.dropFrom !== null && g.dropFrom !== undefined && g.dropTo !== null && g.dropTo !== undefined && bySlot.has(g.dropFrom)) {
@@ -111,11 +111,11 @@ export function inventoryScreen(id: string, desc: Api.InventoryDesc = {}): Api.I
       const it = sel >= 0 ? bySlot.get(sel) : undefined;
       kit.column("Detail", { width: phone ? grow() : px(200), gap: t.sm }, () => {
         if (!it) {
-          kit.label("Hint", desc.hintLabel ?? "Select an item. Drag it to another slot to move it.", { step: "meta", color: token("fgMuted"), width: grow() });
+          kit.label("Hint", desc.hintLabel ?? "Select an item. Drag it to another slot to move it.", { step: "meta", color: token("inkMuted"), width: grow() });
           return;
         }
         kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
-        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("inkMuted"), width: grow() });
         if ((it.count ?? 0) > 1) kit.keyValue("Count", desc.countLabel ?? "Count", `${it.count}`, true);
         if (desc.useLabel !== "") {
           if ((kit.button("Use", desc.useLabel ?? "Use", { variant: "primary", width: grow() }) as Api.Response).clicked) out.used = it.id ?? null;
@@ -143,8 +143,8 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
   // Back from every input: the button, a press on the scrim, Escape, B.
   out.closed = screen(id, desc.title ?? "Levels", 720, () => {
     kit.row("Total", { gap: t.xs, cross: "center" }, () => {
-      iconOr("Star", "star", 18, token("accent"), starsLabel(earned, levels.length * 3));
-      kit.label("Count", `${earned} / ${levels.length * 3}`, { font: "mono", color: token("fgMuted"), nowrap: true });
+      iconOr("Star", "star", 18, token("primary"), starsLabel(earned, levels.length * 3));
+      kit.label("Count", `${earned} / ${levels.length * 3}`, { font: "mono", color: token("inkMuted"), nowrap: true });
     });
     // A numeral is the card's face, in display type on a square card; a
     // name takes a wider card and a smaller step, wrapped to two lines (cut
@@ -157,14 +157,14 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
       const l = levels[i]!;
       const name = l.name ?? `${i + 1}`;
       if (l.locked) {
-        iconOr("Lock", "lock", 28, token("fgSubtle"), (desc.lockedLabel ?? "{name}, locked").replaceAll("{name}", name));
+        iconOr("Lock", "lock", 28, token("inkFaint"), (desc.lockedLabel ?? "{name}, locked").replaceAll("{name}", name));
         return;
       }
       if ([...name].length > 3) kit.label("Name", name, { step: phone ? "base" : "lg", font: "display", align: "center", width: grow(), maxLines: 2, ellipsis: true });
       else kit.label("Name", name, { step: "xl3", font: "display", nowrap: true });
       const stars = Math.min(3, l.stars ?? 0);
       kit.row("Stars", { gap: 2 }, () => {
-        for (let k = 0; k < 3; k++) iconOr(kit.idi("Star", k), "star", 14, token(k < stars ? "accent" : "fillStrong"), k === 0 ? starsLabel(stars, 3) : "");
+        for (let k = 0; k < 3; k++) iconOr(kit.idi("Star", k), "star", 14, token(k < stars ? "primary" : "controlStrong"), k === 0 ? starsLabel(stars, 3) : "");
       });
     });
     if (g.clicked !== null && g.clicked !== undefined && !levels[g.clicked]?.locked) out.chosen = g.clicked;
@@ -176,7 +176,7 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
   return out;
 }
 
-const MEDALS: readonly Api.ThemeColor[] = ["warn", "fgMuted", "accentInk"];
+const MEDALS: readonly Api.ThemeColor[] = ["warn", "inkMuted", "highlight"];
 
 export function leaderboardScreen(id: string, desc: Api.LeaderboardDesc = {}): Api.LeaderboardResult {
   const { t, phone } = frame();
@@ -203,14 +203,14 @@ export function leaderboardScreen(id: string, desc: Api.LeaderboardDesc = {}): A
       });
     } else if (entries.length === 0) {
       kit.column("Empty", { width: grow(), height, align: "center", cross: "center" }, () => {
-        kit.label("Message", desc.empty ?? "No scores yet", { color: token("fgMuted"), align: "center", width: grow() });
+        kit.label("Message", desc.empty ?? "No scores yet", { color: token("inkMuted"), align: "center", width: grow() });
       });
     } else {
       const player = entries.findIndex((e) => e.player);
       kit.list("Rows", { count: entries.length, rowHeight: t.row, height, width: grow(), selected: player >= 0 ? player : null }, (i) => {
         const e = entries[i]!;
         const rank = e.rank ?? i + 1;
-        kit.label("Rank", `${rank}`, { width: px(40), font: "mono", step: rank <= 3 ? "lg" : "body", color: token(rank <= 3 ? MEDALS[rank - 1]! : "fgMuted"), nowrap: true });
+        kit.label("Rank", `${rank}`, { width: px(40), font: "mono", step: rank <= 3 ? "lg" : "body", color: token(rank <= 3 ? MEDALS[rank - 1]! : "inkMuted"), nowrap: true });
         kit.label("Name", e.name ?? "", { width: grow(), nowrap: true });
         kit.label("Score", e.score ?? "", { font: "mono", nowrap: true });
       });

package/src/ui-kit/story.ts

@@ -15,8 +15,10 @@ export function cutscene(id: string, desc: Api.CutsceneDesc = {}): Api.CutsceneR
   kit.setNavigation(true);
   const letterbox = desc.letterbox ?? true;
   if (letterbox) {
+    // Cinematic bars are black in every style: not a token, which a light
+    // style (kestrel's paper) would turn into cream panels.
     for (const [name, anchor] of [["Top", "top"], ["Bottom", "bottom"]] as const) {
-      kit.anchor(`${id}.${name}`, { anchor, margin: 0, width: grow(), height: pct(0.1), background: token("stage") }, () => {});
+      kit.anchor(`${id}.${name}`, { anchor, margin: 0, width: grow(), height: pct(0.1), background: { color: { r: 0, g: 0, b: 0 } } }, () => {});
     }
   }
   const line = lines[index]!;
@@ -68,13 +70,13 @@ export function tutorialOverlay(id: string, desc: Api.TutorialDesc = {}): Api.Tu
     direction: "column",
     gap: t.sm,
     padding: all(t.lg),
-    background: token("surfaceRaised"),
+    background: token("panelRaised"),
     radius: t.panel,
   }, () => {
     const count = (desc.stepLabel ?? "{step} of {count}").replaceAll("{step}", `${index + 1}`).replaceAll("{count}", `${steps.length}`);
-    kit.label("Count", count, { step: "meta", color: token("fgMuted") });
+    kit.label("Count", count, { step: "meta", color: token("inkMuted") });
     if (step.title) kit.label("Title", step.title, { step: "lg", width: grow() });
-    if (step.text) kit.label("Text", step.text, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (step.text) kit.label("Text", step.text, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), gap: t.sm, align: "spaceBetween", cross: "center" }, () => {
       if ((kit.button("Skip", desc.skipLabel ?? "Skip", { variant: "quiet", size: "small" }) as Api.Response).clicked) out.skipped = true;
       const lastStep = index + 1 >= steps.length;

package/src/ui-kit/util.ts

@@ -1,5 +1,5 @@
 // Small helpers the screen templates share: sizes, insets, the frame's
-// tokens, number and time formats, and HUD capsules. Nothing here keeps
+// tokens, number and time formats, and HUD boxes. Nothing here keeps
 // state: what must persist lives in the UI's memory (og.ui.memory).
 
 import type * as Api from "@origingame/engine";
@@ -25,7 +25,7 @@ export function frame(): { theme: Api.UiTheme; viewport: Api.Viewport; t: Tokens
 
 export interface Tokens {
   xxs: number; xs: number; sm: number; md: number; lg: number; xl: number; xxl: number; xl3: number;
-  card: number; panel: number; block: number; button: number;
+  small: number; control: number; bar: number; panel: number;
   controlSm: number; controlMd: number; controlLg: number; gutter: number; row: number;
 }
 
@@ -34,7 +34,7 @@ function tokens(t: Api.UiTheme): Tokens {
   const r = (k: string): number => t.radius[k] ?? 0;
   return {
     xxs: s("xxs"), xs: s("xs"), sm: s("sm"), md: s("md"), lg: s("lg"), xl: s("xl"), xxl: s("xxl"), xl3: s("xl3"),
-    card: r("card"), panel: r("panel"), block: r("block"), button: r("button"),
+    small: r("small"), control: r("control"), bar: r("bar"), panel: r("panel"),
     controlSm: t.sizes.controlSm, controlMd: t.sizes.controlMd, controlLg: t.sizes.controlLg, gutter: t.sizes.gutter, row: t.sizes.row,
   };
 }
@@ -73,17 +73,17 @@ export function lapTime(seconds: number): string {
   return `${m}:${s.toString().padStart(2, "0")}.${(ms % 1000).toString().padStart(3, "0")}`;
 }
 
-/** A HUD capsule: a translucent dark pill (material-thick) that keeps text legible over any art. */
-export function capsule(id: string, build: () => void, desc: { gap?: number; padX?: number; height?: number } = {}): Api.Response {
+/** A HUD box: the style's `hud` fill and frame, cornered by its control radius, that keeps text legible over any art. */
+export function hudBox(id: string, build: () => void, desc: { gap?: number; padX?: number; height?: number } = {}): Api.Response {
   const { t } = frame();
   return kit.row(id, {
     padding: xy(desc.padX ?? t.md, 0),
     height: px(desc.height ?? t.controlMd),
     gap: desc.gap ?? t.sm,
     cross: "center",
-    background: token("materialThick"),
-    radius: t.button,
-    frame: "capsule",
+    background: token("hud"),
+    radius: t.control,
+    frame: "hud",
   }, build) as Api.Response;
 }
 

package/src/web/shell.ts

@@ -30,6 +30,7 @@ import { laneChoice } from "./lanes.ts";
 import { createRpcRings, readFrames, waitForFrames, writeFrame, type RpcRings } from "./rpc-ring.ts";
 import { localPlatform, storagePersistence, type PlatformCall, type PlatformHost } from "../platform-local.ts";
 import type { BootPhases } from "./worker.ts";
+import type { TraceDocument } from "../trace.ts";
 
 export interface ShellOptions {
   /** The play surface. Its pixel size is set from its CSS size and the device pixel ratio. */
@@ -78,6 +79,8 @@ export interface ShellOptions {
   readonly locale?: string;
   /** What answers og.platform's calls; default: the browser's own storage (`setPlatform` changes it, a Player bridge for instance). */
   readonly platform?: PlatformHost;
+  /** Record the run's trace from the boot on, the boot scene's loads included (`trace()` reads it; `trace("start")` begins one later). */
+  readonly trace?: boolean;
 }
 
 /** The pixel size of a canvas laid out at `cssWidth`×`cssHeight` on this display, with the DPR cap. */
@@ -93,6 +96,17 @@ export const PAGE_PREFERENCES = [
   ["reducedTransparency", "(prefers-reduced-transparency: reduce)"],
 ] as const;
 
+/**
+ * What carries og.platform's rooms on the web (docs/design.md §2.8): the engine's room ops
+ * (`{ op: "create" | "join" | "leave" | "send", ... }`, og-net's protocol) in, its room events
+ * (`joined`, `peer_joined`, `peer_left`, `message`, `left`, `error`) out, in order.
+ */
+export interface RoomHost {
+  /** og.platform.roomInfo's `host`: `player` for the Player's rooms. */
+  readonly host: string;
+  handle(ops: readonly Record<string, unknown>[], deliver: (events: unknown[]) => void): void;
+}
+
 /** The page's motion, contrast and transparency preferences and the platform's editing keys, as the viewport carries them to og-ui. */
 export function pagePreferences(): { reducedMotion: boolean; highContrast: boolean; reducedTransparency: boolean; macKeys: boolean } {
   const query = (q: string) => globalThis.matchMedia?.(q).matches ?? false;
@@ -203,6 +217,7 @@ export class Shell {
   /** When the deadline was last looked at: a late look means the page itself was blocked. */
   #watched = 0;
   #watchdog: ReturnType<typeof setInterval> | undefined;
+  #rooms: RoomHost | null = null;
   #platform: PlatformHost = localPlatform(storagePersistence(`og.platform:${globalThis.location?.pathname ?? "/"}`));
 
   private constructor(worker: Worker, ready: Ready, rpc: RpcRings | undefined) {
@@ -250,6 +265,14 @@ export class Shell {
         this.#answer(m.frame);
         return;
       }
+      if (m.type === "room") {
+        const ops = (m as unknown as { ops: Record<string, unknown>[] }).ops ?? [];
+        const deliver = (events: unknown[]) => worker.postMessage({ type: "room-events", events });
+        if (this.#rooms) this.#rooms.handle(ops, deliver);
+        // No room host: what asked for a room hears so (the engine refuses first while its host is none).
+        else deliver(ops.filter((o) => o["op"] === "create" || o["op"] === "join").map((o) => ({ type: "error", op: o["op"], code: "unavailable", message: "this page carries no rooms" })));
+        return;
+      }
       if (m.type === "platform") {
         const calls = (m as unknown as { calls: PlatformCall[] }).calls ?? [];
         this.#platform.handle(calls, (request, answer) => worker.postMessage({ type: "platform-answer", request, answer }));
@@ -347,6 +370,7 @@ export class Shell {
         locale: options.locale ?? globalThis.navigator?.language,
         ...(options.expect ? { expect: options.expect } : {}),
         ...(options.prime ? { prime: true } : {}),
+        ...(options.trace ? { trace: true } : {}),
         viewport: { width: canvas.clientWidth || canvas.width / dpr, height: canvas.clientHeight || canvas.height / dpr, dpr, coarsePointer: globalThis.matchMedia?.("(pointer: coarse)").matches ?? false, ...pagePreferences() },
       },
       [offscreen],
@@ -416,6 +440,27 @@ export class Shell {
   }
 
   /** Call the engine in the Worker: `advance`, `command`, `hash`, `frame`, or `probe` with a member name. */
+  /**
+   * The run's trace in the Chrome trace format, as `og run --trace` writes it natively (src/trace.ts):
+   * buffered in the engine Worker, taken here. `take` (the default) answers the document so far (null
+   * when no trace is recorded), `start` begins one (`ShellOptions.trace` starts one at the boot),
+   * `stop` ends it.
+   */
+  trace(action: "take" | "start" | "stop" = "take"): Promise<TraceDocument | null | boolean> {
+    return this.call("trace", action) as Promise<TraceDocument | null | boolean>;
+  }
+
+  /** Saves the trace so far as a JSON file the browser downloads (`name`, default `trace.json`): open it in Perfetto. False when none is recorded. */
+  async saveTrace(name = "trace.json"): Promise<boolean> {
+    const doc = await this.trace("take");
+    if (!doc || typeof doc !== "object") return false;
+    const url = URL.createObjectURL(new Blob([JSON.stringify(doc)], { type: "application/json" }));
+    const a = Object.assign(document.createElement("a"), { href: url, download: name });
+    a.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+    return true;
+  }
+
   call(method: string, ...args: unknown[]): Promise<unknown> {
     if (this.#stopped) return Promise.reject(this.#stopped);
     const id = this.#next++;
@@ -425,10 +470,23 @@ export class Shell {
     });
   }
 
+  /**
+   * What carries og.platform's rooms from now on (og.platform.roomInfo's `host`); null for
+   * none, where roomCreate and roomJoin are refused. A host already carrying a room keeps it
+   * until its `left`: the engine is told the new host only for its next room. `link` is the room
+   * a Play link named (`?room=<id>`, the play page passes it): the engine joins it once, itself,
+   * as soon as a host carries rooms (og.RoomJoined answers, as for roomJoin; with none it says
+   * this page carries no rooms), and og.platform.roomInfo's `link` names it.
+   */
+  setRooms(host: RoomHost | null, link?: string): void {
+    this.#rooms = host;
+    this.worker.postMessage({ type: "room-host", host: host ? host.host : "none", ...(link ? { join: link } : {}) });
+  }
+
   /** What answers og.platform's calls from now on (og.platform.info reports its host and capabilities). */
   setPlatform(host: PlatformHost): void {
     this.#platform = host;
-    this.worker.postMessage({ type: "platform-host", host: host.host, capabilities: host.capabilities });
+    this.worker.postMessage({ type: "platform-host", host: host.host, capabilities: host.capabilities, time: host.time });
   }
 
   /** What stopped the engine (a panic, an error, a hang), or null while it runs. */

package/src/web/worker.ts

@@ -44,7 +44,7 @@
 // Worker's animation frames while the clock played, so isolated pages never
 // answered.
 
-import { createEngine, systemClock, type Engine, type GameToken } from "../runtime.ts";
+import { boundHost, createEngine, systemClock, type Engine, type GameToken } from "../runtime.ts";
 import type { PlatformAnswer, PlatformHost } from "../platform-local.ts";
 import { loadWebHost, type WebGlue } from "./host.ts";
 import { drainRing, stampAt, type InjectedInput } from "./input.ts";
@@ -53,6 +53,7 @@ import { readFrames, waitForFrames, writeFrame, type RpcRings } from "./rpc-ring
 import { loadBasisTranscoder, transcodeKtx2, TEXTURE_FORMATS, type BasisTranscoder, type TextureFormat } from "./basis.ts";
 import type { HostError } from "./shell.ts";
 import { PlatformCounter, settle, SETTLE_FIRST_MS, SETTLE_MS } from "./settle.ts";
+import { Trace, unixMs } from "../trace.ts";
 
 interface Start {
   type: "start";
@@ -92,6 +93,8 @@ interface Start {
    * game's first screen (its UI is built by ticks), then the ticks that apply the platform's answers to it (settle.ts).
    */
   prime?: boolean;
+  /** Record the run's trace from the boot on (src/trace.ts; the shell's `trace()` reads it). */
+  trace?: boolean;
 }
 
 type Viewport = { width: number; height: number; dpr: number; safeArea?: Record<string, number>; covered?: Record<string, number>; coarsePointer?: boolean; reducedMotion?: boolean; highContrast?: boolean; reducedTransparency?: boolean; macKeys?: boolean };
@@ -112,10 +115,27 @@ type Message =
   | { type: "viewport"; viewport: Viewport }
   | { type: "resize"; width: number; height: number; viewport: Viewport }
   | { type: "platform-answer"; request: number; answer: PlatformAnswer }
-  | { type: "platform-host"; host: string; capabilities: string[] }
+  | { type: "platform-host"; host: string; capabilities: string[]; time?: number }
+  | { type: "room-events"; events: unknown[] }
+  | { type: "room-host"; host: string; join?: string }
   | AudioMessage
   | AudioLatencyMessage;
 
+/**
+ * Rooms (docs/design.md §2.8): the engine's room ops (og_room_take) go to the
+ * page as `room` messages, which the shell's room host carries (the Player's
+ * room.*, docs/platform-asks.md #16); the page's `room-events` come back
+ * through og_room_deliver, in order, and `room-host` names what carries them.
+ * Ops are taken after every frame and after events are delivered, so
+ * lockstep's inputs leave on the frame that made them.
+ */
+function pumpRoom(engine: Engine): void {
+  const host = boundHost();
+  if (!host) return;
+  const ops = JSON.parse(host.abi.og_room_take(engine.id)) as unknown[];
+  if (ops.length > 0) self.postMessage({ type: "room", ops });
+}
+
 /** og.platform's host in the Worker: the calls go to the page (counted), whose answers come back as `platform-answer`. */
 function toPage(host: string, capabilities: readonly string[], counter: PlatformCounter): PlatformHost {
   return {
@@ -159,12 +179,21 @@ export interface WebExtras {
   og_web_memory?(engine: number): string;
   /** Make one pipeline no frame used yet (og-render's Renderer::warm); false when none is left. */
   og_web_warm?(engine: number): boolean;
+  /** `og render`'s every-frame capture (development builds): the display frame drawn last as RGBA8 rows at the canvas's size; empty until its readback lands. */
+  og_web_render_frame?(engine: number): Uint8Array;
   /** The first Rust panic recorded (JSON: kind, message, location, tick, lane), or `null`. */
   og_web_panic?(): string;
   /** Test hook: the next item at a lanes site panics (in a lane when the call splits). */
   og_web_lanes_fault?(site: string): boolean;
+  /** The trace (crates/og-runtime/src/trace.rs): on or off for an engine (0xffffffff: the loads before one exists). */
+  og_web_trace?(engine: number, on: boolean): void;
+  /** The trace's spans since the last take: `{ now, events }`, Chrome trace events on the engine's clock. */
+  og_web_trace_take?(engine: number, last: boolean): string;
 }
 
+/** The trace's key for loads made before the engine exists (og-runtime's `BEFORE_ENGINE`). */
+const TRACE_BEFORE_ENGINE = 0xffffffff;
+
 /** Where the runtime asks for a bundle's files: `<root>/cooked/<file>` (crates/og-runtime/src/assets.rs). */
 export function cookedDir(root: string): string {
   return `${root.replace(/\/+$/, "")}/cooked`;
@@ -514,6 +543,9 @@ export function startWorker(game: GameToken): void {
     phaseAt = now;
   };
   const firstFrameMessage = () => ({ type: "frame", first: true, boot: { ...boot, at: Math.round(performance.now()) } });
+  /** What the trace's document records beside its events: the renderer's tier and the lanes. */
+  let lastTier = "none";
+  let lanesState: unknown = null;
   let glueRef: (WebGlue & WebExtras & WebAudioGlue) | null = null;
   let audio: WorkerAudio | null = null;
   /** Captures waiting for their readback (requested on tick N, answered on N + 1). */
@@ -592,7 +624,21 @@ export function startWorker(game: GameToken): void {
   };
 
   /** What a frame's answer tells the shell: the UI's focused text control (text-input.ts), a copy, and the accessibility tree when it changed (a11y.ts). */
+  /** The run's trace while one is recorded (src/trace.ts): taken after every frame, so the engine holds a frame's spans at most. */
+  let trace: Trace | null = null;
+  const takeTrace = (last = false) => {
+    if (!trace || !engine || !glueRef?.og_web_trace_take) return;
+    trace.append(glueRef.og_web_trace_take(engine.id, last), unixMs());
+  };
+  const traceOn = (on: boolean) => {
+    if (!engine || !glueRef?.og_web_trace) return false;
+    if (on && !trace) trace = new Trace({ producer: "og web trace", process: "og web" });
+    if (!on) trace = null;
+    glueRef.og_web_trace(engine.id, on);
+    return true;
+  };
   const relay = (answered: ReturnType<Engine["frame"]>) => {
+    takeTrace();
     if (!answered.ok) return;
     const target = JSON.stringify(answered.text ?? null);
     if (target !== textTarget) {
@@ -676,6 +722,7 @@ export function startWorker(game: GameToken): void {
         }
         behind = answered.behind ?? 0;
         relay(answered);
+        pumpRoom(engine);
         if (typeof answered.tick === "number") lastTick = answered.tick;
         if (!firstFrame && answered.rendered !== false) {
           firstFrame = true;
@@ -777,11 +824,25 @@ export function startWorker(game: GameToken): void {
   };
 
   const calls: Record<string, (e: Engine, args: unknown[]) => unknown> = {
-    advance: (e, [n]) => e.advance(Number(n)),
+    // A harness's ticks carry the room as the page's own frames do: lockstep's inputs leave with them.
+    advance: (e, [n]) => {
+      const answered = e.advance(Number(n));
+      pumpRoom(e);
+      return answered;
+    },
     command: (e, [action, args]) => e.command(String(action), (args as string[]) ?? []),
     hash: (e) => e.hash(),
     /** What the engine holds (ProbeMemory: the wasm linear memory, the counted heap, the world, streaming, audio), in every build. */
     memory: (e) => JSON.parse(glueRef?.og_web_memory?.(e.id) ?? "null"),
+    /**
+     * The display frame drawn last as RGBA8 rows (the probe's Capture::frame,
+     * `og render`'s every-frame capture), or null until its readback lands: the
+     * first call turns the keeping of frames on; ask again before the next frame.
+     */
+    renderFrame: (e) => {
+      const rgba = glueRef?.og_web_render_frame?.(e.id);
+      return rgba && rgba.length > 0 ? rgba : null;
+    },
     /** What the lanes did so far (crates/og-runtime/src/lanes.rs `report`). */
     lanes: () => JSON.parse(glueRef?.og_web_lanes?.() ?? "null"),
     /** Test hook: the next item at lanes site `site` panics (og_web_lanes_fault); false when the module has no such hook or site. */
@@ -789,8 +850,14 @@ export function startWorker(game: GameToken): void {
     frame: (e, [ms]) => {
       const answered = e.frame(Number(ms));
       relay(answered);
+      pumpRoom(e);
       return answered;
     },
+    /** og.net on this page: og.net.status (lockstep running, its start tick, the seats, the first divergent tick) and the shared hash, as `og run --json` reports them natively (`lockstep`, `netHash`). */
+    net: (e) => {
+      const abi = boundHost()!.abi;
+      return { status: JSON.parse(abi.og_net_status(e.id)), hash: JSON.parse(abi.og_net_hash(e.id)), room: JSON.parse(abi.og_platform_room_info(e.id)) };
+    },
     // The frames played since the last reset (at most FRAME_RECORDS, oldest first); `true` resets.
     timings: (_, [reset]) => {
       const n = Math.min(recorded, FRAME_RECORDS);
@@ -799,6 +866,22 @@ export function startWorker(game: GameToken): void {
       if (reset) recorded = 0;
       return answer;
     },
+    /**
+     * The run's trace (src/trace.ts): `start` begins one (dropping any), `stop` ends it, `take` (the
+     * default) answers the document so far, a Chrome trace as `og run --trace` writes it; null when
+     * none is recorded or the module cannot trace.
+     */
+    trace: (_, [action]) => {
+      const a = String(action ?? "take");
+      if (a === "start") {
+        traceOn(false);
+        return traceOn(true);
+      }
+      if (a === "stop") return traceOn(false);
+      if (!trace) return null;
+      takeTrace(true);
+      return trace.document({ tier: lastTier, lanes: lanesState });
+    },
     probe: (e, [member, ...rest]) => {
       const f = (e.probe as unknown as Record<string, unknown>)[String(member)];
       if (typeof f !== "function") throw new TypeError(`probe has no member '${String(member)}'`);
@@ -870,6 +953,8 @@ export function startWorker(game: GameToken): void {
           installFetcher(glue, fetched.manifest ?? "", data.basis, () => (rendering && engine ? engine.id : null));
         }
         phase("bundle");
+        // A trace from the boot on records the boot scene's loads too.
+        if (data.trace) glue.og_web_trace?.(TRACE_BEFORE_ENGINE, true);
         const created = createEngine(game, {
           ...(data.seed === undefined ? {} : { seed: data.seed }),
           ...(data.root === undefined ? {} : { root: data.root }),
@@ -881,6 +966,10 @@ export function startWorker(game: GameToken): void {
         });
         if (!created.ok) throw new Error(created.reason);
         engine = created.value;
+        if (data.trace) {
+          traceOn(true);
+          glue.og_web_trace?.(TRACE_BEFORE_ENGINE, false);
+        }
         // og.platform: calls go to the page, which answers them (the Player, or the browser's storage).
         // The time is the browser's until the Player's answers carry its own (docs/platform-asks.md).
         engine.setClock(systemClock("browser"));
@@ -896,6 +985,8 @@ export function startWorker(game: GameToken): void {
           rendering = true;
         }
         phase("attach");
+        lastTier = tier;
+        lanesState = lanes;
         // The textures go to the renderer's encodings, so after it is attached (the game starts later).
         const loaded = fetched ? await transcodeBundle(glue, rendering ? engine.id : null, fetched, data.basis, progress, data.expect ? received : undefined) : null;
         phase("transcode");
@@ -982,7 +1073,17 @@ export function startWorker(game: GameToken): void {
       engine.answerPlatform(data.request, data.answer);
       platformCounter.answered();
     }
-    if (data.type === "platform-host") engine.attachPlatform(toPage(data.host, data.capabilities, platformCounter));
+    if (data.type === "platform-host") engine.attachPlatform({ ...toPage(data.host, data.capabilities, platformCounter), time: data.time });
+    if (data.type === "room-host") {
+      boundHost()?.abi.og_room_set_host(engine.id, JSON.stringify({ host: data.host, ...(data.join ? { join: data.join } : {}) }));
+      // A Play link's join leaves now, not with the next frame (the page may be behind its gate).
+      pumpRoom(engine);
+    }
+    if (data.type === "room-events") {
+      const abi = boundHost()?.abi;
+      for (const event of data.events) abi?.og_room_deliver(engine.id, JSON.stringify(event));
+      pumpRoom(engine);
+    }
     if (data.type === "play") {
       playing = data.on;
       last = 0;