@origingame/engine 0.1.1 → 0.3.0

package/src/node/run.ts

@@ -5,7 +5,8 @@
 //   bun src/node/run.ts --entry <game.js|.ts> [--root <project>] [--ticks N] [--seed S]
 //       [--setup action[:arg...]]... [--commands "t:action[:args];..."] [--out <dir>]
 //       [--port P] [--size WxH] [--realtime] [--watch <bundle.js>] [--no-render]
-//       [--audio null|device|<out.wav>] [--platform-store <file.json>] [--clock <UTC ms>] [--locale <tag>] [--json]
+//       [--audio null|device|<out.wav>] [--platform-store <file.json>] [--clock <UTC ms>] [--locale <tag>]
+//       [--trace <out.json> [--trace-append]] [--room ws://127.0.0.1:P/<room>] [--json]
 //
 // - Without --commands, --port or --watch: advance --ticks N at once and print
 //   the world hash (M2's hello world).
@@ -19,11 +20,21 @@
 //   through the probe's `reload` (snapshot, swap, restore), printing one JSON
 //   line per reload with the latency from the file write to the first frame
 //   of the new bundle.
+// - With --room: the engine joins that room through `og relay` (og.platform's
+//   rooms, og.net's lockstep), the link pumped around every frame, and the run
+//   takes frames (never one big advance), so a tick lockstep holds waits for
+//   the other players' inputs; it ends at `quit`, --ticks or the script's end.
 // - Without a renderer (no usable adapter, as in the platform's engine and
 //   probe sandboxes, or OG_RENDERER=none) the run is the same run: the play
 //   surface keeps --size, a `screenshot` writes no PNG and is listed in
 //   --json's `unchecked` ("no renderer, frame unchecked"), the tier is
 //   `none`, and the exit status does not change.
+// - With --trace: the run in the Chrome trace format (src/trace.ts and
+//   crates/og-runtime/src/trace.rs have the threads): each tick with its
+//   systems, each frame with its render passes' CPU encoding and their GPU
+//   time, each load, og-lanes' jobs on their pool threads, every span where
+//   it ran; --trace-append adds them to the file og wrote first (its
+//   metadata, its origin and the cook's spans).
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -32,7 +43,8 @@ import { pathToFileURL } from "node:url";
 import { loadNativeHost, native } from "./index.ts";
 import { openAudio, type AudioSink } from "./audio.ts";
 import { nativePlatform } from "./platform.ts";
-import { beginBundle, createEngine, fixedClock, type Engine, type GameToken } from "../runtime.ts";
+import { Trace, unixMs, type TraceDocument } from "../trace.ts";
+import { beginBundle, boundHost, createEngine, fixedClock, type Engine, type GameToken } from "../runtime.ts";
 
 const argv = process.argv.slice(2);
 let entry = "";
@@ -51,6 +63,9 @@ let audioOut = "null";
 let platformStore: string | undefined;
 let locale: string | undefined;
 let clock: number | undefined;
+let tracePath: string | undefined;
+let traceAppend = false;
+let room: string | undefined;
 const setup: string[] = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i]!;
@@ -79,6 +94,9 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === "--platform-store") platformStore = resolve(next());
   else if (a === "--locale") locale = next();
   else if (a === "--clock") clock = Number(next());
+  else if (a === "--trace") tracePath = resolve(next());
+  else if (a === "--trace-append") traceAppend = true;
+  else if (a === "--room") room = next();
   else if (a === "--headless") {
     // Native runs are always headless; accepted for `og run --headless`.
   } else fail(`unknown argument '${a}'`);
@@ -97,6 +115,17 @@ if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535))
 
 loadNativeHost();
 const extras = native();
