murow 0.0.1

package/dist/protocol/index.js

@@ -0,0 +1,43 @@
+/**
+ * Protocol Layer - Type-safe networking primitives
+ *
+ * This layer enforces:
+ * - Type-safe intent definitions (extend Intent interface)
+ * - Type-safe snapshot definitions (Snapshot<YourState>)
+ * - Memory-efficient encoding (use PooledCodec from core)
+ *
+ * You provide:
+ * - Your intent types
+ * - Your state types
+ * - Your schemas (for binary encoding)
+ * - Codec instances (instantiate once, reuse)
+ *
+ * @example
+ * ```ts
+ * // Define your types
+ * interface MoveIntent extends Intent {
+ *   kind: 1;
+ *   tick: number;
+ *   dx: number;
+ *   dy: number;
+ * }
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * // Create codecs once (reuse these!)
+ * const intentRegistry = new IntentRegistry();
+ * intentRegistry.register(1, new PooledCodec(moveSchema));
+ *
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec(stateSchema)
+ * );
+ *
+ * // Use them
+ * const buf = intentRegistry.encode(intent);
+ * const snapshot = snapshotCodec.decode(buf);
+ * ```
+ */
+export * from "./intent";
+export * from "./snapshot";

package/dist/protocol/intent/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Intent system for client-to-server actions.
+ *
+ * Intents are player/AI actions that need to be:
+ * 1. Encoded efficiently (binary)
+ * 2. Sent over network
+ * 3. Decoded on the other end
+ * 4. Processed deterministically
+ *
+ * @example
+ * ```ts
+ * import { Intent, IntentRegistry } from './protocol/intent';
+ * import { PooledCodec } from '../core/pooled-codec';
+ * import { BinaryCodec } from '../core/binary-codec';
+ *
+ * // 1. Define your intent type
+ * interface MoveIntent extends Intent {
+ *   kind: 1;
+ *   tick: number;
+ *   dx: number;
+ *   dy: number;
+ * }
+ *
+ * // 2. Create registry and register once (reuse this instance)
+ * const registry = new IntentRegistry();
+ * registry.register(1, new PooledCodec({
+ *   kind: BinaryCodec.u8,
+ *   tick: BinaryCodec.u32,
+ *   dx: BinaryCodec.f32,
+ *   dy: BinaryCodec.f32,
+ * }));
+ *
+ * // 3. Encode/decode
+ * const buf = registry.encode(intent);
+ * const decoded = registry.decode(1, buf);
+ * ```
+ */
+export type { Intent } from "./intent";
+export { IntentRegistry } from "./intent-registry";

package/dist/protocol/intent/index.js

@@ -0,0 +1,38 @@
+/**
+ * Intent system for client-to-server actions.
+ *
+ * Intents are player/AI actions that need to be:
+ * 1. Encoded efficiently (binary)
+ * 2. Sent over network
+ * 3. Decoded on the other end
+ * 4. Processed deterministically
+ *
+ * @example
+ * ```ts
+ * import { Intent, IntentRegistry } from './protocol/intent';
+ * import { PooledCodec } from '../core/pooled-codec';
+ * import { BinaryCodec } from '../core/binary-codec';
+ *
+ * // 1. Define your intent type
+ * interface MoveIntent extends Intent {
+ *   kind: 1;
+ *   tick: number;
+ *   dx: number;
+ *   dy: number;
+ * }
+ *
+ * // 2. Create registry and register once (reuse this instance)
+ * const registry = new IntentRegistry();
+ * registry.register(1, new PooledCodec({
+ *   kind: BinaryCodec.u8,
+ *   tick: BinaryCodec.u32,
+ *   dx: BinaryCodec.f32,
+ *   dy: BinaryCodec.f32,
+ * }));
+ *
+ * // 3. Encode/decode
+ * const buf = registry.encode(intent);
+ * const decoded = registry.decode(1, buf);
+ * ```
+ */
+export { IntentRegistry } from "./intent-registry";

package/dist/protocol/intent/intent-registry.d.ts

