@couch-kit/display 0.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @couch-kit/display

package/README.md

@@ -0,0 +1,93 @@
+# @couch-kit/display
+
+Browser **display host** for cross-network Couch Kit games. It owns the
+authoritative `GameHostRuntime` — exactly like the React Native
+`GameHostProvider` does on an Android TV — but bridges the runtime to a shared,
+game-agnostic [relay server](https://github.com/faluciano/react-native-couch-kit/tree/main/services/relay)
+instead of a local LAN WebSocket. That lets phones on **different networks** join
+a game hosted in a browser tab.
+
+```
+ phone ─┐                       ┌─ RelayDisplayHost (owns the runtime)
+ phone ─┼─ WebSocket ─▶ relay ◀─┘        browser display tab
+ phone ─┘             (you deploy it)
+```
+
+- The display owns the game; the relay only routes opaque envelopes by room code,
+  so **one relay deployment serves every game** you build.
+- Framework-agnostic (no React dependency): subscribe with `subscribe` /
+  `getState` from any UI, e.g. React's `useSyncExternalStore`.
+
+## Install
+
+```bash
+bun add @couch-kit/display @couch-kit/core @couch-kit/runtime @couch-kit/client
+```
+
+## Usage
+
+```ts
+import { RelayDisplayHost } from "@couch-kit/display";
+import { gameReducer, initialState } from "./shared"; // shared with the controller
+
+const display = new RelayDisplayHost({
+  url: "wss://your-relay.example.com", // YOUR relay — see note below
+  roomId: "ABCD",
+  reducer: gameReducer,
+  initialState,
+});
+
+// Render whenever authoritative state changes.
+display.subscribe(() => render(display.getState()));
+```
+
+Phones connect to the same room with the client's relay transport:
+
+```ts
+import { createRelayTransport } from "@couch-kit/client";
+
+useGameClient({
+  reducer: gameReducer,
+  initialState,
+  createTransport: createRelayTransport({
+    url: "wss://your-relay.example.com",
+    roomId: "ABCD",
+  }),
+});
+```
+
+## API
+
+`new RelayDisplayHost(options)` — `options` is the game's
+`GameHostRuntimeConfig` (`reducer`, `initialState`, and the usual runtime knobs)
+plus the relay coordinates:
+
+| Option      | Description                                    |
+| ----------- | ---------------------------------------------- |
+| `url`       | WebSocket URL of **your** relay server         |
+| `roomId`    | Room code phones use to reach this display     |
+| `reducer`   | The shared game reducer                        |
+| `initialState` | The shared initial state                    |
+
+Instance methods:
+
+- `getState()` — current authoritative state.
+- `subscribe(listener)` — subscribe to state changes; returns an unsubscribe fn.
+- `dispatch(action)` — dispatch a trusted host-side action.
+- `stop()` — tear down the runtime and close the relay socket.
+
+The host maps relay `PEER_JOINED` / `DATA` / `PEER_LEFT` to the runtime's
+`handleConnection` / `handleMessage` / `handleDisconnect`, and implements the
+runtime's transport by wrapping outbound messages in relay `DATA` envelopes
+(unicast when addressed, room broadcast otherwise). Inbound phone messages are
+size-bounded (`DEFAULT_MAX_MESSAGE_BYTES`) before parsing.
+
+## Deploy your own relay — the SDK never points at anyone else's
+
+The relay `url` is **required config with no default**. Couch Kit ships the relay
+as *source you deploy yourself*
+([`services/relay`](https://github.com/faluciano/react-native-couch-kit/tree/main/services/relay)),
+not a hosted service. Every game you build points at the relay **you** deploy;
+nobody consuming this SDK is routed through another developer's infrastructure.
+One relay deployment can serve all of your games — it is game-agnostic and keyed
+only by room code.

package/dist/index.js

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

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { RelayDisplayHost, type RelayDisplayHostOptions, } from "./relay-display-host";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAC"}

package/lib/relay-display-host.d.ts

@@ -0,0 +1,51 @@
+import { type GameHostRuntimeConfig } from "@couch-kit/runtime";
+import type { IGameState, IAction } from "@couch-kit/core";
+/**
+ * Options for {@link RelayDisplayHost}.
+ *
+ * The caller supplies the game's runtime config (reducer + initial state, same
+ * object used by the RN-TV host) and the shared relay coordinates; the display
+ * host owns the authoritative runtime and the relay socket.
+ */
+export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction> extends GameHostRuntimeConfig<S, A> {
+    /** WebSocket URL of the shared relay server. */
+    url: string;
+    /** Room code phones will use to reach this display. */
+    roomId: string;
+}
+/**
+ * Browser **display host** for the cross-network relay transport.
+ *
+ * It owns a {@link GameHostRuntime} (the authoritative game) exactly like the
+ * React Native `GameHostProvider` does, but bridges the runtime to a shared,
+ * game-agnostic relay instead of a local WebSocket server:
+ *
+ * - Connects to the relay and creates the room.
+ * - Maps relay `PEER_JOINED` / `DATA` / `PEER_LEFT` to
+ *   `runtime.handleConnection` / `handleMessage` / `handleDisconnect`, using the
+ *   relay-assigned `peerId` as the stable connection id.
+ * - Implements {@link GameRuntimeTransport} by wrapping outbound host messages in
+ *   relay `DATA` envelopes (`to` for unicast, absent for room broadcast).
+ *
+ * Framework-agnostic (no React): a display UI subscribes via {@link subscribe} /
+ * {@link getState} (e.g. React's `useSyncExternalStore`).
+ */
+export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
+    private readonly runtime;
+    private readonly ws;
+    private readonly roomId;
+    /** Connected phone connection ids (relay peer ids). */
+    private readonly peers;
+    constructor(options: RelayDisplayHostOptions<S, A>);
+    /** Current authoritative game state. */
+    getState: () => S;
+    /** Subscribe to state changes (for `useSyncExternalStore` or manual render). */
+    subscribe: (listener: () => void) => (() => void);
+    /** Dispatch a trusted host-display action. */
+    dispatch: (action: A) => void;
+    /** Tear down the runtime and relay socket. */
+    stop(): void;
+    private sendEnvelope;
+    private handleRelayMessage;
+}
+//# sourceMappingURL=relay-display-host.d.ts.map

package/lib/relay-display-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-display-host.d.ts","sourceRoot":"","sources":["../src/relay-display-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AAMxE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,CAC9E,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC;IAsClD,wCAAwC;IACxC,QAAQ,QAAO,CAAC,CAA4B;IAE5C,gFAAgF;IAChF,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CACb;IAEnC,8CAA8C;IAC9C,QAAQ,GAAI,QAAQ,CAAC,KAAG,IAAI,CAAkC;IAE9D,8CAA8C;IAC9C,IAAI,IAAI,IAAI;IAMZ,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,kBAAkB;CAqC3B"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@couch-kit/display",
+  "version": "0.0.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "Browser display host for cross-network Couch Kit games — owns the authoritative runtime and bridges it to a game-agnostic relay",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faluciano/react-native-couch-kit.git",
+    "directory": "packages/display"
+  },
+  "homepage": "https://github.com/faluciano/react-native-couch-kit#readme",
+  "keywords": [
+    "couch-kit",
+    "party-game",
+    "browser-display",
+    "relay",
+    "cross-network",
+    "websocket"
+  ],
+  "main": "./dist/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "lib",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target browser --external @couch-kit/core --external @couch-kit/runtime --external @couch-kit/client && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist lib"
+  },
+  "dependencies": {
+    "@couch-kit/client": "0.9.0",
+    "@couch-kit/core": "0.9.3",
+    "@couch-kit/runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export {
+  RelayDisplayHost,
+  type RelayDisplayHostOptions,
+} from "./relay-display-host";

