@couch-kit/host 0.3.0

package/README.md

@@ -0,0 +1,147 @@
+# @couch-kit/host
+
+The server-side library for React Native TV applications. This package turns your TV app into a local game server.
+
+> **Looking for a working example?** Check out the [Buzz](https://github.com/faluciano/buzz-tv-party-game) starter project for a complete host setup including asset extraction, QR code display, and player tracking.
+
+## Features
+
+- **Dual-Port Architecture:**
+  - **Port 8080:** Static File Server (serves the web controller).
+  - **Port 8082:** WebSocket Game Server (handles real-time logic).
+- **Session Recovery:** Tracks user secrets to support reconnection (handling page refreshes).
+- **Large Message Support:** Capable of sending game states larger than 64KB (64-bit frame lengths).
+- **Smart Network Discovery:** Uses the device IPv4 address for LAN URLs.
+- **Game Loop:** Manages the canonical `IGameState` using a reducer.
+- **Dev Mode:** Supports hot-reloading the web controller during development.
+- **Debug Mode:** Optional logging for troubleshooting connection issues.
+
+## Installation
+
+```bash
+bun add @couch-kit/host
+```
+
+> **Note:** This library includes native dependencies (`react-native-tcp-socket`, `react-native-fs`, etc.). React Native's autolinking will handle the setup for Android. Ensure your `android/build.gradle` is configured correctly if you encounter build issues.
+
+## Usage
+
+## API
+
+### `<GameHostProvider config={...}>`
+
+Config:
+
+- `initialState`: initial host state
+- `reducer`: `(state, action) => state` (shared reducer)
+- `port?`: HTTP static server port (default `8080`)
+- `wsPort?`: WebSocket game server port (default `8082`)
+- `staticDir?`: absolute path to the directory of static files to serve. On Android, APK assets live inside a zip archive and cannot be served directly — use this to point to a writable filesystem path where you've extracted the `www/` assets at runtime. Defaults to `${RNFS.MainBundlePath}/www`.
+- `devMode?`: if true, do not start the TV static file server; instead point phones at `devServerUrl`
+- `devServerUrl?`: URL of your laptop dev server (e.g. `http://192.168.1.50:5173`)
+- `debug?`: enable verbose logs
+
+### `useGameHost()`
+
+Returns:
+
+- `state`: canonical host state
+- `dispatch(action)`: dispatches an action into your reducer
+- `serverUrl`: HTTP URL phones should open (or `devServerUrl` in dev mode)
+- `serverError`: static server error (if startup fails)
+
+## System Actions (Important)
+
+The host will dispatch a few **system action types** into your reducer. Treat these as reserved:
+
+- `PLAYER_JOINED`: payload `{ id: string, name: string, avatar?: string, secret?: string }`
+- `PLAYER_LEFT`: payload `{ playerId: string }`
+
+If you want to track players in `state.players`, handle these action types in your reducer. The `secret` field can be used to identify returning players.
+
+### 1. Configure the Provider
+
+Wrap your root component (or the game screen) with `GameHostProvider`.
+
+```tsx
+import { GameHostProvider } from "@couch-kit/host";
+import { gameReducer, initialState } from "./shared/gameLogic";
+
+export default function App() {
+  return (
+    <GameHostProvider
+      config={{
+        reducer: gameReducer,
+        initialState: initialState,
+        port: 8080, // Optional: HTTP port (default 8080)
+        wsPort: 8082, // Optional: WebSocket port (default 8082)
+        debug: true, // Optional: Enable detailed logs
+      }}
+    >
+      <GameScreen />
+    </GameHostProvider>
+  );
+}
+```
+
+### 2. Access State & Actions
+
+Use the `useGameHost` hook to access the game state, dispatch actions, and get the server URL (for QR codes).
+
+```tsx
+import { useGameHost } from "@couch-kit/host";
+import QRCode from "react-native-qrcode-svg";
+import { View, Text, Button } from "react-native";
+
+function GameScreen() {
+  const { state, dispatch, serverUrl } = useGameHost();
+
+  return (
+    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
+      {state.status === "lobby" && (
+        <>
+          <Text style={{ fontSize: 24, marginBottom: 20 }}>Join the Game!</Text>
+          {serverUrl && <QRCode value={serverUrl} size={200} />}
+          <Text style={{ marginTop: 20 }}>Scan to connect</Text>
+          <Text>Players Connected: {Object.keys(state.players).length}</Text>
+
+          <Button
+            title="Start Game"
+            onPress={() => dispatch({ type: "START_GAME" })}
+          />
+        </>
+      )}
+
+      {state.status === "playing" && (
+        <Text style={{ fontSize: 40 }}>Current Score: {state.score}</Text>
+      )}
+    </View>
+  );
+}
+```
+
+## Development Mode
+
+To iterate on your web controller without rebuilding the Android app constantly:
+
+1.  Start your web project locally (`vite dev` usually runs on `localhost:5173`).
+2.  Configure the Host to point to your laptop:
+
+```tsx
+<GameHostProvider
+    config={{
+        devMode: true,
+        devServerUrl: 'http://192.168.1.50:5173' // Your laptop's IP
+    }}
+>
+```
+
+The TV will now tell phones to load the controller from your laptop.
+
+Important: when the controller is served from the laptop, the client-side hook cannot infer the TV WebSocket host from `window.location.hostname`. In dev mode, pass `url: "ws://TV_IP:8082"` to `useGameClient()`.
+
+## Bundling / Assets
+
+In production, the host serves static controller assets from `${RNFS.MainBundlePath}/www`.
+
+The CLI `couch-kit bundle` copies your web build output into `android/app/src/main/assets/www` (default). Ensure your app packaging makes those assets available under the expected `www` folder.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@couch-kit/host",
+  "version": "0.3.0",
+  "main": "src/index.tsx",
+  "react-native": "src/index.tsx",
+  "source": "src/index.tsx",
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "!lib/typescript/example",
+    "!android/build",
+    "!ios/build",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__"
+  ],
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "clean": "del-cli lib"
+  },
+  "dependencies": {
+    "@couch-kit/core": "0.2.0",
+    "js-sha1": "^0.7.0",
+    "react-native-fs": "^2.20.0",
+    "react-native-network-info": "^5.2.1",
+    "react-native-nitro-http-server": "^1.5.4",
+    "react-native-nitro-modules": "^0.33.2",
+    "react-native-tcp-socket": "^6.0.6"
+  },
+  "devDependencies": {
+    "@types/react": "~17.0.21",
+    "@types/react-native": "0.70.0",
+    "react": "18.2.0",
+    "react-native": "0.72.6",
+    "del-cli": "^5.1.0",
+    "jest": "^29.7.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  }
+}