@@ -0,0 +1,54 @@
+import type { Intent } from "./intent";
+/**
+ * Generic codec interface (users import from core/pooled-codec)
+ */
+export interface Codec<T> {
+    encode(value: T): Uint8Array;
+    decode(buf: Uint8Array): T;
+}
+/**
+ * Registry for mapping intent kinds to their codecs.
+ *
+ * Users instantiate this once and register their intent types with
+ * PooledCodec instances (from core/pooled-codec).
+ *
+ * @example
+ * ```ts
+ * import { IntentRegistry } from './protocol/intent';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * const registry = new IntentRegistry();
+ *
+ * registry.register(1, new PooledCodec({
+ *   kind: BinaryCodec.u8,
+ *   tick: BinaryCodec.u32,
+ *   dx: BinaryCodec.f32,
+ *   dy: BinaryCodec.f32,
+ * }));
+ *
+ * // Encode/decode
+ * const buf = registry.encode(intent);
+ * const decoded = registry.decode(1, buf);
+ * ```
+ */
+export declare class IntentRegistry {
+    private codecs;
+    /**
+     * Register a codec for a specific intent kind.
+     * Call this once per intent type at startup.
+     */
+    register<T extends Intent>(kind: number, codec: Codec<T>): void;
+    /**
+     * Encode an intent into binary format.
+     */
+    encode<T extends Intent>(intent: T): Uint8Array;
+    /**
+     * Decode binary data into an intent.
+     */
+    decode(kind: number, buf: Uint8Array): Intent;
+    has(kind: number): boolean;
+    unregister(kind: number): boolean;
+    clear(): void;
+    getKinds(): number[];
+}

package/dist/protocol/intent/intent-registry.js

@@ -0,0 +1,73 @@
+/**
+ * Registry for mapping intent kinds to their codecs.
+ *
+ * Users instantiate this once and register their intent types with
+ * PooledCodec instances (from core/pooled-codec).
+ *
+ * @example
+ * ```ts
+ * import { IntentRegistry } from './protocol/intent';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * const registry = new IntentRegistry();
+ *
+ * registry.register(1, new PooledCodec({
+ *   kind: BinaryCodec.u8,
+ *   tick: BinaryCodec.u32,
+ *   dx: BinaryCodec.f32,
+ *   dy: BinaryCodec.f32,
+ * }));
+ *
+ * // Encode/decode
+ * const buf = registry.encode(intent);
+ * const decoded = registry.decode(1, buf);
+ * ```
+ */
+export class IntentRegistry {
+    constructor() {
+        this.codecs = new Map();
+    }
+    /**
+     * Register a codec for a specific intent kind.
+     * Call this once per intent type at startup.
+     */
+    register(kind, codec) {
+        if (this.codecs.has(kind)) {
+            throw new Error(`Intent kind ${kind} is already registered`);
+        }
+        this.codecs.set(kind, codec);
+    }
+    /**
+     * Encode an intent into binary format.
+     */
+    encode(intent) {
+        const codec = this.codecs.get(intent.kind);
+        if (!codec) {
+            throw new Error(`No codec registered for intent kind ${intent.kind}`);
+        }
+        return codec.encode(intent);
+    }
+    /**
+     * Decode binary data into an intent.
+     */
+    decode(kind, buf) {
+        const codec = this.codecs.get(kind);
+        if (!codec) {
+            throw new Error(`No codec registered for intent kind ${kind}`);
+        }
+        return codec.decode(buf);
+    }
+    has(kind) {
+        return this.codecs.has(kind);
+    }
+    unregister(kind) {
+        return this.codecs.delete(kind);
+    }
+    clear() {
+        this.codecs.clear();
+    }
+    getKinds() {
+        return Array.from(this.codecs.keys());
+    }
+}

package/dist/protocol/intent/intent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Base interface for all game intents.
+ *
+ * Intents represent player or AI actions that need to be processed by the game simulation.
+ * They are timestamped with a tick number for deterministic replay and synchronization.
+ */
+export interface Intent {
+    /** The game tick at which this intent should be processed */
+    tick: number;
+    /** Numeric identifier for the intent type (used for codec lookup) */
+    kind: number;
+}

package/dist/protocol/intent/intent.js

@@ -0,0 +1 @@
+export {};

package/dist/protocol/snapshot/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Snapshot system for server-to-client state updates.
+ *
+ * Snapshots are delta updates that contain:
+ * 1. Server tick number
+ * 2. Partial state updates (only what changed)
+ *
+ * They need to be:
+ * 1. Encoded efficiently (binary)
+ * 2. Sent over network
+ * 3. Decoded on the client
+ * 4. Merged into client state
+ *
+ * @example
+ * ```ts
+ * import { Snapshot, SnapshotCodec, applySnapshot } from './protocol/snapshot';
+ * import { PooledCodec } from '../core/pooled-codec';
+ * import { BinaryCodec } from '../core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * // 1. Create codec once (reuse this instance)
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // ... your schema })
+ * );
+ *
+ * // 2. Server: Encode snapshot
+ * const snapshot: Snapshot<GameState> = {
+ *   tick: 100,
+ *   updates: { players: { 1: { x: 5, y: 10 } } }
+ * };
+ * const buf = snapshotCodec.encode(snapshot);
+ *
+ * // 3. Client: Decode and apply
+ * const snapshot = snapshotCodec.decode(buf);
+ * applySnapshot(clientState, snapshot);
+ * ```
+ */
+export type { Snapshot } from "./snapshot";
+export { applySnapshot } from "./snapshot";
+export { SnapshotCodec } from "./snapshot-codec";
+export { SnapshotRegistry } from "./snapshot-registry";

