@al8b/runtime-realtime 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# @al8b/runtime-realtime
+
+Realtime transport adapter for [@al8b/runtime](../runtime/README.md). Enables multiplayer and synchronization features through a pluggable realtime bridge.
+
+## Installation
+
+```bash
+npm install @al8b/runtime-realtime @al8b/runtime
+```
+
+## Usage
+
+Implement a `RealtimeBridge` for your chosen transport (WebSocket, WebRTC, etc.), then adapt it to the runtime:
+
+```ts
+import { createRealtimeBridge, type RealtimeBridge } from "@al8b/runtime-realtime";
+import { createRuntime } from "@al8b/runtime";
+
+// Your realtime transport implementation
+const myWebSocketBridge: RealtimeBridge = {
+  async connect() {
+    // Connect to websocket server
+  },
+  async disconnect() {
+    // Clean up websocket
+  },
+  send(channel, payload) {
+    // Send message on channel
+  },
+  subscribe(channel, handler) {
+    // Listen for messages on channel
+    return () => {
+      // Unsubscribe
+    };
+  },
+};
+
+// Adapt it to the runtime
+const bridge = {
+  ...createRealtimeBridge(myWebSocketBridge),
+  // Optionally add other bridge capabilities
+  getSession: () => getSessionFromServer(),
+  saveSnapshot: (snap) => cloudSave(snap),
+};
+
+// Create runtime with realtime bridge
+const runtime = createRuntime({
+  sources: { /* ... */ },
+  resources: { /* ... */ },
+  bridge,
+});
+
+await runtime.start();
+```
+
+## API
+
+### `createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge`
+
+Adapts a `RealtimeBridge` to a `RuntimeBridge`.
+
+**Event Channels:**
+
+The adapter subscribes to these channels:
+- `"host.event"` - Incoming host events (mapped to HostEvent)
+- `"player.message"` - Direct player-to-host messages
+
+Game emissions are sent on:
+- `"runtime.emit"` - Game-side events (name + payload)
+
+**Composition:**
+
+The returned `RuntimeBridge` only implements `emit` and `subscribe`. To add other capabilities:
+
+```ts
+const bridge = {
+  ...createRealtimeBridge(realtime),
+  request: async (name, payload) => { /* ... */ },
+  getSession: () => { /* ... */ },
+  saveSnapshot: async (snap) => { /* ... */ },
+  loadSnapshot: async (meta) => { /* ... */ },
+};
+```
+
+### `RealtimeBridge`
+
+Interface for a realtime transport:
+
+```ts
+export interface RealtimeBridge {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  send(channel: string, payload: unknown): void;
+  subscribe(channel: string, handler: (payload: unknown) => void): () => void;
+}
+```
+
+## Example: WebSocket Transport
+
+```ts
+import { createRealtimeBridge } from "@al8b/runtime-realtime";
+import type { RealtimeBridge } from "@al8b/runtime-realtime";
+
+class WebSocketRealtimeBridge implements RealtimeBridge {
+  private ws: WebSocket | null = null;
+  private subscriptions = new Map<string, Set<(payload: unknown) => void>>();
+
+  async connect() {
+    return new Promise<void>((resolve, reject) => {
+      this.ws = new WebSocket("wss://realtime.example.com");
+      this.ws.onopen = () => resolve();
+      this.ws.onerror = () => reject(new Error("WebSocket connection failed"));
+      this.ws.onmessage = (event) => {
+        const message = JSON.parse(event.data);
+        const handlers = this.subscriptions.get(message.channel);
+        handlers?.forEach((h) => h(message.payload));
+      };
+    });
+  }
+
+  async disconnect() {
+    this.ws?.close();
+  }
+
+  send(channel: string, payload: unknown) {
+    this.ws?.send(JSON.stringify({ channel, payload }));
+  }
+
+  subscribe(channel: string, handler: (payload: unknown) => void) {
+    if (!this.subscriptions.has(channel)) {
+      this.subscriptions.set(channel, new Set());
+    }
+    this.subscriptions.get(channel)!.add(handler);
+    return () => {
+      this.subscriptions.get(channel)?.delete(handler);
+    };
+  }
+}
+
+const bridge = createRealtimeBridge(new WebSocketRealtimeBridge());
+```
+
+## Multiplayer Patterns
+
+Once integrated, games can emit realtime events:
+
+```loot
+// In LootiScript
+host.emit("player.move", { x: 100, y: 50 })
+host.emit("player.action", { action: "jump" })
+```
+
+The realtime bridge forwards these to the backend, which can synchronize across players.
+
+## Notes
+
+- The adapter is transport-agnostic; implement `RealtimeBridge` for your chosen protocol
+- Channel names are conventions between your game and backend; adjust as needed
+- Reliability, ordering, and backpressure handling are transport responsibilities
+- Games should not assume synchronous delivery; use async request/response patterns for critical data
+
+## Scripts
+
+```bash
+bun run build  # Build the package
+bun run test   # Run tests
+bun run clean  # Clean build artifacts
+```

