twd-relay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BRIKEV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# twd-relay
+
+WebSocket relay for [TWD](https://github.com/nicolo-ribaudo/twd-js) — lets AI agents and external tools trigger and observe in-browser test runs.
+
+Your app runs tests in the browser with twd-js. twd-relay adds a relay server and a browser client so that a **client** (script, CI, or AI agent) can send a “run” command over WebSocket; the relay forwards it to the browser, and test events are streamed back. No Vite or specific framework required: the relay can run standalone and work with any app that loads the browser client.
+
+---
+
+## Architecture
+
+- **Relay server** — WebSocket server that accepts one browser connection and many client connections. Clients send commands (`run`, `status`); the relay forwards them to the browser. The browser runs tests and streams events back; the relay broadcasts those to all clients. A lock prevents concurrent runs.
+
+- **Browser client** (`twd-relay/browser`) — Runs in your app. Connects to the relay, listens for commands, uses `twd-js/runner` to execute tests, and streams results back. Logs connection state in the console (e.g. `[twd-relay] Connected to relay`).
+
+- **Vite plugin** (`twd-relay/vite`) — Optional. Attaches the relay to your Vite dev server so the WebSocket is on the same origin. Also available: a **standalone CLI** that runs the relay on its own HTTP server (default port 9876).
+
+### Protocol (summary)
+
+1. Browser connects → sends `{ type: 'hello', role: 'browser' }`
+2. Client connects → sends `{ type: 'hello', role: 'client' }`
+3. Client sends `{ type: 'run', scope: 'all' }` → relay forwards to browser
+4. Browser runs tests and streams events → relay broadcasts to clients
+5. `run:complete` clears the run lock (and the send-run script exits)
+
+---
+
+## Installation
+
+```bash
+npm install twd-relay
+```
+
+Peer dependency: **twd-js** (>=1.4.0). Your app must use twd-js for tests; the browser client imports `twd-js/runner` at runtime.
+
+---
+
+## Quick start (standalone relay)
+
+Works with any framework. Run the relay on one port and your app on another.
+
+**1. Start the relay** (from this repo, or use the CLI in your project):
+
+```bash
+npm run relay
+# or: npx twd-relay
+# Listens on ws://localhost:9876/__twd/ws (use --port to change)
+```
+
+**2. In your app**, connect the browser client and call `connect()`:
+
+```js
+import { createBrowserClient } from 'twd-relay/browser';
+
+const client = createBrowserClient({
+  url: 'ws://localhost:9876/__twd/ws',
+});
+client.connect();
+```
+
+**3. Open your app in a browser** — the page connects to the relay as “browser”.
+
+**4. Trigger a run** — something must connect as a **client** and send `run`:
+
+- From this repo: `npm run send-run` (or `node scripts/send-run.js [--port 9876]`). The script exits when it receives `run:complete`.
+- From another project (if `ws` is available, e.g. via twd-relay): use the one-liner below.
+
+### One-liner to trigger a run
+
+Run from a directory where `ws` is installed (e.g. project with twd-relay):
+
+```bash
+node -e 'const Ws=require("ws");const w=new Ws("ws://localhost:9876/__twd/ws");let s=false;w.on("open",()=>w.send(JSON.stringify({type:"hello",role:"client"})));w.on("message",d=>{const m=JSON.parse(d);console.log(m.type,m);if(m.type==="connected"&&m.browser&&!s){s=true;w.send(JSON.stringify({type:"run",scope:"all"}));}if(m.type==="run:complete"){w.close();}});w.on("close",()=>process.exit(0));'
+```
+
+Change the URL if your relay uses another port or path.
+
+---
+
+## Vite plugin (optional)
+
+If you use Vite, you can attach the relay to the dev server so the WebSocket is on the same host/port:
+
+```js
+// vite.config.ts
+import { twdRemote } from 'twd-relay/vite';
+
+export default defineConfig({
+  plugins: [react(), twdRemote()],
+});
+```
+
+Then in your app you can omit the URL; the client defaults to `ws(s)://<current host>/__twd/ws`.
+
+---
+
+## Scripts (this repo)
+
+| Script        | Description |
+|---------------|-------------|
+| `npm run build`   | Build relay, browser, vite entry points + CLI |
+| `npm run relay`   | Build and start the standalone relay (port 9876) |
+| `npm run send-run`| Connect as client and send `run`; exits on `run:complete` |
+| `npm run dev`     | Start relay only (assumes already built) |
+| `npm run test`    | Run tests (watch) |
+| `npm run test:ci` | Run tests with coverage |
+
+---
+
+## Exports
+
+| Export | Use |
+|--------|-----|
+| `twd-relay` (main) | Relay server: `createTwdRelay(httpServer, options)` |
+| `twd-relay/browser` | Browser client: `createBrowserClient(options)` |
+| `twd-relay/vite`   | Vite plugin: `twdRemote(options)` |
+
+CLI: `twd-relay` (or `npx twd-relay`) runs the standalone relay; supports `--port`.
+
+---
+
+## License
+
+MIT · [BRIKEV](https://github.com/BRIKEV/twd-relay)

package/dist/browser.cjs.js

@@ -0,0 +1 @@
+"use strict";var k=Object.create;var T=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var P=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var L=(n,o,c,d)=>{if(o&&typeof o=="object"||typeof o=="function")for(let a of D(o))!A.call(n,a)&&a!==c&&T(n,a,{get:()=>o[a],enumerable:!(d=b(o,a))||d.enumerable});return n};var $=(n,o,c)=>(c=n!=null?k(P(n)):{},L(o||!n||!n.__esModule?T(c,"default",{value:n,enumerable:!0}):c,n));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function I(){return`${window.location.protocol==="https:"?"wss:":"ws:"}//${window.location.host}/__twd/ws`}function p(n,o){if(!n.parent)return"";const c=o.get(n.parent);return c?c.name:""}function M(n){const o=n?.url??I(),c=n?.reconnect??!0,d=n?.reconnectInterval??2e3,a="[twd-relay]";let t=null,m=!1,w=null;function i(r){t&&t.readyState===WebSocket.OPEN&&t.send(JSON.stringify(r))}function u(){window.dispatchEvent(new CustomEvent("twd:state-change"))}async function _(){const r=window.__TWD_STATE__;if(!r){i({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const s=r.handlers,y=Array.from(s.values()).filter(e=>e.type==="test").length;i({type:"run:start",testCount:y});let l=0,h=0,E=0;const g=performance.now(),O={onStart(e){e.status="running",u(),i({type:"test:start",id:e.id,name:e.name,suite:p(e,s)})},onPass(e){l++,e.status="pass",u(),i({type:"test:pass",id:e.id,name:e.name,suite:p(e,s),duration:performance.now()-g})},onFail(e,f){h++,e.status="fail",e.logs=[f.message],u(),i({type:"test:fail",id:e.id,name:e.name,suite:p(e,s),error:f.message,duration:performance.now()-g})},onSkip(e){E++,e.status="skip",u(),i({type:"test:skip",id:e.id,name:e.name,suite:p(e,s)})},onSuiteStart(e){e.status="running",u()},onSuiteEnd(e){e.status="idle",u()}};try{const{TestRunner:e}=await import("twd-js/runner");await new e(O).runAll()}catch(e){const f=e instanceof Error?e.message:String(e);i({type:"error",code:"RUNNER_ERROR",message:f})}const R=performance.now()-g;i({type:"run:complete",passed:l,failed:h,skipped:E,duration:R}),u()}function C(){const r=window.__TWD_STATE__;if(!r){i({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const s=r.handlers,y=[];for(const[,l]of s)l.type==="test"&&y.push({id:l.id,name:l.name,suite:p(l,s),status:l.status??"idle"});i({type:"status:result",tests:y})}function N(r){let s;try{s=JSON.parse(r.data)}catch{return}s.type==="run"?(console.info(a,"Received run command — running tests..."),_()):s.type==="status"&&C()}function v(){c&&!m&&(console.info(a,`Reconnecting in ${d}ms...`),w=setTimeout(()=>{S()},d))}function S(){t&&(t.readyState===WebSocket.OPEN||t.readyState===WebSocket.CONNECTING)||(m=!1,console.info(a,"Connecting to",o),t=new WebSocket(o),t.addEventListener("open",()=>{i({type:"hello",role:"browser"}),console.info(a,"Connected to relay — ready to receive run/status commands")}),t.addEventListener("message",N),t.addEventListener("close",r=>{t=null,m||console.info(a,"Disconnected",r.code?`(code ${r.code})`:"",r.reason||""),v()}),t.addEventListener("error",()=>{}))}function W(){m=!0,w&&(clearTimeout(w),w=null),t&&(t.close(1e3,"Client disconnecting"),t=null)}return{connect:S,disconnect:W,get connected(){return t!==null&&t.readyState===WebSocket.OPEN}}}exports.createBrowserClient=M;

package/dist/browser.d.ts

@@ -0,0 +1,18 @@
+export declare interface BrowserClient {
+    connect(): void;
+    disconnect(): void;
+    readonly connected: boolean;
+}
+
+export declare interface BrowserClientOptions {
+    /** WebSocket URL. Default: auto-detected from window.location */
+    url?: string;
+    /** Auto-reconnect on disconnect. Default: true */
+    reconnect?: boolean;
+    /** Milliseconds between reconnect attempts. Default: 2000 */
+    reconnectInterval?: number;
+}
+
+export declare function createBrowserClient(options?: BrowserClientOptions): BrowserClient;
+
+export { }

package/dist/browser.es.js

@@ -0,0 +1,131 @@
+function k() {
+  return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}/__twd/ws`;
+}
+function l(a, d) {
+  if (!a.parent) return "";
+  const f = d.get(a.parent);
+  return f ? f.name : "";
+}
+function O(a) {
+  const d = a?.url ?? k(), f = a?.reconnect ?? !0, g = a?.reconnectInterval ?? 2e3, c = "[twd-relay]";
+  let n = null, p = !1, m = null;
+  function r(t) {
+    n && n.readyState === WebSocket.OPEN && n.send(JSON.stringify(t));
+  }
+  function i() {
+    window.dispatchEvent(new CustomEvent("twd:state-change"));
+  }
+  async function T() {
+    const t = window.__TWD_STATE__;
+    if (!t) {
+      r({ type: "error", code: "NO_TWD", message: "TWD not initialized" });
+      return;
+    }
+    const o = t.handlers, w = Array.from(o.values()).filter((e) => e.type === "test").length;
+    r({ type: "run:start", testCount: w });
+    let s = 0, h = 0, E = 0;
+    const y = performance.now(), v = {
+      onStart(e) {
+        e.status = "running", i(), r({
+          type: "test:start",
+          id: e.id,
+          name: e.name,
+          suite: l(e, o)
+        });
+      },
+      onPass(e) {
+        s++, e.status = "pass", i(), r({
+          type: "test:pass",
+          id: e.id,
+          name: e.name,
+          suite: l(e, o),
+          duration: performance.now() - y
+        });
+      },
+      onFail(e, u) {
+        h++, e.status = "fail", e.logs = [u.message], i(), r({
+          type: "test:fail",
+          id: e.id,
+          name: e.name,
+          suite: l(e, o),
+          error: u.message,
+          duration: performance.now() - y
+        });
+      },
+      onSkip(e) {
+        E++, e.status = "skip", i(), r({
+          type: "test:skip",
+          id: e.id,
+          name: e.name,
+          suite: l(e, o)
+        });
+      },
+      onSuiteStart(e) {
+        e.status = "running", i();
+      },
+      onSuiteEnd(e) {
+        e.status = "idle", i();
+      }
+    };
+    try {
+      const { TestRunner: e } = await import("twd-js/runner");
+      await new e(v).runAll();
+    } catch (e) {
+      const u = e instanceof Error ? e.message : String(e);
+      r({ type: "error", code: "RUNNER_ERROR", message: u });
+    }
+    const R = performance.now() - y;
+    r({ type: "run:complete", passed: s, failed: h, skipped: E, duration: R }), i();
+  }
+  function _() {
+    const t = window.__TWD_STATE__;
+    if (!t) {
+      r({ type: "error", code: "NO_TWD", message: "TWD not initialized" });
+      return;
+    }
+    const o = t.handlers, w = [];
+    for (const [, s] of o)
+      s.type === "test" && w.push({
+        id: s.id,
+        name: s.name,
+        suite: l(s, o),
+        status: s.status ?? "idle"
+      });
+    r({ type: "status:result", tests: w });
+  }
+  function N(t) {
+    let o;
+    try {
+      o = JSON.parse(t.data);
+    } catch {
+      return;
+    }
+    o.type === "run" ? (console.info(c, "Received run command — running tests..."), T()) : o.type === "status" && _();
+  }
+  function C() {
+    f && !p && (console.info(c, `Reconnecting in ${g}ms...`), m = setTimeout(() => {
+      S();
+    }, g));
+  }
+  function S() {
+    n && (n.readyState === WebSocket.OPEN || n.readyState === WebSocket.CONNECTING) || (p = !1, console.info(c, "Connecting to", d), n = new WebSocket(d), n.addEventListener("open", () => {
+      r({ type: "hello", role: "browser" }), console.info(c, "Connected to relay — ready to receive run/status commands");
+    }), n.addEventListener("message", N), n.addEventListener("close", (t) => {
+      n = null, p || console.info(c, "Disconnected", t.code ? `(code ${t.code})` : "", t.reason || ""), C();
+    }), n.addEventListener("error", () => {
+    }));
+  }
+  function W() {
+    p = !0, m && (clearTimeout(m), m = null), n && (n.close(1e3, "Client disconnecting"), n = null);
+  }
+  return {
+    connect: S,
+    disconnect: W,
+    get connected() {
+      return n !== null && n.readyState === WebSocket.OPEN;
+    }
+  };
+}
+export {
+  O as createBrowserClient
+};

package/dist/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { createServer } from "http";
+import { WebSocketServer, WebSocket } from "ws";
+const DEFAULT_PATH = "/__twd/ws";
+function createTwdRelay(server2, options) {
+  const path = options?.path ?? DEFAULT_PATH;
+  const onError = options?.onError;
+  const wss = new WebSocketServer({ noServer: true });
+  let browser = null;
+  const clients = /* @__PURE__ */ new Set();
+  let runInProgress = false;
+  function sendError(ws, code, message) {
+    const msg = { type: "error", code, message };
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+  function broadcastToClients(data) {
+    for (const client of clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(data);
+      }
+    }
+  }
+  function sendConnectedStatus(ws) {
+    const msg = { type: "connected", browser: browser !== null && browser.readyState === WebSocket.OPEN };
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+  function notifyBrowserDisconnected() {
+    broadcastToClients(JSON.stringify({ type: "connected", browser: false }));
+  }
+  function handleBrowserMessage(data) {
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (parsed.type === "run:complete") {
+      runInProgress = false;
+    }
+    broadcastToClients(data);
+  }
+  function handleClientMessage(ws, data) {
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      sendError(ws, "INVALID_MESSAGE", "Invalid JSON");
+      return;
+    }
+    if (!parsed.type) {
+      sendError(ws, "INVALID_MESSAGE", 'Missing "type" field');
+      return;
+    }
+    if (parsed.type === "run") {
+      if (!browser || browser.readyState !== WebSocket.OPEN) {
+        sendError(ws, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      if (runInProgress) {
+        sendError(ws, "RUN_IN_PROGRESS", "A test run is already in progress");
+        return;
+      }
+      runInProgress = true;
+      browser.send(data);
+      return;
+    }
+    if (parsed.type === "status") {
+      if (!browser || browser.readyState !== WebSocket.OPEN) {
+        sendError(ws, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      browser.send(data);
+      return;
+    }
+    sendError(ws, "UNKNOWN_COMMAND", `Unknown command: ${parsed.type}`);
+  }
+  function handleConnection(ws) {
+    let identified = false;
+    const identifyHandler = (raw) => {
+      const data = typeof raw === "string" ? raw : raw.toString();
+      if (!identified) {
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch {
+          sendError(ws, "INVALID_MESSAGE", "Invalid JSON");
+          return;
+        }
+        if (parsed.type !== "hello" || parsed.role !== "browser" && parsed.role !== "client") {
+          sendError(ws, "INVALID_MESSAGE", 'First message must be a hello with role "browser" or "client"');
+          return;
+        }
+        identified = true;
+        if (parsed.role === "browser") {
+          if (browser && browser.readyState === WebSocket.OPEN) {
+            browser.close(1e3, "Replaced by new browser");
+          }
+          browser = ws;
+          runInProgress = false;
+          ws.on("close", () => {
+            if (browser === ws) {
+              browser = null;
+              runInProgress = false;
+              notifyBrowserDisconnected();
+            }
+          });
+          broadcastToClients(JSON.stringify({ type: "connected", browser: true }));
+          ws.on("message", (raw2) => {
+            const msg = typeof raw2 === "string" ? raw2 : raw2.toString();
+            handleBrowserMessage(msg);
+          });
+        } else {
+          clients.add(ws);
+          ws.on("close", () => {
+            clients.delete(ws);
+          });
+          sendConnectedStatus(ws);
+          ws.on("message", (raw2) => {
+            const msg = typeof raw2 === "string" ? raw2 : raw2.toString();
+            handleClientMessage(ws, msg);
+          });
+        }
+        ws.removeListener("message", identifyHandler);
+      }
+    };
+    ws.on("message", identifyHandler);
+    ws.on("error", (err) => {
+      if (onError) onError(err);
+    });
+  }
+  const upgradeHandler = (request, socket, head) => {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+    if (url.pathname === path) {
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        handleConnection(ws);
+      });
+    }
+  };
+  server2.on("upgrade", upgradeHandler);
+  wss.on("error", (err) => {
+    if (onError) onError(err);
+  });
+  return {
+    close() {
+      server2.removeListener("upgrade", upgradeHandler);
+      for (const client of clients) {
+        client.close(1e3, "Relay shutting down");
+      }
+      clients.clear();
+      if (browser && browser.readyState === WebSocket.OPEN) {
+        browser.close(1e3, "Relay shutting down");
+      }
+      browser = null;
+      runInProgress = false;
+      wss.close();
+    },
+    get browserConnected() {
+      return browser !== null && browser.readyState === WebSocket.OPEN;
+    },
+    get clientCount() {
+      return clients.size;
+    }
+  };
+}
+const args = process.argv.slice(2);
+let port = 9876;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--port" && args[i + 1]) {
+    port = parseInt(args[i + 1], 10);
+    if (isNaN(port)) {
+      console.error("Invalid port number:", args[i + 1]);
+      process.exit(1);
+    }
+    i++;
+  }
+}
+const server = createServer();
+const relay = createTwdRelay(server, {
+  onError(err) {
+    console.error("[twd-relay] Error:", err.message);
+  }
+});
+server.listen(port, () => {
+  console.log(`TWD Relay running on ws://localhost:${port}/__twd/ws`);
+  console.log("Waiting for connections...");
+});
+function shutdown() {
+  console.log("\nShutting down...");
+  relay.close();
+  server.close(() => {
+    process.exit(0);
+  });
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/dist/createTwdRelay-22etCW_8.js

@@ -0,0 +1,123 @@
+import { WebSocketServer as P, WebSocket as o } from "ws";
+const R = "/__twd/ws";
+function J(p, N) {
+  const E = N?.path ?? R, f = N?.onError, u = new P({ noServer: !0 });
+  let t = null;
+  const c = /* @__PURE__ */ new Set();
+  let a = !1;
+  function s(e, n, r) {
+    const i = { type: "error", code: n, message: r };
+    e.readyState === o.OPEN && e.send(JSON.stringify(i));
+  }
+  function S(e) {
+    for (const n of c)
+      n.readyState === o.OPEN && n.send(e);
+  }
+  function h(e) {
+    const n = { type: "connected", browser: t !== null && t.readyState === o.OPEN };
+    e.readyState === o.OPEN && e.send(JSON.stringify(n));
+  }
+  function m() {
+    S(JSON.stringify({ type: "connected", browser: !1 }));
+  }
+  function b(e) {
+    let n;
+    try {
+      n = JSON.parse(e);
+    } catch {
+      return;
+    }
+    n.type === "run:complete" && (a = !1), S(e);
+  }
+  function A(e, n) {
+    let r;
+    try {
+      r = JSON.parse(n);
+    } catch {
+      s(e, "INVALID_MESSAGE", "Invalid JSON");
+      return;
+    }
+    if (!r.type) {
+      s(e, "INVALID_MESSAGE", 'Missing "type" field');
+      return;
+    }
+    if (r.type === "run") {
+      if (!t || t.readyState !== o.OPEN) {
+        s(e, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      if (a) {
+        s(e, "RUN_IN_PROGRESS", "A test run is already in progress");
+        return;
+      }
+      a = !0, t.send(n);
+      return;
+    }
+    if (r.type === "status") {
+      if (!t || t.readyState !== o.OPEN) {
+        s(e, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      t.send(n);
+      return;
+    }
+    s(e, "UNKNOWN_COMMAND", `Unknown command: ${r.type}`);
+  }
+  function I(e) {
+    let n = !1;
+    const r = (i) => {
+      const y = typeof i == "string" ? i : i.toString();
+      if (!n) {
+        let d;
+        try {
+          d = JSON.parse(y);
+        } catch {
+          s(e, "INVALID_MESSAGE", "Invalid JSON");
+          return;
+        }
+        if (d.type !== "hello" || d.role !== "browser" && d.role !== "client") {
+          s(e, "INVALID_MESSAGE", 'First message must be a hello with role "browser" or "client"');
+          return;
+        }
+        n = !0, d.role === "browser" ? (t && t.readyState === o.OPEN && t.close(1e3, "Replaced by new browser"), t = e, a = !1, e.on("close", () => {
+          t === e && (t = null, a = !1, m());
+        }), S(JSON.stringify({ type: "connected", browser: !0 })), e.on("message", (l) => {
+          const g = typeof l == "string" ? l : l.toString();
+          b(g);
+        })) : (c.add(e), e.on("close", () => {
+          c.delete(e);
+        }), h(e), e.on("message", (l) => {
+          const g = typeof l == "string" ? l : l.toString();
+          A(e, g);
+        })), e.removeListener("message", r);
+      }
+    };
+    e.on("message", r), e.on("error", (i) => {
+      f && f(i);
+    });
+  }
+  const O = (e, n, r) => {
+    new URL(e.url ?? "/", `http://${e.headers.host ?? "localhost"}`).pathname === E && u.handleUpgrade(e, n, r, (y) => {
+      I(y);
+    });
+  };
+  return p.on("upgrade", O), u.on("error", (e) => {
+    f && f(e);
+  }), {
+    close() {
+      p.removeListener("upgrade", O);
+      for (const e of c)
+        e.close(1e3, "Relay shutting down");
+      c.clear(), t && t.readyState === o.OPEN && t.close(1e3, "Relay shutting down"), t = null, a = !1, u.close();
+    },
+    get browserConnected() {
+      return t !== null && t.readyState === o.OPEN;
+    },
+    get clientCount() {
+      return c.size;
+    }
+  };
+}
+export {
+  J as c
+};

package/dist/createTwdRelay-VRmjHboP.cjs

@@ -0,0 +1 @@
+"use strict";const o=require("ws"),I="/__twd/ws";function P(N,p){const b=p?.path??I,f=p?.onError,S=new o.WebSocketServer({noServer:!0});let t=null;const l=new Set;let a=!1;function s(e,n,r){const c={type:"error",code:n,message:r};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(c))}function u(e){for(const n of l)n.readyState===o.WebSocket.OPEN&&n.send(e)}function E(e){const n={type:"connected",browser:t!==null&&t.readyState===o.WebSocket.OPEN};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(n))}function h(){u(JSON.stringify({type:"connected",browser:!1}))}function m(e){let n;try{n=JSON.parse(e)}catch{return}n.type==="run:complete"&&(a=!1),u(e)}function W(e,n){let r;try{r=JSON.parse(n)}catch{s(e,"INVALID_MESSAGE","Invalid JSON");return}if(!r.type){s(e,"INVALID_MESSAGE",'Missing "type" field');return}if(r.type==="run"){if(!t||t.readyState!==o.WebSocket.OPEN){s(e,"NO_BROWSER","No browser connected");return}if(a){s(e,"RUN_IN_PROGRESS","A test run is already in progress");return}a=!0,t.send(n);return}if(r.type==="status"){if(!t||t.readyState!==o.WebSocket.OPEN){s(e,"NO_BROWSER","No browser connected");return}t.send(n);return}s(e,"UNKNOWN_COMMAND",`Unknown command: ${r.type}`)}function A(e){let n=!1;const r=c=>{const y=typeof c=="string"?c:c.toString();if(!n){let d;try{d=JSON.parse(y)}catch{s(e,"INVALID_MESSAGE","Invalid JSON");return}if(d.type!=="hello"||d.role!=="browser"&&d.role!=="client"){s(e,"INVALID_MESSAGE",'First message must be a hello with role "browser" or "client"');return}n=!0,d.role==="browser"?(t&&t.readyState===o.WebSocket.OPEN&&t.close(1e3,"Replaced by new browser"),t=e,a=!1,e.on("close",()=>{t===e&&(t=null,a=!1,h())}),u(JSON.stringify({type:"connected",browser:!0})),e.on("message",i=>{const g=typeof i=="string"?i:i.toString();m(g)})):(l.add(e),e.on("close",()=>{l.delete(e)}),E(e),e.on("message",i=>{const g=typeof i=="string"?i:i.toString();W(e,g)})),e.removeListener("message",r)}};e.on("message",r),e.on("error",c=>{f&&f(c)})}const O=(e,n,r)=>{new URL(e.url??"/",`http://${e.headers.host??"localhost"}`).pathname===b&&S.handleUpgrade(e,n,r,y=>{A(y)})};return N.on("upgrade",O),S.on("error",e=>{f&&f(e)}),{close(){N.removeListener("upgrade",O);for(const e of l)e.close(1e3,"Relay shutting down");l.clear(),t&&t.readyState===o.WebSocket.OPEN&&t.close(1e3,"Relay shutting down"),t=null,a=!1,S.close()},get browserConnected(){return t!==null&&t.readyState===o.WebSocket.OPEN},get clientCount(){return l.size}}}exports.c=P;

package/dist/index.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./createTwdRelay-VRmjHboP.cjs");exports.createTwdRelay=e.c;

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { Server } from 'http';
+
+export declare type BrowserEvent = ConnectedEvent | RunStartEvent | TestStartEvent | TestPassEvent | TestFailEvent | TestSkipEvent | RunCompleteEvent;
+
+export declare type Command = RunCommand | StatusCommand;
+
+export declare interface ConnectedEvent {
+    type: 'connected';
+    browser: boolean;
+}
+
+export declare function createTwdRelay(server: Server, options?: TwdRelayOptions): TwdRelay;
+
+export declare interface HelloBrowserMessage {
+    type: 'hello';
+    role: 'browser';
+}
+
+export declare interface HelloClientMessage {
+    type: 'hello';
+    role: 'client';
+}
+
+export declare type HelloMessage = HelloBrowserMessage | HelloClientMessage;
+
+export declare type InboundMessage = HelloMessage | Command | BrowserEvent;
+
+export declare interface RunCommand {
+    type: 'run';
+    scope: 'all';
+}
+
+export declare interface RunCompleteEvent {
+    type: 'run:complete';
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration: number;
+}
+
+export declare interface RunStartEvent {
+    type: 'run:start';
+    testCount: number;
+}
+
+export declare interface StatusCommand {
+    type: 'status';
+}
+
+export declare interface TestFailEvent {
+    type: 'test:fail';
+    id: string;
+    name: string;
+    suite: string;
+    error: string;
+    duration: number;
+}
+
+export declare interface TestPassEvent {
+    type: 'test:pass';
+    id: string;
+    name: string;
+    suite: string;
+    duration: number;
+}
+
+export declare interface TestSkipEvent {
+    type: 'test:skip';
+    id: string;
+    name: string;
+    suite: string;
+}
+
+export declare interface TestStartEvent {
+    type: 'test:start';
+    id: string;
+    name: string;
+    suite: string;
+}
+
+export declare type TwdErrorCode = 'NO_BROWSER' | 'RUN_IN_PROGRESS' | 'UNKNOWN_COMMAND' | 'INVALID_MESSAGE';
+
+export declare interface TwdErrorMessage {
+    type: 'error';
+    code: TwdErrorCode;
+    message: string;
+}
+
+export declare interface TwdRelay {
+    close(): void;
+    readonly browserConnected: boolean;
+    readonly clientCount: number;
+}
+
+export declare interface TwdRelayOptions {
+    path?: string;
+    onError?: (error: Error) => void;
+}
+
+export { }

package/dist/index.es.js

@@ -0,0 +1,4 @@
+import { c as r } from "./createTwdRelay-22etCW_8.js";
+export {
+  r as createTwdRelay
+};

package/dist/vite.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./createTwdRelay-VRmjHboP.cjs");function n(t){return{name:"twd-relay",configureServer(e){if(!e.httpServer)return;const r=o.c(e.httpServer,{path:t?.path??"/__twd/ws"});e.httpServer.on("close",()=>r.close())}}}exports.twdRemote=n;

package/dist/vite.d.ts

@@ -0,0 +1,17 @@
+import { Server } from 'http';
+
+export declare function twdRemote(options?: TwdRemoteOptions): VitePlugin;
+
+export declare interface TwdRemoteOptions {
+    /** WebSocket path. Default: '/__twd/ws' */
+    path?: string;
+}
+
+declare interface VitePlugin {
+    name: string;
+    configureServer?: (server: {
+        httpServer: Server | null;
+    }) => void;
+}
+
+export { }

package/dist/vite.es.js

@@ -0,0 +1,16 @@
+import { c as o } from "./createTwdRelay-22etCW_8.js";
+function n(e) {
+  return {
+    name: "twd-relay",
+    configureServer(t) {
+      if (!t.httpServer) return;
+      const r = o(t.httpServer, {
+        path: e?.path ?? "/__twd/ws"
+      });
+      t.httpServer.on("close", () => r.close());
+    }
+  };
+}
+export {
+  n as twdRemote
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "twd-relay",
+  "version": "0.1.0",
+  "description": "WebSocket relay for TWD — enables AI agents and external tools to run and observe in-browser tests",
+  "license": "MIT",
+  "author": "BRIKEV",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BRIKEV/twd-relay.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "twd-relay": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.es.js",
+      "default": "./dist/browser.es.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.es.js",
+      "require": "./dist/vite.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "vite build && vite build -c vite.cli.config.ts && node -e \"const fs=require('fs');const f='dist/cli.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'))\" && chmod +x dist/cli.js",
+    "dev": "node dist/cli.js",
+    "relay": "npm run build && node dist/cli.js",
+    "send-run": "node scripts/send-run.js",
+    "test": "vitest",
+    "test:ci": "vitest --run --coverage"
+  },
+  "peerDependencies": {
+    "twd-js": ">=1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "twd-js": {
+      "optional": false
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18"
+  }
+}