+
+// --trace: the Chrome trace (src/trace.ts), continuing og's prelude (the cook) when appending.
+const trace = tracePath
+  ? new Trace({ producer: "og run --trace", process: "og run", ...(traceAppend && existsSync(tracePath) ? { prior: JSON.parse(readFileSync(tracePath, "utf8")) as Partial<TraceDocument> } : {}) })
+  : undefined;
+/** Takes the engine's spans (each where it ran) onto the trace; `last` waits for the GPU's frames in flight. */
+function takeTrace(engineId: number, last = false): void {
+  if (!trace) return;
+  const taken = extras.og_node_trace_take(engineId, last);
+  trace.append(taken, unixMs());
+}
 let version = 0;
 /**
  * Import a bundle as a fresh module. A re-import goes through a copy under
@@ -131,15 +160,22 @@ function projectProfile(text: string | undefined): "2d" | "3d" | undefined {
 }
 
 const game = await importGame(entry);
+// Loads made while the engine is created (its boot scene's) are traced too.
+const BEFORE_ENGINE = 0xffffffff;
+if (tracePath) extras.og_node_trace(BEFORE_ENGINE, true);
 const project = projectText(root);
 const profile = projectProfile(project);
-const probing = commands !== undefined || port !== undefined || watchFile !== undefined;
+const probing = commands !== undefined || port !== undefined || watchFile !== undefined || room !== undefined;
 // With a renderer, GameDesc.start runs once it is attached (as the web Worker
 // does), so og.render.capabilities reports the play surface's size there.
 const deferStart = probing && render;
 const created = createEngine(game, { ...(seed === undefined ? {} : { seed }), ...(root ? { root } : {}), ...(project === undefined ? {} : { project }), ...(profile ? { profile } : {}), ...(locale ? { locale } : {}), ...(deferStart ? { deferStart } : {}) });
 if (!created.ok) fail(`${entry}: ${created.reason}`);
 const engine: Engine = created.value;
+if (tracePath) {
+  extras.og_node_trace(engine.id, true);
+  extras.og_node_trace(BEFORE_ENGINE, false);
+}
 // og.platform: the local store, in memory unless --platform-store names a file;
 // its clock the system's, or with --clock one that starts there and moves with the ticks.
 if (clock !== undefined) engine.setClock(fixedClock(engine, clock));
@@ -216,6 +252,23 @@ if (port !== undefined) {
   process.stdout.write(`probe: ws://127.0.0.1:${listening}/probe\n`);
 }
 
+if (room !== undefined) {
+  const linked = JSON.parse(extras.og_node_room_connect(engine.id, room)) as { ok: boolean; reason?: string };
+  if (!linked.ok) fail(`--room ${room}: ${linked.reason}`);
+  // The relay joins the room the URL names: wait for its answer before the first tick.
+  for (let i = 0; i < 2000 && (JSON.parse(abiRoomInfo()) as { state: string }).state !== "in"; i++) {
+    extras.og_node_room_pump(engine.id);
+    await new Promise((r) => setTimeout(r, 1));
+  }
+}
+
+function abiRoomInfo(): string {
+  return boundHost()!.abi.og_platform_room_info(engine.id);
+}
+
+type NetStatus = { running: boolean; startTick: number | null; waits: number; desync: number | null };
+const netStatus = (): NetStatus => JSON.parse(boundHost()!.abi.og_net_status(engine.id)) as NetStatus;
+
 let untilTick = -1;
 if (commands !== undefined) {
   const report = engine.probe.commands(commands) as { scheduled: number; untilTick: number; warnings: string[] } | null;
@@ -286,7 +339,9 @@ if (!probing) {
     }
     const elapsed = realtime ? performance.now() - last : tickMs;
     last = performance.now();
+    if (room !== undefined) extras.og_node_room_pump(engine.id);
     const answer = engine.frame(elapsed);
+    if (room !== undefined) extras.og_node_room_pump(engine.id);
     if (!answer.ok) {
       frameFailed = answer.reason ?? "the frame failed";
       break;
@@ -297,6 +352,7 @@ if (!probing) {
     }
     sink.pump();
     if (listening !== undefined) extras.og_node_probe_serve(engine.id);
+    takeTrace(engine.id);
     drain();
     const tick = answer.tick ?? 0;
     if (answer.quit) {
@@ -304,12 +360,28 @@ if (!probing) {
       break;
     }
     if (ticks !== undefined && tick >= ticks) break;
-    if (ticks === undefined && commands !== undefined && listening === undefined && !watchFile && tick > untilTick) break;
+    // The script ends once its last step has run: a restore moving og.Time
+    // forward or back moves the steps with it (they keep their delays), so
+    // the tick its last step was scheduled for is no end (brasswick #13).
+    const left = answer.pending ?? (tick > untilTick ? 0 : 1);
+    if (ticks === undefined && commands !== undefined && listening === undefined && !watchFile && left === 0) break;
     if (realtime || listening !== undefined || watchFile) await sleep(Math.max(0, tickMs - (performance.now() - last)));
+    // In a room a frame that took no tick waits for the other players' inputs,
+    // and outside lockstep (its lobby, or a game that leaves it off) the run
+    // keeps the tick's pace with the other peers: an unpaced lobby would
+    // spend the run's --ticks before they arrive.
+    else if (room !== undefined && (answer.ticks ?? 0) === 0) await sleep(1);
+    else if (room !== undefined && !netStatus().running) await sleep(Math.max(0, tickMs - (performance.now() - last)));
   }
 }
 const ms = performance.now() - t0;
 drain();
+if (tracePath) {
+  takeTrace(engine.id, true);
+  mkdirSync(dirname(tracePath), { recursive: true });
+  writeFileSync(tracePath, JSON.stringify(trace!.document()));
+  outputs.push(tracePath);
+}
 let wavSha256: string | undefined;
 if (audioMode === "capture") {
   const wavPath = resolve(audioOut);
@@ -323,6 +395,8 @@ const audioStats = sink.stats();
 sink.close();
 if (frameFailed) process.stderr.write(`og run: ${frameFailed}\n`);
 const dump = engine.probe.dump({ what: "world" }) as unknown as { hash: string; entities: number; tick: number; systems?: SystemTimes };
+// The script's expectations (`expect:` steps): a failure fails the run.
+const expectations = engine.probe.expectations();
 // og polish's order statistics (src/node/polish.ts), so the two agree.
 const percentile = (xs: number[], q: number): number => {
   if (xs.length === 0) return 0;
@@ -355,19 +429,30 @@ const summary = {
   ticks: ticks ?? dump.tick,
   tick: dump.tick,
   hash: dump.hash,
+  // og.net's shared hash: the world without this peer's session, what lockstep peers compare.
+  netHash: JSON.parse(boundHost()!.abi.og_net_hash(engine.id)) as string,
+  // With --room: lockstep's state at the end (the tick it started, the waits, the first divergent tick).
+  ...(room !== undefined ? { lockstep: netStatus() } : {}),
   entities: dump.entities,
   advanceMs: +ms.toFixed(2),
   frames,
   systems,
   runtime: typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.version}`,
   tier,
+  // Whether the device timed each render pass on the GPU (RenderCapabilities.gpuTimestamps): the trace's gpu thread and ProbeTimings.gpuPasses.
+  gpuTimestamps: (JSON.parse(boundHost()!.abi.og_render_capabilities(engine.id)) as { gpuTimestamps?: boolean }).gpuTimestamps ?? false,
   quit,
   unchecked,
   audio: { mode: audioMode, commands: audioStats.commands, receivedHash: audioStats.receivedHash, wavSha256 },
   outputs,
   warnings,
+  expectations,
 };
 if (asJson) process.stdout.write(JSON.stringify(summary) + "\n");
-else process.stdout.write(`tick ${dump.tick} hash ${dump.hash} entities ${dump.entities}\n`);
+else {
+  process.stdout.write(`tick ${dump.tick} hash ${dump.hash} entities ${dump.entities}\n`);
+  if (expectations.results.length > 0) process.stdout.write(`expectations: ${expectations.passed} passed, ${expectations.failed} failed, ${expectations.unchecked} unchecked\n`);
+}
 if (listening !== undefined) extras.og_node_probe_close(engine.id);
-process.exit(frameFailed ? 1 : 0);
+if (room !== undefined) extras.og_node_room_close(engine.id);
+process.exit(frameFailed || expectations.failed > 0 ? 1 : 0);

package/src/p2.ts

@@ -1,4 +1,4 @@
-// The phase 2 modules' namespaces (IDL `terrain`): thin calls into the host's binding symbols,
+// The phase 2 and depth modules' namespaces (IDL `terrain`, `stream`, `path`, `timeline`): thin calls into the host's binding symbols,
 // typed by the generated declarations through index.ts.
 
 import type { HostAbi } from "./generated/abi.ts";
@@ -33,3 +33,21 @@ export const stream = Object.freeze({
   budget: (world: W) => parse(abi().og_stream_budget(world.id)),
   setBudget: (world: W, bytes: number) => parse(abi().og_stream_set_budget(world.id, bytes)),
 });
+
+// Depth S2 (IDL `path`, `timeline`).
+export const path = Object.freeze({
+  create: (world: W, desc?: unknown) => parse(abi().og_path_create(world.id, json(desc))),
+  find: (world: W, name: string) => parse(abi().og_path_find(world.id, name)),
+  sample: (world: W, p: number, t: number) => parse(abi().og_path_sample(world.id, p, t)),
+  length: (world: W, p: number) => parse(abi().og_path_length(world.id, p)),
+  nearest: (world: W, p: number, point: unknown) =>
+    parse(abi().og_path_nearest(world.id, p, JSON.stringify(point))),
+});
+
+export const timeline = Object.freeze({
+  info: (world: W, asset: number) => parse(abi().og_timeline_info(world.id, asset)),
+  play: (world: W, entity: number) => parse(abi().og_timeline_play(world.id, entity)),
+  pause: (world: W, entity: number) => parse(abi().og_timeline_pause(world.id, entity)),
+  seek: (world: W, entity: number, time: number) => parse(abi().og_timeline_seek(world.id, entity, time)),
+  stop: (world: W, entity: number) => parse(abi().og_timeline_stop(world.id, entity)),
+});

package/src/playtest.ts

@@ -52,6 +52,42 @@ export interface PlaytestRun {
   wav(file: string): { rate: number; frames: number; peak: number; rms: number };
   /** The runs of PlaytestDesc.then, in order, each with its own files (empty without `then`). */
   readonly then: readonly PlaytestRun[];