package/dist/createRealtimeBridge.d.mts

@@ -0,0 +1,27 @@
+import { RealtimeBridge } from './types.mjs';
+import { RuntimeBridge } from '@al8b/runtime';
+
+/**
+ * Create a RuntimeBridge adapter from a RealtimeBridge.
+ *
+ * This adapter maps realtime transport channels to RuntimeBridge events.
+ * Incoming messages on the `"host.event"` channel are delivered as HostEvent.
+ * Outgoing `bridge.emit` calls are sent on the `"runtime.emit"` channel.
+ *
+ * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,
+ * or `loadSnapshot`. Compose those capabilities separately:
+ *
+ * ```ts
+ * const bridge = {
+ *   ...createRealtimeBridge(realtime),
+ *   getSession: () => fetchSession(userId),
+ *   saveSnapshot: (snap) => cloudSave(userId, snap),
+ * };
+ * ```
+ *
+ * @param realtime - The realtime transport bridge
+ * @returns A RuntimeBridge that integrates with the realtime transport
+ */
+declare function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge;
+
+export { createRealtimeBridge };

package/dist/createRealtimeBridge.d.ts

@@ -0,0 +1,27 @@
+import { RealtimeBridge } from './types.js';
+import { RuntimeBridge } from '@al8b/runtime';
+
+/**
+ * Create a RuntimeBridge adapter from a RealtimeBridge.
+ *
+ * This adapter maps realtime transport channels to RuntimeBridge events.
+ * Incoming messages on the `"host.event"` channel are delivered as HostEvent.
+ * Outgoing `bridge.emit` calls are sent on the `"runtime.emit"` channel.
+ *
+ * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,
+ * or `loadSnapshot`. Compose those capabilities separately:
+ *
+ * ```ts
+ * const bridge = {
+ *   ...createRealtimeBridge(realtime),
+ *   getSession: () => fetchSession(userId),
+ *   saveSnapshot: (snap) => cloudSave(userId, snap),
+ * };
+ * ```
+ *
+ * @param realtime - The realtime transport bridge
+ * @returns A RuntimeBridge that integrates with the realtime transport
+ */
+declare function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge;
+
+export { createRealtimeBridge };

package/dist/createRealtimeBridge.js

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/createRealtimeBridge.ts
+var createRealtimeBridge_exports = {};
+__export(createRealtimeBridge_exports, {
+  createRealtimeBridge: () => createRealtimeBridge
+});
+module.exports = __toCommonJS(createRealtimeBridge_exports);
+function createRealtimeBridge(realtime) {
+  const isHostEvent = /* @__PURE__ */ __name((payload) => {
+    return payload !== null && typeof payload === "object" && "type" in payload && typeof payload.type === "string";
+  }, "isHostEvent");
+  const subscribe = /* @__PURE__ */ __name((handler) => {
+    const unsub1 = realtime.subscribe("host.event", (payload) => {
+      if (isHostEvent(payload)) {
+        handler({
+          ...payload,
+          source: payload.source ?? "realtime"
+        });
+      }
+    });
+    const unsub2 = realtime.subscribe("player.message", (payload) => {
+      handler({
+        type: "player.message",
+        payload,
+        source: "realtime"
+      });
+    });
+    return () => {
+      unsub1();
+      unsub2();
+    };
+  }, "subscribe");
+  const emit = /* @__PURE__ */ __name((name, payload) => {
+    realtime.send("runtime.emit", {
+      name,
+      payload
+    });
+  }, "emit");
+  return {
+    emit,
+    subscribe
+  };
+}
+__name(createRealtimeBridge, "createRealtimeBridge");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRealtimeBridge
+});
+//# sourceMappingURL=createRealtimeBridge.js.map