package/dist/protocol/snapshot/index.js

@@ -0,0 +1,43 @@
+/**
+ * Snapshot system for server-to-client state updates.
+ *
+ * Snapshots are delta updates that contain:
+ * 1. Server tick number
+ * 2. Partial state updates (only what changed)
+ *
+ * They need to be:
+ * 1. Encoded efficiently (binary)
+ * 2. Sent over network
+ * 3. Decoded on the client
+ * 4. Merged into client state
+ *
+ * @example
+ * ```ts
+ * import { Snapshot, SnapshotCodec, applySnapshot } from './protocol/snapshot';
+ * import { PooledCodec } from '../core/pooled-codec';
+ * import { BinaryCodec } from '../core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * // 1. Create codec once (reuse this instance)
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // ... your schema })
+ * );
+ *
+ * // 2. Server: Encode snapshot
+ * const snapshot: Snapshot<GameState> = {
+ *   tick: 100,
+ *   updates: { players: { 1: { x: 5, y: 10 } } }
+ * };
+ * const buf = snapshotCodec.encode(snapshot);
+ *
+ * // 3. Client: Decode and apply
+ * const snapshot = snapshotCodec.decode(buf);
+ * applySnapshot(clientState, snapshot);
+ * ```
+ */
+export { applySnapshot } from "./snapshot";
+export { SnapshotCodec } from "./snapshot-codec";
+export { SnapshotRegistry } from "./snapshot-registry";

package/dist/protocol/snapshot/snapshot-codec.d.ts

@@ -0,0 +1,48 @@
+import type { Snapshot } from "./snapshot";
+/**
+ * Generic codec interface (users import from core/pooled-codec)
+ */
+export interface Codec<T> {
+    encode(value: T): Uint8Array;
+    decode(buf: Uint8Array): T;
+}
+/**
+ * Codec for encoding/decoding snapshots with binary serialization.
+ *
+ * Users instantiate this once with a PooledCodec for their state schema.
+ *
+ * @example
+ * ```ts
+ * import { SnapshotCodec } from './protocol/snapshot';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // schema })
+ * );
+ *
+ * // Encode/decode
+ * const buf = snapshotCodec.encode(snapshot);
+ * const decoded = snapshotCodec.decode(buf);
+ * ```
+ */
+export declare class SnapshotCodec<T> {
+    private updatesCodec;
+    /**
+     * @param updatesCodec Codec for encoding/decoding the state updates
+     */
+    constructor(updatesCodec: Codec<Partial<T>>);
+    /**
+     * Encode a snapshot into binary format.
+     * Format: [tick: u32][updates: encoded by updatesCodec]
+     */
+    encode(snapshot: Snapshot<T>): Uint8Array;
+    /**
+     * Decode binary data into a snapshot.
+     */
+    decode(buf: Uint8Array): Snapshot<T>;
+}

package/dist/protocol/snapshot/snapshot-codec.js

@@ -0,0 +1,56 @@
+/**
+ * Codec for encoding/decoding snapshots with binary serialization.
+ *
+ * Users instantiate this once with a PooledCodec for their state schema.
+ *
+ * @example
+ * ```ts
+ * import { SnapshotCodec } from './protocol/snapshot';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // schema })
+ * );
+ *
+ * // Encode/decode
+ * const buf = snapshotCodec.encode(snapshot);
+ * const decoded = snapshotCodec.decode(buf);
+ * ```
+ */
+export class SnapshotCodec {
+    /**
+     * @param updatesCodec Codec for encoding/decoding the state updates
+     */
+    constructor(updatesCodec) {
+        this.updatesCodec = updatesCodec;
+    }
+    /**
+     * Encode a snapshot into binary format.
+     * Format: [tick: u32][updates: encoded by updatesCodec]
+     */
+    encode(snapshot) {
+        const updatesBytes = this.updatesCodec.encode(snapshot.updates);
+        const buf = new Uint8Array(4 + updatesBytes.length);
+        // Encode tick (4 bytes, little-endian)
+        new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
+        // Encode updates
+        buf.set(updatesBytes, 4);
+        return buf;
+    }
+    /**
+     * Decode binary data into a snapshot.
+     */
+    decode(buf) {
+        // Decode tick (first 4 bytes)
+        const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
+        // Decode updates (remaining bytes)
+        const updatesBytes = buf.subarray(4);
+        const updates = this.updatesCodec.decode(updatesBytes);
+        return { tick, updates };
+    }
+}