+  /** og.net's shared hash at the end (og.net.hash): the world without this process's session, what lockstep peers compare. */
+  readonly netHash: string;
+  /** With PlaytestDesc.room: og.net.status at the end (running, the start tick, the seats, the first divergent tick); null outside a room. */
+  readonly lockstep: PlaytestLockstep | null;
+  /** With PlaytestDesc.room: the room's other processes (peer scripts 1, 2, ...), each with its own files; empty outside a room. */
+  readonly peers: readonly PlaytestRun[];
+}
+
+/** og.net.status of a playtest process in a room, at its end. */
+export interface PlaytestLockstep {
+  readonly running: boolean;
+  readonly peer: number | null;
+  readonly startTick: number | null;
+  readonly players: number | null;
+  readonly waits: number;
+  /** The first divergent tick, once og.Desync was sent. */
+  readonly desync: number | null;
+}
+
+/** PlaytestDesc.room: the script's processes play together in one room. */
+export interface PlaytestRoom {
+  /** How many processes join the room (2 to 16). */
+  readonly players: number;
+  /** Each process's script by its place (0 is the playtest's own `commands`); a process without one runs `commands`. */
+  readonly commands?: readonly string[];
+  /** The room's name in the relay (default `playtest`). */
+  readonly name?: string;
+  /**
+   * The tick every process stops at (`og run --ticks`), when the scripts do not end first: their
+   * `netHash` there is what lockstep makes equal. Leave it out to end each script by its `quit`
+   * (or its last step). A script's steps are on the room's shared ticks once lockstep runs (a
+   * peer that takes the authority's snapshot at the start moves to its tick and its steps stay
+   * on theirs, a step whose tick it jumped past running at once), so a `quit` or an `expect` at
+   * tick t runs at tick t on every peer.
+   */
+  readonly ticks?: number;
 }
 
 /** The checks a playtest makes; a playtest that made none fails. */