package/dist/createRealtimeBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createRealtimeBridge.ts"],"sourcesContent":["import type { RuntimeBridge, HostEvent } from \"@al8b/runtime\";\nimport type { RealtimeBridge } from \"./types\";\n\n/**\n * Create a RuntimeBridge adapter from a RealtimeBridge.\n *\n * This adapter maps realtime transport channels to RuntimeBridge events.\n * Incoming messages on the `\"host.event\"` channel are delivered as HostEvent.\n * Outgoing `bridge.emit` calls are sent on the `\"runtime.emit\"` channel.\n *\n * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,\n * or `loadSnapshot`. Compose those capabilities separately:\n *\n * ```ts\n * const bridge = {\n *   ...createRealtimeBridge(realtime),\n *   getSession: () => fetchSession(userId),\n *   saveSnapshot: (snap) => cloudSave(userId, snap),\n * };\n * ```\n *\n * @param realtime - The realtime transport bridge\n * @returns A RuntimeBridge that integrates with the realtime transport\n */\nexport function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge {\n\tconst isHostEvent = (payload: unknown): payload is HostEvent => {\n\t\treturn (\n\t\t\tpayload !== null &&\n\t\t\ttypeof payload === \"object\" &&\n\t\t\t\"type\" in payload &&\n\t\t\ttypeof (payload as any).type === \"string\"\n\t\t);\n\t};\n\n\tconst subscribe: RuntimeBridge[\"subscribe\"] = (handler) => {\n\t\t// Subscribe to incoming host events from realtime\n\t\tconst unsub1 = realtime.subscribe(\"host.event\", (payload) => {\n\t\t\tif (isHostEvent(payload)) {\n\t\t\t\thandler({\n\t\t\t\t\t...payload,\n\t\t\t\t\tsource: (payload.source ?? \"realtime\") as \"host\" | \"backend\" | \"realtime\",\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\t\t// Also subscribe to player messages for direct game-to-host communication\n\t\tconst unsub2 = realtime.subscribe(\"player.message\", (payload) => {\n\t\t\thandler({\n\t\t\t\ttype: \"player.message\",\n\t\t\t\tpayload,\n\t\t\t\tsource: \"realtime\",\n\t\t\t});\n\t\t});\n\n\t\treturn () => {\n\t\t\tunsub1();\n\t\t\tunsub2();\n\t\t};\n\t};\n\n\tconst emit: RuntimeBridge[\"emit\"] = (name, payload) => {\n\t\t// Forward game emissions back to the realtime transport\n\t\trealtime.send(\"runtime.emit\", { name, payload });\n\t};\n\n\treturn {\n\t\temit,\n\t\tsubscribe,\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAGA;;;;;AAqBO,SAASA,qBAAqBC,UAAwB;AAC5D,QAAMC,cAAc,wBAACC,YAAAA;AACpB,WACCA,YAAY,QACZ,OAAOA,YAAY,YACnB,UAAUA,WACV,OAAQA,QAAgBC,SAAS;EAEnC,GAPoB;AASpB,QAAMC,YAAwC,wBAACC,YAAAA;AAE9C,UAAMC,SAASN,SAASI,UAAU,cAAc,CAACF,YAAAA;AAChD,UAAID,YAAYC,OAAAA,GAAU;AACzBG,gBAAQ;UACP,GAAGH;UACHK,QAASL,QAAQK,UAAU;QAC5B,CAAA;MACD;IACD,CAAA;AAGA,UAAMC,SAASR,SAASI,UAAU,kBAAkB,CAACF,YAAAA;AACpDG,cAAQ;QACPF,MAAM;QACND;QACAK,QAAQ;MACT,CAAA;IACD,CAAA;AAEA,WAAO,MAAA;AACND,aAAAA;AACAE,aAAAA;IACD;EACD,GAxB8C;AA0B9C,QAAMC,OAA8B,wBAACC,MAAMR,YAAAA;AAE1CF,aAASW,KAAK,gBAAgB;MAAED;MAAMR;IAAQ,CAAA;EAC/C,GAHoC;AAKpC,SAAO;IACNO;IACAL;EACD;AACD;AA7CgBL;","names":["createRealtimeBridge","realtime","isHostEvent","payload","type","subscribe","handler","unsub1","source","unsub2","emit","name","send"]}