package/dist/protocol/snapshot/snapshot-registry.d.ts

@@ -0,0 +1,100 @@
+import type { Snapshot } from "./snapshot";
+/**
+ * Generic codec interface (users import from core/pooled-codec)
+ */
+interface Codec<T> {
+    encode(value: T): Uint8Array;
+    decode(buf: Uint8Array): T;
+}
+/**
+ * Registry for multiple snapshot types with different update schemas.
+ *
+ * This allows efficient delta encoding by only sending specific update types
+ * instead of encoding all fields (including empty/nil ones).
+ *
+ * ## Memory Efficiency
+ *
+ * The encoding path minimizes allocations:
+ * 1. PooledCodec acquires a buffer from its pool (reused across calls)
+ * 2. PooledCodec writes data directly to the buffer at sequential offsets
+ * 3. SnapshotRegistry creates ONE final buffer: [typeId(1) + tick(4) + updatesBytes]
+ * 4. Total allocations per encode: 1 pooled buffer + 1 final buffer
+ *
+ * Buffer Layout:
+ * ```
+ * ┌─────────┬────────────┬──────────────────┐
+ * │ Type ID │    Tick    │  Updates (codec) │
+ * │ (u8)    │   (u32)    │   (variable)     │
+ * │ 1 byte  │  4 bytes   │    N bytes       │
+ * └─────────┴────────────┴──────────────────┘
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { SnapshotRegistry } from './protocol/snapshot';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * // Define different update types
+ * interface PlayerUpdate {
+ *   players: Array<{ entityId: number; x: number; y: number }>;
+ * }
+ *
+ * interface ScoreUpdate {
+ *   score: number;
+ * }
+ *
+ * // Create registry
+ * const registry = new SnapshotRegistry<PlayerUpdate | ScoreUpdate>();
+ *
+ * // Register codecs for each update type
+ * registry.register('players', new PooledCodec({
+ *   players: // schema
+ * }));
+ *
+ * registry.register('score', new PooledCodec({
+ *   score: BinaryCodec.u32
+ * }));
+ *
+ * // Server: Encode specific update type
+ * const buf = registry.encode('players', {
+ *   tick: 100,
+ *   updates: { players: [{ entityId: 1, x: 5, y: 10 }] }
+ * });
+ *
+ * // Client: Decode (type is embedded in message)
+ * const { type, snapshot } = registry.decode(buf);
+ * applySnapshot(state, snapshot);
+ * ```
+ */
+export declare class SnapshotRegistry<T> {
+    private codecs;
+    private typeIds;
+    private idToType;
+    private nextId;
+    /**
+     * Register a codec for a specific update type.
+     * Call this once per update type at startup.
+     */
+    register<U extends Partial<T>>(type: string, codec: Codec<U>): void;
+    /**
+     * Encode a snapshot with a specific update type.
+     * Format: [typeId: u8][tick: u32][updates: encoded by codec]
+     *
+     * Efficiently writes to a single buffer:
+     * - PooledCodec writes updates to its pooled buffer
+     * - We allocate ONE final buffer for [typeId + tick + updates]
+     * - Direct memory copy, no intermediate allocations
+     */
+    encode<U extends Partial<T>>(type: string, snapshot: Snapshot<U>): Uint8Array;
+    /**
+     * Decode a snapshot and return both the type and the snapshot.
+     */
+    decode(buf: Uint8Array): {
+        type: string;
+        snapshot: Snapshot<Partial<T>>;
+    };
+    has(type: string): boolean;
+    getTypes(): string[];
+}
+export {};

package/dist/protocol/snapshot/snapshot-registry.js