@@ -106,9 +142,25 @@ export interface PlaytestDesc {
    * process has its own store in memory.
    */
   readonly store?: "keep";
-  /** More processes after the script, in order, each a fresh `og run` (a relaunch): their runs are `run.then`. */
+  /**
+   * Play the script in a room (docs/design.md §2.8, §2.10): the playtest starts a relay
+   * (`og relay`, in its own process) and runs `players` processes at once, each `og run
+   * --room ws://127.0.0.1:P/<name>` with its own script (`room.commands[i]`, else `commands`)
+   * and its own files. The first is the run; the others are `run.peers`. Every process stops
+   * at `room.ticks`, or at its script's `quit`, which lands on one tick of the room for all.
+   * `runs` is refused with it; each `then` step relaunches every process at once into a room of
+   * its own (`<name>.then-<n>`), each running the step's script, its runs in `run.then[n].peers`;
+   * `store: "keep"` keeps one store per place across them.
+   */
+  readonly room?: PlaytestRoom;
+  /** More processes after the script, in order, each a fresh `og run` (a relaunch): their runs are `run.then`. With `room`, every place of the room relaunches at once. */
   readonly then?: readonly PlaytestStep[];
-  readonly check: (run: PlaytestRun, t: PlaytestChecks) => void | Promise<void>;
+  /**
+   * Checks over what the run wrote. Optional when the script carries `expect:` steps: each
+   * expectation is a check (a failed one fails the playtest with its tick and observed value,
+   * a frame one without a renderer is unchecked), so a playtest can be its script alone.
+   */
+  readonly check?: (run: PlaytestRun, t: PlaytestChecks) => void | Promise<void>;
 }
 
 /** A later process of a playtest (`PlaytestDesc.then`). */