package/dist/createRealtimeBridge.mjs

@@ -0,0 +1,45 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/createRealtimeBridge.ts
+function createRealtimeBridge(realtime) {
+  const isHostEvent = /* @__PURE__ */ __name((payload) => {
+    return payload !== null && typeof payload === "object" && "type" in payload && typeof payload.type === "string";
+  }, "isHostEvent");
+  const subscribe = /* @__PURE__ */ __name((handler) => {
+    const unsub1 = realtime.subscribe("host.event", (payload) => {
+      if (isHostEvent(payload)) {
+        handler({
+          ...payload,
+          source: payload.source ?? "realtime"
+        });
+      }
+    });
+    const unsub2 = realtime.subscribe("player.message", (payload) => {
+      handler({
+        type: "player.message",
+        payload,
+        source: "realtime"
+      });
+    });
+    return () => {
+      unsub1();
+      unsub2();
+    };
+  }, "subscribe");
+  const emit = /* @__PURE__ */ __name((name, payload) => {
+    realtime.send("runtime.emit", {
+      name,
+      payload
+    });
+  }, "emit");
+  return {
+    emit,
+    subscribe
+  };
+}
+__name(createRealtimeBridge, "createRealtimeBridge");
+export {
+  createRealtimeBridge
+};
+//# sourceMappingURL=createRealtimeBridge.mjs.map