@@ -0,0 +1,136 @@
+/**
+ * Registry for multiple snapshot types with different update schemas.
+ *
+ * This allows efficient delta encoding by only sending specific update types
+ * instead of encoding all fields (including empty/nil ones).
+ *
+ * ## Memory Efficiency
+ *
+ * The encoding path minimizes allocations:
+ * 1. PooledCodec acquires a buffer from its pool (reused across calls)
+ * 2. PooledCodec writes data directly to the buffer at sequential offsets
+ * 3. SnapshotRegistry creates ONE final buffer: [typeId(1) + tick(4) + updatesBytes]
+ * 4. Total allocations per encode: 1 pooled buffer + 1 final buffer
+ *
+ * Buffer Layout:
+ * ```
+ * ┌─────────┬────────────┬──────────────────┐
+ * │ Type ID │    Tick    │  Updates (codec) │
+ * │ (u8)    │   (u32)    │   (variable)     │
+ * │ 1 byte  │  4 bytes   │    N bytes       │
+ * └─────────┴────────────┴──────────────────┘
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { SnapshotRegistry } from './protocol/snapshot';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * // Define different update types
+ * interface PlayerUpdate {
+ *   players: Array<{ entityId: number; x: number; y: number }>;
+ * }
+ *
+ * interface ScoreUpdate {
+ *   score: number;
+ * }
+ *
+ * // Create registry
+ * const registry = new SnapshotRegistry<PlayerUpdate | ScoreUpdate>();
+ *
+ * // Register codecs for each update type
+ * registry.register('players', new PooledCodec({
+ *   players: // schema
+ * }));
+ *
+ * registry.register('score', new PooledCodec({
+ *   score: BinaryCodec.u32
+ * }));
+ *
+ * // Server: Encode specific update type
+ * const buf = registry.encode('players', {
+ *   tick: 100,
+ *   updates: { players: [{ entityId: 1, x: 5, y: 10 }] }
+ * });
+ *
+ * // Client: Decode (type is embedded in message)
+ * const { type, snapshot } = registry.decode(buf);
+ * applySnapshot(state, snapshot);
+ * ```
+ */
+export class SnapshotRegistry {
+    constructor() {
+        this.codecs = new Map();
+        this.typeIds = new Map();
+        this.idToType = new Map();
+        this.nextId = 0;
+    }
+    /**
+     * Register a codec for a specific update type.
+     * Call this once per update type at startup.
+     */
+    register(type, codec) {
+        if (this.codecs.has(type)) {
+            throw new Error(`Snapshot type "${type}" is already registered`);
+        }
+        const typeId = this.nextId++;
+        this.codecs.set(type, codec);
+        this.typeIds.set(type, typeId);
+        this.idToType.set(typeId, type);
+    }
+    /**
+     * Encode a snapshot with a specific update type.
+     * Format: [typeId: u8][tick: u32][updates: encoded by codec]
+     *
+     * Efficiently writes to a single buffer:
+     * - PooledCodec writes updates to its pooled buffer
+     * - We allocate ONE final buffer for [typeId + tick + updates]
+     * - Direct memory copy, no intermediate allocations
+     */
+    encode(type, snapshot) {
+        const codec = this.codecs.get(type);
+        const typeId = this.typeIds.get(type);
+        if (!codec || typeId === undefined) {
+            throw new Error(`No codec registered for snapshot type "${type}"`);
+        }
+        // Encode updates using the specific codec (acquires from pool)
+        const updatesBytes = codec.encode(snapshot.updates);
+        // Allocate single buffer for complete message
+        const buf = new Uint8Array(1 + 4 + updatesBytes.length);
+        // Write type ID (1 byte)
+        buf[0] = typeId;
+        // Write tick (4 bytes, little-endian)
+        new DataView(buf.buffer).setUint32(1, snapshot.tick, true);
+        // Write updates (direct copy)
+        buf.set(updatesBytes, 5);
+        return buf;
+    }
+    /**
+     * Decode a snapshot and return both the type and the snapshot.
+     */
+    decode(buf) {
+        // Decode type ID (first byte)
+        const typeId = buf[0];
+        const type = this.idToType.get(typeId);
+        if (!type) {
+            throw new Error(`Unknown snapshot type ID: ${typeId}`);
+        }
+        const codec = this.codecs.get(type);
+        if (!codec) {
+            throw new Error(`No codec registered for snapshot type "${type}"`);
+        }
+        // Decode tick (bytes 1-4)
+        const tick = new DataView(buf.buffer, buf.byteOffset + 1).getUint32(0, true);
+        // Decode updates (remaining bytes)
+        const updatesBytes = buf.subarray(5);
+        const updates = codec.decode(updatesBytes);
+        return { type, snapshot: { tick, updates } };
+    }
+    has(type) {
+        return this.codecs.has(type);
+    }
+    getTypes() {
+        return Array.from(this.codecs.keys());
+    }
+}