@@ -124,8 +176,9 @@ export const PLAYTEST_CLOCK = 1767225600000;
 
 /** Declare a playtest: the default export of a `tests/*.og.ts` file. */
 export function playtest(desc: PlaytestDesc): PlaytestDesc {
-  if (!desc.name || !desc.commands || typeof desc.check !== "function") {
-    throw new Error("playtest({ name, commands, check }) needs all three");
+  const expects = /(^|;)\s*[\d.]+:expect:/.test(desc.commands ?? "");
+  if (!desc.name || !desc.commands || (typeof desc.check !== "function" && !expects)) {
+    throw new Error("playtest({ name, commands, check }) needs all three (check may be left out when the commands carry expect: steps)");
   }
   return Object.freeze({ ...desc });
 }

package/src/runtime.ts

@@ -1179,6 +1179,8 @@ export class Engine {
     /** Wall milliseconds a tick took (this frame's mean, or the last frame's that ticked) and the last render took. */
     stepMs?: number;
     renderMs?: number;
+    /** The command channel's steps still to run (scheduled, or a screenshot waiting for its frame): a script has ended at 0, however a restore moved og.Time. */
+    pending?: number;
     reason?: string;
     /** The UI's focused text control (web/text-input.ts's TextTarget), or null. */
     text?: { path: string; rect: [number, number, number, number]; multiline: boolean; selection: string; composing: boolean } | null;
@@ -1309,6 +1311,10 @@ function makeProbe(id: number) {
     commands: (script: string) => parse(a().og_engine_probe_commands(id, script)),
     listen: (seconds?: number) => parse(a().og_engine_probe_listen(id, seconds)),
     memory: () => parse(a().og_engine_probe_memory(id)),
+    describe: () => parse(a().og_engine_probe_describe(id)),
+    expect: (what: string) => parse(a().og_engine_probe_expect(id, what)),
+    expectations: () => parse(a().og_engine_probe_expectations(id)),
+    saveScene: (write?: boolean, spawned?: boolean) => parse(a().og_engine_probe_save_scene(id, write, spawned)),
   });
 }
 