package/dist/createRealtimeBridge.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createRealtimeBridge.ts"],"sourcesContent":["import type { RuntimeBridge, HostEvent } from \"@al8b/runtime\";\nimport type { RealtimeBridge } from \"./types\";\n\n/**\n * Create a RuntimeBridge adapter from a RealtimeBridge.\n *\n * This adapter maps realtime transport channels to RuntimeBridge events.\n * Incoming messages on the `\"host.event\"` channel are delivered as HostEvent.\n * Outgoing `bridge.emit` calls are sent on the `\"runtime.emit\"` channel.\n *\n * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,\n * or `loadSnapshot`. Compose those capabilities separately:\n *\n * ```ts\n * const bridge = {\n *   ...createRealtimeBridge(realtime),\n *   getSession: () => fetchSession(userId),\n *   saveSnapshot: (snap) => cloudSave(userId, snap),\n * };\n * ```\n *\n * @param realtime - The realtime transport bridge\n * @returns A RuntimeBridge that integrates with the realtime transport\n */\nexport function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge {\n\tconst isHostEvent = (payload: unknown): payload is HostEvent => {\n\t\treturn (\n\t\t\tpayload !== null &&\n\t\t\ttypeof payload === \"object\" &&\n\t\t\t\"type\" in payload &&\n\t\t\ttypeof (payload as any).type === \"string\"\n\t\t);\n\t};\n\n\tconst subscribe: RuntimeBridge[\"subscribe\"] = (handler) => {\n\t\t// Subscribe to incoming host events from realtime\n\t\tconst unsub1 = realtime.subscribe(\"host.event\", (payload) => {\n\t\t\tif (isHostEvent(payload)) {\n\t\t\t\thandler({\n\t\t\t\t\t...payload,\n\t\t\t\t\tsource: (payload.source ?? \"realtime\") as \"host\" | \"backend\" | \"realtime\",\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\t\t// Also subscribe to player messages for direct game-to-host communication\n\t\tconst unsub2 = realtime.subscribe(\"player.message\", (payload) => {\n\t\t\thandler({\n\t\t\t\ttype: \"player.message\",\n\t\t\t\tpayload,\n\t\t\t\tsource: \"realtime\",\n\t\t\t});\n\t\t});\n\n\t\treturn () => {\n\t\t\tunsub1();\n\t\t\tunsub2();\n\t\t};\n\t};\n\n\tconst emit: RuntimeBridge[\"emit\"] = (name, payload) => {\n\t\t// Forward game emissions back to the realtime transport\n\t\trealtime.send(\"runtime.emit\", { name, payload });\n\t};\n\n\treturn {\n\t\temit,\n\t\tsubscribe,\n\t};\n}\n"],"mappings":";;;;AAwBO,SAASA,qBAAqBC,UAAwB;AAC5D,QAAMC,cAAc,wBAACC,YAAAA;AACpB,WACCA,YAAY,QACZ,OAAOA,YAAY,YACnB,UAAUA,WACV,OAAQA,QAAgBC,SAAS;EAEnC,GAPoB;AASpB,QAAMC,YAAwC,wBAACC,YAAAA;AAE9C,UAAMC,SAASN,SAASI,UAAU,cAAc,CAACF,YAAAA;AAChD,UAAID,YAAYC,OAAAA,GAAU;AACzBG,gBAAQ;UACP,GAAGH;UACHK,QAASL,QAAQK,UAAU;QAC5B,CAAA;MACD;IACD,CAAA;AAGA,UAAMC,SAASR,SAASI,UAAU,kBAAkB,CAACF,YAAAA;AACpDG,cAAQ;QACPF,MAAM;QACND;QACAK,QAAQ;MACT,CAAA;IACD,CAAA;AAEA,WAAO,MAAA;AACND,aAAAA;AACAE,aAAAA;IACD;EACD,GAxB8C;AA0B9C,QAAMC,OAA8B,wBAACC,MAAMR,YAAAA;AAE1CF,aAASW,KAAK,gBAAgB;MAAED;MAAMR;IAAQ,CAAA;EAC/C,GAHoC;AAKpC,SAAO;IACNO;IACAL;EACD;AACD;AA7CgBL;","names":["createRealtimeBridge","realtime","isHostEvent","payload","type","subscribe","handler","unsub1","source","unsub2","emit","name","send"]}

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export { RealtimeBridge } from './types.mjs';
+export { createRealtimeBridge } from './createRealtimeBridge.mjs';
+import '@al8b/runtime';

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RealtimeBridge } from './types.js';
+export { createRealtimeBridge } from './createRealtimeBridge.js';
+import '@al8b/runtime';

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRealtimeBridge: () => createRealtimeBridge
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/createRealtimeBridge.ts
+function createRealtimeBridge(realtime) {
+  const isHostEvent = /* @__PURE__ */ __name((payload) => {
+    return payload !== null && typeof payload === "object" && "type" in payload && typeof payload.type === "string";
+  }, "isHostEvent");
+  const subscribe = /* @__PURE__ */ __name((handler) => {
+    const unsub1 = realtime.subscribe("host.event", (payload) => {
+      if (isHostEvent(payload)) {
+        handler({
+          ...payload,
+          source: payload.source ?? "realtime"
+        });
+      }
+    });
+    const unsub2 = realtime.subscribe("player.message", (payload) => {
+      handler({
+        type: "player.message",
+        payload,
+        source: "realtime"
+      });
+    });
+    return () => {
+      unsub1();
+      unsub2();
+    };
+  }, "subscribe");
+  const emit = /* @__PURE__ */ __name((name, payload) => {
+    realtime.send("runtime.emit", {
+      name,
+      payload
+    });
+  }, "emit");
+  return {
+    emit,
+    subscribe
+  };
+}
+__name(createRealtimeBridge, "createRealtimeBridge");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRealtimeBridge
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/createRealtimeBridge.ts"],"sourcesContent":["export type { RealtimeBridge } from \"./types\";\nexport { createRealtimeBridge } from \"./createRealtimeBridge\";\n","import type { RuntimeBridge, HostEvent } from \"@al8b/runtime\";\nimport type { RealtimeBridge } from \"./types\";\n\n/**\n * Create a RuntimeBridge adapter from a RealtimeBridge.\n *\n * This adapter maps realtime transport channels to RuntimeBridge events.\n * Incoming messages on the `\"host.event\"` channel are delivered as HostEvent.\n * Outgoing `bridge.emit` calls are sent on the `\"runtime.emit\"` channel.\n *\n * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,\n * or `loadSnapshot`. Compose those capabilities separately:\n *\n * ```ts\n * const bridge = {\n *   ...createRealtimeBridge(realtime),\n *   getSession: () => fetchSession(userId),\n *   saveSnapshot: (snap) => cloudSave(userId, snap),\n * };\n * ```\n *\n * @param realtime - The realtime transport bridge\n * @returns A RuntimeBridge that integrates with the realtime transport\n */\nexport function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge {\n\tconst isHostEvent = (payload: unknown): payload is HostEvent => {\n\t\treturn (\n\t\t\tpayload !== null &&\n\t\t\ttypeof payload === \"object\" &&\n\t\t\t\"type\" in payload &&\n\t\t\ttypeof (payload as any).type === \"string\"\n\t\t);\n\t};\n\n\tconst subscribe: RuntimeBridge[\"subscribe\"] = (handler) => {\n\t\t// Subscribe to incoming host events from realtime\n\t\tconst unsub1 = realtime.subscribe(\"host.event\", (payload) => {\n\t\t\tif (isHostEvent(payload)) {\n\t\t\t\thandler({\n\t\t\t\t\t...payload,\n\t\t\t\t\tsource: (payload.source ?? \"realtime\") as \"host\" | \"backend\" | \"realtime\",\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\t\t// Also subscribe to player messages for direct game-to-host communication\n\t\tconst unsub2 = realtime.subscribe(\"player.message\", (payload) => {\n\t\t\thandler({\n\t\t\t\ttype: \"player.message\",\n\t\t\t\tpayload,\n\t\t\t\tsource: \"realtime\",\n\t\t\t});\n\t\t});\n\n\t\treturn () => {\n\t\t\tunsub1();\n\t\t\tunsub2();\n\t\t};\n\t};\n\n\tconst emit: RuntimeBridge[\"emit\"] = (name, payload) => {\n\t\t// Forward game emissions back to the realtime transport\n\t\trealtime.send(\"runtime.emit\", { name, payload });\n\t};\n\n\treturn {\n\t\temit,\n\t\tsubscribe,\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AACA;;;;;;;ACuBO,SAASA,qBAAqBC,UAAwB;AAC5D,QAAMC,cAAc,wBAACC,YAAAA;AACpB,WACCA,YAAY,QACZ,OAAOA,YAAY,YACnB,UAAUA,WACV,OAAQA,QAAgBC,SAAS;EAEnC,GAPoB;AASpB,QAAMC,YAAwC,wBAACC,YAAAA;AAE9C,UAAMC,SAASN,SAASI,UAAU,cAAc,CAACF,YAAAA;AAChD,UAAID,YAAYC,OAAAA,GAAU;AACzBG,gBAAQ;UACP,GAAGH;UACHK,QAASL,QAAQK,UAAU;QAC5B,CAAA;MACD;IACD,CAAA;AAGA,UAAMC,SAASR,SAASI,UAAU,kBAAkB,CAACF,YAAAA;AACpDG,cAAQ;QACPF,MAAM;QACND;QACAK,QAAQ;MACT,CAAA;IACD,CAAA;AAEA,WAAO,MAAA;AACND,aAAAA;AACAE,aAAAA;IACD;EACD,GAxB8C;AA0B9C,QAAMC,OAA8B,wBAACC,MAAMR,YAAAA;AAE1CF,aAASW,KAAK,gBAAgB;MAAED;MAAMR;IAAQ,CAAA;EAC/C,GAHoC;AAKpC,SAAO;IACNO;IACAL;EACD;AACD;AA7CgBL;","names":["createRealtimeBridge","realtime","isHostEvent","payload","type","subscribe","handler","unsub1","source","unsub2","emit","name","send"]}