package/src/relay-display-host.ts

@@ -0,0 +1,155 @@
+import {
+  GameHostRuntime,
+  frameByteLength,
+  DEFAULT_MAX_MESSAGE_BYTES,
+  type GameHostRuntimeConfig,
+  type GameRuntimeTransport,
+} from "@couch-kit/runtime";
+import type { IGameState, IAction, HostMessage } from "@couch-kit/core";
+import {
+  RelayMessageTypes,
+  type RelayServerMessage,
+} from "@couch-kit/client";
+
+/**
+ * Options for {@link RelayDisplayHost}.
+ *
+ * The caller supplies the game's runtime config (reducer + initial state, same
+ * object used by the RN-TV host) and the shared relay coordinates; the display
+ * host owns the authoritative runtime and the relay socket.
+ */
+export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction>
+  extends GameHostRuntimeConfig<S, A> {
+  /** WebSocket URL of the shared relay server. */
+  url: string;
+  /** Room code phones will use to reach this display. */
+  roomId: string;
+}
+
+/**
+ * Browser **display host** for the cross-network relay transport.
+ *
+ * It owns a {@link GameHostRuntime} (the authoritative game) exactly like the
+ * React Native `GameHostProvider` does, but bridges the runtime to a shared,
+ * game-agnostic relay instead of a local WebSocket server:
+ *
+ * - Connects to the relay and creates the room.
+ * - Maps relay `PEER_JOINED` / `DATA` / `PEER_LEFT` to
+ *   `runtime.handleConnection` / `handleMessage` / `handleDisconnect`, using the
+ *   relay-assigned `peerId` as the stable connection id.
+ * - Implements {@link GameRuntimeTransport} by wrapping outbound host messages in
+ *   relay `DATA` envelopes (`to` for unicast, absent for room broadcast).
+ *
+ * Framework-agnostic (no React): a display UI subscribes via {@link subscribe} /
+ * {@link getState} (e.g. React's `useSyncExternalStore`).
+ */
+export class RelayDisplayHost<S extends IGameState, A extends IAction> {
+  private readonly runtime: GameHostRuntime<S, A>;
+  private readonly ws: WebSocket;
+  private readonly roomId: string;
+  /** Connected phone connection ids (relay peer ids). */
+  private readonly peers = new Set<string>();
+
+  constructor(options: RelayDisplayHostOptions<S, A>) {
+    const { url, roomId, ...runtimeConfig } = options;
+    this.roomId = roomId;
+    this.runtime = new GameHostRuntime<S, A>(runtimeConfig);
+    this.ws = new WebSocket(url);
+
+    this.ws.onopen = () => {
+      this.ws.send(
+        JSON.stringify({
+          type: RelayMessageTypes.CREATE_ROOM,
+          roomId: this.roomId,
+        }),
+      );
+    };
+
+    this.ws.onmessage = (event: MessageEvent) => {
+      let msg: RelayServerMessage;
+      try {
+        msg = JSON.parse(event.data as string) as RelayServerMessage;
+      } catch {
+        return;
+      }
+      this.handleRelayMessage(msg);
+    };
+
+    this.ws.onerror = (event) =>
+      this.runtime.handleError(
+        event instanceof Error ? event : new Error("Relay socket error"),
+      );
+
+    const transport: GameRuntimeTransport = {
+      send: (connectionId, message) =>
+        this.sendEnvelope(message, connectionId),
+      broadcast: (message) => this.sendEnvelope(message),
+    };
+    this.runtime.setTransport(transport);
+  }
+
+  /** Current authoritative game state. */
+  getState = (): S => this.runtime.getState();
+
+  /** Subscribe to state changes (for `useSyncExternalStore` or manual render). */
+  subscribe = (listener: () => void): (() => void) =>
+    this.runtime.subscribe(listener);
+
+  /** Dispatch a trusted host-display action. */
+  dispatch = (action: A): void => this.runtime.dispatch(action);
+
+  /** Tear down the runtime and relay socket. */
+  stop(): void {
+    this.runtime.setTransport(null);
+    this.runtime.stop();
+    this.ws.close();
+  }
+
+  private sendEnvelope(message: HostMessage, to?: string): void {
+    const envelope: Record<string, unknown> = {
+      type: RelayMessageTypes.DATA,
+      roomId: this.roomId,
+      data: JSON.stringify(message),
+    };
+    if (to !== undefined) envelope.to = to;
+    this.ws.send(JSON.stringify(envelope));
+  }
+
+  private handleRelayMessage(msg: RelayServerMessage): void {
+    switch (msg.type) {
+      case RelayMessageTypes.PEER_JOINED:
+        this.peers.add(msg.peerId);
+        this.runtime.handleConnection(msg.peerId);
+        break;
+      case RelayMessageTypes.PEER_LEFT:
+        this.peers.delete(msg.peerId);
+        this.runtime.handleDisconnect(msg.peerId);
+        break;
+      case RelayMessageTypes.DATA: {
+        // A game message from a phone. `from` is the phone's connection id.
+        if (!msg.from) break;
+        // Enforce the same inbound bound as the WebSocket transport before
+        // parsing untrusted phone input.
+        if (frameByteLength(msg.data) > DEFAULT_MAX_MESSAGE_BYTES) break;
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(msg.data);
+        } catch {
+          break;
+        }
+        this.runtime
+          .handleMessage(msg.from, parsed)
+          .catch((err) =>
+            this.runtime.handleError(
+              err instanceof Error ? err : new Error(String(err)),
+            ),
+          );
+        break;
+      }
+      case RelayMessageTypes.ERROR:
+        this.runtime.handleError(new Error(msg.message));
+        break;
+      // ROOM_CREATED / ROOM_JOINED are acknowledgements; no action needed.
+    }
+  }
+}