@crowdedkingdoms/construct 0.0.0 → 0.2.1-dev.1

package/src/platform/studio/agentLocomotion.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { AgentLocomotion } from './agentLocomotion';
+
+describe('AgentLocomotion', () => {
+  it('maps MOVE directions onto Input.axes and expires them', () => {
+    const loco = new AgentLocomotion();
+    loco.applyMove({ direction: 'FORWARD', intensity: 1, durationMs: 200, nowMs: 1_000 });
+    expect(loco.sample(1_050)).toMatchObject({ x: 0, y: 1, yaw: 0, pitch: 0 });
+    loco.applyMove({ direction: 'LEFT', intensity: 0.5, durationMs: 200, nowMs: 1_100 });
+    expect(loco.sample(1_150).x).toBe(-0.5);
+    expect(loco.sample(1_400)).toMatchObject({ x: 0, y: 0 });
+  });
+
+  it('converts LOOK degrees to radians once, then clears', () => {
+    const loco = new AgentLocomotion();
+    loco.applyLook({ deltaYaw: 90, deltaPitch: -45 });
+    const first = loco.sample(0);
+    expect(first.yaw).toBeCloseTo(Math.PI / 2, 5);
+    expect(first.pitch).toBeCloseTo(-Math.PI / 4, 5);
+    expect(loco.sample(1)).toMatchObject({ yaw: 0, pitch: 0 });
+  });
+
+  it('clear drops both wishes', () => {
+    const loco = new AgentLocomotion();
+    loco.applyMove({ direction: 'RIGHT', intensity: 1, durationMs: 1_000, nowMs: 0 });
+    loco.applyLook({ deltaYaw: 10, deltaPitch: 0 });
+    loco.clear();
+    expect(loco.sample(10)).toEqual({ x: 0, y: 0, yaw: 0, pitch: 0 });
+  });
+});

package/src/platform/studio/agentLocomotion.ts

@@ -0,0 +1,97 @@
+/**
+ * Agent Play locomotion, consumed by scenes the same way they consume WASD.
+ * StudioService writes wishes; HolodeckScene samples them each frame.
+ * Human input (the control gate) calls `clear`.
+ */
+export interface AgentMoveWish {
+  readonly direction: 'FORWARD' | 'BACKWARD' | 'LEFT' | 'RIGHT' | 'UP' | 'DOWN';
+  readonly intensity: number;
+  readonly untilMs: number;
+}
+
+export interface AgentLookWish {
+  readonly yawDelta: number;
+  readonly pitchDelta: number;
+}
+
+export interface AgentLocomotionSample {
+  /** Camera-relative axes, same convention as `Input.axes()` (−1..1). */
+  readonly x: number;
+  readonly y: number;
+  /** Radians to add this frame (already converted from the LOOK command). */
+  readonly yaw: number;
+  readonly pitch: number;
+}
+
+const DEG_TO_RAD = Math.PI / 180;
+
+export class AgentLocomotion {
+  private move: AgentMoveWish | null = null;
+  private look: AgentLookWish | null = null;
+
+  applyMove(input: {
+    direction: AgentMoveWish['direction'];
+    intensity: number;
+    durationMs: number;
+    nowMs: number;
+  }): void {
+    const intensity = clamp01(input.intensity);
+    const durationMs = Math.max(16, Math.min(2_000, input.durationMs));
+    this.move = {
+      direction: input.direction,
+      intensity,
+      untilMs: input.nowMs + durationMs,
+    };
+  }
+
+  applyLook(input: { deltaYaw: number; deltaPitch: number }): void {
+    this.look = {
+      yawDelta: finite(input.deltaYaw) * DEG_TO_RAD,
+      pitchDelta: finite(input.deltaPitch) * DEG_TO_RAD,
+    };
+  }
+
+  clear(): void {
+    this.move = null;
+    this.look = null;
+  }
+
+  sample(nowMs: number): AgentLocomotionSample {
+    let x = 0;
+    let y = 0;
+    if (this.move && nowMs < this.move.untilMs) {
+      const i = this.move.intensity;
+      switch (this.move.direction) {
+        case 'FORWARD':
+          y = i;
+          break;
+        case 'BACKWARD':
+          y = -i;
+          break;
+        case 'RIGHT':
+          x = i;
+          break;
+        case 'LEFT':
+          x = -i;
+          break;
+        default:
+          break;
+      }
+    } else {
+      this.move = null;
+    }
+    const yaw = this.look?.yawDelta ?? 0;
+    const pitch = this.look?.pitchDelta ?? 0;
+    this.look = null;
+    return { x, y, yaw, pitch };
+  }
+}
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function finite(value: number): number {
+  return Number.isFinite(value) ? value : 0;
+}