package/src/declarations.d.ts

@@ -0,0 +1,6 @@
+declare module "react-native-nitro-http-server" {
+  export class StaticServer {
+    start(port: number, path: string, host?: string): Promise<void>;
+    stop(): void;
+  }
+}

package/src/event-emitter.ts

@@ -0,0 +1,69 @@
+/**
+ * Lightweight EventEmitter implementation for cross-platform compatibility.
+ * Works in browser, React Native, and Node.js environments.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Listener = (...args: any[]) => void;
+
+export class EventEmitter {
+  private listeners: Map<string, Listener[]> = new Map();
+
+  on(event: string, listener: Listener): this {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(listener);
+    return this;
+  }
+
+  once(event: string, listener: Listener): this {
+    const onceWrapper: Listener = (...args: any[]) => {
+      this.off(event, onceWrapper);
+      listener(...args);
+    };
+    return this.on(event, onceWrapper);
+  }
+
+  off(event: string, listener: Listener): this {
+    const listeners = this.listeners.get(event);
+    if (listeners) {
+      const index = listeners.indexOf(listener);
+      if (index !== -1) {
+        listeners.splice(index, 1);
+      }
+    }
+    return this;
+  }
+
+  emit(event: string, ...args: any[]): boolean {
+    const listeners = this.listeners.get(event);
+    if (!listeners || listeners.length === 0) {
+      return false;
+    }
+
+    // Create a copy to avoid issues if listeners are added/removed during emit
+    const listenersCopy = [...listeners];
+    for (const listener of listenersCopy) {
+      try {
+        listener(...args);
+      } catch (error) {
+        console.error(`Error in event listener for "${event}":`, error);
+      }
+    }
+    return true;
+  }
+
+  removeAllListeners(event?: string): this {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+    return this;
+  }
+
+  listenerCount(event: string): number {
+    return this.listeners.get(event)?.length ?? 0;
+  }
+}

package/src/events.d.ts

@@ -0,0 +1,20 @@
+import { EventEmitter } from "./event-emitter";
+
+// Since the EventEmitter type definition might not perfectly match the Node.js one in RN environment,
+// we'll declare the interface we expect.
+export interface GameWebSocketServer extends EventEmitter {
+  on(event: "connection", listener: (socketId: string) => void): this;
+  on(
+    event: "message",
+    listener: (socketId: string, message: unknown) => void,
+  ): this;
+  on(event: "disconnect", listener: (socketId: string) => void): this;
+  on(event: "listening", listener: (port: number) => void): this;
+  on(event: "error", listener: (error: Error) => void): this;
+
+  emit(event: "connection", socketId: string): boolean;
+  emit(event: "message", socketId: string, message: unknown): boolean;
+  emit(event: "disconnect", socketId: string): boolean;
+  emit(event: "listening", port: number): boolean;
+  emit(event: "error", error: Error): boolean;
+}

package/src/index.tsx

@@ -0,0 +1,4 @@
+export * from './provider';
+export * from './server';
+export * from './websocket';
+export * from './network';

package/src/network.ts

@@ -0,0 +1,25 @@
+import { NetworkInfo } from "react-native-network-info";
+
+/**
+ * Smart IP Discovery
+ * Prioritizes interfaces that are likely to be the main network (WiFi/Ethernet)
+ * over internal/virtual interfaces.
+ */
+export async function getBestIpAddress(): Promise<string | null> {
+  try {
+    // 1. Try to get the standard IP address (usually WiFi)
+    const ip = await NetworkInfo.getIPV4Address();
+
+    if (ip && ip !== "0.0.0.0" && ip !== "127.0.0.1") {
+      return ip;
+    }
+
+    // Fallback logic could go here (e.g., iterating interfaces if exposed by a native module)
+    // For now, react-native-network-info is the standard abstraction.
+
+    return null;
+  } catch (error) {
+    console.warn("[CouchKit] Failed to get IP address:", error);
+    return null;
+  }
+}