@@ -1361,17 +1367,21 @@ export const load = Object.freeze({
   environment: (world: WorldImpl, path: string) => parse(abi().og_load_environment(world.id, path)),
   emitter: (world: WorldImpl, path: string) => parse(abi().og_load_emitter(world.id, path)),
   shader: (world: WorldImpl, path: string) => parse(abi().og_load_shader(world.id, path)),
-  skin: (world: WorldImpl, path: string) => parse(abi().og_load_skin(world.id, path)),
+  style: (world: WorldImpl, path: string) => parse(abi().og_load_style(world.id, path)),
   look: (world: WorldImpl, path: string) => parse(abi().og_load_look(world.id, path)),
   lookInfo: (world: WorldImpl, look: number) => parse(abi().og_load_look_info(world.id, look)),
   palette: (world: WorldImpl, path: string) => parse(abi().og_load_palette(world.id, path)),
   soundInfo: (world: WorldImpl, sound: number) => parse(abi().og_load_sound_info(world.id, sound)),
+  video: (world: WorldImpl, path: string) => parse(abi().og_load_video(world.id, path)),
+  videoInfo: (world: WorldImpl, video: number) => parse(abi().og_load_video_info(world.id, video)),
   status: (world: WorldImpl, asset: number) => abi().og_load_status(world.id, asset),
   error: (world: WorldImpl, asset: number) => parse(abi().og_load_error(world.id, asset)),
   gltfInfo: (world: WorldImpl, asset: number) => parse(abi().og_load_gltf_info(world.id, asset)),
   animation: (world: WorldImpl, path: string) => parse(abi().og_load_animation(world.id, path)),
+  timeline: (world: WorldImpl, path: string) => parse(abi().og_load_timeline(world.id, path)),
   flipbook: (world: WorldImpl, path: string) => parse(abi().og_load_flipbook(world.id, path)),
   rig: (world: WorldImpl, path: string) => parse(abi().og_load_rig(world.id, path)),
+  rig2d: (world: WorldImpl, path: string) => parse(abi().og_load_rig2d(world.id, path)),
   tilemap: (world: WorldImpl, path: string) => parse(abi().og_load_tilemap(world.id, path)),
 });
 
@@ -1379,8 +1389,10 @@ export const anim = Object.freeze({
   graph: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_graph(world.id, json(desc))),
   humanoid: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_humanoid(world.id, json(desc))),
   retarget: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_retarget(world.id, json(desc))),
-  // One lookup for a flipbook's clips (an index, -1 when missing) and a
-  // loaded model's (og.load.animation: a ClipAsset, 0 when missing).
+  rig2dInfo: (world: WorldImpl, rig: number) => parse(abi().og_anim_rig2d_info(world.id, rig)),
+  skeleton2dBoxes: (world: WorldImpl, entity: number) => parse(abi().og_anim_skeleton2d_boxes(world.id, entity)),
+  // One lookup for a flipbook's or a 2D rig's clips (an index, -1 when
+  // missing) and a loaded model's (og.load.animation: a ClipAsset, 0 when missing).
   clip: (info: { clips?: ReadonlyArray<{ clip: number; name: string }>; skeleton?: number }, name: string): number =>
     info?.clips?.find((c) => c.name === name)?.clip ?? (info?.skeleton !== undefined ? 0 : -1),
 });

package/src/targets.ts

@@ -0,0 +1,28 @@
+// Depth S8's additions (IDL `render` render targets and custom post
+// passes, `load.post`): thin calls into the host's binding symbols, typed by
+// the generated declarations through index.ts.
+
+import type { HostAbi } from "./generated/abi.ts";
+import { boundHost } from "./runtime.ts";
+
+type W = { readonly id: number };
+
+function abi(): HostAbi<Uint32Array, unknown> {
+  const h = boundHost();
+  if (!h) throw new Error("no engine host is loaded: start the game through @origingame/engine's web or node loader");
+  return h.abi;
+}
+
+const parse = <T>(text: string): T => JSON.parse(text) as T;
+const json = (value: unknown): string | undefined => (value === undefined ? undefined : JSON.stringify(value));
+
+export const targetsRender = Object.freeze({
+  renderTarget: (world: W, desc?: unknown) => parse(abi().og_render_render_target(world.id, json(desc))),
+  setPostParam: (world: W, post: number, name: string, value: ReadonlyArray<number>) =>
+    parse(abi().og_render_set_post_param(world.id, post, name, JSON.stringify(value))),
+  postErrors: (world: W) => parse(abi().og_render_post_errors(world.id)),
+});
+
+export const targetsLoad = Object.freeze({
+  post: (world: W, path: string) => parse(abi().og_load_post(world.id, path)),
+});

package/src/trace.ts