package/src/platform/studio/clientModHost.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@crowdedkingdoms/crowdyjs', () => ({ PlayerCodeBroker: class {} }));
+
+const {
+  DEFAULT_VOXEL_STATE,
+  HostCallRefusedError,
+  OFFERED_HOST_CALLS,
+  bytesToBase64,
+  parseVoxelSetArgs,
+  routeClientHostCall,
+  voxelsFromBase64,
+} = await import('./clientModHost');
+
+const grid = { low: { x: -1n, y: 0n, z: -1n }, high: { x: 1n, y: 0n, z: 1n } };
+
+function reads() {
+  const calls: string[] = [];
+  return {
+    calls,
+    reads: {
+      actorsInChunk: (x: bigint, y: bigint, z: bigint) => {
+        calls.push(`${x},${y},${z}`);
+        return x === 0n && z === 0n ? [{ uuid: 'me', name: 'neo' }] : [];
+      },
+      chunkVoxels: (x: bigint) => (x === 0n ? { voxelsBase64: bytesToBase64(sampleGrid()) } : null),
+    },
+  };
+}
+
+function sampleGrid(): Uint8Array {
+  const g = new Uint8Array(4096);
+  g[1 + 0 * 16 + 2 * 256] = 7; // x=1, y=0, z=2
+  return g;
+}
+
+describe('routeClientHostCall', () => {
+  it('offers world_read plus voxel_set and pointer_clicks', () => {
+    expect([...OFFERED_HOST_CALLS]).toEqual([
+      'actors_list',
+      'actors_list_radius',
+      'chunk_get',
+      'voxels_list',
+      'voxel_set',
+      'pointer_clicks',
+    ]);
+  });
+
+  it('answers actors_list for one chunk', async () => {
+    const r = reads();
+    const out = await routeClientHostCall(
+      { fn: 'actors_list', args: { x: '0', y: '0', z: '0' } } as never,
+      r.reads,
+      grid,
+    );
+    expect(out).toEqual({ actors: [{ uuid: 'me', name: 'neo' }] });
+  });
+
+  it('clamps actors_list_radius to the grid and to radius 8', async () => {
+    const r = reads();
+    await routeClientHostCall(
+      { fn: 'actors_list_radius', args: { x: '0', y: '0', z: '0', radius: 50 } } as never,
+      r.reads,
+      grid,
+    );
+    // 3x1x3 chunks inside the grid, never beyond it.
+    expect(r.calls.length).toBe(9);
+    expect(r.calls.every((c) => c.split(',').every((v) => Math.abs(Number(v)) <= 1))).toBe(true);
+  });
+
+  it('serves chunk_get as base64 and voxels_list as sparse rows', async () => {
+    const r = reads();
+    const dense = (await routeClientHostCall(
+      { fn: 'chunk_get', args: { x: 0, y: 0, z: 0 } } as never,
+      r.reads,
+      grid,
+    )) as {
+      voxelsBase64: string;
+    };
+    expect(atob(dense.voxelsBase64).length).toBe(4096);
+    const sparse = await routeClientHostCall(
+      { fn: 'voxels_list', args: { x: 0, y: 0, z: 0 } } as never,
+      r.reads,
+      grid,
+    );
+    expect(sparse).toEqual({ voxels: [{ x: 1, y: 0, z: 2, voxelType: 7 }] });
+    expect(
+      await routeClientHostCall(
+        { fn: 'voxels_list', args: { x: 5, y: 0, z: 0 } } as never,
+        r.reads,
+        grid,
+      ),
+    ).toEqual({
+      voxels: [],
+    });
+  });
+
+  it('refuses host calls it does not offer', async () => {
+    const r = reads();
+    for (const fn of ['model_invoke', 'emit_spatial', 'fetch', 'eval']) {
+      await expect(
+        routeClientHostCall({ fn, args: {} } as never, r.reads, grid),
+      ).rejects.toBeInstanceOf(HostCallRefusedError);
+    }
+  });
+
+  it('drains pointer_clicks when the game supplies an input sink', async () => {
+    const r = reads();
+    await expect(
+      routeClientHostCall({ fn: 'pointer_clicks', args: {} } as never, r.reads, grid),
+    ).rejects.toBeInstanceOf(HostCallRefusedError);
+    const snapshot = {
+      nowMs: 50,
+      buttons: 1,
+      holdingMs: { '0': 40 },
+      clicks: [{ t: 'down' as const, button: 0, atMs: 10, nx: 0, ny: 0 }],
+    };
+    expect(
+      await routeClientHostCall(
+        { fn: 'pointer_clicks', args: {} } as never,
+        r.reads,
+        grid,
+        undefined,
+        { drainPointerClicks: () => snapshot },
+      ),
+    ).toEqual(snapshot);
+  });
+
+  it('refuses voxel_set when the game did not supply a write sink', async () => {
+    const r = reads();
+    await expect(
+      routeClientHostCall(
+        {
+          fn: 'voxel_set',
+          args: { chunkX: 0, chunkY: 0, chunkZ: 0, x: 1, y: 0, z: 2, voxelType: 3 },
+        } as never,
+        r.reads,
+        grid,
+      ),
+    ).rejects.toBeInstanceOf(HostCallRefusedError);
+  });
+
+  it('writes a voxel through the Paint-equivalent sink', async () => {
+    const r = reads();
+    const written: unknown[] = [];
+    const out = await routeClientHostCall(
+      {
+        fn: 'voxel_set',
+        args: { chunk: { x: '0', y: '0', z: '0' }, voxel: [1, 0, 2], voxel_type: 7 },
+      } as never,
+      r.reads,
+      grid,
+      {
+        setVoxel: async (input) => {
+          written.push(input);
+          return true;
+        },
+      },
+    );
+    expect(out).toEqual({ ok: true });
+    expect(written).toEqual([
+      {
+        chunk: { x: 0, y: 0, z: 0 },
+        x: 1,
+        y: 0,
+        z: 2,
+        voxelType: 7,
+        state: DEFAULT_VOXEL_STATE,
+      },
+    ]);
+  });
+
+  it('parses flattened chunkX host-call args the broker clamps', () => {
+    expect(
+      parseVoxelSetArgs({
+        chunkX: 3,
+        chunkY: 0,
+        chunkZ: 3,
+        x: 8,
+        y: 1,
+        z: 4,
+        voxelType: 2,
+        state_base64: 'AA==',
+      }),
+    ).toEqual({
+      chunk: { x: 3, y: 0, z: 3 },
+      x: 8,
+      y: 1,
+      z: 4,
+      voxelType: 2,
+      state: 'AA==',
+    });
+  });
+
+  it('decodes an empty grid to no rows', () => {
+    expect(voxelsFromBase64(null)).toEqual([]);
+    expect(voxelsFromBase64(bytesToBase64(new Uint8Array(4096)))).toEqual([]);
+  });
+});