package/src/provider.tsx

@@ -0,0 +1,187 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useReducer,
+  useRef,
+} from "react";
+import { GameWebSocketServer } from "./websocket";
+import { useStaticServer } from "./server";
+import {
+  MessageTypes,
+  type IGameState,
+  type IAction,
+  type ClientMessage,
+} from "@couch-kit/core";
+
+interface GameHostConfig<S extends IGameState, A extends IAction> {
+  initialState: S;
+  reducer: (state: S, action: A) => S;
+  port?: number; // Static server port (default 8080)
+  wsPort?: number; // WebSocket port (default: HTTP port + 2, i.e. 8082)
+  devMode?: boolean;
+  devServerUrl?: string;
+  staticDir?: string; // Override the default www directory path (required on Android)
+  debug?: boolean;
+}
+
+interface GameHostContextValue<S extends IGameState, A extends IAction> {
+  state: S;
+  dispatch: (action: A) => void;
+  serverUrl: string | null;
+  serverError: Error | null;
+}
+
+// Create Context with 'any' fallback because Context generics are tricky in React
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const GameHostContext = createContext<GameHostContextValue<any, any> | null>(
+  null,
+);
+
+export function GameHostProvider<S extends IGameState, A extends IAction>({
+  children,
+  config,
+}: {
+  children: React.ReactNode;
+  config: GameHostConfig<S, A>;
+}) {
+  const [state, dispatch] = useReducer(config.reducer, config.initialState);
+
+  // Keep a ref to state so we can access it inside callbacks/effects that don't depend on it
+  const stateRef = useRef(state);
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  // 1. Start Static File Server (Port 8080)
+  const { url: serverUrl, error: serverError } = useStaticServer({
+    port: config.port || 8080,
+    devMode: config.devMode,
+    devServerUrl: config.devServerUrl,
+    staticDir: config.staticDir,
+  });
+
+  // 2. Start WebSocket Server (Convention: HTTP port + 2, avoids Metro on 8081)
+  const wsServer = useRef<GameWebSocketServer | null>(null);
+
+  // Track active sessions: secret -> playerId
+  const sessions = useRef<Map<string, string>>(new Map());
+
+  useEffect(() => {
+    const httpPort = config.port || 8080;
+    const port = config.wsPort || httpPort + 2;
+    const server = new GameWebSocketServer({ port, debug: config.debug });
+
+    server.start();
+    wsServer.current = server;
+
+    server.on("listening", (p) => {
+      if (config.debug)
+        console.log(`[GameHost] WebSocket listening on port ${p}`);
+    });
+
+    server.on("connection", (socketId) => {
+      if (config.debug) console.log(`[GameHost] Client connected: ${socketId}`);
+    });
+
+    server.on("message", (socketId, message: ClientMessage) => {
+      if (config.debug)
+        console.log(`[GameHost] Msg from ${socketId}:`, message);
+
+      switch (message.type) {
+        case MessageTypes.JOIN: {
+          // Check for existing session
+          const { secret, ...payload } = message.payload;
+
+          if (secret) {
+            // Update the session map with the new socket ID for this secret
+            sessions.current.set(secret, socketId);
+          }
+
+          dispatch({
+            type: "PLAYER_JOINED",
+            payload: { id: socketId, secret, ...payload },
+          } as unknown as A);
+
+          server.send(socketId, {
+            type: MessageTypes.WELCOME,
+            payload: {
+              playerId: socketId,
+              state: stateRef.current,
+              serverTime: Date.now(),
+            },
+          });
+          break;
+        }
+
+        case MessageTypes.ACTION:
+          dispatch(message.payload as A);
+          break;
+
+        case MessageTypes.PING:
+          server.send(socketId, {
+            type: MessageTypes.PONG,
+            payload: {
+              id: message.payload.id,
+              origTimestamp: message.payload.timestamp,
+              serverTime: Date.now(),
+            },
+          });
+          break;
+      }
+    });
+
+    server.on("disconnect", (socketId) => {
+      if (config.debug)
+        console.log(`[GameHost] Client disconnected: ${socketId}`);
+
+      // We do NOT remove the session from the map here,
+      // allowing them to reconnect later with the same secret.
+
+      dispatch({
+        type: "PLAYER_LEFT",
+        payload: { playerId: socketId },
+      } as unknown as A);
+    });
+
+    return () => {
+      server.stop();
+    };
+  }, []); // Run once on mount
+
+  // 3. Broadcast State Updates
+  // Whenever React state changes, send it to all clients
+  useEffect(() => {
+    if (wsServer.current) {
+      // Optimization: In the future, send deltas or only send if changed significantly
+      wsServer.current.broadcast({
+        type: MessageTypes.STATE_UPDATE,
+        payload: {
+          newState: state,
+          timestamp: Date.now(),
+        },
+      });
+    }
+  }, [state]);
+
+  // Keep stateRef in sync inside this effect too just in case (redundant but safe)
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  return (
+    <GameHostContext.Provider
+      value={{ state, dispatch, serverUrl, serverError }}
+    >
+      {children}
+    </GameHostContext.Provider>
+  );
+}
+
+export function useGameHost<S extends IGameState, A extends IAction>() {
+  const context = useContext(GameHostContext);
+  if (!context) {
+    throw new Error("useGameHost must be used within a GameHostProvider");
+  }
+  return context as GameHostContextValue<S, A>;
+}

