ugly-game 0.6.1 → 0.7.1

package/dist/index.d.ts

@@ -16,5 +16,7 @@ export * from './loop/gameLoop';
 export * from './loop/layout';
 export * from './loop/controlBlock';
 export * from './loop/deltaRing';
+export * from './loop/commandQueue';
+export * from './loop/lockstep';
 export * from './loop/simCore';
 export * from './loop/simHost';

package/dist/index.js

@@ -18,6 +18,8 @@ export * from './loop/gameLoop';
 export * from './loop/layout';
 export * from './loop/controlBlock';
 export * from './loop/deltaRing';
+export * from './loop/commandQueue';
+export * from './loop/lockstep';
 export * from './loop/simCore';
 export * from './loop/simHost';
 // NOTE: './loop/simHost.worker' is intentionally NOT in the barrel — it is a worker entry, imported directly as

package/dist/loop/commandQueue.d.ts

@@ -0,0 +1,16 @@
+export interface Stamped<I> {
+    c: I;
+    at: number;
+    by?: string;
+    seq?: number;
+}
+export declare class CommandQueue<I> {
+    private q;
+    push(s: Stamped<I>): void;
+    /** Splice out and return every command with `at <= tick` (in order), INCLUDING late ones (`at < tick`). */
+    due(tick: number): Stamped<I>[];
+    /** Drop commands with `at <= tick`, keeping the future — used on resync after loading an authoritative snapshot. */
+    prune(tick: number): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/loop/commandQueue.js

@@ -0,0 +1,39 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// COMMAND QUEUE — the lockstep input buffer. In a co-op sim, inputs (commands) are stamped with the tick they must
+// apply on (`at`) so every client applies the identical stream in the identical order. The worker drains everything
+// `due` at each tick before advancing. Late arrivals (`at < tick` — the tick already stepped) are still returned so
+// the caller can flag divergence. `prune` keeps the future (drops applied history) — the resync primitive; `clear`
+// resets for a new game. Generalized from cogsworth's factoryCommand.ts, parameterized over the game's Input type.
+// ─────────────────────────────────────────────────────────────────────────────
+export class CommandQueue {
+    // Kept sorted ascending by (at, seq) so `due` is a cheap prefix splice.
+    q = [];
+    push(s) {
+        const key = (x) => x.seq ?? 0;
+        let i = this.q.length;
+        while (i > 0) {
+            const p = this.q[i - 1];
+            if (p.at < s.at || (p.at === s.at && key(p) <= key(s)))
+                break;
+            i--;
+        }
+        this.q.splice(i, 0, s);
+    }
+    /** Splice out and return every command with `at <= tick` (in order), INCLUDING late ones (`at < tick`). */
+    due(tick) {
+        let i = 0;
+        while (i < this.q.length && this.q[i].at <= tick)
+            i++;
+        return i === 0 ? [] : this.q.splice(0, i);
+    }
+    /** Drop commands with `at <= tick`, keeping the future — used on resync after loading an authoritative snapshot. */
+    prune(tick) {
+        this.q = this.q.filter((s) => s.at > tick);
+    }
+    clear() {
+        this.q.length = 0;
+    }
+    get size() {
+        return this.q.length;
+    }
+}

package/dist/loop/controlBlock.d.ts

@@ -9,6 +9,7 @@ export declare const CTL_HEADER: {
     readonly TARGET_TICK: 7;
     readonly COOP: 8;
     readonly LATE: 9;
+    readonly STEP_BUDGET: 10;
 };
 export declare function controlByteLength(scalarNames: readonly string[]): number;
 export type { ScalarCell } from './layout';
@@ -24,8 +25,11 @@ export interface ControlView<S extends string> {
     targetTick: number;
     coop: boolean;
     late: number;
+    stepBudget: number;
     scalar(name: S): ScalarCell;
     raw(): Int32Array;
+    /** Atomically read-and-zero STEP_BUDGET — the worker consumes the burst so it can't be applied twice. */
+    takeStepBudget(): number;
     /** Spin-wait (bounded) until PAUSED reaches `target`; returns true if it did. Main-thread safe (no Atomics.wait). */
     waitPaused(target: boolean, spinMax?: number): boolean;
     notify(slot: number): void;

package/dist/loop/controlBlock.js

@@ -15,8 +15,9 @@ export const CTL_HEADER = {
     TARGET_TICK: 7,
     COOP: 8,
     LATE: 9,
+    STEP_BUDGET: 10, // main writes a burst of N forced ticks; the worker takes-and-zeros it (deterministic advance)
 };
-const HEADER_LEN = 10;
+const HEADER_LEN = 11;
 export function controlByteLength(scalarNames) {
     return (HEADER_LEN + scalarNames.length) * 4;
 }
@@ -94,6 +95,15 @@ export function createControlView(buf, scalarNames) {
         set late(v) {
             setn(H.LATE, v);
         },
+        get stepBudget() {
+            return n(H.STEP_BUDGET);
+        },
+        set stepBudget(v) {
+            setn(H.STEP_BUDGET, v);
+        },
+        takeStepBudget() {
+            return Atomics.exchange(a, H.STEP_BUDGET, 0);
+        },
         scalar(name) {
             const slot = idx.get(name);
             if (slot === undefined) {

package/dist/loop/lockstep.d.ts

@@ -0,0 +1,37 @@
+import type { Stamped } from './commandQueue';
+export interface LockstepMsg {
+    t: string;
+    [k: string]: unknown;
+}
+export interface LockstepTransport {
+    send(m: LockstepMsg): void;
+    onMessage(cb: (m: LockstepMsg) => void): void;
+    me(): string;
+}
+export interface LockstepClock {
+    targetTick(): number;
+    setEpoch(tick: number): void;
+}
+export interface LockstepHooks<I> {
+    onCommand(s: Stamped<I>): void;
+    probeHash(): string;
+    hashAt(tick: number): string | undefined;
+    onNeedSnap(from: string): void;
+    onSnapReady(from: string): void;
+}
+export interface Lockstep<I> {
+    send(cmd: I): void;
+    targetTick(): number;
+    onFrame(tick: number): void;
+    needSnap(from?: string): void;
+    snapReady(to: string): void;
+    repin(tick: number): void;
+}
+export interface LockstepOpts<I> {
+    transport: LockstepTransport;
+    clock: LockstepClock;
+    hooks: LockstepHooks<I>;
+    lead?: number;
+    hashEvery?: number;
+}
+export declare function createLockstep<I>(opts: LockstepOpts<I>): Lockstep<I>;

package/dist/loop/lockstep.js

@@ -0,0 +1,63 @@
+export function createLockstep(opts) {
+    const { transport, clock, hooks } = opts;
+    const lead = opts.lead ?? 20;
+    const hashEvery = opts.hashEvery ?? 600;
+    const me = transport.me();
+    const targetTick = () => clock.targetTick();
+    const send = (cmd) => {
+        transport.send({ t: 'cmd', cmd, at: targetTick() + lead, by: me });
+    };
+    const needSnap = (from) => {
+        transport.send({ t: 'need-snap', from: from ?? me });
+    };
+    const snapReady = (to) => {
+        transport.send({ t: 'snap-ready', from: me, to });
+    };
+    const repin = (tick) => {
+        clock.setEpoch(tick);
+        transport.send({ t: 'epoch', tick });
+    };
+    const onFrame = (tick) => {
+        if (hashEvery > 0 && tick % hashEvery === 0) {
+            transport.send({ t: 'hash', tick, hash: hooks.probeHash(), by: me });
+        }
+    };
+    transport.onMessage((m) => {
+        switch (m.t) {
+            case 'cmd':
+                hooks.onCommand({
+                    c: m.cmd,
+                    at: m.at,
+                    by: m.by,
+                    seq: m.seq,
+                });
+                break;
+            case 'hash': {
+                if (m.by === me)
+                    break; // our own echo
+                const local = hooks.hashAt(m.tick);
+                if (local !== undefined && local !== m.hash) {
+                    // Deterministic tiebreak: the higher peer-id yields and requests an authoritative snapshot (from = me, the
+                    // loser). Total order on ids means exactly one side moves — no ping-pong.
+                    if (me > m.by)
+                        needSnap();
+                }
+                break;
+            }
+            case 'need-snap':
+                if (m.from !== me)
+                    hooks.onNeedSnap(m.from);
+                break;
+            case 'snap-ready':
+                if (m.to === undefined || m.to === me)
+                    hooks.onSnapReady(m.from);
+                break;
+            case 'epoch':
+                clock.setEpoch(m.tick);
+                break;
+            default:
+                break;
+        }
+    });
+    return { send, targetTick, onFrame, needSnap, snapReady, repin };
+}

package/dist/loop/simCore.d.ts

@@ -1,8 +1,50 @@
 import type { DeterministicSim } from '../moat';
 import type { ControlView } from './controlBlock';
+import type { CommandQueue } from './commandQueue';
 export interface SimClock {
     now(): number;
 }
+/** The lockstep-capable sim contract. `tick(state, due)` applies the inputs due THIS tick (in order) then advances
+ *  exactly one tick — a superset of the single-player `step` (which fuses one input + one advance). `probeHash` is an
+ *  optional fast dynamic-only hash for co-op divergence probes; `hash` is the full bit-sensitive digest. */
+export interface SimHostSim<S, I> {
+    clone(s: S): S;
+    hash(s: S): string;
+    probeHash?(s: S): string;
+    tick(s: S, due: I[]): void;
+}
+export interface CoopStepOpts<S, I> {
+    sim: SimHostSim<S, I>;
+    state: S;
+    ctl: ControlView<string>;
+    queue: CommandQueue<I>;
+    tickOf: (s: S) => number;
+    maxCatchUpFrames?: number;
+    onLate?: (count: number) => void;
+}
+export interface SoloStepOpts<S, I> {
+    sim: SimHostSim<S, I>;
+    state: S;
+    ctl: ControlView<string>;
+    queue: CommandQueue<I>;
+    tickOf: (s: S) => number;
+    clock: SimClock;
+    lastRef: {
+        t: number;
+    };
+    fps?: number;
+    maxCatchUpFrames?: number;
+}
+/** Single-player stepping: derive a target tick from elapsed wall time (a free-run 60-UPS accumulator, clamped by
+ *  maxCatchUpFrames), publish it to `ctl.targetTick`, then reuse `coopStepBatch` — so solo and co-op run the identical
+ *  drain-due-then-tick path (the only difference is WHO sets the target: the accumulator vs the shared clock).
+ *  Returns the leftover accumulator (seconds). */
+export declare function soloStepBatch<S, I>(opts: SoloStepOpts<S, I>, acc: number): number;
+/** Advance a lockstep sim toward the server-derived `ctl.targetTick`: for each tick, apply the commands due at that
+ *  tick (flagging late arrivals), then `sim.tick`. A `ctl.stepBudget` burst forces extra ticks first (deterministic
+ *  harness/test advance). Catch-up per call is clamped by `maxCatchUpFrames` so a large gap degrades UPS instead of
+ *  blocking. Returns the number of ticks stepped. Pure w.r.t. the control block — the worker calls it each loop. */
+export declare function coopStepBatch<S, I>(opts: CoopStepOpts<S, I>): number;
 export interface FixedStepOpts<S, I> {
     sim: DeterministicSim<S, I>;
     state: S;

package/dist/loop/simCore.js

@@ -1,3 +1,61 @@
+/** Single-player stepping: derive a target tick from elapsed wall time (a free-run 60-UPS accumulator, clamped by
+ *  maxCatchUpFrames), publish it to `ctl.targetTick`, then reuse `coopStepBatch` — so solo and co-op run the identical
+ *  drain-due-then-tick path (the only difference is WHO sets the target: the accumulator vs the shared clock).
+ *  Returns the leftover accumulator (seconds). */
+export function soloStepBatch(opts, acc) {
+    const fps = opts.fps ?? 60;
+    const T = 1 / fps;
+    const maxCatch = opts.maxCatchUpFrames ?? 6;
+    const now = opts.clock.now();
+    const elapsed = Math.max(0, (now - opts.lastRef.t) / 1000);
+    opts.lastRef.t = now;
+    let a = Math.min(acc + elapsed, maxCatch * T);
+    const frames = Math.floor(a / T);
+    a -= frames * T;
+    opts.ctl.targetTick = opts.tickOf(opts.state) + frames;
+    const stepped = coopStepBatch({
+        sim: opts.sim,
+        state: opts.state,
+        ctl: opts.ctl,
+        queue: opts.queue,
+        tickOf: opts.tickOf,
+        maxCatchUpFrames: maxCatch,
+    });
+    if (stepped > 0)
+        opts.ctl.ups = Math.round(stepped / Math.max(elapsed, T)) || opts.ctl.ups;
+    return a;
+}
+/** Advance a lockstep sim toward the server-derived `ctl.targetTick`: for each tick, apply the commands due at that
+ *  tick (flagging late arrivals), then `sim.tick`. A `ctl.stepBudget` burst forces extra ticks first (deterministic
+ *  harness/test advance). Catch-up per call is clamped by `maxCatchUpFrames` so a large gap degrades UPS instead of
+ *  blocking. Returns the number of ticks stepped. Pure w.r.t. the control block — the worker calls it each loop. */
+export function coopStepBatch(opts) {
+    const maxCatch = opts.maxCatchUpFrames ?? 30;
+    let stepped = 0;
+    const stepOnce = () => {
+        const due = opts.queue.due(opts.tickOf(opts.state));
+        if (due.length) {
+            const now = opts.tickOf(opts.state);
+            let late = 0;
+            for (const s of due)
+                if (s.at < now)
+                    late++;
+            if (late && opts.onLate)
+                opts.onLate(late);
+        }
+        opts.sim.tick(opts.state, due.map((d) => d.c));
+        stepped++;
+    };
+    // STEP_BUDGET burst first (forced, deterministic — independent of the target).
+    let budget = opts.ctl.takeStepBudget();
+    while (budget-- > 0 && stepped < maxCatch)
+        stepOnce();
+    // Then chase the target.
+    const target = opts.ctl.targetTick;
+    while (opts.tickOf(opts.state) < target && stepped < maxCatch)
+        stepOnce();
+    return stepped;
+}
 export function fixedStepBatch(opts, acc) {
     const fps = opts.fps ?? 60;
     const maxCatch = (opts.maxCatchUpFrames ?? 6) / fps; // seconds

package/dist/loop/simHost.d.ts

@@ -1,7 +1,7 @@
 import type { Layout } from './layout';
 import { type ControlView } from './controlBlock';
-import { type SimClock } from './simCore';
-import type { DeterministicSim } from '../moat';
+import { type SimClock, type SimHostSim } from './simCore';
+import { type Lockstep, type LockstepTransport, type LockstepClock } from './lockstep';
 import type { NetAdapter } from './gameLoop';
 export interface WorkerLike {
     postMessage(m: unknown): void;
@@ -10,30 +10,18 @@ export interface WorkerLike {
     }) => void) | null;
     terminate(): void;
 }
-export type HostToWorker<I> = {
-    t: 'init';
-    ctlBuf: ArrayBufferLike;
-    dataBuf: ArrayBufferLike;
-    scalars: readonly string[];
-    simFps: number;
-} | {
-    t: 'input';
-    v: I;
-} | {
-    t: 'resync-req';
-};
-export type WorkerToHost = {
-    t: 'ready';
-} | {
-    t: 'hash';
-    hash: string;
-} | {
-    t: 'cold';
-    payload: unknown;
-};
+export interface CoopOpts {
+    transport: LockstepTransport;
+    clock: LockstepClock;
+    lead?: number;
+    hashEvery?: number;
+    onNeedSnap?: (from: string) => void;
+    onSnapReady?: (from: string) => void;
+}
 export interface SimHostOpts<State, Input> {
     layout: Layout<State>;
-    sim: DeterministicSim<State, Input>;
+    sim: SimHostSim<State, Input>;
+    tickOf: (s: State) => number;
     seed?: (s: State) => void;
     scalars?: readonly string[];
     worker?: () => WorkerLike;
@@ -41,6 +29,10 @@ export interface SimHostOpts<State, Input> {
     simFps?: number;
     maxCatchUpFrames?: number;
     net?: NetAdapter;
+    coop?: CoopOpts;
+    /** Extra params forwarded verbatim in the worker `init` message — e.g. a map size a worker rebuilds its Layout
+     *  from. Must be structured-cloneable. */
+    initParams?: Record<string, unknown>;
 }
 export interface SimHost<State, Input> {
     readonly state: State;
@@ -50,6 +42,7 @@ export interface SimHost<State, Input> {
     ctl: ControlView<string>;
     hash(): string;
     netAdapter(): NetAdapter;
+    lockstep?: Lockstep<Input>;
     stop(): void;
     /** Fallback/test only: advance the main-thread sim to wall time `nowMs`. Undefined when a worker owns stepping. */
     pump?(nowMs: number): void;

package/dist/loop/simHost.js

@@ -1,5 +1,7 @@
 import { createControlView, controlByteLength, } from './controlBlock';
-import { fixedStepBatch } from './simCore';
+import { soloStepBatch, coopStepBatch, } from './simCore';
+import { CommandQueue } from './commandQueue';
+import { createLockstep, } from './lockstep';
 const canSAB = () => typeof SharedArrayBuffer !== 'undefined' &&
     (globalThis
         .crossOriginIsolated ??
@@ -16,8 +18,10 @@ export function createSimHost(opts) {
     const state = opts.layout.attach(dataBuf);
     const ctl = createControlView(ctlBuf, scalars);
     opts.seed?.(state);
-    const inputQ = [];
     const clock = opts.clock ?? { now: () => Date.now() };
+    const queue = new CommandQueue();
+    const probe = () => opts.sim.probeHash ? opts.sim.probeHash(state) : opts.sim.hash(state);
+    const sampled = new Map(); // our probe hash per grid tick (for divergence compare)
     let lastHash = opts.sim.hash(state);
     // ── Worker path ──────────────────────────────────────────────
     let worker = null;
@@ -25,55 +29,97 @@ export function createSimHost(opts) {
         worker = opts.worker();
         worker.onmessage = (e) => {
             const m = e.data;
-            if (m.t === 'hash')
+            if (m.t === 'hash' && typeof m.hash === 'string') {
                 lastHash = m.hash;
+                if (typeof m.tick === 'number')
+                    sampled.set(m.tick, m.hash);
+            }
         };
-        const init = {
+        worker.postMessage({
             t: 'init',
             ctlBuf,
             dataBuf,
             scalars,
             simFps: opts.simFps ?? 60,
-        };
-        worker.postMessage(init);
+            coop: !!opts.coop,
+            ...opts.initParams,
+        });
         ctl.playing = true;
     }
+    // ── Lockstep driver (co-op) — lives on the main thread; feeds commands to the queue (fallback) or worker. ──
+    const enqueue = (s) => {
+        if (worker)
+            worker.postMessage({ t: 'cmd', s });
+        else
+            queue.push(s);
+    };
+    let lockstep;
+    if (opts.coop) {
+        lockstep = createLockstep({
+            transport: opts.coop.transport,
+            clock: opts.coop.clock,
+            lead: opts.coop.lead,
+            hashEvery: opts.coop.hashEvery,
+            hooks: {
+                onCommand: enqueue,
+                probeHash: probe,
+                hashAt: (t) => sampled.get(t),
+                onNeedSnap: opts.coop.onNeedSnap ?? (() => undefined),
+                onSnapReady: opts.coop.onSnapReady ?? (() => undefined),
+            },
+        });
+        ctl.coop = true;
+    }
     // ── Fallback path (main-thread stepping) ─────────────────────
     const lastRef = { t: clock.now() };
     let acc = 0;
+    const hashEvery = opts.coop?.hashEvery ?? 600;
     const pump = (nowMs) => {
-        // The fallback clock is driven by the caller's timestamp for determinism in tests + frame-locked stepping.
         const drivenClock = { now: () => nowMs };
-        acc = fixedStepBatch({
-            sim: opts.sim,
-            state,
-            ctl,
-            nextInput: () => inputQ.shift(),
-            clock: drivenClock,
-            lastRef,
-            fps: opts.simFps,
-            maxCatchUpFrames: opts.maxCatchUpFrames,
-        }, acc);
+        if (lockstep) {
+            const tk = opts.tickOf(state);
+            if (tk % hashEvery === 0)
+                sampled.set(tk, probe());
+            ctl.targetTick = lockstep.targetTick();
+            lockstep.onFrame(tk);
+            coopStepBatch({
+                sim: opts.sim,
+                state,
+                ctl,
+                queue,
+                tickOf: opts.tickOf,
+                maxCatchUpFrames: opts.maxCatchUpFrames ?? 30,
+            });
+        }
+        else {
+            acc = soloStepBatch({
+                sim: opts.sim,
+                state,
+                ctl,
+                queue,
+                tickOf: opts.tickOf,
+                clock: drivenClock,
+                lastRef,
+                fps: opts.simFps,
+                maxCatchUpFrames: opts.maxCatchUpFrames,
+            }, acc);
+        }
         lastHash = opts.sim.hash(state);
     };
-    // Solo default: nothing to catch up or resync (single-player). A co-op game passes its own NetAdapter.
     const noop = () => undefined;
     const net = opts.net ?? {
-        window: opts.maxCatchUpFrames ?? 6,
+        window: opts.maxCatchUpFrames ?? 30,
         catchUp: noop,
-        resync: noop,
+        resync: () => lockstep?.needSnap(),
     };
     return {
         state,
         available: useWorker,
         send(input) {
-            if (worker) {
-                const msg = { t: 'input', v: input };
-                worker.postMessage(msg);
-            }
-            else {
-                inputQ.push(input);
-            }
+            if (lockstep)
+                lockstep.send(input); // stamped + forwarded; comes back via onCommand
+            else
+                enqueue({ c: input, at: opts.tickOf(state) + 1 }); // solo: apply next tick
         },
         edit(fn) {
             if (worker) {
@@ -89,12 +135,13 @@ export function createSimHost(opts) {
                 }
             }
             else {
-                fn(state); // fallback: no concurrent stepping, apply directly
+                fn(state);
             }
         },
         ctl,
         hash: () => lastHash,
         netAdapter: () => net,
+        lockstep,
         stop() {
             ctl.running = false;
             worker?.terminate();

package/dist/loop/simHost.worker.d.ts

@@ -1,8 +1,10 @@
-import type { DeterministicSim } from '../moat';
 import type { Layout } from './layout';
+import { type ControlView } from './controlBlock';
+import { type SimHostSim } from './simCore';
 export interface SimWorkerConfig<S, I> {
-    sim: DeterministicSim<S, I>;
-    layout: Layout<S>;
-    makeInput?: (raw: unknown) => I;
+    sim: SimHostSim<S, I>;
+    layout: Layout<S> | ((init: Record<string, unknown>) => Layout<S>);
+    tickOf: (s: S) => number;
+    mirror?: (s: S, ctl: ControlView<string>) => void;
 }
 export declare function runSimWorker<S, I>(cfg: SimWorkerConfig<S, I>): void;

package/dist/loop/simHost.worker.js

@@ -1,55 +1,86 @@
 import { createControlView } from './controlBlock';
-import { fixedStepBatch } from './simCore';
+import { soloStepBatch, coopStepBatch, } from './simCore';
+import { CommandQueue } from './commandQueue';
 export function runSimWorker(cfg) {
     const ctx = globalThis;
-    const inputQ = [];
+    const queue = new CommandQueue();
     let state = null;
     let ctl = null;
     let acc = 0;
+    let coop = false;
     const clock = { now: () => performance.now() };
     const lastRef = { t: 0 };
     let fps = 60;
-    let upsCount = 0;
-    let upsWinStart = 0;
     const loop = () => {
         if (state && ctl?.running) {
-            const before = ctl.tick;
-            acc = fixedStepBatch({
-                sim: cfg.sim,
-                state,
-                ctl,
-                nextInput: () => inputQ.shift(),
-                clock,
-                lastRef,
-                fps,
-            }, acc);
-            const stepped = ctl.tick - before;
-            upsCount += stepped;
-            const now = clock.now();
-            if (upsWinStart === 0)
-                upsWinStart = now;
-            else if (now - upsWinStart >= 500) {
-                ctl.ups = Math.round((upsCount * 1000) / (now - upsWinStart));
-                upsCount = 0;
-                upsWinStart = now;
+            const before = cfg.tickOf(state);
+            if (coop) {
+                coopStepBatch({
+                    sim: cfg.sim,
+                    state,
+                    ctl,
+                    queue,
+                    tickOf: cfg.tickOf,
+                    maxCatchUpFrames: 30,
+                });
+            }
+            else {
+                acc = soloStepBatch({
+                    sim: cfg.sim,
+                    state,
+                    ctl,
+                    queue,
+                    tickOf: cfg.tickOf,
+                    clock,
+                    lastRef,
+                    fps,
+                }, acc);
+            }
+            const stepped = cfg.tickOf(state) - before;
+            // Pause handshake: ack PAUSED, wait for release, rebuild on DIRTY. (Atomics.wait is worker-only.)
+            if (ctl.pauseReq) {
+                ctl.paused = true;
+                ctl.notify(3 /* PAUSED slot */);
+                // Read PAUSE_REQ atomically (not via the getter — narrowing would read it as never-changing) and block until
+                // the main thread clears + notifies it.
+                while (Atomics.load(ctl.raw(), 2 /* PAUSE_REQ */) === 1) {
+                    Atomics.wait(ctl.raw(), 2, 1, 200);
+                }
+                ctl.paused = false;
+                ctl.dirty = false;
+                lastRef.t = clock.now();
+                acc = 0;
+            }
+            if (stepped > 0) {
+                ctl.tick = cfg.tickOf(state);
+                cfg.mirror?.(state, ctl); // publish worker-owned scalars for the main thread
+                ctx.postMessage({
+                    t: 'hash',
+                    hash: cfg.sim.hash(state),
+                    tick: cfg.tickOf(state),
+                });
             }
-            if (stepped > 0)
-                ctx.postMessage({ t: 'hash', hash: cfg.sim.hash(state) });
         }
         setTimeout(loop, 1);
     };
     ctx.onmessage = (e) => {
         const m = e.data;
         if (m.t === 'init') {
-            state = cfg.layout.attach(m.dataBuf);
+            const layout = typeof cfg.layout === 'function' ? cfg.layout(m) : cfg.layout;
+            state = layout.attach(m.dataBuf);
             ctl = createControlView(m.ctlBuf, m.scalars ?? []);
             fps = m.simFps ?? 60;
+            coop = !!m.coop;
             ctl.running = true;
             lastRef.t = clock.now();
             loop();
         }
+        else if (m.t === 'cmd') {
+            queue.push(m.s);
+        }
         else {
-            inputQ.push(cfg.makeInput ? cfg.makeInput(m.v) : m.v);
+            // resync-req: keep future commands, drop the applied history (an authoritative snapshot is being loaded).
+            queue.prune(state ? cfg.tickOf(state) : 0);
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "type": "module",
   "exports": {
     ".": {