package/dist/index.mjs

@@ -0,0 +1,45 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/createRealtimeBridge.ts
+function createRealtimeBridge(realtime) {
+  const isHostEvent = /* @__PURE__ */ __name((payload) => {
+    return payload !== null && typeof payload === "object" && "type" in payload && typeof payload.type === "string";
+  }, "isHostEvent");
+  const subscribe = /* @__PURE__ */ __name((handler) => {
+    const unsub1 = realtime.subscribe("host.event", (payload) => {
+      if (isHostEvent(payload)) {
+        handler({
+          ...payload,
+          source: payload.source ?? "realtime"
+        });
+      }
+    });
+    const unsub2 = realtime.subscribe("player.message", (payload) => {
+      handler({
+        type: "player.message",
+        payload,
+        source: "realtime"
+      });
+    });
+    return () => {
+      unsub1();
+      unsub2();
+    };
+  }, "subscribe");
+  const emit = /* @__PURE__ */ __name((name, payload) => {
+    realtime.send("runtime.emit", {
+      name,
+      payload
+    });
+  }, "emit");
+  return {
+    emit,
+    subscribe
+  };
+}
+__name(createRealtimeBridge, "createRealtimeBridge");
+export {
+  createRealtimeBridge
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createRealtimeBridge.ts"],"sourcesContent":["import type { RuntimeBridge, HostEvent } from \"@al8b/runtime\";\nimport type { RealtimeBridge } from \"./types\";\n\n/**\n * Create a RuntimeBridge adapter from a RealtimeBridge.\n *\n * This adapter maps realtime transport channels to RuntimeBridge events.\n * Incoming messages on the `\"host.event\"` channel are delivered as HostEvent.\n * Outgoing `bridge.emit` calls are sent on the `\"runtime.emit\"` channel.\n *\n * Note: This adapter does not implement `request`, `getSession`, `saveSnapshot`,\n * or `loadSnapshot`. Compose those capabilities separately:\n *\n * ```ts\n * const bridge = {\n *   ...createRealtimeBridge(realtime),\n *   getSession: () => fetchSession(userId),\n *   saveSnapshot: (snap) => cloudSave(userId, snap),\n * };\n * ```\n *\n * @param realtime - The realtime transport bridge\n * @returns A RuntimeBridge that integrates with the realtime transport\n */\nexport function createRealtimeBridge(realtime: RealtimeBridge): RuntimeBridge {\n\tconst isHostEvent = (payload: unknown): payload is HostEvent => {\n\t\treturn (\n\t\t\tpayload !== null &&\n\t\t\ttypeof payload === \"object\" &&\n\t\t\t\"type\" in payload &&\n\t\t\ttypeof (payload as any).type === \"string\"\n\t\t);\n\t};\n\n\tconst subscribe: RuntimeBridge[\"subscribe\"] = (handler) => {\n\t\t// Subscribe to incoming host events from realtime\n\t\tconst unsub1 = realtime.subscribe(\"host.event\", (payload) => {\n\t\t\tif (isHostEvent(payload)) {\n\t\t\t\thandler({\n\t\t\t\t\t...payload,\n\t\t\t\t\tsource: (payload.source ?? \"realtime\") as \"host\" | \"backend\" | \"realtime\",\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\t\t// Also subscribe to player messages for direct game-to-host communication\n\t\tconst unsub2 = realtime.subscribe(\"player.message\", (payload) => {\n\t\t\thandler({\n\t\t\t\ttype: \"player.message\",\n\t\t\t\tpayload,\n\t\t\t\tsource: \"realtime\",\n\t\t\t});\n\t\t});\n\n\t\treturn () => {\n\t\t\tunsub1();\n\t\t\tunsub2();\n\t\t};\n\t};\n\n\tconst emit: RuntimeBridge[\"emit\"] = (name, payload) => {\n\t\t// Forward game emissions back to the realtime transport\n\t\trealtime.send(\"runtime.emit\", { name, payload });\n\t};\n\n\treturn {\n\t\temit,\n\t\tsubscribe,\n\t};\n}\n"],"mappings":";;;;AAwBO,SAASA,qBAAqBC,UAAwB;AAC5D,QAAMC,cAAc,wBAACC,YAAAA;AACpB,WACCA,YAAY,QACZ,OAAOA,YAAY,YACnB,UAAUA,WACV,OAAQA,QAAgBC,SAAS;EAEnC,GAPoB;AASpB,QAAMC,YAAwC,wBAACC,YAAAA;AAE9C,UAAMC,SAASN,SAASI,UAAU,cAAc,CAACF,YAAAA;AAChD,UAAID,YAAYC,OAAAA,GAAU;AACzBG,gBAAQ;UACP,GAAGH;UACHK,QAASL,QAAQK,UAAU;QAC5B,CAAA;MACD;IACD,CAAA;AAGA,UAAMC,SAASR,SAASI,UAAU,kBAAkB,CAACF,YAAAA;AACpDG,cAAQ;QACPF,MAAM;QACND;QACAK,QAAQ;MACT,CAAA;IACD,CAAA;AAEA,WAAO,MAAA;AACND,aAAAA;AACAE,aAAAA;IACD;EACD,GAxB8C;AA0B9C,QAAMC,OAA8B,wBAACC,MAAMR,YAAAA;AAE1CF,aAASW,KAAK,gBAAgB;MAAED;MAAMR;IAAQ,CAAA;EAC/C,GAHoC;AAKpC,SAAO;IACNO;IACAL;EACD;AACD;AA7CgBL;","names":["createRealtimeBridge","realtime","isHostEvent","payload","type","subscribe","handler","unsub1","source","unsub2","emit","name","send"]}