package/src/server.ts

@@ -0,0 +1,70 @@
+import { useEffect, useState } from "react";
+import { StaticServer } from "react-native-nitro-http-server";
+import RNFS from "react-native-fs";
+import { getBestIpAddress } from "./network";
+
+interface CouchKitHostConfig {
+  port?: number;
+  devMode?: boolean;
+  devServerUrl?: string; // e.g. "http://localhost:5173"
+  staticDir?: string; // Override the default www directory path (required on Android)
+}
+
+export const useStaticServer = (config: CouchKitHostConfig) => {
+  const [url, setUrl] = useState<string | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let server: StaticServer | null = null;
+
+    const startServer = async () => {
+      // In Dev Mode, we don't start the static server.
+      // We just resolve the IP so the host knows where it is.
+      if (config.devMode && config.devServerUrl) {
+        const ip = await getBestIpAddress();
+        if (ip) {
+          // In dev mode, the URL is the laptop's dev server,
+          // but we might need the TV's IP for the WebSocket connection later.
+          setUrl(config.devServerUrl);
+        } else {
+          setError(new Error("Could not detect TV IP address"));
+        }
+        return;
+      }
+
+      // Production Mode: Serve assets from bundle
+      try {
+        // Use staticDir if provided (required on Android where MainBundlePath is undefined),
+        // otherwise fall back to iOS MainBundlePath
+        const path = config.staticDir || `${RNFS.MainBundlePath}/www`;
+        const port = config.port || 8080;
+
+        server = new StaticServer();
+
+        // Use '0.0.0.0' to bind to all interfaces (local network)
+        await server.start(port, path, "0.0.0.0");
+
+        // We prefer the actual IP over "localhost" returned by some libs
+        const ip = await getBestIpAddress();
+        if (ip) {
+          setUrl(`http://${ip}:${port}`);
+        } else {
+          // Fallback if we can't detect IP (though HttpServer doesn't return the URL directly like the old lib)
+          setUrl(`http://localhost:${port}`);
+        }
+      } catch (e) {
+        setError(e as Error);
+      }
+    };
+
+    startServer();
+
+    return () => {
+      if (server) {
+        server.stop();
+      }
+    };
+  }, [config.port, config.devMode, config.devServerUrl, config.staticDir]);
+
+  return { url, error };
+};

