@origingame/engine 0.0.0-stage → 0.1.1

package/src/web/host.ts

@@ -0,0 +1,166 @@
+// The web host binding: the wasm-bindgen module of crates/og-host-web
+// (origin-engine.js + origin-engine_bg.wasm, `--target web`). Column views
+// are typed arrays over the module's `memory.buffer` at the byte offsets the
+// host answers, so a system writes engine memory directly. Runs in the engine
+// Worker (worker.ts) and anywhere else wasm runs (the cross-host test runs it
+// under bun).
+
+import { ARRAYS, bindHost, boundHost, type ColumnArray, type HostBinding } from "../runtime.ts";
+import type { HostAbi } from "../generated/abi.ts";
+import bindings from "../../types/bindings.json" with { type: "json" };
+
+interface CallDecl {
+  readonly symbol: string;
+  readonly module: string;
+  readonly returns: string;
+  readonly publish: boolean;
+}
+
+/**
+ * A publish build exports only the player-facing members (the commands
+ * module and the probe's other members are compiled out). The runtime binds
+ * every symbol, so each missing non-publish symbol answers its refusal: the
+ * probe's `null` (or `false`), a command's `{ ok: false }`.
+ */
+export function withPublishRefusals(glue: Record<string, unknown>): Record<string, unknown> {
+  const missing = (bindings.calls as CallDecl[]).filter((c) => !c.publish && typeof glue[c.symbol] !== "function");
+  if (missing.length === 0) return glue;
+  const out: Record<string, unknown> = { ...glue };
+  const reason = JSON.stringify({ ok: false, reason: "not in a publish build: the command channel and the probe's development members are compiled out" });
+  for (const c of missing) {
+    const answer: unknown =
+      c.returns === "bool" ? false
+      : c.returns === "u32" || c.returns === "i32" ? 0
+      : c.returns.startsWith("List<") ? "[]"
+      : c.module === "probe" ? "null"
+      : reason;
+    out[c.symbol] = () => answer;
+  }
+  return out;
+}
+
+/** The wasm-bindgen glue module: its default export initialises it. */
+export interface WebGlue extends Record<string, unknown> {
+  default(input?: { module_or_path: unknown }): Promise<{ memory: WebAssembly.Memory }>;
+  og_web_init(): void;
+  /** The lanes variant only (wasm-bindgen-rayon): starts `threads` Workers sharing the module's memory. */
+  initThreadPool?(threads: number): Promise<unknown>;
+  /** The lanes variant only: lanes run on the pool from now on (crates/og-lanes). */
+  og_lanes_ready?(threads: number): void;
+}
+
+/**
+ * How long the lanes pool may take to start. wasm-bindgen-rayon waits for
+ * each pool Worker's ready message with no timeout and no error handler, so
+ * a Worker that never loads (a `worker-src` that refuses `blob:`, a failed
+ * module import inside it) would otherwise hang the boot.
+ */
+export const LANES_POOL_DEADLINE_MS = 10_000;
+
+/**
+ * Runs `start` (the glue's `initThreadPool`) and settles when it does, when a
+ * Worker it creates fires `error`, or at the deadline, whichever comes first.
+ * While it runs, `globalThis.Worker` is wrapped to record the pool's Workers;
+ * on a failure they are terminated. The pool can still be creating Workers
+ * after a failure (wasm-bindgen-rayon fetches its script per Worker), so the
+ * wrapper stays until `start` settles and terminates each late one; a pool
+ * that never settles leaves it for the life of the engine Worker, which
+ * starts no other Workers.
+ */
+async function startPool(start: () => Promise<unknown>, deadlineMs: number): Promise<void> {
+  const scope = globalThis as { Worker?: typeof Worker };
+  const Original = scope.Worker;
+  if (typeof Original !== "function") {
+    await start();
+    return;
+  }
+  const workers: Worker[] = [];
+  let abandoned = false;
+  let fail: (e: Error) => void = () => {};
+  const failure = new Promise<never>((_, reject) => (fail = reject));
+  failure.catch(() => {});
+  scope.Worker = new Proxy(Original, {
+    construct(target, args, newTarget) {
+      const w = Reflect.construct(target, args, newTarget) as Worker;
+      if (abandoned) {
+        w.terminate();
+        return w;
+      }
+      workers.push(w);
+      w.addEventListener("error", (e) => {
+        const message = (e as ErrorEvent).message;
+        fail(new Error(`a lanes pool Worker failed to load${message ? ` (${message})` : ""}`));
+      });
+      return w;
+    },
+  });
+  const pool = Promise.resolve().then(start);
+  const restore = () => {
+    scope.Worker = Original;
+  };
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`the lanes pool did not start within ${deadlineMs / 1000} s`)), deadlineMs);
+  });
+  try {
+    await Promise.race([pool, failure, deadline]);
+    restore();
+  } catch (e) {
+    abandoned = true;
+    for (const w of workers) w.terminate();
+    pool.then(restore, restore);
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Initialise the glue with the wasm (a URL, a Response or the bytes) and bind
+ * the runtime to it. With `threads`, the glue is the lanes variant and its
+ * Worker pool starts first, within {@link LANES_POOL_DEADLINE_MS}; a failure
+ * there (an error, a pool Worker's `error` event or the deadline) terminates
+ * the pool's Workers and throws before the engine is told or anything is
+ * bound, so the caller can discard this glue and load the single-threaded
+ * variant instead.
+ */
+export async function loadWebHost(glue: WebGlue, wasm?: unknown, threads?: number): Promise<HostBinding> {
+  const bound = boundHost();
+  if (bound) return bound;
+  const exports = await glue.default(wasm === undefined ? undefined : { module_or_path: wasm });
+  if (threads !== undefined) {
+    if (!glue.initThreadPool || !glue.og_lanes_ready) throw new Error("the module is not the lanes variant (no initThreadPool)");
+    const init = glue.initThreadPool;
+    await startPool(() => init(threads), LANES_POOL_DEADLINE_MS);
+    glue.og_lanes_ready(threads);
+  }
+  glue.og_web_init();
+  const memory = exports.memory;
+  // Arrays by (offset, length, kind) over the current buffer: a system's
+  // views cost no allocation while its columns stay put.
+  let cache = new Map<string, ColumnArray>();
+  let cachedBuffer: ArrayBufferLike = memory.buffer;
+  const binding: HostBinding = {
+    abi: withPublishRefusals(glue) as unknown as HostAbi<Uint32Array, unknown>,
+    name: "web",
+    columns(raw, kinds, count) {
+      const offsets = raw as Uint32Array;
+      if (!offsets || offsets.length === 0) return null;
+      if (cachedBuffer !== memory.buffer || cache.size > 4096) {
+        cache = new Map();
+        cachedBuffer = memory.buffer;
+      }
+      return Array.from(offsets, (offset, i) => {
+        const kind = kinds[i]!;
+        const key = `${offset}:${count * kind.stride}:${kind.array}`;
+        let a = cache.get(key);
+        if (!a) cache.set(key, (a = new ARRAYS[kind.array](memory.buffer, offset, count * kind.stride) as ColumnArray));
+        return a;
+      });
+    },
+    // A grown memory detaches every array over the old buffer.
+    fresh: (array) => array.buffer === memory.buffer,
+  };
+  bindHost(binding);
+  return binding;
+}

package/src/web/input.ts

@@ -0,0 +1,237 @@
+// The input ring: the main thread writes page input into a SharedArrayBuffer
+// the engine Worker drains once per frame (docs/design.md §2.2). One slot is
+// 16 int32: kind, action, button, key length, x, y, deltaX, deltaY (as f32
+// bits), then up to 32 bytes of the key code; a pointer slot carries its
+// engine pointer id (0 the primary, 1 to 4 further touches) in word 8
+// instead. A gamepad slot (kind 3) is a pad's whole state: word 2 the pad,
+// word 3 connected, words 4-7 the axes, word 8 the button mask, words 9-10
+// the triggers. A text slot (kind 4) carries typed or composed text: word 1
+// 0 committed or 1 composing, word 2 1 when it continues the slot before it
+// (text past 48 bytes is split between characters over several slots,
+// joined again by drainRing), word 3 the UTF-8 length, the text in words
+// 4-15. An a11y slot (kind 5) is laid out as a text slot with word 1 the
+// action (A11Y_ACTIONS) and the control's path as its text. A key or pointer slot carries the event's time in words
+// 6-7 (an f64: performance.timeOrigin + the event's timeStamp, ms; 0 when
+// unknown), which the Worker turns into the event's `at` within the tick.
+// Without cross-origin isolation the shell posts the same events as
+// messages instead. crates/og-input/src/ring.rs decodes the same layout.
+
+/** An event as the probe's input() and the engine's input layer take it (IDL InjectedInput). */
+export type InjectedInput =
+  | {
+      kind: "key";
+      key: string;
+      action: "press" | "down" | "up";
+      /** The page's clock when it happened (performance.timeOrigin + timeStamp, ms): the Worker turns it into `at`. */
+      time?: number;
+      /** When it happened, in ticks from the start of the tick that reads it (-1 to 1; IDL KeyInput.at). */
+      at?: number;
+    }
+  | {
+      kind: "pointer";
+      action: "click" | "move" | "down" | "up";
+      x: number;
+      y: number;
+      button: "none" | "left" | "middle" | "right";
+      /** Which pointer: 0 the primary (omitted), 1 to 4 further touches (multi-touch). */
+      id?: number;
+      time?: number;
+      at?: number;
+    }
+  | { kind: "wheel"; x: number; y: number; deltaX: number; deltaY: number }
+  | {
+      kind: "gamepad";
+      pad: number;
+      connected: boolean;
+      /** Held standard-mapping buttons by name (GAMEPAD_BUTTONS). */
+      buttons: GamepadButtonName[];
+      /** Left x, y, right x, y; -1..1, y down. */
+      axes: number[];
+      /** Left and right analog triggers, 0..1. */
+      triggers: number[];
+    }
+  | {
+      kind: "text";
+      /** Typed text (a key's character, a paste, an IME commit), or with `composing` an input method's composition so far (empty ends it). */
+      text: string;
+      composing?: boolean;
+    }
+  | {
+      kind: "a11y";
+      /** What a screen reader asked of the UI control at `path` (a11y.ts): focus it, activate it, or step an adjustable one. */
+      action: A11yActionName;
+      /** The control's path, as og.ui.a11y() names it. */
+      path: string;
+    };
+
+export type A11yActionName = (typeof A11Y_ACTIONS)[number];
+
+/** og-input's A11yAct, by index. */
+export const A11Y_ACTIONS = ["focus", "activate", "increment", "decrement"] as const;
+
+export type GamepadButtonName = (typeof GAMEPAD_BUTTONS)[number];
+
+/** The W3C standard mapping's buttons, by index (og-input's GAMEPAD_BUTTONS). */
+export const GAMEPAD_BUTTONS = [
+  "a", "b", "x", "y", "leftBumper", "rightBumper", "leftTrigger", "rightTrigger",
+  "back", "start", "leftStick", "rightStick", "up", "down", "left", "right", "home",
+] as const;
+
+const SLOT = 16;
+const HEADER = 2; // write index, read index (monotonic)
+export const RING_SLOTS = 256;
+
+const KINDS = ["key", "pointer", "wheel", "gamepad", "text", "a11y"] as const;
+/** Bytes of text one slot holds (words 4-15). */
+const TEXT_BYTES = 48;
+
+/** UTF-8 pieces of at most TEXT_BYTES, split between characters. */
+function textPieces(text: string): Uint8Array[] {
+  const encoder = new TextEncoder();
+  const out: Uint8Array[] = [];
+  let piece = "";
+  for (const ch of text) {
+    if (encoder.encode(piece + ch).length > TEXT_BYTES) {
+      out.push(encoder.encode(piece));
+      piece = "";
+    }
+    piece += ch;
+  }
+  out.push(encoder.encode(piece));
+  return out;
+}
+const ACTIONS = ["press", "down", "up", "click", "move"] as const;
+const BUTTONS = ["none", "left", "middle", "right"] as const;
+
+export function createRing(): SharedArrayBuffer {
+  return new SharedArrayBuffer((HEADER + RING_SLOTS * SLOT) * 4);
+}
+
+/** Main thread: append one event; false when the ring is full (the event is dropped). */
+export function writeRing(buffer: SharedArrayBuffer, event: InjectedInput): boolean {
+  const ints = new Int32Array(buffer);
+  const floats = new Float32Array(buffer);
+  const write = Atomics.load(ints, 0);
+  const read = Atomics.load(ints, 1);
+  if (write - read >= RING_SLOTS) return false;
+  if (event.kind === "text" || event.kind === "a11y") {
+    // An a11y slot is a text slot whose text is the control's path.
+    const pieces = textPieces(event.kind === "text" ? event.text : event.path);
+    if (write - read + pieces.length > RING_SLOTS) return false;
+    pieces.forEach((bytes, k) => {
+      const at = HEADER + ((write + k) % RING_SLOTS) * SLOT;
+      new Int32Array(buffer, at * 4, SLOT).fill(0);
+      ints[at] = KINDS.indexOf(event.kind);
+      ints[at + 1] = event.kind === "text" ? (event.composing ? 1 : 0) : A11Y_ACTIONS.indexOf(event.action);
+      ints[at + 2] = k > 0 ? 1 : 0;
+      ints[at + 3] = bytes.length;
+      new Uint8Array(buffer, (at + 4) * 4, TEXT_BYTES).set(bytes);
+    });
+    Atomics.store(ints, 0, write + pieces.length);
+    return true;
+  }
+  const at = HEADER + (write % RING_SLOTS) * SLOT;
+  new Int32Array(buffer, at * 4, SLOT).fill(0);
+  ints[at] = KINDS.indexOf(event.kind);
+  if (event.kind === "gamepad") {
+    ints[at + 2] = event.pad;
+    ints[at + 3] = event.connected ? 1 : 0;
+    for (let i = 0; i < 4; i++) floats[at + 4 + i] = event.axes[i] ?? 0;
+    ints[at + 8] = event.buttons.reduce((m, b) => m | (1 << GAMEPAD_BUTTONS.indexOf(b)), 0);
+    floats[at + 9] = event.triggers[0] ?? 0;
+    floats[at + 10] = event.triggers[1] ?? 0;
+    Atomics.store(ints, 0, write + 1);
+    return true;
+  }
+  ints[at + 1] = "action" in event ? ACTIONS.indexOf(event.action) : 0;
+  ints[at + 2] = event.kind === "pointer" ? BUTTONS.indexOf(event.button) : 0;
+  const key = event.kind === "key" ? new TextEncoder().encode(event.key).subarray(0, 32) : new Uint8Array(0);
+  ints[at + 3] = key.length;
+  floats[at + 4] = "x" in event ? event.x : 0;
+  floats[at + 5] = "y" in event ? event.y : 0;
+  floats[at + 6] = event.kind === "wheel" ? event.deltaX : 0;
+  floats[at + 7] = event.kind === "wheel" ? event.deltaY : 0;
+  new Uint8Array(buffer, (at + 8) * 4, 32).fill(0).set(key);
+  if (event.kind === "pointer") ints[at + 8] = event.id ?? 0;
+  if ((event.kind === "key" || event.kind === "pointer") && event.time !== undefined) new Float64Array(buffer, (at + 6) * 4, 1)[0] = event.time;
+  Atomics.store(ints, 0, write + 1);
+  return true;
+}
+
+/** Worker: every event written since the last drain, oldest first. */
+export function drainRing(buffer: SharedArrayBuffer): InjectedInput[] {
+  const ints = new Int32Array(buffer);
+  const floats = new Float32Array(buffer);
+  const write = Atomics.load(ints, 0);
+  let read = Atomics.load(ints, 1);
+  const out: InjectedInput[] = [];
+  for (; read < write; read++) {
+    const at = HEADER + (read % RING_SLOTS) * SLOT;
+    const kind = KINDS[ints[at]!];
+    if (kind === "text") {
+      const text = new TextDecoder().decode(new Uint8Array(buffer, (at + 4) * 4, ints[at + 3]!).slice());
+      const composing = ints[at + 1] === 1;
+      const last = out[out.length - 1];
+      if (ints[at + 2] === 1 && last?.kind === "text" && (last.composing ?? false) === composing) last.text += text;
+      else out.push(composing ? { kind, text, composing } : { kind, text });
+      continue;
+    }
+    if (kind === "a11y") {
+      const path = new TextDecoder().decode(new Uint8Array(buffer, (at + 4) * 4, ints[at + 3]!).slice());
+      const action = A11Y_ACTIONS[ints[at + 1]!] ?? "focus";
+      const last = out[out.length - 1];
+      if (ints[at + 2] === 1 && last?.kind === "a11y" && last.action === action) last.path += path;
+      else out.push({ kind, action, path });
+      continue;
+    }
+    if (kind === "gamepad") {
+      const mask = ints[at + 8]!;
+      out.push({
+        kind,
+        pad: ints[at + 2]!,
+        connected: ints[at + 3]! !== 0,
+        buttons: GAMEPAD_BUTTONS.filter((_, i) => mask & (1 << i)),
+        axes: [floats[at + 4]!, floats[at + 5]!, floats[at + 6]!, floats[at + 7]!],
+        triggers: [floats[at + 9]!, floats[at + 10]!],
+      });
+      continue;
+    }
+    const action = ACTIONS[ints[at + 1]!]!;
+    const x = floats[at + 4]!;
+    const y = floats[at + 5]!;
+    const time = kind === "key" || kind === "pointer" ? new Float64Array(buffer, (at + 6) * 4, 1)[0]! : 0;
+    const stamped = time > 0 ? { time } : {};
+    if (kind === "key") {
+      const bytes = new Uint8Array(buffer, (at + 8) * 4, ints[at + 3]!).slice();
+      out.push({ kind, key: new TextDecoder().decode(bytes), action: action as "press" | "down" | "up", ...stamped });
+    } else if (kind === "pointer") {
+      const id = ints[at + 8]!;
+      out.push({
+        kind,
+        action: action as "click" | "move" | "down" | "up",
+        x,
+        y,
+        button: BUTTONS[ints[at + 2]!]!,
+        ...(id > 0 ? { id } : {}),
+        ...stamped,
+      });
+    } else if (kind === "wheel") {
+      out.push({ kind, x, y, deltaX: floats[at + 6]!, deltaY: floats[at + 7]! });
+    }
+  }
+  Atomics.store(ints, 1, read);
+  return out;
+}
+
+/**
+ * `at` of an event that happened at `time` (the page's clock, ms) and is
+ * injected now, before the tick that reads it: the sim clock is `behind` ms
+ * (the accumulator the last frame left, plus what elapsed since) ahead of the
+ * last tick's start, so the event falls at `(behind - age) / tickMs` ticks
+ * into the next tick, clamped to -1..1. 0 without a time.
+ */
+export function stampAt(time: number | undefined, now: number, behind: number, tickMs: number): number {
+  if (time === undefined || !(time > 0) || !(tickMs > 0)) return 0;
+  const at = (behind - (now - time)) / tickMs;
+  return Number.isFinite(at) ? Math.max(-1, Math.min(1, at)) : 0;
+}

package/src/web/lanes.ts

@@ -0,0 +1,21 @@
+// The boot rule for the lanes variant (docs/web-export.md §Lanes), shared by
+// the shell, which starts the variant it picks, and the exported game's
+// service worker (shell/sw.ts), which precaches the variant this rule will
+// pick, so the two never disagree.
+
+/** The most Workers lanes take beside the engine Worker. */
+export const LANES_MAX_THREADS = 8;
+
+/**
+ * Lanes or not, decided at boot: the lanes variant needs shared memory
+ * (`crossOriginIsolated`) and more than two logical cores. The pool takes
+ * the cores but one, at most LANES_MAX_THREADS: the core left is the page's,
+ * and the engine Worker needs none of its own while a lane runs, since it
+ * waits for the pool (rayon blocks the calling thread until the lane ends).
+ */
+export function laneChoice(offered: boolean, isolated: boolean, cores: number): { threads: number } | { why: string } {
+  if (!offered) return { why: "the build has no lanes variant" };
+  if (!isolated) return { why: "the page is not cross-origin isolated (COOP/COEP)" };
+  if (!(cores > 2)) return { why: `${cores || "unknown"} logical cores: single-threaded` };
+  return { threads: Math.min(cores - 1, LANES_MAX_THREADS) };
+}

package/src/web/play.ts

@@ -0,0 +1,20 @@
+// The play page `og build` ships (dist/index.html loads dist/play.js): the
+// player shell of shell/page.ts on the page's canvas, the engine Worker
+// (dist/game.js), the cooked bundle next to the page, the Basis transcoder
+// under basis/ and the audio worklet (dist/audio-worklet.js).
+//
+// - A `replay-seed` query parameter starts a deterministic replay from that
+//   uint32 seed; `webgl=1` takes the WebGL2 fallback; `autoplay=0` leaves the
+//   clock to the probe (no gate, no play), as test harnesses drive it.
+// - The probe is published on `globalThis.__runtime_probe__`: every member
+//   answers a Promise (the call crosses the request ring to the Worker, or
+//   postMessage without cross-origin isolation), and the platform's og-probe
+//   wire is served over it (shell/wire.ts).
+
+import { play } from "../../shell/page.ts";
+
+export { play };
+
+void play().catch(() => {
+  /* the error card is already on screen */
+});

package/src/web/rpc-ring.ts

@@ -0,0 +1,110 @@
+// The probe's request ring (docs/design.md §3.4): the shell calls the engine
+// Worker without a postMessage hop. Two SharedArrayBuffer byte rings, one for
+// request frames (shell → Worker) and one for answer frames (Worker →
+// shell), each carrying JSON-RPC 2.0 text framed as a little-endian u32
+// length then UTF-8. The Worker drains requests between ticks and answers
+// each with `og_engine_call`; the shell wakes on Atomics.notify.
+//
+// Layout of one ring: Int32 [0] write and [1] read byte counters (monotonic,
+// unsigned 32-bit arithmetic), [2] a notify word, then `capacity` data bytes.
+// A frame longer than a ring's capacity cannot cross it; `writeFrame`
+// answers false and the caller falls back to postMessage.
+
+const HEADER = 16;
+
+/** The shell's and the Worker's halves share these two buffers. */
+export interface RpcRings {
+  readonly requests: SharedArrayBuffer;
+  readonly answers: SharedArrayBuffer;
+}
+
+/** Requests are small; answers carry capture PNGs, so they get more room. */
+export function createRpcRings(requestBytes = 1 << 20, answerBytes = 16 << 20): RpcRings {
+  return {
+    requests: new SharedArrayBuffer(HEADER + requestBytes),
+    answers: new SharedArrayBuffer(HEADER + answerBytes),
+  };
+}
+
+function capacity(ring: SharedArrayBuffer): number {
+  return ring.byteLength - HEADER;
+}
+
+function copyIn(ring: SharedArrayBuffer, at: number, bytes: Uint8Array): void {
+  const cap = capacity(ring);
+  const data = new Uint8Array(ring, HEADER, cap);
+  const start = at % cap;
+  const first = Math.min(bytes.length, cap - start);
+  data.set(bytes.subarray(0, first), start);
+  if (first < bytes.length) data.set(bytes.subarray(first), 0);
+}
+
+function copyOut(ring: SharedArrayBuffer, at: number, length: number): Uint8Array {
+  const cap = capacity(ring);
+  const data = new Uint8Array(ring, HEADER, cap);
+  const out = new Uint8Array(length);
+  const start = at % cap;
+  const first = Math.min(length, cap - start);
+  out.set(data.subarray(start, start + first), 0);
+  if (first < length) out.set(data.subarray(0, length - first), first);
+  return out;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Append one frame; false when it does not fit now (or ever: longer than the ring). */
+export function writeFrame(ring: SharedArrayBuffer, text: string): boolean {
+  const ints = new Int32Array(ring, 0, 4);
+  const body = encoder.encode(text);
+  const need = 4 + body.length;
+  const write = Atomics.load(ints, 0) >>> 0;
+  const read = Atomics.load(ints, 1) >>> 0;
+  if (need > capacity(ring) - ((write - read) >>> 0)) return false;
+  const len = new Uint8Array(4);
+  new DataView(len.buffer).setUint32(0, body.length, true);
+  copyIn(ring, write, len);
+  copyIn(ring, (write + 4) >>> 0, body);
+  Atomics.store(ints, 0, (write + need) | 0);
+  Atomics.add(ints, 2, 1);
+  Atomics.notify(ints, 2);
+  return true;
+}
+
+/** Every frame written since the last read, oldest first. */
+export function readFrames(ring: SharedArrayBuffer): string[] {
+  const ints = new Int32Array(ring, 0, 4);
+  const write = Atomics.load(ints, 0) >>> 0;
+  let read = Atomics.load(ints, 1) >>> 0;
+  const out: string[] = [];
+  while (read !== write) {
+    const length = new DataView(copyOut(ring, read, 4).buffer).getUint32(0, true);
+    out.push(decoder.decode(copyOut(ring, (read + 4) >>> 0, length)));
+    read = (read + 4 + length) >>> 0;
+  }
+  Atomics.store(ints, 1, read | 0);
+  return out;
+}
+
+/** Whether frames are waiting. */
+export function hasFrames(ring: SharedArrayBuffer): boolean {
+  const ints = new Int32Array(ring, 0, 4);
+  return Atomics.load(ints, 0) !== Atomics.load(ints, 1);
+}
+
+type WaitAsync = (a: Int32Array, i: number, v: number, t?: number) => { async: boolean; value: Promise<string> | string };
+
+/**
+ * Resolves when the ring has frames or `timeoutMs` passed. Uses
+ * Atomics.waitAsync where the platform has it (no polling), else a timer.
+ */
+export function waitForFrames(ring: SharedArrayBuffer, timeoutMs = 50): Promise<void> {
+  if (hasFrames(ring)) return Promise.resolve();
+  const ints = new Int32Array(ring, 0, 4);
+  const waitAsync = (Atomics as unknown as { waitAsync?: WaitAsync }).waitAsync;
+  if (waitAsync) {
+    const r = waitAsync(ints, 2, Atomics.load(ints, 2), timeoutMs);
+    return r.async ? (r.value as Promise<string>).then(() => undefined) : Promise.resolve();
+  }
+  return new Promise((resolve) => setTimeout(resolve, Math.min(timeoutMs, 4)));
+}

package/src/web/settle.ts

@@ -0,0 +1,122 @@
+// The platform's first answers behind the play gate (docs/web-export.md
+// §The shell). The shell takes the game's first tick behind the gate and
+// holds the clock; og.platform's answers apply at the start of the next
+// tick, so without more ticks a returning player's title would show the
+// defaults (English, no Continue) until the tap. So after the first tick
+// the Worker waits for the host's answers to the calls it made and takes one
+// tick to apply them, then again for the calls that tick made (a slot's
+// parts after its manifest), until a tick asks the host nothing new, at
+// most SETTLE_TICKS ticks, before it draws the first frame (within
+// SETTLE_FIRST_MS) and after it (within SETTLE_MS, each settling tick
+// drawn). The ticks are the game's own ticks, and the answers reach the
+// world as every answer does, at a tick's start, as host input a replay
+// repeats; the gate's tap ends the settling, and play goes on from there.
+
+import type { PlatformAnswer, PlatformCall, PlatformHost } from "../platform-local.ts";
+
+/** The most ticks the Worker takes behind the gate to apply the platform's answers. */
+export const SETTLE_TICKS = 8;
+/** How long the first frame waits for the first tick's answers, ms. */
+export const SETTLE_FIRST_MS = 300;
+/** How long, from the first tick, the Worker keeps applying answers behind the gate, ms. */
+export const SETTLE_MS = 5000;
+
+/**
+ * Counts what a platform host was asked and what it answered: the calls
+ * sent to it (telemetry is never answered) and the answers that arrived
+ * since the last tick took them.
+ */
+export class PlatformCounter {
+  #sent = 0;
+  #answered = 0;
+  #fresh = false;
+  #wake: (() => void) | null = null;
+
+  /** The host, counting the calls it is handed. */
+  wrap(host: PlatformHost): PlatformHost {
+    return {
+      host: host.host,
+      capabilities: host.capabilities,
+      handle: (calls: readonly PlatformCall[], answer: (request: number, result: PlatformAnswer) => void) => {
+        this.sent(calls);
+        host.handle(calls, (request, result) => {
+          this.answered();
+          answer(request, result);
+        });
+      },
+    };
+  }
+
+  /** Calls handed to the host. */
+  sent(calls: readonly PlatformCall[]): void {
+    this.#sent += calls.filter((c) => c.method !== "telemetry").length;
+  }
+
+  /** One answer arrived (the engine has it; the next tick applies it). */
+  answered(): void {
+    this.#answered++;
+    this.#fresh = true;
+    if (this.waiting === 0) this.#wake?.();
+  }
+
+  /** Calls the host has not answered yet. */
+  get waiting(): number {
+    return Math.max(0, this.#sent - this.#answered);
+  }
+
+  /** Whether an answer arrived since the last `took`. */
+  get fresh(): boolean {
+    return this.#fresh;
+  }
+
+  /** A tick took the answers that had arrived. */
+  took(): void {
+    this.#fresh = false;
+  }
+
+  /** Resolves when the host answered every call it was handed, or at `until` (performance.now()). */
+  quiet(until: number): Promise<void> {
+    if (this.waiting === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        if (this.#wake === done) this.#wake = null;
+        resolve();
+      };
+      const timer = setTimeout(done, Math.max(0, until - performance.now()));
+      this.#wake = done;
+    });
+  }
+}
+
+/**
+ * Behind the gate: while the host answers what the game asked, take one
+ * tick to apply the answers (and `drawn` after each), until a tick leaves
+ * nothing new to apply, `stop()` says play began, `until` passes or
+ * `ticks` reach SETTLE_TICKS. `pending` is the engine's count of calls the
+ * world has no answer to yet (Engine.platformPending): with nothing in
+ * flight at the host, a pending call is one the engine answers itself at
+ * the next tick (a slot whose parts all arrived), so that tick is taken
+ * too. Returns the ticks taken.
+ */
+export async function settle(
+  counter: PlatformCounter,
+  advance: () => { ok: boolean; reason?: string },
+  o: { until: number; ticks?: number; stop?: () => boolean; drawn?: () => void; pending?: () => number },
+): Promise<number> {
+  const most = o.ticks ?? SETTLE_TICKS;
+  const due = () => counter.fresh || (counter.waiting === 0 && (o.pending?.() ?? 0) > 0);
+  let taken = 0;
+  while (taken < most && !o.stop?.()) {
+    if (counter.waiting > 0) await counter.quiet(o.until);
+    if (o.stop?.() || !due()) break;
+    counter.took();
+    const r = advance();
+    if (!r.ok) throw new Error(r.reason ?? "a tick behind the gate failed");
+    taken++;
+    o.drawn?.();
+    if (!due() && counter.waiting === 0) break;
+    if (performance.now() >= o.until) break;
+  }
+  return taken;
+}