package/dist/types.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Realtime transport bridge for multiplayer and synchronization features.
+ *
+ * This interface abstracts over specific realtime transports (WebSocket, WebRTC, etc.)
+ * and can be adapted into a RuntimeBridge for host-side communication.
+ */
+interface RealtimeBridge {
+    /**
+     * Connect to the realtime service.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the realtime service.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message on a channel.
+     * @param channel - Channel name
+     * @param payload - Message payload
+     */
+    send(channel: string, payload: unknown): void;
+    /**
+     * Subscribe to a channel.
+     * @param channel - Channel name
+     * @param handler - Called when a message arrives on the channel
+     * @returns Unsubscribe function
+     */
+    subscribe(channel: string, handler: (payload: unknown) => void): () => void;
+}
+
+export type { RealtimeBridge };

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Realtime transport bridge for multiplayer and synchronization features.
+ *
+ * This interface abstracts over specific realtime transports (WebSocket, WebRTC, etc.)
+ * and can be adapted into a RuntimeBridge for host-side communication.
+ */
+interface RealtimeBridge {
+    /**
+     * Connect to the realtime service.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the realtime service.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message on a channel.
+     * @param channel - Channel name
+     * @param payload - Message payload
+     */
+    send(channel: string, payload: unknown): void;
+    /**
+     * Subscribe to a channel.
+     * @param channel - Channel name
+     * @param handler - Called when a message arrives on the channel
+     * @returns Unsubscribe function
+     */
+    subscribe(channel: string, handler: (payload: unknown) => void): () => void;
+}
+
+export type { RealtimeBridge };