@@ -0,0 +1,169 @@
+// The run's trace in the Chrome trace format (the Trace Event Format's JSON
+// object form, which Perfetto and chrome://tracing open), the same document
+// on both hosts: native `og run --trace` (src/node/run.ts) and the web
+// Worker (src/web/worker.ts, read through the shell's `trace()`).
+//
+// The engine records every span where it ran and hands them over as Chrome
+// trace events on its own clock (crates/og-runtime/src/trace.rs: `{ now,
+// events }`, `ts` in µs); a take is placed on the document's origin (Unix
+// milliseconds) by the difference between the host's time and the engine's
+// clock read together. Threads of process 1: 1 engine, 2 render, 3 load,
+// 4 cook (og's, natively), 5 gpu, 16 + n og-lanes' pool thread n, 48 + n
+// the cook's thread n; threads that appear mid-run arrive with their names.
+
+export type TraceEvent = Record<string, unknown> & { ph: string; pid: number; tid: number; name: string; ts?: number; dur?: number };
+
+/** A Chrome trace document as written to a file. */
+export type TraceDocument = {
+  traceEvents: TraceEvent[];
+  displayTimeUnit: "ms";
+  otherData: { originUnixMs: number; producer: string; [k: string]: unknown };
+};
+
+/** The fixed threads and their names. */
+export const TRACE_THREADS: readonly (readonly [number, string])[] = [
+  [1, "engine"],
+  [2, "render"],
+  [3, "load"],
+  [4, "cook"],
+  [5, "gpu"],
+];
+
+/** The process and fixed threads' metadata events. */
+export function traceMetadata(process: string): TraceEvent[] {
+  const out: TraceEvent[] = [{ name: "process_name", ph: "M", pid: 1, tid: 0, args: { name: process } }];
+  for (const [tid, name] of TRACE_THREADS) {
+    out.push({ name: "thread_name", ph: "M", pid: 1, tid, args: { name } });
+    out.push({ name: "thread_sort_index", ph: "M", pid: 1, tid, args: { sort_index: tid } });
+  }
+  return out;
+}
+
+/** Unix milliseconds, to the microsecond where the clock has it. */
+export function unixMs(): number {
+  return performance.timeOrigin + performance.now();
+}
+
+/** A trace being recorded: takes appended as they come, the document at the end. */
+export class Trace {
+  readonly events: TraceEvent[];
+  readonly origin: number;
+  readonly producer: string;
+  /** Thread names already in the document (a take names a thread once per engine trace; a document may hold several). */
+  private named = new Set<number>();
+  /** µs from the engine's clock to the document's origin, set by the first take. */
+  private shift: number | undefined;
+
+  /** A new document from `origin` (Unix ms), or one continued from `prior` (og's prelude: the cook). */
+  constructor(opts: { origin?: number; prior?: Partial<TraceDocument>; producer: string; process?: string }) {
+    this.producer = opts.producer;
+    if (opts.prior?.traceEvents) {
+      this.events = [...opts.prior.traceEvents];
+      this.origin = opts.prior.otherData?.originUnixMs ?? opts.origin ?? unixMs();
+    } else {
+      this.events = traceMetadata(opts.process ?? opts.producer);
+      this.origin = opts.origin ?? unixMs();
+    }
+    for (const e of this.events) if (e.ph === "M" && e.name === "thread_name") this.named.add(e.tid);
+  }
+
+  /**
+   * Places one take of the engine (`og_*_trace_take`'s JSON) on the
+   * document's origin: `hostNow` is the host's Unix ms read beside the take.
+   */
+  append(taken: string | { now: number; events: TraceEvent[] }, hostNow: number = unixMs()): void {
+    const t = typeof taken === "string" ? (JSON.parse(taken) as { now: number; events: TraceEvent[] }) : taken;
+    // One shift for the whole trace, from the first take: both clocks are
+    // monotonic at the same rate, and a shift read again at every take
+    // would move spans that abut across two takes by its jitter (tens of
+    // µs), so that they overlap.
+    this.shift ??= Math.round((hostNow - t.now - this.origin) * 1000);
+    const shift = this.shift;
+    for (const e of t.events) {
+      if (e.ph === "M") {
+        if (e.name === "thread_name") {
+          if (this.named.has(e.tid)) continue;
+          this.named.add(e.tid);
+        }
+        this.events.push(e);
+        continue;
+      }
+      this.events.push({ ...e, ts: (e.ts ?? 0) + shift });
+    }
+  }
+
+  document(extra: Record<string, unknown> = {}): TraceDocument {
+    return { traceEvents: this.events, displayTimeUnit: "ms", otherData: { originUnixMs: this.origin, producer: this.producer, ...extra } };
+  }
+}
+
+/** What {@link checkTrace} found. */
+export type TraceCheck = { errors: string[]; spans: number; threads: Record<number, string> };
+
+/**
+ * Holds a document to the format as Perfetto's importer reads it, and to
+ * what this engine's traces promise: `traceEvents` a list; every `X` event
+ * a name, integer `ts`, `dur` ≥ 0 and integer `pid`/`tid`; metadata with
+ * `args.name`; every span on a thread nested inside the one it starts in
+ * (never overlapping it); and spans that lie where they ran. A thread whose
+ * children are laid end to end from their parent's start in every parent
+ * (the first child at the parent's `ts`, each next one where the previous
+ * ended), over at least `endToEndAfter` parents with two or more children,
+ * is reported: recorded starts leave gaps somewhere. The GPU's passes
+ * (`cat` "gpu") are exempt: one timestamp ends a pass and begins the next,
+ * so they are back to back by the measurement's construction.
+ */
+export function checkTrace(doc: unknown, endToEndAfter = 8): TraceCheck {
+  const errors: string[] = [];
+  const threads: Record<number, string> = {};
+  const d = doc as Partial<TraceDocument> | null;
+  if (!d || !Array.isArray(d.traceEvents)) return { errors: ["traceEvents is not a list"], spans: 0, threads };
+  const byTid = new Map<number, { ts: number; dur: number; name: string }[]>();
+  const backToBack = new Set<number>();
+  for (const e of d.traceEvents) {
+    if (!Number.isInteger(e.pid) || !Number.isInteger(e.tid)) errors.push(`${e.name}: pid/tid not integers`);
+    if (e.ph === "M") {
+      const name = (e.args as { name?: unknown } | undefined)?.name;
+      if ((e.name === "thread_name" || e.name === "process_name") && typeof name !== "string") errors.push(`${e.name} metadata without args.name`);
+      if (e.name === "thread_name" && typeof name === "string") threads[e.tid] = name;
+      continue;
+    }
+    if (e.ph !== "X") continue;
+    if (typeof e.name !== "string" || !Number.isInteger(e.ts) || !Number.isInteger(e.dur) || (e.dur as number) < 0) {
+      errors.push(`malformed span ${JSON.stringify(e).slice(0, 120)}`);
+      continue;
+    }
+    let list = byTid.get(e.tid);
+    if (!list) byTid.set(e.tid, (list = []));
+    list.push({ ts: e.ts as number, dur: e.dur as number, name: e.name });
+    if (e.cat === "gpu") backToBack.add(e.tid);
+  }
+  let spans = 0;
+  for (const [tid, list] of byTid) {
+    if (!(tid in threads)) errors.push(`thread ${tid} has spans and no name`);
+    spans += list.length;
+    // Parents first: earlier start, then the longer one.
+    list.sort((a, b) => a.ts - b.ts || b.dur - a.dur);
+    const stack: { ts: number; end: number; name: string; children: { ts: number; end: number }[] }[] = [];
+    const closed: { ts: number; children: { ts: number; end: number }[] }[] = [];
+    const close = () => closed.push(stack.pop()!);
+    for (const s of list) {
+      const end = s.ts + s.dur;
+      while (stack.length && stack[stack.length - 1]!.end <= s.ts) close();
+      const top = stack[stack.length - 1];
+      if (top && end > top.end) {
+        errors.push(`thread ${tid}: ${s.name} [${s.ts}, ${end}] overlaps ${top.name} [${top.ts}, ${top.end}] without nesting`);
+        continue;
+      }
+      top?.children.push({ ts: s.ts, end });
+      stack.push({ ts: s.ts, end, name: s.name, children: [] });
+    }
+    while (stack.length) close();
+    const parents = closed.filter((p) => p.children.length >= 2);
+    const laid = parents.filter((p) => p.children[0]!.ts === p.ts && p.children.every((c, i) => i === 0 || c.ts === p.children[i - 1]!.end));
+    if (!backToBack.has(tid) && parents.length >= endToEndAfter && laid.length === parents.length) {
+      errors.push(`thread ${tid} (${threads[tid] ?? "?"}): the children of all ${parents.length} parents are laid end to end from the parent's start: starts were derived, not recorded`);
+    }
+  }
+  return { errors, spans, threads };
+}