package/src/platform/studio/clientModHost.ts

@@ -0,0 +1,369 @@
+/**
+ * The host side of CLIENT mods: what a sandboxed player module may ask the
+ * game for, and how a consented grid-attached mod is started for a visitor.
+ *
+ * The SDK's `PlayerCodeBroker` has already validated every call against the
+ * platform allowlist, clamped chunk coordinates to the mod's grid AABB, rate-
+ * limited it, and answered `grid_info` / `hud_set` / `overlay_draw` itself.
+ * What reaches `routeClientHostCall` is world_read, `voxel_set`, and
+ * `pointer_clicks`. Reads return only what the running player can already
+ * lawfully see. Writes go through ChunkStore.setVoxel (optimistic + UDP) and
+ * markDirty (durable write-back), the same route Paint uses. Never hand a mod
+ * the raw client.
+ */
+import {
+  PlayerCodeBroker,
+  type CrowdyClient,
+  type PlayerCodeGridBounds,
+  type PlayerCodeHostCall,
+  type PlayerCodePresentation,
+} from '@crowdedkingdoms/crowdyjs';
+import type { CrowdyStudioTextHud } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+import type { ModOverlayStore } from './modOverlay';
+
+export interface ClientModHostReads {
+  actorsInChunk(x: bigint, y: bigint, z: bigint): Array<Record<string, unknown>>;
+  chunkVoxels(x: bigint, y: bigint, z: bigint): { voxelsBase64: string | null } | null;
+}
+
+export interface ClientModHostWrites {
+  setVoxel(input: {
+    chunk: { x: number; y: number; z: number };
+    x: number;
+    y: number;
+    z: number;
+    voxelType: number;
+    state?: string;
+  }): Promise<boolean>;
+}
+
+export interface ClientModHostInput {
+  drainPointerClicks(): unknown;
+}
+
+/** The host calls this game answers. Exported so the docs and tests agree. */
+export const OFFERED_HOST_CALLS = [
+  'actors_list',
+  'actors_list_radius',
+  'chunk_get',
+  'voxels_list',
+  'voxel_set',
+  'pointer_clicks',
+] as const;
+
+/** One zero byte, base64: the smallest non-empty voxel state the API accepts. */
+export const DEFAULT_VOXEL_STATE = 'AA==';
+
+const MAX_RADIUS = 8;
+
+function toBigInt(value: unknown): bigint {
+  return BigInt(value as string | number | bigint);
+}
+
+export class HostCallRefusedError extends Error {
+  constructor(readonly fn: string) {
+    super(`host call '${fn}' is not offered by this game`);
+    this.name = 'HostCallRefusedError';
+  }
+}
+
+export async function routeClientHostCall(
+  call: PlayerCodeHostCall,
+  reads: ClientModHostReads,
+  grid?: PlayerCodeGridBounds,
+  writes?: ClientModHostWrites,
+  input?: ClientModHostInput,
+): Promise<unknown> {
+  const { fn, args } = call;
+  switch (fn) {
+    case 'actors_list':
+      return { actors: reads.actorsInChunk(toBigInt(args.x), toBigInt(args.y), toBigInt(args.z)) };
+    case 'actors_list_radius': {
+      const origin = { x: toBigInt(args.x), y: toBigInt(args.y), z: toBigInt(args.z) };
+      const requested = Number(args.radius ?? args.r ?? 0);
+      const radius = BigInt(
+        Number.isFinite(requested) ? Math.max(0, Math.min(MAX_RADIUS, Math.floor(requested))) : 0,
+      );
+      const low = grid
+        ? {
+            x: maxBig(grid.low.x, origin.x - radius),
+            y: maxBig(grid.low.y, origin.y - radius),
+            z: maxBig(grid.low.z, origin.z - radius),
+          }
+        : origin;
+      const high = grid
+        ? {
+            x: minBig(grid.high.x, origin.x + radius),
+            y: minBig(grid.high.y, origin.y + radius),
+            z: minBig(grid.high.z, origin.z + radius),
+          }
+        : origin;
+      const actors: Array<Record<string, unknown>> = [];
+      for (let x = low.x; x <= high.x; x++)
+        for (let y = low.y; y <= high.y; y++)
+          for (let z = low.z; z <= high.z; z++) actors.push(...reads.actorsInChunk(x, y, z));
+      return { actors };
+    }
+    case 'chunk_get':
+    case 'voxels_list': {
+      const chunk = reads.chunkVoxels(toBigInt(args.x), toBigInt(args.y), toBigInt(args.z));
+      if (!chunk) return fn === 'chunk_get' ? { voxelsBase64: null } : { voxels: [] };
+      return fn === 'chunk_get'
+        ? { voxelsBase64: chunk.voxelsBase64 }
+        : { voxels: voxelsFromBase64(chunk.voxelsBase64) };
+    }
+    case 'voxel_set': {
+      if (!writes) throw new HostCallRefusedError(fn);
+      const parsed = parseVoxelSetArgs(args);
+      if (!parsed) return { ok: false, error: 'invalid voxel_set arguments' };
+      const ok = await writes.setVoxel({
+        chunk: parsed.chunk,
+        x: parsed.x,
+        y: parsed.y,
+        z: parsed.z,
+        voxelType: parsed.voxelType,
+        state: parsed.state,
+      });
+      return { ok };
+    }
+    case 'pointer_clicks': {
+      if (!input) throw new HostCallRefusedError(fn);
+      return input.drainPointerClicks();
+    }
+    default:
+      throw new HostCallRefusedError(fn);
+  }
+}
+
+function intInRange(value: unknown, min: number, max: number): number | null {
+  const n =
+    typeof value === 'number'
+      ? value
+      : typeof value === 'string' && /^-?\d+$/.test(value)
+        ? Number(value)
+        : typeof value === 'bigint'
+          ? Number(value)
+          : NaN;
+  if (!Number.isInteger(n) || n < min || n > max) return null;
+  return n;
+}
+
+function coordField(record: Record<string, unknown>, ...keys: string[]): unknown {
+  for (const key of keys) {
+    if (record[key] !== undefined) return record[key];
+  }
+  return undefined;
+}
+
+function asCoord3(value: unknown): { x: unknown; y: unknown; z: unknown } | null {
+  if (Array.isArray(value) && value.length >= 3) {
+    return { x: value[0], y: value[1], z: value[2] };
+  }
+  if (value && typeof value === 'object') {
+    const rec = value as Record<string, unknown>;
+    return { x: rec.x, y: rec.y, z: rec.z };
+  }
+  return null;
+}
+
+/** Accept the SDK tuple shape and the flattened host-call JSON the broker clamps. */
+export function parseVoxelSetArgs(args: Record<string, unknown>): {
+  chunk: { x: number; y: number; z: number };
+  x: number;
+  y: number;
+  z: number;
+  voxelType: number;
+  state: string;
+} | null {
+  const chunkRaw =
+    asCoord3(args.chunk) ??
+    ({
+      x: coordField(args, 'chunkX', 'chunk_x'),
+      y: coordField(args, 'chunkY', 'chunk_y'),
+      z: coordField(args, 'chunkZ', 'chunk_z'),
+    } as { x: unknown; y: unknown; z: unknown });
+  const voxelRaw =
+    asCoord3(args.voxel) ??
+    ({
+      x: coordField(args, 'x', 'vx'),
+      y: coordField(args, 'y', 'vy'),
+      z: coordField(args, 'z', 'vz'),
+    } as { x: unknown; y: unknown; z: unknown });
+  const cx = intInRange(chunkRaw.x, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+  const cy = intInRange(chunkRaw.y, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+  const cz = intInRange(chunkRaw.z, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+  const x = intInRange(voxelRaw.x, 0, 15);
+  const y = intInRange(voxelRaw.y, 0, 15);
+  const z = intInRange(voxelRaw.z, 0, 15);
+  const voxelType = intInRange(coordField(args, 'voxelType', 'voxel_type', 'type'), 0, 255);
+  if (
+    cx === null ||
+    cy === null ||
+    cz === null ||
+    x === null ||
+    y === null ||
+    z === null ||
+    voxelType === null
+  ) {
+    return null;
+  }
+  const stateRaw = coordField(args, 'state', 'state_base64', 'stateBase64');
+  const state =
+    typeof stateRaw === 'string' && stateRaw.length > 0 ? stateRaw : DEFAULT_VOXEL_STATE;
+  return { chunk: { x: cx, y: cy, z: cz }, x, y, z, voxelType, state };
+}
+
+/** Sparse `{x,y,z,voxelType}` rows for the non-zero cells of a dense grid. */
+export function voxelsFromBase64(
+  voxelsBase64: string | null,
+): Array<{ x: number; y: number; z: number; voxelType: number }> {
+  if (!voxelsBase64) return [];
+  const binary = atob(voxelsBase64);
+  const out: Array<{ x: number; y: number; z: number; voxelType: number }> = [];
+  for (let i = 0; i < binary.length && i < 4096; i++) {
+    const type = binary.charCodeAt(i);
+    if (type === 0) continue;
+    out.push({ x: i & 15, y: (i >> 4) & 15, z: (i >> 8) & 15, voxelType: type });
+  }
+  return out;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
+  return btoa(binary);
+}
+
+interface CachedArtifact {
+  bytes: Uint8Array;
+  artifactHash?: string;
+  fuelPerDispatch?: string | bigint;
+}
+
+const artifactCache = new Map<string, CachedArtifact>();
+
+/**
+ * Fetch a consented grid-attached client mod's artifact and run it in a
+ * hash-verified broker with the same allowlist, grid clamp, rate caps and
+ * circuit breaker as the Studio's own Test/Run path. Its HUD output lands in
+ * the persistent text HUD. Returns null (fails closed) when the artifact
+ * cannot be fetched.
+ */
+export async function runConsentedGridMod(options: {
+  client: CrowdyClient;
+  appId: string;
+  attachmentId: string;
+  artifactCacheKey: string;
+  hudSource: string;
+  hudLabel: string;
+  /** The module's name, which addressed grid events target (default `hudLabel`). */
+  moduleName?: string;
+  grid: PlayerCodeGridBounds;
+  workerUrl: string;
+  reads: ClientModHostReads;
+  writes?: ClientModHostWrites;
+  hud: CrowdyStudioTextHud;
+  overlay?: ModOverlayStore;
+  input?: ClientModHostInput;
+  /**
+   * Answers the host calls this game does not route itself (DN-10: the rest
+   * of the client catalog, through CrowdyJS `createGridHostCalls`).
+   */
+  serverCalls?: (call: PlayerCodeHostCall) => Promise<unknown>;
+  /**
+   * How often the worker self-drives `on_tick`. Omitted/0 means invoke-only
+   * and a HUD mod then never runs (measured 2026-09-07: broker started, HUD
+   * stayed empty). Studio Test/Deploy reads `[package.metadata.crowdy]
+   * tick_interval_ms` from the CLIENT Cargo.toml (default 1000, clamped
+   * 16–1000). Pass this only for grid-attached visitors until that field is
+   * stored on the compiled version.
+   */
+  tickIntervalMs?: number;
+}): Promise<{ stop: () => void } | null> {
+  let fetched: { bytes: ArrayBuffer; artifactHash?: string; fuelPerDispatch?: string | bigint };
+  const cached = artifactCache.get(options.artifactCacheKey);
+  if (cached) {
+    fetched = {
+      bytes: cached.bytes.slice().buffer,
+      artifactHash: cached.artifactHash,
+      fuelPerDispatch: cached.fuelPerDispatch,
+    };
+  } else {
+    try {
+      fetched = await options.client.marketplace.clientArtifactBytes({
+        appId: options.appId,
+        attachmentId: options.attachmentId,
+      });
+    } catch {
+      return null;
+    }
+    artifactCache.set(options.artifactCacheKey, {
+      bytes: new Uint8Array(fetched.bytes).slice(),
+      artifactHash: fetched.artifactHash,
+      fuelPerDispatch: fetched.fuelPerDispatch,
+    });
+  }
+  const broker = new PlayerCodeBroker({
+    workerUrl: options.workerUrl,
+    grid: options.grid,
+    artifactHash: fetched.artifactHash,
+    fuelPerDispatch: fetched.fuelPerDispatch != null ? BigInt(fetched.fuelPerDispatch) : undefined,
+    tickIntervalMs: options.tickIntervalMs ?? 1000,
+    moduleName: options.moduleName ?? options.hudLabel,
+    onHostCall: (call) =>
+      routeWithFallback(
+        call,
+        () => routeClientHostCall(call, options.reads, options.grid, options.writes, options.input),
+        options.serverCalls,
+      ),
+    onPresentation: (presentation: PlayerCodePresentation) => {
+      if (presentation.channel === 'hud') {
+        options.hud.set({
+          source: options.hudSource,
+          label: options.hudLabel,
+          payload: presentation.payload,
+        });
+      }
+      if (presentation.channel === 'overlay') {
+        options.overlay?.apply(options.hudSource, presentation.payload, options.grid);
+      }
+    },
+    onCircuitOpen: () => {
+      options.hud.remove(options.hudSource);
+      options.overlay?.remove(options.hudSource);
+    },
+  });
+  await broker.start(fetched.bytes);
+  return {
+    stop: () => {
+      broker.stop();
+      options.hud.remove(options.hudSource);
+      options.overlay?.remove(options.hudSource);
+    },
+  };
+}
+
+/**
+ * The game's own router first (local reads, optimistic writes); anything it
+ * does not offer goes to `serverCalls` when the game supplied it.
+ */
+export async function routeWithFallback(
+  call: PlayerCodeHostCall,
+  local: () => Promise<unknown>,
+  serverCalls?: (call: PlayerCodeHostCall) => Promise<unknown>,
+): Promise<unknown> {
+  try {
+    return await local();
+  } catch (error) {
+    if (error instanceof HostCallRefusedError && serverCalls) return serverCalls(call);
+    throw error;
+  }
+}
+
+function minBig(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}
+
+function maxBig(a: bigint, b: bigint): bigint {
+  return a > b ? a : b;
+}