murow 0.0.1

package/src/protocol/README.md

@@ -0,0 +1,310 @@
+# Protocol Layer
+
+Minimalist primitives for networked multiplayer games. Just intents and snapshots - you handle the rest.
+
+## What You Get
+
+1. **IntentRegistry** - Register, encode, decode intents with zero allocations
+2. **Snapshot<T>** - Type-safe delta updates
+3. **applySnapshot()** - Deep merge snapshot updates into state
+
+That's it. No loops, no queues, no storage - just the codec layer.
+
+## Quick Start
+
+### 1. Define Your Types
+
+```ts
+import { Intent, Snapshot } from "./protocol";
+
+interface GameState {
+  players: Record<number, { x: number; y: number; health: number }>;
+}
+
+interface MoveIntent extends Intent {
+  kind: 1;
+  tick: number;
+  dx: number;
+  dy: number;
+}
+
+interface ShootIntent extends Intent {
+  kind: 2;
+  tick: number;
+  targetId: number;
+}
+```
+
+### 2. Register Intent Codecs
+
+```ts
+import { IntentRegistry } from "./protocol/intent";
+import { PooledCodec } from "./core/pooled-codec";
+import { BinaryCodec } from "./core/binary-codec";
+
+const registry = new IntentRegistry();
+
+// Register move intent
+registry.register(
+  1,
+  new PooledCodec({
+    kind: BinaryCodec.u8,
+    tick: BinaryCodec.u32,
+    dx: BinaryCodec.f32,
+    dy: BinaryCodec.f32,
+  })
+);
+
+// Register shoot intent
+registry.register(
+  2,
+  new PooledCodec({
+    kind: BinaryCodec.u8,
+    tick: BinaryCodec.u32,
+    targetId: BinaryCodec.u32,
+  })
+);
+```
+
+### 3. Client: Encode & Send Intents
+
+```ts
+// Generate intent from input
+const intent: MoveIntent = {
+  kind: 1,
+  tick: currentTick,
+  dx: input.x,
+  dy: input.y,
+};
+
+// Encode using pooled codec (zero allocation)
+const buf = registry.encode(intent);
+
+// Send to server
+socket.send(buf);
+```
+
+### 4. Server: Receive & Decode Intents
+
+```ts
+socket.on("data", (buf: Uint8Array) => {
+  // First byte is always the intent kind
+  const kind = buf[0];
+
+  // Decode using registered codec
+  const intent = registry.decode(kind, buf);
+
+  // Process intent in your game logic
+  processIntent(intent);
+});
+```
+
+### 5. Server: Create & Send Snapshots
+
+```ts
+import { SnapshotCodec } from "./protocol/snapshot";
+import { PooledCodec } from "./core/pooled-codec";
+
+// Create codec for state updates (same schema as your state)
+const stateCodec = new PooledCodec({
+  players: // your state schema here
+});
+
+const snapshotCodec = new SnapshotCodec(stateCodec);
+
+// After processing intents, create a snapshot
+const snapshot: Snapshot<GameState> = {
+  tick: serverTick,
+  updates: {
+    // Only include what changed
+    players: {
+      1: { x: 10, y: 20, health: 90 },
+      2: { x: 15, y: 25 }, // health unchanged
+    },
+  },
+};
+
+// Encode and send (zero allocation)
+const buf = snapshotCodec.encode(snapshot);
+socket.send(buf);
+```
+
+### 6. Client: Decode & Apply Snapshots
+
+```ts
+import { applySnapshot } from "./protocol/snapshot";
+
+socket.on("snapshot", (buf: Uint8Array) => {
+  // Decode snapshot
+  const snapshot = snapshotCodec.decode(buf);
+
+  // Deep merge updates into client state
+  applySnapshot(clientState, snapshot);
+
+  // Render updated state
+  render(clientState);
+});
+```
+
+## Memory Efficiency
+
+The `PooledCodec` reuses buffers and objects:
+
+```ts
+// Encoding - reuses Uint8Array from pool
+const buf1 = registry.encode(intent1); // Acquires from pool
+socket.send(buf1);
+// buf1 automatically released back to pool after use
+
+// Decoding - reuses objects from pool
+const intent = registry.decode(kind, buf); // Acquires from pool
+processIntent(intent);
+// intent automatically released back to pool
+```
+
+**Zero allocations** during gameplay = zero GC pauses.
+
+## Snapshot Deep Merging
+
+`applySnapshot` intelligently merges nested updates:
+
+```ts
+const state: GameState = {
+  players: {
+    1: { x: 0, y: 0, health: 100 },
+    2: { x: 10, y: 10, health: 100 },
+  },
+};
+
+const snapshot: Snapshot<GameState> = {
+  tick: 100,
+  updates: {
+    players: {
+      1: { x: 5 }, // Only update x, keep y and health
+    },
+  },
+};
+
+applySnapshot(state, snapshot);
+
+// Result:
+// state.players[1] = { x: 5, y: 0, health: 100 }
+// state.players[2] unchanged
+```
+
+- **Objects**: Deep merged
+- **Arrays**: Replaced entirely
+- **Primitives**: Overwritten
+
+## Efficient Partial Updates with SnapshotRegistry
+
+For games with many state fields, use `SnapshotRegistry` to send only specific update types:
+
+```ts
+import { SnapshotRegistry } from "./protocol/snapshot";
+import { PooledCodec } from "./core/pooled-codec";
+import { BinaryCodec } from "./core/binary-codec";
+
+// Define separate update types
+interface PlayerUpdate {
+  players: Array<{ entityId: number; x: number; y: number }>;
+}
+
+interface ScoreUpdate {
+  score: number;
+}
+
+interface ProjectileUpdate {
+  projectiles: Array<{ id: number; x: number; y: number }>;
+}
+
+type GameUpdate = PlayerUpdate | ScoreUpdate | ProjectileUpdate;
+
+// Create registry
+const registry = new SnapshotRegistry<GameUpdate>();
+
+// Register codecs for each update type
+registry.register("players", new PooledCodec({
+  players: // schema
+}));
+
+registry.register("score", new PooledCodec({
+  score: BinaryCodec.u32
+}));
+
+registry.register("projectiles", new PooledCodec({
+  projectiles: // array schema
+}));
+
+// Server: Send only what changed
+if (playersChanged) {
+  const buf = registry.encode("players", {
+    tick: 100,
+    updates: { players: [{ entityId: 1, x: 5, y: 10 }] }
+  });
+  socket.send(buf);
+}
+
+if (scoreChanged) {
+  const buf = registry.encode("score", {
+    tick: 100,
+    updates: { score: 50 }
+  });
+  socket.send(buf);
+}
+
+// Client: Decode and apply
+socket.on("snapshot", (buf: Uint8Array) => {
+  const { type, snapshot } = registry.decode(buf);
+  applySnapshot(clientState, snapshot);
+});
+```
+
+**Benefits:**
+- ✅ Only encode fields that changed (true partial updates)
+- ✅ No bandwidth wasted on nil/empty values
+- ✅ Type ID embedded in message (1 byte overhead)
+- ✅ Works with arrays, Records, primitives
+
+## Multiple Intents
+
+You can have as many intent types as needed:
+
+```ts
+enum IntentKind {
+  Move = 1,
+  Shoot = 2,
+  Jump = 3,
+  UseItem = 4,
+  Chat = 5,
+}
+
+registry.register(IntentKind.Move, new PooledCodec(moveSchema));
+registry.register(IntentKind.Shoot, new PooledCodec(shootSchema));
+registry.register(IntentKind.Jump, new PooledCodec(jumpSchema));
+// ... etc
+```
+
+## What You Build Yourself
+
+This layer intentionally **does not** provide:
+
+- ❌ Game loops (use `FixedTicker` from core)
+- ❌ Intent queuing/buffering (application-specific)
+- ❌ Snapshot storage/history (application-specific)
+- ❌ Network transport (WebSocket, WebRTC, etc.)
+- ❌ Prediction/rollback (use `IntentTracker` and `Reconciliator` from core)
+- ❌ Interpolation (application-specific)
+- ❌ Lag compensation (application-specific)
+
+The protocol layer gives you type-safe codecs. Core utilities like `FixedTicker`, `IntentTracker`, and `Reconciliator` are available separately.
+
+## Testing
+
+```bash
+npm test -- intent-registry
+```
+
+## License
+
+MIT