package/dist/types.js

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Realtime transport bridge for multiplayer and synchronization features.\n *\n * This interface abstracts over specific realtime transports (WebSocket, WebRTC, etc.)\n * and can be adapted into a RuntimeBridge for host-side communication.\n */\nexport interface RealtimeBridge {\n\t/**\n\t * Connect to the realtime service.\n\t */\n\tconnect(): Promise<void>;\n\n\t/**\n\t * Disconnect from the realtime service.\n\t */\n\tdisconnect(): Promise<void>;\n\n\t/**\n\t * Send a message on a channel.\n\t * @param channel - Channel name\n\t * @param payload - Message payload\n\t */\n\tsend(channel: string, payload: unknown): void;\n\n\t/**\n\t * Subscribe to a channel.\n\t * @param channel - Channel name\n\t * @param handler - Called when a message arrives on the channel\n\t * @returns Unsubscribe function\n\t */\n\tsubscribe(channel: string, handler: (payload: unknown) => void): () => void;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;;","names":[]}

package/dist/types.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@al8b/runtime-realtime",
+	"version": "0.1.0",
+	"sideEffects": false,
+	"files": [
+		"dist/**/*",
+		"README.md",
+		"package.json"
+	],
+	"scripts": {
+		"build": "tsup",
+		"clean": "bun --bun ../../../scripts/clean-package.mjs dist",
+		"test": "vitest run --passWithNoTests"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@al8b/runtime": "workspace:*"
+	},
+	"devDependencies": {
+		"typescript": "~5.9.3"
+	},
+	"keywords": [
+		"runtime",
+		"realtime",
+		"multiplayer",
+		"websocket"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}