ugly-game 0.5.2 → 0.5.4

package/dist/input/browserBackend.d.ts

@@ -27,6 +27,10 @@ export declare class BrowserRawBackend {
     private paused;
     constructor(opts: BrowserBackendOpts);
     setPaused(p: boolean): void;
+    /** Drop every held key / mouse button / touch. Called when the window can no longer observe releases (blur,
+     *  tab hidden, pointer-lock lost) so a key held across the disruption can't stick "on" and drive the avatar
+     *  forever. Public so a host can force it (e.g. right before opening a modal that steals focus). */
+    releaseHeld(): void;
     private on;
     private cursor;
     private gesture;

package/dist/input/browserBackend.js

@@ -36,6 +36,10 @@ export class BrowserRawBackend {
     paused = false; // while a menu is open: suspend gameplay input + don't grab pointer lock
     constructor(opts) { this.target = opts.target; this.pointerLock = opts.pointerLock ?? false; this.attach(); }
     setPaused(p) { this.paused = p; }
+    /** Drop every held key / mouse button / touch. Called when the window can no longer observe releases (blur,
+     *  tab hidden, pointer-lock lost) so a key held across the disruption can't stick "on" and drive the avatar
+     *  forever. Public so a host can force it (e.g. right before opening a modal that steals focus). */
+    releaseHeld() { this.keysDown.clear(); this.touches.clear(); this.pointerButtons.clear(); }
     on(el, type, fn, o) {
         const handler = fn;
         el.addEventListener(type, handler, o);
@@ -54,7 +58,21 @@ export class BrowserRawBackend {
         this.on(window, 'keydown', (e) => { if (!this.keysDown.has(e.code))
             this.edges.add('key:' + e.code); this.keysDown.add(e.code); });
         this.on(window, 'keyup', (e) => { this.keysDown.delete(e.code); });
-        this.on(window, 'blur', () => { this.keysDown.clear(); this.touches.clear(); this.pointerButtons.clear(); });
+        // RELEASE ALL held input whenever the window can no longer see the keys being let go. `blur` alone is not
+        // enough: on macOS an app-switch (Cmd+Tab) delivers the keyup to the background, and the reliable page-side
+        // signal is `visibilitychange`→hidden (blur can be missed). Losing pointer lock (Esc / menu) is the same
+        // hazard. Without this a movement key held at switch-time stays in keysDown and the avatar walks that way
+        // forever ("stuck always going backward"). We clear ONLY on the disruptive edge — never when the tab becomes
+        // visible again or when lock is ACQUIRED, which would wrongly drop a key the player is legitimately holding.
+        this.on(window, 'blur', () => { this.releaseHeld(); });
+        const onHidden = () => { if (document.hidden)
+            this.releaseHeld(); };
+        const onUnlock = () => { if (document.pointerLockElement !== this.target)
+            this.releaseHeld(); };
+        document.addEventListener('visibilitychange', onHidden);
+        document.addEventListener('pointerlockchange', onUnlock);
+        this.disposers.push(() => { document.removeEventListener('visibilitychange', onHidden); });
+        this.disposers.push(() => { document.removeEventListener('pointerlockchange', onUnlock); });
         this.on(this.target, 'wheel', (e) => { this.pwheel += e.deltaY; e.preventDefault(); }, { passive: false });
         this.on(this.target, 'contextmenu', (e) => { e.preventDefault(); });
         this.on(this.target, 'pointerdown', (e) => {

package/dist/net/commands.d.ts

@@ -0,0 +1,47 @@
+/** A command stamped for the agreed tick, with the server's total-order seq + issuer id. */
+export interface Stamped<C> {
+    c: C;
+    at: number;
+    seq?: number;
+    by?: string;
+}
+/** Ordered command buffer: insert stamped commands, drain the ones DUE at a tick in a stable order. */
+export declare class CommandQueue<C> {
+    private q;
+    /** Insert; keeps the buffer sorted by (at, seq, by) so every client drains in the identical order. */
+    add(s: Stamped<C>): void;
+    /** All commands that apply exactly ON `tick`, in order (removed from the queue). */
+    due(tick: number): Stamped<C>[];
+    /** How many buffered commands are already LATE (at < tick) — a divergence signal. */
+    lateCount(tick: number): number;
+    /** Drop everything strictly before `tick` (post-resync prune). */
+    prune(tick: number): void;
+    clear(): void;
+    get size(): number;
+}
+/** Order-sensitive rolling digest of the APPLIED command stream. Two clients that applied the same commands in
+ *  the same order share a journal — so a journal match + a state MISMATCH localises the bug to the sim (not the
+ *  relay), and a journal mismatch localises it to ordering/relay. */
+export declare class CommandJournal {
+    private h;
+    private n;
+    record(at: number, seq: number, by: string): void;
+    get digest(): string;
+    get count(): number;
+}
+/** A ring of recent (frame → state clone) checkpoints for cheap rewind, bounded to `capacity` frames. Keyed by
+ *  frame, so re-checkpointing a frame during replay REPLACES it (the corrected state), and the oldest frames
+ *  evict once the window is full. Stores + hands out owned clones. */
+export declare class CheckpointRing<S> {
+    private clone;
+    private capacity;
+    private m;
+    constructor(clone: (s: S) => S, capacity?: number);
+    put(frame: number, state: S): void;
+    /** The newest checkpoint at or before `frame` (owned clone), or null if it has scrolled out of the ring. */
+    atOrBefore(frame: number): {
+        frame: number;
+        state: S;
+    } | null;
+    get oldest(): number;
+}

package/dist/net/commands.js

@@ -0,0 +1,98 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// COMMANDS — the generic lockstep command plumbing, extracted from cogsworth's
+// factoryCommand.ts so any deterministic game reuses it: an ordered queue keyed by
+// (tick, seq), an order-sensitive JOURNAL digest (separates sim-nondeterminism from
+// relay bugs), and a CHECKPOINT ring for cheap rewind. Generic over the command
+// payload C and the state S. Deterministic: integer ordering + fnv1a only.
+// ─────────────────────────────────────────────────────────────────────────────
+import { fnv1a } from '../stateTree';
+/** Ordered command buffer: insert stamped commands, drain the ones DUE at a tick in a stable order. */
+export class CommandQueue {
+    q = [];
+    /** Insert; keeps the buffer sorted by (at, seq, by) so every client drains in the identical order. */
+    add(s) {
+        this.q.push(s);
+        this.q.sort((a, b) => a.at - b.at ||
+            (a.seq ?? 0) - (b.seq ?? 0) ||
+            (a.by ?? '').localeCompare(b.by ?? ''));
+    }
+    /** All commands that apply exactly ON `tick`, in order (removed from the queue). */
+    due(tick) {
+        const out = [];
+        while (this.q.length && this.q[0].at <= tick) {
+            if (this.q[0].at === tick)
+                out.push(this.q.shift());
+            else
+                this.q.shift(); // an at<tick command is LATE — dropped here; the caller tracks it as divergence
+        }
+        return out;
+    }
+    /** How many buffered commands are already LATE (at < tick) — a divergence signal. */
+    lateCount(tick) {
+        return this.q.filter((s) => s.at < tick).length;
+    }
+    /** Drop everything strictly before `tick` (post-resync prune). */
+    prune(tick) {
+        this.q = this.q.filter((s) => s.at >= tick);
+    }
+    clear() {
+        this.q = [];
+    }
+    get size() {
+        return this.q.length;
+    }
+}
+/** Order-sensitive rolling digest of the APPLIED command stream. Two clients that applied the same commands in
+ *  the same order share a journal — so a journal match + a state MISMATCH localises the bug to the sim (not the
+ *  relay), and a journal mismatch localises it to ordering/relay. */
+export class CommandJournal {
+    h = 'seed';
+    n = 0;
+    record(at, seq, by) {
+        this.h = fnv1a(`${this.h}|${at}:${seq}:${by}`);
+        this.n++;
+    }
+    get digest() {
+        return this.h;
+    }
+    get count() {
+        return this.n;
+    }
+}
+/** A ring of recent (frame → state clone) checkpoints for cheap rewind, bounded to `capacity` frames. Keyed by
+ *  frame, so re-checkpointing a frame during replay REPLACES it (the corrected state), and the oldest frames
+ *  evict once the window is full. Stores + hands out owned clones. */
+export class CheckpointRing {
+    clone;
+    capacity;
+    m = new Map();
+    constructor(clone, capacity = 120) {
+        this.clone = clone;
+        this.capacity = capacity;
+    }
+    put(frame, state) {
+        this.m.set(frame, this.clone(state));
+        while (this.m.size > this.capacity) {
+            let oldest = Infinity;
+            for (const f of this.m.keys())
+                if (f < oldest)
+                    oldest = f;
+            this.m.delete(oldest);
+        }
+    }
+    /** The newest checkpoint at or before `frame` (owned clone), or null if it has scrolled out of the ring. */
+    atOrBefore(frame) {
+        let best = -Infinity;
+        for (const f of this.m.keys())
+            if (f <= frame && f > best)
+                best = f;
+        return best === -Infinity ? null : { frame: best, state: this.clone(this.m.get(best)) };
+    }
+    get oldest() {
+        let o = Infinity;
+        for (const f of this.m.keys())
+            if (f < o)
+                o = f;
+        return o;
+    }
+}

package/dist/net/divergence.d.ts

@@ -0,0 +1,21 @@
+export type DivergenceStatus = 'pending' | 'ok' | 'diverged';
+export interface DivergenceResult {
+    status: DivergenceStatus;
+    iResync?: boolean;
+    peer?: string;
+    tick?: number;
+}
+export declare class DivergenceMonitor {
+    private me;
+    private gridEvery;
+    private local;
+    private remote;
+    constructor(me: string, gridEvery?: number);
+    /** Both clients probe on the SAME ticks (multiples of the grid) without coordinating. */
+    isProbeTick(tick: number): boolean;
+    /** Record + compare our own hash at a probe tick. */
+    recordLocal(tick: number, hash: string): DivergenceResult;
+    /** Record + compare a peer's hash. */
+    recordRemote(tick: number, hash: string, by: string): DivergenceResult;
+    private compare;
+}

package/dist/net/divergence.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// DIVERGENCE MONITOR — lockstep desync detection + recovery arbitration. Clients
+// sample their state hash on a FIXED tick grid (so both pick the same ticks with no
+// coordination) and exchange them. On a mismatch, a TOTAL-ORDER tiebreak (`me > by`)
+// decides exactly ONE side to yield and resync from the other's snapshot — arbitrary
+// but AGREED, so there's no resync ping-pong. Extracted from cogsworth's onHash path.
+// ─────────────────────────────────────────────────────────────────────────────
+export class DivergenceMonitor {
+    me;
+    gridEvery;
+    local = new Map();
+    remote = new Map();
+    constructor(me, gridEvery = 600) {
+        this.me = me;
+        this.gridEvery = gridEvery;
+    }
+    /** Both clients probe on the SAME ticks (multiples of the grid) without coordinating. */
+    isProbeTick(tick) {
+        return tick % this.gridEvery === 0;
+    }
+    /** Record + compare our own hash at a probe tick. */
+    recordLocal(tick, hash) {
+        this.local.set(tick, hash);
+        return this.compare(tick);
+    }
+    /** Record + compare a peer's hash. */
+    recordRemote(tick, hash, by) {
+        if (by === this.me)
+            return { status: 'pending' }; // ignore our own echo
+        this.remote.set(tick, { hash, by });
+        return this.compare(tick);
+    }
+    compare(tick) {
+        const l = this.local.get(tick);
+        const r = this.remote.get(tick);
+        if (l === undefined || r === undefined)
+            return { status: 'pending', tick };
+        if (l === r.hash)
+            return { status: 'ok', tick, peer: r.by };
+        // divergence — the HIGHER id yields (fetches the lower id's snapshot). Exactly one side moves.
+        return { status: 'diverged', iResync: this.me > r.by, peer: r.by, tick };
+    }
+}

package/dist/net/index.d.ts

@@ -0,0 +1,7 @@
+export * from './protocol';
+export * from './commands';
+export * from './lww';
+export * from './sharedClock';
+export * from './divergence';
+export * from './reconcile';
+export * from './roomSocket';

package/dist/net/index.js

@@ -0,0 +1,10 @@
+// `ugly-game/net` — the CLIENT + pure deterministic-netcode surface. The server room (roomCore.ts) is
+// DELIBERATELY not re-exported here: it uses Cloudflare Workers globals and must stay reachable ONLY as
+// `ugly-game/net/roomCore` so a browser bundle importing `ugly-game/net` never pulls server code.
+export * from './protocol';
+export * from './commands';
+export * from './lww';
+export * from './sharedClock';
+export * from './divergence';
+export * from './reconcile';
+export * from './roomSocket';

package/dist/net/lww.d.ts

@@ -0,0 +1,19 @@
+export interface LwwEdit<K, V> {
+    key: K;
+    val: V;
+    stamp: number;
+    by: string;
+}
+export declare class LwwStore<K, V> {
+    private map;
+    private clock;
+    /** Local edit → assign the next stamp (max-seen + 1) and apply. Returns the wire edit to broadcast. */
+    set(key: K, val: V, by: string): LwwEdit<K, V>;
+    /** Apply a REMOTE edit under last-write-wins. Advances the local clock past the seen stamp so our next local
+     *  edit outranks it. Returns true if this edit won (the visible value changed) → the app re-renders that cell. */
+    apply(e: LwwEdit<K, V>): boolean;
+    get(key: K): V | undefined;
+    /** The full delta set — sent to a joining peer so they reconstruct base ⊕ deltas. */
+    snapshot(): LwwEdit<K, V>[];
+    get size(): number;
+}

package/dist/net/lww.js

@@ -0,0 +1,38 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// LWW STORE — a last-write-wins keyed delta store for FREE-ROAM games (all-mine-sky
+// voxel edits). Each edit carries a monotonic stamp (lamport-ish: max-seen+1, tie-
+// broken by author id) so concurrent edits to the same cell converge identically on
+// every client regardless of arrival order — no shared tick, applied on arrival.
+// Doubles as the save format ("send current state on join"). Deterministic.
+// ─────────────────────────────────────────────────────────────────────────────
+export class LwwStore {
+    map = new Map();
+    clock = 0;
+    /** Local edit → assign the next stamp (max-seen + 1) and apply. Returns the wire edit to broadcast. */
+    set(key, val, by) {
+        const e = { key, val, stamp: ++this.clock, by };
+        this.map.set(key, e);
+        return e;
+    }
+    /** Apply a REMOTE edit under last-write-wins. Advances the local clock past the seen stamp so our next local
+     *  edit outranks it. Returns true if this edit won (the visible value changed) → the app re-renders that cell. */
+    apply(e) {
+        if (e.stamp > this.clock)
+            this.clock = e.stamp;
+        const cur = this.map.get(e.key);
+        if (cur && (cur.stamp > e.stamp || (cur.stamp === e.stamp && cur.by >= e.by)))
+            return false; // an existing write outranks it
+        this.map.set(e.key, e);
+        return true;
+    }
+    get(key) {
+        return this.map.get(key)?.val;
+    }
+    /** The full delta set — sent to a joining peer so they reconstruct base ⊕ deltas. */
+    snapshot() {
+        return [...this.map.values()];
+    }
+    get size() {
+        return this.map.size;
+    }
+}

package/dist/net/protocol.d.ts

@@ -0,0 +1,24 @@
+/** Every wire message. `t` is the tag; the rest is tag-specific (opaque for game payloads). */
+export interface RoomMsg {
+    t: string;
+    [k: string]: unknown;
+}
+/** Well-known control tags the platform interprets. Game payloads ride under `relay`/`cur` and are opaque. */
+export declare const TAG: {
+    readonly hello: "hello";
+    readonly ping: "ping";
+    readonly pong: "pong";
+    readonly cur: "cur";
+    readonly relay: "relay";
+    readonly hash: "hash";
+    readonly needSnap: "need-snap";
+    readonly snapReady: "snap-ready";
+    readonly epoch: "epoch";
+    readonly repin: "repin";
+    readonly bye: "bye";
+};
+export type Tag = (typeof TAG)[keyof typeof TAG];
+/** A relayed wire message after the server assigns total order (distinct from commands.Stamped<C>). */
+export interface StampedMsg extends RoomMsg {
+    seq: number;
+}

package/dist/net/protocol.js

@@ -0,0 +1,20 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// NET PROTOCOL — the message envelope shared by the room server (RoomCore) and the
+// client (RoomSocket). The platform relays a small set of WELL-KNOWN control tags
+// and treats the game payloads under `relay`/`cur` as fully OPAQUE, so lockstep
+// (cogsworth) and free-roam (all-mine-sky) reuse the same transport unchanged.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Well-known control tags the platform interprets. Game payloads ride under `relay`/`cur` and are opaque. */
+export const TAG = {
+    hello: 'hello', // server→client on connect: { peers, epoch, now }
+    ping: 'ping', // client→server: { c } (client stamp) ; server→ pong { now, c }
+    pong: 'pong',
+    cur: 'cur', // presence beacon → fanned to OTHERS, unordered, not echoed (ephemeral)
+    relay: 'relay', // an ordered game edit/command → stamped { seq } and fanned to EVERYONE incl. sender
+    hash: 'hash', // divergence probe → fanned to everyone incl. sender
+    needSnap: 'need-snap', // join/resync: ask a peer to flush a snapshot (bulk fetched over HTTP)
+    snapReady: 'snap-ready',
+    epoch: 'epoch', // server→client after a repin
+    repin: 'repin', // lone client re-pins the shared-clock epoch to its own tick
+    bye: 'bye', // a peer left (server→others) : { by }
+};

package/dist/net/reconcile.d.ts

@@ -0,0 +1,24 @@
+import type { MoatSim } from '../moat';
+export interface Correction {
+    rewound: number;
+    diverged: boolean;
+}
+export declare class Reconciler<S, I> {
+    private sim;
+    private ring;
+    private inputs;
+    private st;
+    private f;
+    private window;
+    constructor(sim: MoatSim<S, I>, base: S, baseFrame?: number, window?: number);
+    /** Step the head forward by applying `input` for the current head frame → advance to head+1. */
+    advance(input: I): void;
+    /** An authoritative/corrected input for `frame` arrives. If it's a past frame within the window, rewind and
+     *  replay to head; if it's the future, just buffer it (applied when advance() reaches it); if it predates the
+     *  window, return rewound<0 (the app should resync from a snapshot). */
+    correct(frame: number, input: I): Correction;
+    private pruneInputs;
+    get state(): S;
+    get frame(): number;
+    hash(): string;
+}

package/dist/net/reconcile.js

@@ -0,0 +1,82 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// RECONCILER — client-side rollback over any MoatSim (the moat's netcode payoff).
+//
+// Live play can't wait for the network: you PREDICT missing/remote inputs and step
+// ahead. When an authoritative (or corrected) input for a PAST frame arrives, you
+// rewind to a checkpoint at/just-before that frame, splice the input into the frame-
+// indexed stream, and REPLAY forward to the present. Because the sim is a
+// deterministic MoatSim (clone/hash/step), the replayed head is BYTE-IDENTICAL to
+// what an in-order application would have produced — that's the whole guarantee, and
+// `reconcile.test.mts` proves it via hash equality. Bounded by a checkpoint window;
+// corrections older than the window return rewound<0 so the app can trigger a resync.
+//
+// This is the generic sibling of the branchable StateTree (full saves / AI explore):
+// StateTree branches for exploration; the Reconciler keeps a bounded LINEAR ring for
+// live rollback. Both are the "savestate substrate" the design calls for.
+// ─────────────────────────────────────────────────────────────────────────────
+import { CheckpointRing } from './commands';
+export class Reconciler {
+    sim;
+    ring;
+    inputs = new Map(); // frame f → the input applied AT f (producing frame f+1)
+    st;
+    f; // head frame
+    window;
+    constructor(sim, base, baseFrame = 0, window = 120) {
+        this.sim = sim;
+        this.window = window;
+        this.ring = new CheckpointRing((s) => sim.clone(s), window);
+        this.st = sim.clone(base);
+        this.f = baseFrame;
+        this.ring.put(this.f, this.st);
+    }
+    /** Step the head forward by applying `input` for the current head frame → advance to head+1. */
+    advance(input) {
+        this.inputs.set(this.f, input);
+        this.sim.step(this.st, input);
+        this.f++;
+        this.ring.put(this.f, this.st);
+        this.pruneInputs();
+    }
+    /** An authoritative/corrected input for `frame` arrives. If it's a past frame within the window, rewind and
+     *  replay to head; if it's the future, just buffer it (applied when advance() reaches it); if it predates the
+     *  window, return rewound<0 (the app should resync from a snapshot). */
+    correct(frame, input) {
+        if (frame >= this.f) {
+            this.inputs.set(frame, input); // future input — buffered for when advance() reaches it
+            return { rewound: -1, diverged: false };
+        }
+        const cp = this.ring.atOrBefore(frame);
+        if (!cp)
+            return { rewound: -1, diverged: false }; // scrolled out of the window
+        const before = this.sim.hash(this.st);
+        this.inputs.set(frame, input);
+        let s = cp.state; // an owned clone
+        for (let g = cp.frame; g < this.f; g++) {
+            const inp = this.inputs.get(g);
+            if (inp === undefined)
+                continue; // no input recorded at g → the sim was idle that frame
+            this.sim.step(s, inp);
+            this.ring.put(g + 1, s); // refresh the checkpoint with the corrected trajectory
+        }
+        this.st = s;
+        return { rewound: cp.frame, diverged: this.sim.hash(this.st) !== before };
+    }
+    pruneInputs() {
+        const keep = this.f - this.window;
+        if (keep <= 0)
+            return;
+        for (const g of this.inputs.keys())
+            if (g < keep)
+                this.inputs.delete(g);
+    }
+    get state() {
+        return this.st;
+    }
+    get frame() {
+        return this.f;
+    }
+    hash() {
+        return this.sim.hash(this.st);
+    }
+}

package/dist/net/roomCore.d.ts

@@ -0,0 +1,31 @@
+interface WS {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+interface DOStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface DOState {
+    storage: DOStorage;
+    acceptWebSocket(ws: WS): void;
+    getWebSockets(): WS[];
+}
+export interface RoomOptions {
+    /** ms per tick for the shared clock epoch (lockstep games). Free-roam games can ignore the epoch. */
+    tickMs?: number;
+}
+export declare class RoomCore {
+    private state;
+    private opts;
+    private seq;
+    constructor(state: DOState, opts?: RoomOptions);
+    fetch(request: Request): Promise<unknown>;
+    /** The app DO forwards its webSocketMessage here. */
+    webSocketMessage(ws: WS, message: string | ArrayBuffer): void;
+    webSocketClose(ws: WS): void;
+    webSocketError(ws: WS): void;
+    private json;
+}
+export {};

package/dist/net/roomCore.js

@@ -0,0 +1,146 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOM CORE — the generic multiplayer room, extracted from cogsworth's GameDO. A
+// game's Durable Object is a THIN delegate that forwards fetch/webSocket* to a
+// RoomCore instance; RoomCore owns the transport and treats game payloads as OPAQUE,
+// so lockstep (cogsworth) and free-roam (all-mine-sky) reuse it unchanged.
+//
+// Runs on Cloudflare Workers. Cloudflare types are declared INLINE (as cogsworth's
+// GameDO already does) so this module needs no @cloudflare/workers-types dependency
+// and never leaks Workers types into the client build. NEVER re-export from index.ts
+// and NEVER import from a client module — reachable only as `ugly-game/net/roomCore`.
+//
+// The server NEVER simulates; it only assigns TOTAL ORDER (a seq) and fans out:
+//   · `relay` / `hash`  → stamped { seq } and sent to EVERYONE incl. the sender
+//   · `cur` (presence)  → sent to OTHERS, unordered, not echoed
+//   · `ping`            → `pong { now, c }` (client clock-offset estimation)
+//   · `need-snap`/`snap-ready` → fan out to others (bulk snapshot bytes go over HTTP)
+//   · `repin`           → lone client re-pins the shared-clock epoch
+// Snapshot bytes are stored chunked (PUT/GET) for join/resync + save. WebSocket
+// HIBERNATION (state.acceptWebSocket) means no duration billed while a room idles.
+// ─────────────────────────────────────────────────────────────────────────────
+const CHUNK = 96 * 1024; // DO value cap is ~128KB; chunk snapshots under it
+const KEYS = { epoch: 'epoch', chunks: 'chunks', bytes: 'bytes', tick: 'tick' };
+export class RoomCore {
+    state;
+    opts;
+    seq = 0; // in-memory total-order counter, re-derived from the live set, never persisted
+    constructor(state, opts = {}) {
+        this.state = state;
+        this.opts = opts;
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        const path = url.pathname.split('/').filter(Boolean).pop() ?? '';
+        // ── WebSocket upgrade (hibernatable) ──
+        if (path === 'ws' || url.searchParams.get('ws') === '1') {
+            if (request.headers.get('Upgrade') !== 'websocket')
+                return new Response('expected websocket', { status: 426 });
+            const pair = new WebSocketPair();
+            this.state.acceptWebSocket(pair[1]);
+            let epoch = await this.state.storage.get(KEYS.epoch);
+            if (epoch === undefined) {
+                epoch = Date.now() - (await this.state.storage.get(KEYS.tick) ?? 0) * (this.opts.tickMs ?? 0);
+                await this.state.storage.put(KEYS.epoch, epoch);
+            }
+            pair[1].send(JSON.stringify({ t: 'hello', peers: this.state.getWebSockets().length, epoch, now: Date.now() }));
+            return new Response(null, { status: 101, webSocket: pair[0] });
+        }
+        // ── snapshot SAVE (join/resync + persistence): body = opaque bytes, stored chunked ──
+        if (request.method === 'PUT' || request.method === 'POST') {
+            const body = new Uint8Array(await request.arrayBuffer());
+            if (body.length === 0 || body.length > 16 * 1024 * 1024)
+                return this.json({ error: 'bad snapshot size' }, 400);
+            const n = Math.ceil(body.length / CHUNK);
+            for (let i = 0; i < n; i++)
+                await this.state.storage.put(`snap:${i}`, body.slice(i * CHUNK, (i + 1) * CHUNK));
+            for (let i = n; i < (await this.state.storage.get(KEYS.chunks) ?? 0); i++)
+                await this.state.storage.delete(`snap:${i}`);
+            await this.state.storage.put(KEYS.chunks, n);
+            await this.state.storage.put(KEYS.bytes, body.length);
+            if (url.searchParams.has('tick'))
+                await this.state.storage.put(KEYS.tick, Number(url.searchParams.get('tick')));
+            return this.json({ ok: true, bytes: body.length, chunks: n });
+        }
+        // ── snapshot LOAD ──
+        const chunks = (await this.state.storage.get(KEYS.chunks)) ?? 0;
+        if (chunks === 0)
+            return this.json({ error: 'not found' }, 404);
+        const parts = [];
+        for (let i = 0; i < chunks; i++) {
+            const p = await this.state.storage.get(`snap:${i}`);
+            if (p)
+                parts.push(new Uint8Array(p));
+        }
+        const out = new Uint8Array(parts.reduce((s, p) => s + p.length, 0));
+        let o = 0;
+        for (const p of parts) {
+            out.set(p, o);
+            o += p.length;
+        }
+        return new Response(out, {
+            status: 200,
+            headers: {
+                'content-type': 'application/octet-stream',
+                'x-room-tick': String((await this.state.storage.get(KEYS.tick)) ?? 0),
+                'cache-control': 'no-store',
+                'x-ugly-no-spa-fallback': '1',
+            },
+        });
+    }
+    /** The app DO forwards its webSocketMessage here. */
+    webSocketMessage(ws, message) {
+        let m = null;
+        try {
+            m = JSON.parse(typeof message === 'string' ? message : new TextDecoder().decode(message));
+        }
+        catch {
+            return;
+        }
+        if (!m || typeof m.t !== 'string')
+            return;
+        if (m.t === 'ping') {
+            ws.send(JSON.stringify({ t: 'pong', now: Date.now(), c: m.c }));
+            return;
+        }
+        if (m.t === 'repin' && typeof m.tick === 'number' && this.state.getWebSockets().length === 1) {
+            const epoch = Date.now() - m.tick * (this.opts.tickMs ?? 0);
+            void this.state.storage.put(KEYS.epoch, epoch);
+            ws.send(JSON.stringify({ t: 'epoch', epoch, now: Date.now() }));
+            return;
+        }
+        if (m.t === 'cur' || m.t === 'need-snap' || m.t === 'snap-ready') {
+            const s = JSON.stringify(m); // ephemeral / handshake → fan out to OTHERS only
+            for (const peer of this.state.getWebSockets())
+                if (peer !== ws)
+                    peer.send(s);
+            return;
+        }
+        // `relay` (an ordered edit/command) + `hash` (a divergence probe) → total-ordered, fanned to EVERYONE incl.
+        // the sender (a lockstep issuer must apply its own edit on the same agreed tick as its peers).
+        const stamped = JSON.stringify({ ...m, seq: ++this.seq });
+        for (const peer of this.state.getWebSockets())
+            peer.send(stamped);
+    }
+    webSocketClose(ws) {
+        try {
+            ws.close(1000, 'bye');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    webSocketError(ws) {
+        try {
+            ws.close(1011, 'error');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    json(obj, status = 200) {
+        return new Response(JSON.stringify(obj), {
+            status,
+            headers: { 'content-type': 'application/json', 'x-ugly-no-spa-fallback': '1' },
+        });
+    }
+}

package/dist/net/roomSocket.d.ts

@@ -0,0 +1,43 @@
+import type { RoomMsg } from './protocol';
+export interface RoomSocketOpts {
+    url: string;
+    me: string;
+    onMessage: (m: RoomMsg) => void;
+    onOpen?: (hello: {
+        peers: number;
+        epoch: number;
+        now: number;
+    }) => void;
+    onClose?: () => void;
+    onPong?: (sentAt: number, serverNow: number) => void;
+    presenceHz?: number;
+    pingMs?: number;
+    reconnect?: boolean;
+}
+export declare class RoomSocket {
+    private o;
+    private ws;
+    private closed;
+    private lastPresence;
+    private presencePending;
+    private presenceTimer;
+    private pingTimer;
+    private backoff;
+    readonly me: string;
+    constructor(o: RoomSocketOpts);
+    private connect;
+    get ready(): boolean;
+    private raw;
+    /** An ORDERED edit/command (`relay`) or a divergence probe (`hash`) — echoed back stamped with a total-order seq. */
+    send(m: RoomMsg): void;
+    hashProbe(tick: number, hash: string): void;
+    needSnap(to?: string): void;
+    snapReady(to?: string): void;
+    repin(tick: number): void;
+    /** Presence beacon (`cur`) — coalesced to presenceHz so a fast cursor/pose doesn't flood the relay. */
+    presence(m: RoomMsg): void;
+    private ping;
+    private pingBurst;
+    private stopTimers;
+    close(): void;
+}

package/dist/net/roomSocket.js

@@ -0,0 +1,140 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOM SOCKET — the client half of the room, extracted + generalized from
+// cogsworth's coop.ts. Owns the WebSocket lifecycle (connect + AUTO-RECONNECT with
+// backoff — cogsworth's lacked this), the ping loop feeding clock-offset estimation,
+// presence throttling, and typed send/route. Game-agnostic: it ships/receives opaque
+// `relay`/`cur`/`hash` payloads and hands them to the app via one `onMessage`.
+// Browser client module (uses WebSocket) — never imports the server RoomCore.
+// ─────────────────────────────────────────────────────────────────────────────
+export class RoomSocket {
+    o;
+    ws = null;
+    closed = false;
+    lastPresence = 0;
+    presencePending = null;
+    presenceTimer = null;
+    pingTimer = null;
+    backoff = 500;
+    me;
+    constructor(o) {
+        this.o = o;
+        this.me = o.me;
+        this.connect();
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const ws = new WebSocket(this.o.url);
+        this.ws = ws;
+        ws.onopen = () => {
+            this.backoff = 500;
+            this.pingBurst();
+            this.pingTimer = setInterval(() => this.ping(), this.o.pingMs ?? 15000);
+        };
+        ws.onmessage = (ev) => {
+            let m = null;
+            try {
+                m = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            if (!m || typeof m.t !== 'string')
+                return;
+            if (m.t === 'pong') {
+                this.o.onPong?.(Number(m.c), Number(m.now));
+                return;
+            }
+            if (m.t === 'hello') {
+                this.o.onOpen?.({ peers: Number(m.peers), epoch: Number(m.epoch), now: Number(m.now) });
+                return;
+            }
+            this.o.onMessage(m);
+        };
+        ws.onclose = () => {
+            this.stopTimers();
+            this.o.onClose?.();
+            if (!this.closed && (this.o.reconnect ?? true)) {
+                setTimeout(() => this.connect(), this.backoff);
+                this.backoff = Math.min(this.backoff * 2, 8000);
+            }
+        };
+        ws.onerror = () => {
+            try {
+                ws.close();
+            }
+            catch {
+                /* noop */
+            }
+        };
+    }
+    get ready() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    raw(m) {
+        if (this.ready)
+            this.ws.send(JSON.stringify(m));
+    }
+    /** An ORDERED edit/command (`relay`) or a divergence probe (`hash`) — echoed back stamped with a total-order seq. */
+    send(m) {
+        this.raw(m);
+    }
+    hashProbe(tick, hash) {
+        this.raw({ t: 'hash', tick, hash, by: this.me });
+    }
+    needSnap(to) {
+        this.raw({ t: 'need-snap', by: this.me, to });
+    }
+    snapReady(to) {
+        this.raw({ t: 'snap-ready', by: this.me, to });
+    }
+    repin(tick) {
+        this.raw({ t: 'repin', tick });
+    }
+    /** Presence beacon (`cur`) — coalesced to presenceHz so a fast cursor/pose doesn't flood the relay. */
+    presence(m) {
+        const now = Date.now();
+        const minGap = 1000 / (this.o.presenceHz ?? 8);
+        if (now - this.lastPresence >= minGap) {
+            this.lastPresence = now;
+            this.raw({ ...m, t: 'cur', by: this.me });
+        }
+        else {
+            this.presencePending = { ...m, t: 'cur', by: this.me };
+            if (!this.presenceTimer)
+                this.presenceTimer = setTimeout(() => {
+                    this.presenceTimer = null;
+                    if (this.presencePending) {
+                        this.lastPresence = Date.now();
+                        this.raw(this.presencePending);
+                        this.presencePending = null;
+                    }
+                }, minGap - (now - this.lastPresence));
+        }
+    }
+    ping() {
+        this.raw({ t: 'ping', c: Date.now() });
+    }
+    pingBurst() {
+        this.ping();
+        setTimeout(() => this.ping(), 400);
+        setTimeout(() => this.ping(), 900);
+    }
+    stopTimers() {
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        if (this.presenceTimer)
+            clearTimeout(this.presenceTimer);
+        this.pingTimer = this.presenceTimer = null;
+    }
+    close() {
+        this.closed = true;
+        this.stopTimers();
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* noop */
+        }
+    }
+}

package/dist/net/sharedClock.d.ts

@@ -0,0 +1,21 @@
+export declare class SharedClock {
+    private tickMs;
+    private now;
+    private epoch;
+    private offset;
+    private bestRtt;
+    private pinned;
+    constructor(tickMs: number, // ms per tick (e.g. 1000/60)
+    now: () => number);
+    /** From the server `hello`. */
+    setEpoch(epoch: number): void;
+    get hasEpoch(): boolean;
+    get epochMs(): number;
+    /** Feed a ping round-trip: `sentAt` = local ms we sent, `serverNow` = server ms in the pong. Keeps the sample
+     *  with the smallest round-trip (its midpoint is the least-biased estimate of the server clock). */
+    onPong(sentAt: number, serverNow: number): void;
+    /** The tick the whole room should be on right now. */
+    targetTick(): number;
+    get offsetMs(): number;
+    get rttMs(): number;
+}

package/dist/net/sharedClock.js

@@ -0,0 +1,51 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// SHARED CLOCK — "what tick is it, everywhere, right now?" (lockstep games). The
+// room pins an EPOCH: the server-clock instant of tick 0. Each client estimates its
+// offset from the server clock via ping/pong (keeping the FASTEST RTT sample — the
+// least-jittered), then derives targetTick = (serverNow - epoch) / T. Every client
+// chases the same tick without per-frame coordination. Extracted from cogsworth.
+// ─────────────────────────────────────────────────────────────────────────────
+export class SharedClock {
+    tickMs;
+    now;
+    epoch = 0; // server-clock ms of tick 0
+    offset = 0; // serverClock - localClock (ms)
+    bestRtt = Infinity;
+    pinned = false;
+    constructor(tickMs, // ms per tick (e.g. 1000/60)
+    now) {
+        this.tickMs = tickMs;
+        this.now = now;
+    }
+    /** From the server `hello`. */
+    setEpoch(epoch) {
+        this.epoch = epoch;
+        this.pinned = true;
+    }
+    get hasEpoch() {
+        return this.pinned;
+    }
+    get epochMs() {
+        return this.epoch;
+    }
+    /** Feed a ping round-trip: `sentAt` = local ms we sent, `serverNow` = server ms in the pong. Keeps the sample
+     *  with the smallest round-trip (its midpoint is the least-biased estimate of the server clock). */
+    onPong(sentAt, serverNow) {
+        const recvAt = this.now();
+        const rtt = recvAt - sentAt;
+        if (rtt < this.bestRtt) {
+            this.bestRtt = rtt;
+            this.offset = serverNow + rtt / 2 - recvAt; // server clock at receive ≈ serverNow + rtt/2
+        }
+    }
+    /** The tick the whole room should be on right now. */
+    targetTick() {
+        return Math.floor((this.now() + this.offset - this.epoch) / this.tickMs);
+    }
+    get offsetMs() {
+        return this.offset;
+    }
+    get rttMs() {
+        return this.bestRtt;
+    }
+}

package/package.json

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