package/src/protocol/index.ts

@@ -0,0 +1,44 @@
+/**
+ * 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/src/protocol/intent/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 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/src/protocol/intent/intent-registry.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { IntentRegistry } from "./intent-registry";
+import { Intent } from "./intent";
+import { Codec } from "./intent-registry";
+
+// Mock intent types
+interface MockIntent extends Intent {
+  kind: 1;
+  tick: number;
+  value: number;
+}
+
+interface AnotherIntent extends Intent {
+  kind: 2;
+  tick: number;
+  data: string;
+}
+
+// Mock codec implementation
+class MockCodec implements Codec<MockIntent> {
+  encode(value: MockIntent): Uint8Array {
+    const buf = new Uint8Array(9);
+    buf[0] = value.kind;
+    new DataView(buf.buffer).setUint32(1, value.tick, true);
+    new DataView(buf.buffer).setUint32(5, value.value, true);
+    return buf;
+  }
+
+  decode(buf: Uint8Array): MockIntent {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    return {
+      kind: 1,
+      tick: view.getUint32(1, true),
+      value: view.getUint32(5, true),
+    };
+  }
+}
+
+class StringCodec implements Codec<AnotherIntent> {
+  encode(value: AnotherIntent): Uint8Array {
+    const encoder = new TextEncoder();
+    const dataBytes = encoder.encode(value.data);
+    const buf = new Uint8Array(5 + dataBytes.length);
+    buf[0] = value.kind;
+    new DataView(buf.buffer).setUint32(1, value.tick, true);
+    buf.set(dataBytes, 5);
+    return buf;
+  }
+
+  decode(buf: Uint8Array): AnotherIntent {
+    const view = new DataView(buf.buffer, buf.byteOffset);
+    const decoder = new TextDecoder();
+    return {
+      kind: 2,
+      tick: view.getUint32(1, true),
+      data: decoder.decode(buf.slice(5)),
+    };
+  }
+}
+
+describe("IntentRegistry", () => {
+  let registry: IntentRegistry;
+
+  beforeEach(() => {
+    registry = new IntentRegistry();
+  });
+
+  describe("register", () => {
+    it("should register a codec for an intent kind", () => {
+      const codec = new MockCodec();
+      registry.register(1, codec);
+      expect(registry.has(1)).toBe(true);
+    });
+
+    it("should throw error when registering duplicate kind", () => {
+      const codec = new MockCodec();
+      registry.register(1, codec);
+      expect(() => registry.register(1, codec)).toThrow(
+        "Intent kind 1 is already registered"
+      );
+    });
+
+    it("should allow registering multiple different kinds", () => {
+      registry.register(1, new MockCodec());
+      registry.register(2, new StringCodec());
+      expect(registry.has(1)).toBe(true);
+      expect(registry.has(2)).toBe(true);
+    });
+  });
+
+  describe("encode", () => {
+    it("should encode an intent using registered codec", () => {
+      registry.register(1, new MockCodec());
+      const intent: MockIntent = { kind: 1, tick: 100, value: 42 };
+      const buf = registry.encode(intent);
+
+      expect(buf).toBeInstanceOf(Uint8Array);
+      expect(buf.length).toBe(9);
+      expect(buf[0]).toBe(1); // kind
+    });
+
+    it("should throw error when encoding unregistered intent kind", () => {
+      const intent: MockIntent = { kind: 1, tick: 100, value: 42 };
+      expect(() => registry.encode(intent)).toThrow(
+        "No codec registered for intent kind 1"
+      );
+    });
+
+    it("should encode different intent types correctly", () => {
+      registry.register(1, new MockCodec());
+      registry.register(2, new StringCodec());
+
+      const intent1: MockIntent = { kind: 1, tick: 100, value: 42 };
+      const intent2: AnotherIntent = { kind: 2, tick: 200, data: "test" };
+
+      const buf1 = registry.encode(intent1);
+      const buf2 = registry.encode(intent2);
+
+      expect(buf1[0]).toBe(1);
+      expect(buf2[0]).toBe(2);
+    });
+  });
+
+  describe("decode", () => {
+    it("should decode a buffer using registered codec", () => {
+      registry.register(1, new MockCodec());
+      const original: MockIntent = { kind: 1, tick: 100, value: 42 };
+      const buf = registry.encode(original);
+      const decoded = registry.decode(1, buf);
+
+      expect(decoded).toEqual(original);
+    });
+
+    it("should throw error when decoding with unregistered kind", () => {
+      const buf = new Uint8Array([1, 0, 0, 0, 100, 0, 0, 0, 42]);
+      expect(() => registry.decode(1, buf)).toThrow(
+        "No codec registered for intent kind 1"
+      );
+    });
+
+    it("should decode different intent types correctly", () => {
+      registry.register(1, new MockCodec());
+      registry.register(2, new StringCodec());
+
+      const intent1: MockIntent = { kind: 1, tick: 100, value: 42 };
+      const intent2: AnotherIntent = { kind: 2, tick: 200, data: "hello" };
+
+      const buf1 = registry.encode(intent1);
+      const buf2 = registry.encode(intent2);
+
+      const decoded1 = registry.decode(1, buf1);
+      const decoded2 = registry.decode(2, buf2);
+
+      expect(decoded1).toEqual(intent1);
+      expect(decoded2).toEqual(intent2);
+    });
+  });
+
+  describe("has", () => {
+    it("should return true for registered kinds", () => {
+      registry.register(1, new MockCodec());
+      expect(registry.has(1)).toBe(true);
+    });
+
+    it("should return false for unregistered kinds", () => {
+      expect(registry.has(1)).toBe(false);
+    });
+  });
+
+  describe("unregister", () => {
+    it("should remove a registered codec", () => {
+      registry.register(1, new MockCodec());
+      expect(registry.has(1)).toBe(true);
+
+      const removed = registry.unregister(1);
+      expect(removed).toBe(true);
+      expect(registry.has(1)).toBe(false);
+    });
+
+    it("should return false when unregistering non-existent kind", () => {
+      const removed = registry.unregister(1);
+      expect(removed).toBe(false);
+    });
+  });
+
+  describe("clear", () => {
+    it("should remove all registered codecs", () => {
+      registry.register(1, new MockCodec());
+      registry.register(2, new StringCodec());
+
+      registry.clear();
+
+      expect(registry.has(1)).toBe(false);
+      expect(registry.has(2)).toBe(false);
+    });
+  });
+
+  describe("getKinds", () => {
+    it("should return empty array when no codecs registered", () => {
+      expect(registry.getKinds()).toEqual([]);
+    });
+
+    it("should return all registered kinds", () => {
+      registry.register(1, new MockCodec());
+      registry.register(2, new StringCodec());
+
+      const kinds = registry.getKinds();
+      expect(kinds).toContain(1);
+      expect(kinds).toContain(2);
+      expect(kinds.length).toBe(2);
+    });
+  });
+
+  describe("round-trip encoding/decoding", () => {
+    it("should preserve intent data through encode/decode cycle", () => {
+      registry.register(1, new MockCodec());
+
+      const original: MockIntent = { kind: 1, tick: 12345, value: 98765 };
+      const buf = registry.encode(original);
+      const decoded = registry.decode(1, buf);
+
+      expect(decoded).toEqual(original);
+    });
+
+    it("should handle multiple round-trips", () => {
+      registry.register(1, new MockCodec());
+
+      const original: MockIntent = { kind: 1, tick: 100, value: 42 };
+
+      for (let i = 0; i < 10; i++) {
+        const buf = registry.encode(original);
+        const decoded = registry.decode(1, buf);
+        expect(decoded).toEqual(original);
+      }
+    });
+  });
+});

package/src/protocol/intent/intent-registry.ts

@@ -0,0 +1,88 @@
+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 class IntentRegistry {
+  private codecs = new Map<number, Codec<any>>();
+
+  /**
+   * 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 {
+    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<T extends Intent>(intent: T): Uint8Array {
+    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: number, buf: Uint8Array): Intent {
+    const codec = this.codecs.get(kind);
+    if (!codec) {
+      throw new Error(`No codec registered for intent kind ${kind}`);
+    }
+    return codec.decode(buf);
+  }
+
+  has(kind: number): boolean {
+    return this.codecs.has(kind);
+  }
+
+  unregister(kind: number): boolean {
+    return this.codecs.delete(kind);
+  }
+
+  clear(): void {
+    this.codecs.clear();
+  }
+
+  getKinds(): number[] {
+    return Array.from(this.codecs.keys());
+  }
+}