package/src/websocket.ts

@@ -0,0 +1,382 @@
+/**
+ * Lightweight WebSocket Server Implementation
+ * Built on top of react-native-tcp-socket
+ *
+ * Supports: text frames, close frames, ping/pong, multi-frame TCP packets,
+ * and robust buffer management per RFC 6455.
+ */
+
+import TcpSocket from "react-native-tcp-socket";
+import { EventEmitter } from "./event-emitter";
+import { Buffer } from "buffer";
+import { sha1 } from "js-sha1";
+
+interface WebSocketConfig {
+  port: number;
+  debug?: boolean;
+}
+
+// WebSocket opcodes (RFC 6455 Section 5.2)
+const OPCODE = {
+  CONTINUATION: 0x0,
+  TEXT: 0x1,
+  BINARY: 0x2,
+  CLOSE: 0x8,
+  PING: 0x9,
+  PONG: 0xa,
+} as const;
+
+// Simple WebSocket Frame Parser/Builder
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+interface DecodedFrame {
+  opcode: number;
+  payload: Buffer;
+  bytesConsumed: number;
+}
+
+export class GameWebSocketServer extends EventEmitter {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private server: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private clients: Map<string, any>;
+  private port: number;
+  private debug: boolean;
+
+  constructor(config: WebSocketConfig) {
+    super();
+    this.port = config.port;
+    this.debug = !!config.debug;
+    this.clients = new Map();
+  }
+
+  private log(...args: unknown[]) {
+    if (this.debug) {
+      console.log(...args);
+    }
+  }
+
+  private generateSocketId(): string {
+    // Generate a 21-character base36 ID for negligible collision probability
+    const a = Math.random().toString(36).substring(2, 15); // 13 chars
+    const b = Math.random().toString(36).substring(2, 10); // 8 chars
+    return a + b;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public start() {
+    this.log(`[WebSocket] Starting server on port ${this.port}...`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.server = TcpSocket.createServer((socket: any) => {
+      this.log(
+        `[WebSocket] New connection from ${socket.address?.()?.address}`,
+      );
+      let buffer: Buffer = Buffer.alloc(0);
+
+      socket.on("data", (data: Buffer | string) => {
+        this.log(
+          `[WebSocket] Received data chunk: ${typeof data === "string" ? data.length : data.length} bytes`,
+        );
+        // Concatenate new data
+        buffer = Buffer.concat([
+          buffer,
+          typeof data === "string" ? Buffer.from(data) : data,
+        ]);
+
+        // Handshake not yet performed?
+        if (!socket.isHandshakeComplete) {
+          const header = buffer.toString("utf8");
+          const endOfHeader = header.indexOf("\r\n\r\n");
+          if (endOfHeader !== -1) {
+            this.handleHandshake(socket, header);
+            // Retain any bytes after the handshake (could be the first WS frame)
+            const headerByteLength = Buffer.byteLength(
+              header.substring(0, endOfHeader + 4),
+              "utf8",
+            );
+            buffer = buffer.slice(headerByteLength);
+            socket.isHandshakeComplete = true;
+            // Fall through to process any remaining frames below
+          } else {
+            return;
+          }
+        }
+
+        // Process all complete frames in the buffer
+        this.processFrames(socket, buffer, (remaining) => {
+          buffer = remaining;
+        });
+      });
+
+      socket.on("error", (error: Error) => {
+        this.emit("error", error);
+      });
+
+      socket.on("close", () => {
+        if (socket.id) {
+          this.clients.delete(socket.id);
+          this.emit("disconnect", socket.id);
+        }
+      });
+    });
+
+    this.server.listen({ port: this.port, host: "0.0.0.0" }, () => {
+      this.log(`[WebSocket] Server listening on 0.0.0.0:${this.port}`);
+      this.emit("listening", this.port);
+    });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private processFrames(
+    socket: any,
+    buffer: Buffer,
+    setBuffer: (b: Buffer) => void,
+  ) {
+    while (buffer.length > 0) {
+      const frame = this.decodeFrame(buffer);
+      if (!frame) {
+        // Incomplete frame -- keep buffer, wait for more data
+        break;
+      }
+
+      // Advance buffer past the consumed frame
+      buffer = buffer.slice(frame.bytesConsumed);
+
+      // Handle frame by opcode
+      switch (frame.opcode) {
+        case OPCODE.TEXT: {
+          try {
+            const message = JSON.parse(frame.payload.toString("utf8"));
+            this.emit("message", socket.id, message);
+          } catch (e) {
+            // Corrupt JSON in a complete frame -- discard this frame, continue processing
+            this.log(
+              `[WebSocket] Invalid JSON from ${socket.id}, discarding frame`,
+            );
+          }
+          break;
+        }
+
+        case OPCODE.CLOSE: {
+          this.log(`[WebSocket] Close frame from ${socket.id}`);
+          // Send close frame back (RFC 6455 Section 5.5.1)
+          const closeFrame = Buffer.alloc(2);
+          closeFrame[0] = 0x88; // FIN + Close opcode
+          closeFrame[1] = 0x00; // No payload
+          try {
+            socket.write(closeFrame);
+          } catch {
+            // Socket may already be closing
+          }
+          socket.destroy();
+          break;
+        }
+
+        case OPCODE.PING: {
+          this.log(`[WebSocket] Ping from ${socket.id}`);
+          // Respond with pong containing the same payload (RFC 6455 Section 5.5.3)
+          const pongFrame = this.encodeControlFrame(OPCODE.PONG, frame.payload);
+          try {
+            socket.write(pongFrame);
+          } catch {
+            // Socket may be closing
+          }
+          break;
+        }
+
+        case OPCODE.PONG: {
+          // Unsolicited pong -- safe to ignore (RFC 6455 Section 5.5.3)
+          this.log(`[WebSocket] Pong from ${socket.id}`);
+          break;
+        }
+
+        case OPCODE.BINARY: {
+          // Binary frames not supported -- log and discard
+          this.log(
+            `[WebSocket] Binary frame from ${socket.id}, not supported -- discarding`,
+          );
+          break;
+        }
+
+        default: {
+          this.log(
+            `[WebSocket] Unknown opcode 0x${frame.opcode.toString(16)} from ${socket.id}, discarding`,
+          );
+          break;
+        }
+      }
+
+      // If socket was destroyed (e.g., close frame), stop processing
+      if (socket.destroyed) break;
+    }
+
+    setBuffer(buffer);
+  }
+
+  public stop() {
+    if (this.server) {
+      this.server.close();
+      this.clients.forEach((socket) => socket.destroy());
+      this.clients.clear();
+    }
+  }
+
+  public send(socketId: string, data: unknown) {
+    const socket = this.clients.get(socketId);
+    if (socket) {
+      const frame = this.encodeFrame(JSON.stringify(data));
+      socket.write(frame);
+    }
+  }
+
+  public broadcast(data: unknown, excludeId?: string) {
+    const frame = this.encodeFrame(JSON.stringify(data));
+    this.clients.forEach((socket, id) => {
+      if (id !== excludeId) {
+        socket.write(frame);
+      }
+    });
+  }
+
+  // --- Private Helpers ---
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private handleHandshake(socket: any, header: string) {
+    this.log("[WebSocket] Handshake request header:", JSON.stringify(header));
+    const keyMatch = header.match(/Sec-WebSocket-Key: (.+)/);
+    if (!keyMatch) {
+      console.error("[WebSocket] Handshake failed: No Sec-WebSocket-Key found");
+      socket.destroy();
+      return;
+    }
+
+    const key = keyMatch[1].trim();
+    this.log("[WebSocket] Client Key:", key);
+
+    try {
+      const acceptKey = this.generateAcceptKey(key);
+      this.log("[WebSocket] Generated Accept Key:", acceptKey);
+
+      const response = [
+        "HTTP/1.1 101 Switching Protocols",
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        `Sec-WebSocket-Accept: ${acceptKey}`,
+        "\r\n",
+      ].join("\r\n");
+
+      this.log(
+        "[WebSocket] Sending Handshake Response:",
+        JSON.stringify(response),
+      );
+      socket.write(response);
+
+      // Assign ID and store
+      socket.id = this.generateSocketId();
+      this.clients.set(socket.id, socket);
+      this.emit("connection", socket.id);
+    } catch (error) {
+      console.error("[WebSocket] Handshake error:", error);
+      socket.destroy();
+    }
+  }
+
+  private generateAcceptKey(key: string): string {
+    const input = key + GUID;
+    const hash = sha1(input);
+    this.log(`[WebSocket] SHA1 Input: ${input}`);
+    this.log(`[WebSocket] SHA1 Hash (hex): ${hash}`);
+    return Buffer.from(hash, "hex").toString("base64");
+  }
+
+  private decodeFrame(buffer: Buffer): DecodedFrame | null {
+    // Need at least 2 bytes for the header
+    if (buffer.length < 2) return null;
+
+    const firstByte = buffer[0];
+    const opcode = firstByte & 0x0f;
+
+    const secondByte = buffer[1];
+    const isMasked = (secondByte & 0x80) !== 0;
+    let payloadLength = secondByte & 0x7f;
+    let headerLength = 2;
+
+    if (payloadLength === 126) {
+      if (buffer.length < 4) return null; // Need 2 more bytes for extended length
+      payloadLength = buffer.readUInt16BE(2);
+      headerLength = 4;
+    } else if (payloadLength === 127) {
+      if (buffer.length < 10) return null; // Need 8 more bytes for extended length
+      // Read 64-bit length. For safety, only use the lower 32 bits.
+      const highBits = buffer.readUInt32BE(2);
+      if (highBits > 0) {
+        // Payload > 4GB -- reject
+        throw new Error("Frame payload too large");
+      }
+      payloadLength = buffer.readUInt32BE(6);
+      headerLength = 10;
+    }
+
+    const maskLength = isMasked ? 4 : 0;
+    const totalFrameLength = headerLength + maskLength + payloadLength;
+
+    // Check if we have the complete frame
+    if (buffer.length < totalFrameLength) return null;
+
+    let payload: Buffer;
+    if (isMasked) {
+      const mask = buffer.slice(headerLength, headerLength + 4);
+      const maskedPayload = buffer.slice(
+        headerLength + 4,
+        headerLength + 4 + payloadLength,
+      );
+      payload = Buffer.alloc(payloadLength);
+      for (let i = 0; i < payloadLength; i++) {
+        payload[i] = maskedPayload[i] ^ mask[i % 4];
+      }
+    } else {
+      payload = Buffer.from(
+        buffer.slice(headerLength, headerLength + payloadLength),
+      );
+    }
+
+    return { opcode, payload, bytesConsumed: totalFrameLength };
+  }
+
+  private encodeFrame(data: string): Buffer {
+    // Server -> Client frames are NOT masked (text frame)
+    return this.buildFrame(OPCODE.TEXT, Buffer.from(data));
+  }
+
+  private encodeControlFrame(opcode: number, payload: Buffer): Buffer {
+    return this.buildFrame(opcode, payload);
+  }
+
+  private buildFrame(opcode: number, payload: Buffer): Buffer {
+    let headerLength = 2;
+
+    if (payload.length > 65535) {
+      headerLength = 10; // 2 header + 8 length
+    } else if (payload.length > 125) {
+      headerLength = 4; // 2 header + 2 length
+    }
+
+    const frame = Buffer.alloc(headerLength + payload.length);
+    frame[0] = 0x80 | opcode; // FIN bit set + opcode
+
+    if (payload.length > 65535) {
+      frame[1] = 127;
+      // Write 64-bit integer (max safe integer in JS is 2^53, so high 32 bits are 0)
+      frame.writeUInt32BE(0, 2);
+      frame.writeUInt32BE(payload.length, 6);
+    } else if (payload.length > 125) {
+      frame[1] = 126;
+      frame.writeUInt16BE(payload.length, 2);
+    } else {
+      frame[1] = payload.length;
+    }
+
+    payload.copy(frame, headerLength);
+    return frame;
+  }
+}