@lagless/relay-server 0.0.33

package/dist/lib/relay-room.js

@@ -0,0 +1,491 @@
+import { createLogger } from '@lagless/misc';
+import { TickInputKind, HeaderSchema, packServerHello, packPong, packStateResponse, } from '@lagless/net-wire';
+import { InputBinarySchema, LE } from '@lagless/binary';
+import { ServerClock } from './server-clock.js';
+import { InputHandler } from './input-handler.js';
+import { StateTransfer } from './state-transfer.js';
+import { PlayerConnection } from './player-connection.js';
+import { LeaveReason, SERVER_SLOT, } from './types.js';
+const log = createLogger('RelayRoom');
+function uuidToBytes(playerId) {
+    const hex = playerId.replace(/-/g, '');
+    // Valid UUID: 32 hex chars → proper hex-to-bytes conversion
+    if (hex.length === 32 && /^[0-9a-fA-F]{32}$/.test(hex)) {
+        const bytes = new Uint8Array(16);
+        for (let i = 0; i < 16; i++) {
+            bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    // Fallback: XOR-hash arbitrary string into 16 bytes
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < playerId.length; i++) {
+        bytes[i % 16] ^= playerId.charCodeAt(i);
+    }
+    return bytes;
+}
+// ─────────────────────────────────────────────────────────────
+// RelayRoom
+// ─────────────────────────────────────────────────────────────
+/**
+ * Manages one match room. Sealed by design — use RoomHooks for game-specific behavior.
+ */
+export class RelayRoom {
+    matchId;
+    roomType;
+    _config;
+    _hooks;
+    _clock;
+    _inputHandler;
+    _stateTransfer;
+    _connections = new Map();
+    _playersByPlayerId = new Map();
+    _results = new Map();
+    _serverEventJournal = [];
+    _context;
+    _createdAt;
+    _seed;
+    _scopeJson;
+    _inputRegistry;
+    _disposed = false;
+    _reconnectTimer = null;
+    _serverSeq = 1;
+    _latencySimulator = null;
+    _nextSlot;
+    constructor(matchId, roomType, _config, _hooks, inputRegistry, players, seed, scopeJson = '{}') {
+        this.matchId = matchId;
+        this.roomType = roomType;
+        this._config = _config;
+        this._hooks = _hooks;
+        this._createdAt = performance.now();
+        this._seed = seed;
+        this._scopeJson = scopeJson;
+        this._inputRegistry = inputRegistry;
+        this._clock = new ServerClock(_config.tickRateHz);
+        this._inputHandler = new InputHandler(this._clock, _config);
+        this._stateTransfer = new StateTransfer(_config.stateTransferTimeoutMs);
+        this._context = new RoomContextImpl(this);
+        // Initialize player slots
+        let slot = 0;
+        for (const p of players) {
+            const info = {
+                playerId: p.playerId,
+                slot,
+                isBot: p.isBot,
+                metadata: Object.freeze({ ...p.metadata }),
+            };
+            const conn = new PlayerConnection(info, null);
+            this._connections.set(slot, conn);
+            this._playersByPlayerId.set(p.playerId, conn);
+            slot++;
+        }
+        this._nextSlot = slot;
+        // Start reconnect expiry checker
+        if (_config.reconnectTimeoutMs > 0) {
+            this._reconnectTimer = setInterval(() => this.checkReconnectTimeouts(), 1000);
+        }
+        log.info(`Room ${matchId} created with ${players.length} players`);
+    }
+    async init() {
+        await this._hooks.onRoomCreated?.(this._context);
+        // Emit join events for bots — they never connect via WebSocket
+        // but the simulation needs PlayerJoined server events for them
+        for (const conn of this._connections.values()) {
+            if (conn.isBot) {
+                await this._hooks.onPlayerJoin?.(this._context, conn.info);
+            }
+        }
+    }
+    // ─── Public getters ────────────────────────────────────
+    get isDisposed() { return this._disposed; }
+    get tick() { return this._clock.tick; }
+    get config() { return this._config; }
+    get context() { return this._context; }
+    get createdAt() { return this._createdAt; }
+    get hasOpenSlots() {
+        return !this._disposed && this._config.lateJoinEnabled && this._nextSlot < this._config.maxPlayers;
+    }
+    get latencySimulator() { return this._latencySimulator; }
+    set latencySimulator(sim) { this._latencySimulator = sim; }
+    getConnectedHumanCount() {
+        let count = 0;
+        for (const c of this._connections.values()) {
+            if (c.isConnected && !c.isBot)
+                count++;
+        }
+        return count;
+    }
+    getTotalHumanCount() {
+        let count = 0;
+        for (const c of this._connections.values()) {
+            if (!c.isBot)
+                count++;
+        }
+        return count;
+    }
+    // ─── Late-Join ───────────────────────────────────────────
+    addPlayer(playerId, isBot, metadata) {
+        if (this._disposed)
+            return null;
+        if (!this._config.lateJoinEnabled)
+            return null;
+        if (this._nextSlot >= this._config.maxPlayers)
+            return null;
+        if (this._playersByPlayerId.has(playerId))
+            return null;
+        if (this._hooks.shouldAcceptLateJoin?.(this._context, playerId, metadata) === false) {
+            return null;
+        }
+        const slot = this._nextSlot++;
+        const info = {
+            playerId,
+            slot,
+            isBot,
+            metadata: Object.freeze({ ...metadata }),
+        };
+        const conn = new PlayerConnection(info, null);
+        conn.markDisconnected();
+        this._connections.set(slot, conn);
+        this._playersByPlayerId.set(playerId, conn);
+        log.info(`Late-join: player ${playerId} added to room ${this.matchId} (slot=${slot})`);
+        return info;
+    }
+    // ─── Internal API (used by RoomContextImpl) ───────────
+    /** @internal */
+    getPlayerInfos() {
+        const result = [];
+        for (const conn of this._connections.values()) {
+            result.push(conn.info);
+        }
+        return result;
+    }
+    /** @internal */
+    isSlotConnected(slot) {
+        return this._connections.get(slot)?.isConnected ?? false;
+    }
+    /** @internal */
+    sendToSlot(slot, message) {
+        this._connections.get(slot)?.send(message);
+    }
+    /** @internal */
+    broadcastToAll(message) {
+        for (const conn of this._connections.values()) {
+            conn.send(message);
+        }
+    }
+    /** @internal */
+    requestEndMatch() {
+        this.endMatch();
+    }
+    // ─── Connection Handling ───────────────────────────────
+    async handlePlayerConnect(playerId, ws) {
+        if (this._disposed)
+            return false;
+        const conn = this._playersByPlayerId.get(playerId);
+        if (!conn) {
+            log.warn(`Unknown player ${playerId} tried to connect to room ${this.matchId}`);
+            return false;
+        }
+        if (conn.isConnected) {
+            log.warn(`Player ${playerId} already connected to room ${this.matchId}`);
+            return false;
+        }
+        if (conn.isGone) {
+            log.warn(`Player ${playerId} reconnect rejected — already gone`);
+            return false;
+        }
+        const isReconnect = conn.hasConnectedBefore;
+        if (isReconnect) {
+            const canReconnect = this._hooks.shouldAcceptReconnect?.(this._context, playerId) ?? true;
+            if (!canReconnect) {
+                log.info(`Reconnect denied for player ${playerId}`);
+                return false;
+            }
+        }
+        conn.connect(ws);
+        // Send ServerHello
+        const helloMessage = this.buildServerHello(conn.slot);
+        conn.send(helloMessage);
+        log.info(`ServerHello sent to slot=${conn.slot} serverTick=${this._clock.tick}`);
+        // State sync: state transfer if tick > 0, otherwise journal replay
+        const needsStateTransfer = this._clock.tick > 0 && this._config.lateJoinEnabled;
+        if (needsStateTransfer) {
+            const stateResult = await this._stateTransfer.requestState(this._connections, conn.slot);
+            if (stateResult) {
+                this.sendStateToPlayer(conn, stateResult);
+                // Send journal events that happened AFTER the state snapshot tick —
+                // these are not yet reflected in the transferred state
+                const postStateEvents = this._serverEventJournal.filter(e => e.tick > stateResult.tick);
+                if (postStateEvents.length > 0) {
+                    log.info(`Post-state journal: ${postStateEvents.length} events (tick > ${stateResult.tick}) to slot=${conn.slot}`);
+                    this._inputHandler.sendInputBatchToPlayer(postStateEvents, conn);
+                }
+            }
+            else {
+                log.warn(`State transfer failed for player ${playerId} — falling back to journal replay`);
+                this._inputHandler.sendInputBatchToPlayer(this._serverEventJournal, conn);
+            }
+        }
+        else {
+            log.info(`Journal replay: ${this._serverEventJournal.length} events to slot=${conn.slot}`);
+            this._inputHandler.sendInputBatchToPlayer(this._serverEventJournal, conn);
+        }
+        log.info(`Player ${playerId} ${isReconnect ? 'reconnected to' : 'joined'} room ${this.matchId} (slot=${conn.slot})`);
+        if (isReconnect) {
+            await this._hooks.onPlayerReconnect?.(this._context, conn.info);
+        }
+        else {
+            await this._hooks.onPlayerJoin?.(this._context, conn.info);
+        }
+        return true;
+    }
+    async handlePlayerDisconnect(playerId) {
+        const conn = this._playersByPlayerId.get(playerId);
+        if (!conn || !conn.isConnected)
+            return;
+        if (this._config.reconnectTimeoutMs > 0) {
+            conn.markDisconnected();
+        }
+        else {
+            conn.markGone();
+        }
+        log.info(`Player ${playerId} disconnected from room ${this.matchId}`);
+        await this._hooks.onPlayerLeave?.(this._context, conn.info, LeaveReason.Disconnected);
+        this.checkMatchEnd();
+    }
+    // ─── Message Handling ─────────────────────────────────
+    handleMessage(playerId, data) {
+        const conn = this._playersByPlayerId.get(playerId);
+        if (!conn || !conn.isConnected) {
+            log.warn(`handleMessage: player=${playerId} conn=${!!conn} isConnected=${conn?.isConnected}`);
+            return;
+        }
+        if (data.byteLength < HeaderSchema.byteLength) {
+            log.warn(`handleMessage: data too short (${data.byteLength} bytes)`);
+            return;
+        }
+        const view = new DataView(data);
+        const msgType = view.getUint8(1);
+        switch (msgType) {
+            case 9: // MsgType.TickInputBatch
+                this.handleTickInputBatch(conn, data);
+                break;
+            case 4: // MsgType.Ping
+                this.handlePing(conn, data);
+                break;
+            case 8: // MsgType.PlayerFinished
+                this.handlePlayerFinished(conn, data);
+                break;
+            case 7: // MsgType.StateResponse
+                this.handleStateResponse(conn, data);
+                break;
+            default:
+                log.warn(`Unknown message type ${msgType} from player ${playerId} (dataLen=${data.byteLength})`);
+        }
+    }
+    // ─── Disposal ─────────────────────────────────────────
+    async dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        if (this._reconnectTimer) {
+            clearInterval(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+        this._stateTransfer.dispose();
+        log.info(`Room ${this.matchId} disposing`);
+        await this._hooks.onRoomDisposed?.(this._context);
+        for (const conn of this._connections.values()) {
+            conn.markGone();
+        }
+        this._connections.clear();
+        this._playersByPlayerId.clear();
+    }
+    // ─── Server Events (called via RoomContext) ────────────
+    /** @internal - called by RoomContextImpl */
+    _emitServerEvent(inputId, data, tick) {
+        // For server events, we pack: inputId (u8) + data fields
+        // The payload format matches InputBinarySchema convention
+        // but we keep it simple: just the raw bytes the caller provides
+        const payloadArrayBuffer = InputBinarySchema.packBatch(this._inputRegistry, [
+            {
+                inputId,
+                ordinal: 0,
+                values: data,
+            },
+        ]);
+        // TODO: proper InputBinarySchema packing when game provides registry
+        const payload = new Uint8Array(payloadArrayBuffer); // placeholder
+        const input = {
+            tick,
+            playerSlot: SERVER_SLOT,
+            seq: this._serverSeq++,
+            kind: TickInputKind.Server,
+            payload,
+        };
+        this._serverEventJournal.push(input);
+        this._inputHandler.broadcastInput(input, this._connections);
+    }
+    // ─── Private: Message Handlers ────────────────────────
+    handleTickInputBatch(conn, raw) {
+        const results = this._inputHandler.validateClientInputBatch(conn.slot, raw);
+        const accepted = [];
+        for (const result of results) {
+            if (result.accepted) {
+                accepted.push(result.input);
+            }
+            else {
+                this._inputHandler.sendCancel(conn, result.tick, result.seq, result.reason);
+            }
+        }
+        if (accepted.length > 0) {
+            const broadcast = () => this._inputHandler.broadcastInputBatch(accepted, this._connections);
+            if (this._latencySimulator) {
+                this._latencySimulator.apply(broadcast);
+            }
+            else {
+                broadcast();
+            }
+        }
+    }
+    handlePing(conn, raw) {
+        const view = new DataView(raw);
+        const cSend = view.getFloat64(HeaderSchema.byteLength, LE);
+        const now = performance.now();
+        const pong = packPong({
+            cSend,
+            sRecv: now,
+            sSend: now,
+            sTick: this._clock.tick,
+        });
+        const send = () => conn.send(pong);
+        if (this._latencySimulator) {
+            this._latencySimulator.apply(send);
+        }
+        else {
+            send();
+        }
+    }
+    handlePlayerFinished(conn, raw) {
+        const view = new DataView(raw);
+        const offset = HeaderSchema.byteLength;
+        const tick = view.getUint32(offset, LE);
+        // offset + 4: playerSlot (u8) — already known from conn.slot
+        const payloadLength = view.getUint16(offset + 5, LE);
+        const payload = new Uint8Array(raw, offset + 7, payloadLength);
+        // Store raw payload as result (game-specific parsing happens in hooks)
+        this._results.set(conn.slot, payload.slice());
+        log.info(`Player ${conn.playerId} finished at tick ${tick}`);
+        this._hooks.onPlayerFinished?.(this._context, conn.info, payload.slice());
+        this.checkMatchEnd();
+    }
+    handleStateResponse(conn, raw) {
+        const view = new DataView(raw);
+        const offset = HeaderSchema.byteLength;
+        const requestId = view.getUint32(offset, LE);
+        const tick = view.getUint32(offset + 4, LE);
+        const hash = view.getUint32(offset + 8, LE);
+        const stateLength = view.getUint32(offset + 12, LE);
+        const state = raw.slice(offset + 16, offset + 16 + stateLength);
+        this._stateTransfer.receiveResponse(conn.slot, requestId, tick, hash, state);
+    }
+    // ─── Private: Lifecycle ────────────────────────────────
+    checkMatchEnd() {
+        const connectedHumans = this.getConnectedHumanCount();
+        if (connectedHumans === 0) {
+            this.endMatch();
+            return;
+        }
+        const totalHumans = this.getTotalHumanCount();
+        let finishedOrGone = 0;
+        for (const conn of this._connections.values()) {
+            if (conn.isBot)
+                continue;
+            if (this._results.has(conn.slot) || conn.isGone)
+                finishedOrGone++;
+        }
+        if (finishedOrGone >= totalHumans) {
+            this.endMatch();
+        }
+    }
+    async endMatch() {
+        log.info(`Match ${this.matchId} ending`);
+        await this._hooks.onMatchEnd?.(this._context, this._results);
+        await this.dispose();
+    }
+    checkReconnectTimeouts() {
+        for (const conn of this._connections.values()) {
+            if (conn.isReconnectExpired(this._config.reconnectTimeoutMs)) {
+                conn.markGone();
+                log.info(`Reconnect timeout for player ${conn.playerId}`);
+                this._hooks.onPlayerLeave?.(this._context, conn.info, LeaveReason.Timeout);
+                this.checkMatchEnd();
+            }
+        }
+    }
+    buildServerHello(forSlot) {
+        const players = Array.from(this._connections.values()).map(conn => ({
+            playerId: uuidToBytes(conn.playerId),
+            slot: conn.slot,
+            isBot: conn.isBot,
+            metadataJson: JSON.stringify(conn.info.metadata),
+        }));
+        return packServerHello({
+            seed: this._seed,
+            playerSlot: forSlot,
+            serverTick: this._clock.tick,
+            maxPlayers: this._config.maxPlayers,
+            players,
+            scopeJson: this._scopeJson,
+        });
+    }
+    sendStateToPlayer(conn, result) {
+        const msg = packStateResponse({
+            requestId: 0, // not a request from client
+            tick: result.tick,
+            hash: result.hash,
+            state: result.state,
+        });
+        conn.send(msg);
+    }
+}
+// ─────────────────────────────────────────────────────────────
+// RoomContext Implementation
+// ─────────────────────────────────────────────────────────────
+class RoomContextImpl {
+    _room;
+    constructor(_room) {
+        this._room = _room;
+    }
+    get matchId() { return this._room.matchId; }
+    get tick() { return this._room.tick; }
+    get config() { return this._room.config; }
+    get createdAt() { return this._room.createdAt; }
+    emitServerEvent(inputId, data) {
+        this._room._emitServerEvent(inputId, data, this._room.tick + 1);
+    }
+    emitServerEventAt(inputId, data, tick) {
+        if (tick < this._room.tick) {
+            throw new Error(`Cannot emit server event in the past (tick ${tick} < current ${this._room.tick})`);
+        }
+        this._room._emitServerEvent(inputId, data, tick);
+    }
+    getPlayers() {
+        return this._room.getPlayerInfos();
+    }
+    getConnectedPlayerCount() {
+        return this._room.getConnectedHumanCount();
+    }
+    isPlayerConnected(slot) {
+        return this._room.isSlotConnected(slot);
+    }
+    sendTo(slot, message) {
+        this._room.sendToSlot(slot, message);
+    }
+    broadcast(message) {
+        this._room.broadcastToAll(message);
+    }
+    endMatch() {
+        this._room.requestEndMatch();
+    }
+}

package/dist/lib/room-registry.d.ts

@@ -0,0 +1,23 @@
+import { RelayRoom } from './relay-room.js';
+import type { MatchId, RoomTypeDefinition, CreateMatchRequest, RoomHooks, RoomTypeConfig, InputRegistry } from './types.js';
+/**
+ * Manages all rooms on this server instance.
+ * Handles room type registration, creation, lookup, and disposal.
+ */
+export declare class RoomRegistry {
+    private readonly _roomTypes;
+    private readonly _rooms;
+    private _disposalTimer;
+    constructor();
+    registerRoomType<TResult>(typeName: string, config: RoomTypeConfig, hooks: RoomHooks<TResult>, inputRegistry: InputRegistry): void;
+    createRoom(request: CreateMatchRequest, seed: Uint8Array, scopeJson?: string): Promise<RelayRoom>;
+    getRoom(matchId: MatchId): RelayRoom | undefined;
+    get roomCount(): number;
+    getRoomType(typeName: string): RoomTypeDefinition | undefined;
+    private cleanupDisposed;
+    findRoomForLateJoin(roomType: string): RelayRoom | undefined;
+    /** Iterates all active (non-disposed) rooms. */
+    forEachRoom(fn: (room: RelayRoom) => void): void;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=room-registry.d.ts.map

package/dist/lib/room-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-registry.d.ts","sourceRoot":"","sources":["../../src/lib/room-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EACV,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAC/C,SAAS,EAAE,cAAc,EAAE,aAAa,EACzC,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,cAAc,CAAiC;;IAMhD,gBAAgB,CAAC,OAAO,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,aAAa,EAAE,aAAa,GAC3B,IAAI;IAQM,UAAU,CACrB,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,UAAU,EAChB,SAAS,SAAO,GACf,OAAO,CAAC,SAAS,CAAC;IA2Bd,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS;IAIvD,IAAW,SAAS,IAAI,MAAM,CAE7B;IAEM,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIpE,OAAO,CAAC,eAAe;IAShB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IASnE,gDAAgD;IACzC,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAM1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAOtC"}

package/dist/lib/room-registry.js

@@ -0,0 +1,75 @@
+import { createLogger } from '@lagless/misc';
+import { RelayRoom } from './relay-room.js';
+const log = createLogger('RoomRegistry');
+/**
+ * Manages all rooms on this server instance.
+ * Handles room type registration, creation, lookup, and disposal.
+ */
+export class RoomRegistry {
+    _roomTypes = new Map();
+    _rooms = new Map();
+    _disposalTimer;
+    constructor() {
+        this._disposalTimer = setInterval(() => this.cleanupDisposed(), 10_000);
+    }
+    registerRoomType(typeName, config, hooks, inputRegistry) {
+        if (this._roomTypes.has(typeName)) {
+            throw new Error(`Room type "${typeName}" already registered`);
+        }
+        this._roomTypes.set(typeName, { config, hooks, inputRegistry });
+        log.info(`Registered room type "${typeName}"`);
+    }
+    async createRoom(request, seed, scopeJson = '{}') {
+        const roomType = this._roomTypes.get(request.roomType);
+        if (!roomType) {
+            throw new Error(`Unknown room type "${request.roomType}"`);
+        }
+        if (this._rooms.has(request.matchId)) {
+            throw new Error(`Room "${request.matchId}" already exists`);
+        }
+        const room = new RelayRoom(request.matchId, request.roomType, roomType.config, roomType.hooks, roomType.inputRegistry, request.players, seed, scopeJson);
+        await room.init();
+        this._rooms.set(request.matchId, room);
+        log.info(`Created room "${request.matchId}" type="${request.roomType}" (total: ${this._rooms.size})`);
+        return room;
+    }
+    getRoom(matchId) {
+        return this._rooms.get(matchId);
+    }
+    get roomCount() {
+        return this._rooms.size;
+    }
+    getRoomType(typeName) {
+        return this._roomTypes.get(typeName);
+    }
+    cleanupDisposed() {
+        for (const [id, room] of this._rooms) {
+            if (room.isDisposed) {
+                this._rooms.delete(id);
+                log.info(`Cleaned up disposed room "${id}" (remaining: ${this._rooms.size})`);
+            }
+        }
+    }
+    findRoomForLateJoin(roomType) {
+        for (const room of this._rooms.values()) {
+            if (!room.isDisposed && room.roomType === roomType && room.hasOpenSlots) {
+                return room;
+            }
+        }
+        return undefined;
+    }
+    /** Iterates all active (non-disposed) rooms. */
+    forEachRoom(fn) {
+        for (const room of this._rooms.values()) {
+            if (!room.isDisposed)
+                fn(room);
+        }
+    }
+    async dispose() {
+        clearInterval(this._disposalTimer);
+        for (const room of this._rooms.values()) {
+            await room.dispose();
+        }
+        this._rooms.clear();
+    }
+}

package/dist/lib/server-clock.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Authoritative server clock for a match room.
+ * Provides the canonical tick number based on elapsed wall-clock time.
+ */
+export declare class ServerClock {
+    private readonly _startedAt;
+    private readonly _tickMs;
+    constructor(tickRateHz: number, startedAt?: number);
+    get tickMs(): number;
+    get tick(): number;
+    get startedAt(): number;
+    get elapsedMs(): number;
+}
+//# sourceMappingURL=server-clock.d.ts.map

package/dist/lib/server-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-clock.d.ts","sourceRoot":"","sources":["../../src/lib/server-clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,UAAU,EAAE,MAAM,EAAE,SAAS,SAAoB;IAK7D,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,SAAS,IAAI,MAAM,CAE7B;CACF"}

package/dist/lib/server-clock.js

@@ -0,0 +1,24 @@
+/**
+ * Authoritative server clock for a match room.
+ * Provides the canonical tick number based on elapsed wall-clock time.
+ */
+export class ServerClock {
+    _startedAt;
+    _tickMs;
+    constructor(tickRateHz, startedAt = performance.now()) {
+        this._tickMs = 1000 / tickRateHz;
+        this._startedAt = startedAt;
+    }
+    get tickMs() {
+        return this._tickMs;
+    }
+    get tick() {
+        return Math.floor((performance.now() - this._startedAt) / this._tickMs);
+    }
+    get startedAt() {
+        return this._startedAt;
+    }
+    get elapsedMs() {
+        return performance.now() - this._startedAt;
+    }
+}

package/dist/lib/state-transfer.d.ts

@@ -0,0 +1,47 @@
+import type { PlayerConnection } from './player-connection.js';
+import type { PlayerSlot } from './types.js';
+export interface StateResponse {
+    readonly playerSlot: PlayerSlot;
+    readonly tick: number;
+    readonly hash: number;
+    readonly state: ArrayBuffer;
+}
+export interface StateTransferResult {
+    readonly state: ArrayBuffer;
+    readonly tick: number;
+    readonly hash: number;
+    readonly votedBy: number;
+    readonly totalResponses: number;
+}
+/**
+ * Handles state transfer for late-join and reconnect.
+ *
+ * Flow:
+ * 1. New player connects to an active match
+ * 2. Server sends StateRequest to all connected clients
+ * 3. Clients respond with their snapshot + tick + hash
+ * 4. Majority vote selects the correct state
+ * 5. Server sends selected state to the new player
+ */
+export declare class StateTransfer {
+    private readonly _timeoutMs;
+    private _nextRequestId;
+    private readonly _pendingRequests;
+    constructor(_timeoutMs: number);
+    /**
+     * Request state from connected clients and resolve via majority vote.
+     */
+    requestState(connections: ReadonlyMap<PlayerSlot, PlayerConnection>, excludeSlot?: PlayerSlot): Promise<StateTransferResult | null>;
+    /**
+     * Called when a StateResponse message arrives from a client.
+     */
+    receiveResponse(playerSlot: PlayerSlot, requestId: number, tick: number, hash: number, state: ArrayBuffer): void;
+    /**
+     * Cancel all pending requests (e.g. on room disposal).
+     */
+    dispose(): void;
+    private resolveRequest;
+    private majorityVote;
+    private getEligibleRespondents;
+}
+//# sourceMappingURL=state-transfer.d.ts.map

package/dist/lib/state-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transfer.d.ts","sourceRoot":"","sources":["../../src/lib/state-transfer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;;GASG;AACH,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJ7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;gBAGnD,UAAU,EAAE,MAAM;IAGrC;;OAEG;IACI,YAAY,CACjB,WAAW,EAAE,WAAW,CAAC,UAAU,EAAE,gBAAgB,CAAC,EACtD,WAAW,CAAC,EAAE,UAAU,GACvB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAiCtC;;OAEG;IACI,eAAe,CACpB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,IAAI;IAoBP;;OAEG;IACI,OAAO,IAAI,IAAI;IAUtB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,sBAAsB;CAY/B"}