twd-relay 1.0.0 → 1.1.0

package/README.md

@@ -18,9 +18,20 @@ Your app runs tests in the browser with twd-js. twd-relay adds a relay server an
 
 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
+3. Client sends `{ type: 'run', scope: 'all' }` (optionally with `testNames` to filter) → 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)
+5. Browser sends `{ type: 'heartbeat' }` every 3s during a run (relay consumes these, never forwarded to clients)
+6. `run:complete` clears the run lock (and the send-run script exits)
+
+### Heartbeat & frozen-tab recovery
+
+During an active test run the browser sends a heartbeat every 3 seconds. The relay tracks the last heartbeat time and checks every 10 seconds. If no heartbeat arrives for **120 seconds** during an active run, the relay considers the run dead (browser tab frozen by the OS), resets the run lock, and broadcasts to all clients:
+
+```json
+{ "type": "run:abandoned", "reason": "heartbeat_timeout" }
+```
+
+The CLI prints a clear message — `Run abandoned — browser tab appears frozen. Refresh the browser tab and retry.` — and exits with code 1. This is especially useful for AI agent workflows, where the agent gets an actionable signal instead of a silent 180s timeout followed by a cryptic `RUN_IN_PROGRESS` error.
 
 ---
 
@@ -57,6 +68,32 @@ const client = createBrowserClient({
 client.connect();
 ```
 
+Once connected, the browser client sets a colored favicon and prefixes `document.title` so you can spot the active TWD tab at a glance:
+
+| Favicon | Title prefix | State |
+|---|---|---|
+| Blue | `[TWD]` | Connected, idle |
+| Orange | `[TWD ...]` | Tests running |
+| Green | `[TWD ✓]` | Last run passed |
+| Red | `[TWD ✗]` | Last run had failures |
+
+On disconnect or eviction (another tab taking over), the original favicon and title are restored.
+
+### Aborting throttled runs
+
+Chrome aggressively throttles timers in backgrounded tabs, which can stretch a 1-second test run to 30+ seconds. To avoid AI/CI hangs, the browser client monitors per-test wall-clock time. If any single test runs longer than 5 seconds (configurable), the browser emits `run:aborted`, the CLI prints a clear error with recovery guidance, and the run ends with exit code 1.
+
+Override the threshold with `--max-test-duration <ms>` on `twd-relay run`, or pass `maxTestDurationMs` to `createBrowserClient`. Set it to `0` to disable detection entirely:
+
+```bash
+twd-relay run --max-test-duration 15000   # raise to 15s for heavy multistep tests
+twd-relay run --max-test-duration 0       # disable detection
+```
+
+The default of 5 s is deliberate: real TWD tests are typically sub-second, and 5 s is a strong throttling signal. Heavy legitimate tests (complex multistep forms, many API calls) may need to raise this.
+
+Recovery when an abort fires: foreground the TWD tab (identified by the `[TWD …]` title prefix set by the favicon indicator) and retry. For unattended runs (CI, agents), prefer `twd-cli`: it drives a headless browser where the tab is always focused and throttling doesn't apply.
+
 **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`:
@@ -114,7 +151,40 @@ Then in your app you can omit the URL; the client defaults to `ws(s)://<current
 | `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`.
+CLI: `twd-relay` (or `npx twd-relay`) — two subcommands:
+
+- `twd-relay serve` (default) — start the standalone relay
+- `twd-relay run` — connect to a relay and trigger a test run
+
+---
+
+## CLI `run` command
+
+Connect to an existing relay, trigger tests, stream output, and exit with 0 (all pass) or 1 (failures).
+
+```bash
+# Run all tests (connects to Vite dev server on port 5173 by default)
+twd-relay run
+
+# Run on a different port
+twd-relay run --port 9876
+
+# Run specific tests by name (substring match, case-insensitive)
+twd-relay run --test "should show error"
+
+# Multiple filters — runs tests matching any of them
+twd-relay run --test "login" --test "signup"
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--port <port>` | Relay port | 5173 |
+| `--host <host>` | Relay host | localhost |
+| `--path <path>` | WebSocket path | `/__twd/ws` |
+| `--timeout <ms>` | Timeout | 180000 |
+| `--test <name>` | Filter tests by name substring (repeatable) | — |
+
+When `--test` is used and no tests match, the CLI prints the available test names so you can correct the filter.
 
 ---
 

package/dist/browser.cjs.js

@@ -1 +1 @@
-var I=Object.create;var O=Object.defineProperty;var J=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var z=Object.getPrototypeOf,B=Object.prototype.hasOwnProperty;var j=(t,o,l,p)=>{if(o&&typeof o=="object"||typeof o=="function")for(let u of M(o))!B.call(t,u)&&u!==l&&O(t,u,{get:()=>o[u],enumerable:!(p=J(o,u))||p.enumerable});return t};var U=(t,o,l)=>(l=t!=null?I(z(t)):{},j(o||!t||!t.__esModule?O(l,"default",{value:t,enumerable:!0}):l,t));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function x(t){return`${window.location.protocol==="https:"?"wss:":"ws:"}//${window.location.host}${t}`}function g(t,o){if(!t.parent)return"";const l=o.get(t.parent);return l?l.name:""}function F(t){const o=t?.url??x(t?.path??"/__twd/ws"),l=t?.reconnect??!0,p=t?.reconnectInterval??2e3,u=t?.log??!1,C="[twd-relay]";function w(...n){u&&console.info(C,...n)}function N(...n){console.warn(C,...n)}let r=null,h=!1,S=null;function s(n){r&&r.readyState===WebSocket.OPEN&&r.send(JSON.stringify(n))}function f(){window.dispatchEvent(new CustomEvent("twd:state-change"))}async function R(n){const i=window.__TWD_STATE__;if(!i){N("TWD not initialized — make sure twd-js is loaded before running tests"),s({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const d=i.handlers;let c;if(n&&n.length>0){const e=n.map(m=>m.toLowerCase()),a=[];for(const[,m]of d)if(m.type==="test"){const y=m.name.toLowerCase();e.some(P=>y.includes(P))&&a.push(m.id)}if(a.length===0){const m=Array.from(d.values()).filter(y=>y.type==="test").map(y=>y.name);s({type:"run:start",testCount:0}),s({type:"error",code:"NO_MATCH",message:`No tests matched: ${JSON.stringify(n)}. Available tests: ${JSON.stringify(m)}`}),s({type:"run:complete",passed:0,failed:0,skipped:0,duration:0});return}c=a}s({type:"run:start",testCount:c?c.length:Array.from(d.values()).filter(e=>e.type==="test").length});let _=0,b=0,v=0;const T=performance.now(),L={onStart(e){e.status="running",f(),s({type:"test:start",id:e.id,name:e.name,suite:g(e,d)})},onPass(e){_++,e.status="pass",f(),s({type:"test:pass",id:e.id,name:e.name,suite:g(e,d),duration:performance.now()-T})},onFail(e,a){b++,e.status="fail",e.logs=[a.message],f(),s({type:"test:fail",id:e.id,name:e.name,suite:g(e,d),error:a.message,duration:performance.now()-T})},onSkip(e){v++,e.status="skip",f(),s({type:"test:skip",id:e.id,name:e.name,suite:g(e,d)})},onSuiteStart(e){e.status="running",f()},onSuiteEnd(e){e.status="idle",f()}};try{const{TestRunner:e}=await import("twd-js/runner"),a=new e(L);c?await a.runByIds(c):await a.runAll()}catch(e){const a=e instanceof Error?e.message:String(e);N("Runner error:",a),s({type:"error",code:"RUNNER_ERROR",message:a})}const $=performance.now()-T;s({type:"run:complete",passed:_,failed:b,skipped:v,duration:$}),f()}function W(){const n=window.__TWD_STATE__;if(!n){s({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const i=n.handlers,d=[];for(const[,c]of i)c.type==="test"&&d.push({id:c.id,name:c.name,suite:g(c,i),status:c.status??"idle"});s({type:"status:result",tests:d})}function k(n){let i;try{i=JSON.parse(n.data)}catch{return}i.type==="run"?(w("Received run command — running tests..."),R(Array.isArray(i.testNames)?i.testNames:void 0)):i.type==="status"&&W()}function A(){l&&!h&&(w(`Reconnecting in ${p}ms...`),S=setTimeout(()=>{E()},p))}function E(){r&&(r.readyState===WebSocket.OPEN||r.readyState===WebSocket.CONNECTING)||(h=!1,w("Connecting to",o),r=new WebSocket(o),r.addEventListener("open",()=>{s({type:"hello",role:"browser"}),w("Connected to relay — ready to receive run/status commands")}),r.addEventListener("message",k),r.addEventListener("close",n=>{if(r=null,n.reason==="Replaced by new browser"){N("Another browser instance connected — this instance will not reconnect");return}h||w("Disconnected",n.code?`(code ${n.code})`:"",n.reason||""),A()}),r.addEventListener("error",()=>{}))}function D(){h=!0,S&&(clearTimeout(S),S=null),r&&(r.close(1e3,"Client disconnecting"),r=null)}return{connect:E,disconnect:D,get connected(){return r!==null&&r.readyState===WebSocket.OPEN}}}exports.createBrowserClient=F;
+var z=Object.create;var R=Object.defineProperty;var U=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var H=Object.getPrototypeOf,G=Object.prototype.hasOwnProperty;var V=(e,r,s,c)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of q(r))!G.call(e,n)&&n!==s&&R(e,n,{get:()=>r[n],enumerable:!(c=U(r,n))||c.enumerable});return e};var X=(e,r,s)=>(s=e!=null?z(H(e)):{},V(r||!e||!e.__esModule?R(s,"default",{value:e,enumerable:!0}):s,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var M=e=>`data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect x='3' y='4' width='26' height='24' rx='4' fill='${e}'/><circle cx='7' cy='9' r='1' fill='white'/><circle cx='11' cy='9' r='1' fill='white'/><circle cx='15' cy='9' r='1' fill='white'/><path d='M9 20l4 4 10-10' stroke='white' stroke-width='3.5' fill='none' stroke-linecap='round' stroke-linejoin='round'/></svg>`,K={connected:M("%234A90D9"),running:M("%23F5A623"),pass:M("%237ED321"),fail:M("%23D0021B")},Q={connected:"[TWD] ",running:"[TWD ...] ",pass:"[TWD ✓] ",fail:"[TWD ✗] "};function Y(e){let r=null,s=null,c=!1,n=null;function b(){if(n&&n.isConnected)return n;const i=e.querySelector("link[rel='icon']");if(i)n=i;else{const f=e.createElement("link");f.rel="icon",e.head.appendChild(f),n=f}return n}return{save(){if(s!==null)return;const i=e.querySelector("link[rel='icon']");c=i!==null,r=i?.href??null,s=e.title,n=i},restore(){s!==null&&(e.title=s),!c&&n&&n.isConnected?n.remove():c&&r!==null&&n&&n.setAttribute("href",r),r=null,s=null,c=!1,n=null},set(i){b().setAttribute("href",K[i]);const f=s??e.title;e.title=Q[i]+f}}}function Z(e){const r=e.now??(()=>performance.now()),s=e.thresholdMs;let c=null,n=null,b=!1;return{onTestStart(i){c=r(),n=i},onTestEnd(){if(c===null||n===null)return null;const i=n,f=r()-c;return c=null,n=null,s<=0||f<=s?null:{testName:i,durationMs:f}},checkThreshold(){if(s<=0||c===null||n===null)return null;const i=r()-c;return i<=s?null:{testName:n,durationMs:i}},markAborted(){b=!0},isAborted(){return b}}}function ee(e){return`${window.location.protocol==="https:"?"wss:":"ws:"}//${window.location.host}${e}`}function E(e,r){if(!e.parent)return"";const s=r.get(e.parent);return s?s.name:""}function te(e){const r=e?.url??ee(e?.path??"/__twd/ws"),s=e?.reconnect??!0,c=e?.reconnectInterval??2e3,n=e?.log??!1,b=e?.maxTestDurationMs??5e3,i="[twd-relay]";function f(...o){n&&console.info(i,...o)}function _(...o){console.warn(i,...o)}const w=Y(document);let u=null,k=!1,N=null;function d(o){u&&u.readyState===WebSocket.OPEN&&u.send(JSON.stringify(o))}function g(){window.dispatchEvent(new CustomEvent("twd:state-change"))}async function I(o,m={}){const a=Z({thresholdMs:typeof m.maxTestDurationMs=="number"?m.maxTestDurationMs:b});let h=0,S=0,W=0;const C=performance.now();let x;function D(y){a.isAborted()||(a.markAborted(),d({type:"run:aborted",reason:"throttled",durationMs:y.durationMs,testName:y.testName}),d({type:"run:complete",passed:h,failed:S,skipped:W,duration:performance.now()-C}),w.set("fail"),g(),clearInterval(x))}x=setInterval(()=>{d({type:"heartbeat"});const y=a.checkThreshold();y&&D(y)},3e3),w.set("running");try{const y=window.__TWD_STATE__;if(!y){_("TWD not initialized — make sure twd-js is loaded before running tests"),d({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const T=y.handlers;let v;if(o&&o.length>0){const t=o.map(p=>p.toLowerCase()),l=[];for(const[,p]of T)if(p.type==="test"){const A=p.name.toLowerCase();t.some(j=>A.includes(j))&&l.push(p.id)}if(l.length===0){const p=Array.from(T.values()).filter(A=>A.type==="test").map(A=>A.name);d({type:"run:start",testCount:0}),d({type:"error",code:"NO_MATCH",message:`No tests matched: ${JSON.stringify(o)}. Available tests: ${JSON.stringify(p)}`}),d({type:"run:complete",passed:0,failed:0,skipped:0,duration:0}),w.set("pass");return}v=l}d({type:"run:start",testCount:v?v.length:Array.from(T.values()).filter(t=>t.type==="test").length});const F={onStart(t){a.isAborted()||(a.onTestStart(t.name),t.status="running",g(),d({type:"test:start",id:t.id,name:t.name,suite:E(t,T)}))},onPass(t){const l=a.onTestEnd();if(!a.isAborted()){if(l){D(l);return}h++,t.status="pass",g(),d({type:"test:pass",id:t.id,name:t.name,suite:E(t,T),duration:performance.now()-C})}},onFail(t,l){const p=a.onTestEnd();if(!a.isAborted()){if(p){D(p);return}S++,t.status="fail",t.logs=[l.message],g(),d({type:"test:fail",id:t.id,name:t.name,suite:E(t,T),error:l.message,duration:performance.now()-C})}},onSkip(t){const l=a.onTestEnd();if(!a.isAborted()){if(l){D(l);return}W++,t.status="skip",g(),d({type:"test:skip",id:t.id,name:t.name,suite:E(t,T)})}},onSuiteStart(t){a.isAborted()||(t.status="running",g())},onSuiteEnd(t){a.isAborted()||(t.status="idle",g())}};try{const{TestRunner:t}=await import("twd-js/runner"),l=new t(F);v?await l.runByIds(v):await l.runAll()}catch(t){const l=t instanceof Error?t.message:String(t);_("Runner error:",l),d({type:"error",code:"RUNNER_ERROR",message:l}),S++,a.onTestEnd()}const J=performance.now()-C;a.isAborted()?w.set("fail"):(d({type:"run:complete",passed:h,failed:S,skipped:W,duration:J}),w.set(S>0?"fail":"pass")),g()}finally{clearInterval(x)}}function L(){const o=window.__TWD_STATE__;if(!o){d({type:"error",code:"NO_TWD",message:"TWD not initialized"});return}const m=o.handlers,a=[];for(const[,h]of m)h.type==="test"&&a.push({id:h.id,name:h.name,suite:E(h,m),status:h.status??"idle"});d({type:"status:result",tests:a})}function $(o){let m;try{m=JSON.parse(o.data)}catch{return}m.type==="run"?(f("Received run command — running tests..."),I(Array.isArray(m.testNames)?m.testNames:void 0,m)):m.type==="status"&&L()}function P(){s&&!k&&(f(`Reconnecting in ${c}ms...`),N=setTimeout(()=>{O()},c))}function O(){u&&(u.readyState===WebSocket.OPEN||u.readyState===WebSocket.CONNECTING)||(k=!1,f("Connecting to",r),u=new WebSocket(r),u.addEventListener("open",()=>{d({type:"hello",role:"browser"}),w.save(),w.set("connected"),f("Connected to relay — ready to receive run/status commands")}),u.addEventListener("message",$),u.addEventListener("close",o=>{if(u=null,w.restore(),o.reason==="Replaced by new browser"){_("Another browser instance connected — this instance will not reconnect");return}k||f("Disconnected",o.code?`(code ${o.code})`:"",o.reason||""),P()}),u.addEventListener("error",()=>{}))}function B(){k=!0,N&&(clearTimeout(N),N=null),u&&(u.close(1e3,"Client disconnecting"),u=null)}return{connect:O,disconnect:B,get connected(){return u!==null&&u.readyState===WebSocket.OPEN}}}exports.createBrowserClient=te;

package/dist/browser.d.ts

@@ -15,6 +15,13 @@ export declare interface BrowserClientOptions {
     reconnectInterval?: number;
     /** Enable console logging. Default: false */
     log?: boolean;
+    /**
+     * Maximum wall-clock ms any single test may run before the browser
+     * aborts the run with reason 'throttled'. Typically triggered when the
+     * tab is backgrounded and Chrome throttles timers. Default: 5000.
+     * Set to 0 to disable detection.
+     */
+    maxTestDurationMs?: number;
 }
 
 export declare function createBrowserClient(options?: BrowserClientOptions): BrowserClient;

package/dist/browser.es.js

@@ -1,194 +1,312 @@
-function I(i) {
-  return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}${i}`;
+var M = (t) => `data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect x='3' y='4' width='26' height='24' rx='4' fill='${t}'/><circle cx='7' cy='9' r='1' fill='white'/><circle cx='11' cy='9' r='1' fill='white'/><circle cx='15' cy='9' r='1' fill='white'/><path d='M9 20l4 4 10-10' stroke='white' stroke-width='3.5' fill='none' stroke-linecap='round' stroke-linejoin='round'/></svg>`, z = {
+  connected: M("%234A90D9"),
+  running: M("%23F5A623"),
+  pass: M("%237ED321"),
+  fail: M("%23D0021B")
+}, U = {
+  connected: "[TWD] ",
+  running: "[TWD ...] ",
+  pass: "[TWD ✓] ",
+  fail: "[TWD ✗] "
+};
+function j(t) {
+  let f = null, c = null, u = !1, n = null;
+  function b() {
+    if (n && n.isConnected) return n;
+    const s = t.querySelector("link[rel='icon']");
+    if (s) n = s;
+    else {
+      const d = t.createElement("link");
+      d.rel = "icon", t.head.appendChild(d), n = d;
+    }
+    return n;
+  }
+  return {
+    save() {
+      if (c !== null) return;
+      const s = t.querySelector("link[rel='icon']");
+      u = s !== null, f = s?.href ?? null, c = t.title, n = s;
+    },
+    restore() {
+      c !== null && (t.title = c), !u && n && n.isConnected ? n.remove() : u && f !== null && n && n.setAttribute("href", f), f = null, c = null, u = !1, n = null;
+    },
+    set(s) {
+      b().setAttribute("href", z[s]);
+      const d = c ?? t.title;
+      t.title = U[s] + d;
+    }
+  };
 }
-function m(i, p) {
-  if (!i.parent) return "";
-  const w = p.get(i.parent);
-  return w ? w.name : "";
+function q(t) {
+  const f = t.now ?? (() => performance.now()), c = t.thresholdMs;
+  let u = null, n = null, b = !1;
+  return {
+    onTestStart(s) {
+      u = f(), n = s;
+    },
+    onTestEnd() {
+      if (u === null || n === null) return null;
+      const s = n, d = f() - u;
+      return u = null, n = null, c <= 0 || d <= c ? null : {
+        testName: s,
+        durationMs: d
+      };
+    },
+    checkThreshold() {
+      if (c <= 0 || u === null || n === null) return null;
+      const s = f() - u;
+      return s <= c ? null : {
+        testName: n,
+        durationMs: s
+      };
+    },
+    markAborted() {
+      b = !0;
+    },
+    isAborted() {
+      return b;
+    }
+  };
+}
+function H(t) {
+  return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}${t}`;
 }
-function P(i) {
-  const p = i?.url ?? I(i?.path ?? "/__twd/ws"), w = i?.reconnect ?? !0, N = i?.reconnectInterval ?? 2e3, v = i?.log ?? !1, T = "[twd-relay]";
-  function u(...t) {
-    v && console.info(T, ...t);
+function E(t, f) {
+  if (!t.parent) return "";
+  const c = f.get(t.parent);
+  return c ? c.name : "";
+}
+function G(t) {
+  const f = t?.url ?? H(t?.path ?? "/__twd/ws"), c = t?.reconnect ?? !0, u = t?.reconnectInterval ?? 2e3, n = t?.log ?? !1, b = t?.maxTestDurationMs ?? 5e3, s = "[twd-relay]";
+  function d(...r) {
+    n && console.info(s, ...r);
   }
-  function h(...t) {
-    console.warn(T, ...t);
+  function _(...r) {
+    console.warn(s, ...r);
   }
-  let n = null, y = !1, g = null;
-  function r(t) {
-    n && n.readyState === WebSocket.OPEN && n.send(JSON.stringify(t));
+  const w = j(document);
+  let a = null, k = !1, N = null;
+  function l(r) {
+    a && a.readyState === WebSocket.OPEN && a.send(JSON.stringify(r));
   }
-  function l() {
+  function g() {
     window.dispatchEvent(new CustomEvent("twd:state-change"));
   }
-  async function O(t) {
-    const o = window.__TWD_STATE__;
-    if (!o) {
-      h("TWD not initialized — make sure twd-js is loaded before running tests"), r({
-        type: "error",
-        code: "NO_TWD",
-        message: "TWD not initialized"
-      });
-      return;
+  async function I(r, m = {}) {
+    const o = q({ thresholdMs: typeof m.maxTestDurationMs == "number" ? m.maxTestDurationMs : b });
+    let h = 0, S = 0, x = 0;
+    const C = performance.now();
+    let W;
+    function D(y) {
+      o.isAborted() || (o.markAborted(), l({
+        type: "run:aborted",
+        reason: "throttled",
+        durationMs: y.durationMs,
+        testName: y.testName
+      }), l({
+        type: "run:complete",
+        passed: h,
+        failed: S,
+        skipped: x,
+        duration: performance.now() - C
+      }), w.set("fail"), g(), clearInterval(W));
     }
-    const c = o.handlers;
-    let a;
-    if (t && t.length > 0) {
-      const e = t.map((d) => d.toLowerCase()), s = [];
-      for (const [, d] of c) if (d.type === "test") {
-        const f = d.name.toLowerCase();
-        e.some(($) => f.includes($)) && s.push(d.id);
-      }
-      if (s.length === 0) {
-        const d = Array.from(c.values()).filter((f) => f.type === "test").map((f) => f.name);
-        r({
-          type: "run:start",
-          testCount: 0
-        }), r({
+    W = setInterval(() => {
+      l({ type: "heartbeat" });
+      const y = o.checkThreshold();
+      y && D(y);
+    }, 3e3), w.set("running");
+    try {
+      const y = window.__TWD_STATE__;
+      if (!y) {
+        _("TWD not initialized — make sure twd-js is loaded before running tests"), l({
           type: "error",
-          code: "NO_MATCH",
-          message: `No tests matched: ${JSON.stringify(t)}. Available tests: ${JSON.stringify(d)}`
-        }), r({
-          type: "run:complete",
-          passed: 0,
-          failed: 0,
-          skipped: 0,
-          duration: 0
+          code: "NO_TWD",
+          message: "TWD not initialized"
         });
         return;
       }
-      a = s;
-    }
-    r({
-      type: "run:start",
-      testCount: a ? a.length : Array.from(c.values()).filter((e) => e.type === "test").length
-    });
-    let E = 0, _ = 0, b = 0;
-    const S = performance.now(), D = {
-      onStart(e) {
-        e.status = "running", l(), r({
-          type: "test:start",
-          id: e.id,
-          name: e.name,
-          suite: m(e, c)
-        });
-      },
-      onPass(e) {
-        E++, e.status = "pass", l(), r({
-          type: "test:pass",
-          id: e.id,
-          name: e.name,
-          suite: m(e, c),
-          duration: performance.now() - S
-        });
-      },
-      onFail(e, s) {
-        _++, e.status = "fail", e.logs = [s.message], l(), r({
-          type: "test:fail",
-          id: e.id,
-          name: e.name,
-          suite: m(e, c),
-          error: s.message,
-          duration: performance.now() - S
-        });
-      },
-      onSkip(e) {
-        b++, e.status = "skip", l(), r({
-          type: "test:skip",
-          id: e.id,
-          name: e.name,
-          suite: m(e, c)
-        });
-      },
-      onSuiteStart(e) {
-        e.status = "running", l();
-      },
-      onSuiteEnd(e) {
-        e.status = "idle", l();
+      const T = y.handlers;
+      let v;
+      if (r && r.length > 0) {
+        const e = r.map((p) => p.toLowerCase()), i = [];
+        for (const [, p] of T) if (p.type === "test") {
+          const A = p.name.toLowerCase();
+          e.some((J) => A.includes(J)) && i.push(p.id);
+        }
+        if (i.length === 0) {
+          const p = Array.from(T.values()).filter((A) => A.type === "test").map((A) => A.name);
+          l({
+            type: "run:start",
+            testCount: 0
+          }), l({
+            type: "error",
+            code: "NO_MATCH",
+            message: `No tests matched: ${JSON.stringify(r)}. Available tests: ${JSON.stringify(p)}`
+          }), l({
+            type: "run:complete",
+            passed: 0,
+            failed: 0,
+            skipped: 0,
+            duration: 0
+          }), w.set("pass");
+          return;
+        }
+        v = i;
       }
-    };
-    try {
-      const { TestRunner: e } = await import("twd-js/runner"), s = new e(D);
-      a ? await s.runByIds(a) : await s.runAll();
-    } catch (e) {
-      const s = e instanceof Error ? e.message : String(e);
-      h("Runner error:", s), r({
-        type: "error",
-        code: "RUNNER_ERROR",
-        message: s
+      l({
+        type: "run:start",
+        testCount: v ? v.length : Array.from(T.values()).filter((e) => e.type === "test").length
       });
+      const F = {
+        onStart(e) {
+          o.isAborted() || (o.onTestStart(e.name), e.status = "running", g(), l({
+            type: "test:start",
+            id: e.id,
+            name: e.name,
+            suite: E(e, T)
+          }));
+        },
+        onPass(e) {
+          const i = o.onTestEnd();
+          if (!o.isAborted()) {
+            if (i) {
+              D(i);
+              return;
+            }
+            h++, e.status = "pass", g(), l({
+              type: "test:pass",
+              id: e.id,
+              name: e.name,
+              suite: E(e, T),
+              duration: performance.now() - C
+            });
+          }
+        },
+        onFail(e, i) {
+          const p = o.onTestEnd();
+          if (!o.isAborted()) {
+            if (p) {
+              D(p);
+              return;
+            }
+            S++, e.status = "fail", e.logs = [i.message], g(), l({
+              type: "test:fail",
+              id: e.id,
+              name: e.name,
+              suite: E(e, T),
+              error: i.message,
+              duration: performance.now() - C
+            });
+          }
+        },
+        onSkip(e) {
+          const i = o.onTestEnd();
+          if (!o.isAborted()) {
+            if (i) {
+              D(i);
+              return;
+            }
+            x++, e.status = "skip", g(), l({
+              type: "test:skip",
+              id: e.id,
+              name: e.name,
+              suite: E(e, T)
+            });
+          }
+        },
+        onSuiteStart(e) {
+          o.isAborted() || (e.status = "running", g());
+        },
+        onSuiteEnd(e) {
+          o.isAborted() || (e.status = "idle", g());
+        }
+      };
+      try {
+        const { TestRunner: e } = await import("twd-js/runner"), i = new e(F);
+        v ? await i.runByIds(v) : await i.runAll();
+      } catch (e) {
+        const i = e instanceof Error ? e.message : String(e);
+        _("Runner error:", i), l({
+          type: "error",
+          code: "RUNNER_ERROR",
+          message: i
+        }), S++, o.onTestEnd();
+      }
+      const B = performance.now() - C;
+      o.isAborted() ? w.set("fail") : (l({
+        type: "run:complete",
+        passed: h,
+        failed: S,
+        skipped: x,
+        duration: B
+      }), w.set(S > 0 ? "fail" : "pass")), g();
+    } finally {
+      clearInterval(W);
     }
-    const L = performance.now() - S;
-    r({
-      type: "run:complete",
-      passed: E,
-      failed: _,
-      skipped: b,
-      duration: L
-    }), l();
   }
-  function R() {
-    const t = window.__TWD_STATE__;
-    if (!t) {
-      r({
+  function O() {
+    const r = window.__TWD_STATE__;
+    if (!r) {
+      l({
         type: "error",
         code: "NO_TWD",
         message: "TWD not initialized"
       });
       return;
     }
-    const o = t.handlers, c = [];
-    for (const [, a] of o) a.type === "test" && c.push({
-      id: a.id,
-      name: a.name,
-      suite: m(a, o),
-      status: a.status ?? "idle"
+    const m = r.handlers, o = [];
+    for (const [, h] of m) h.type === "test" && o.push({
+      id: h.id,
+      name: h.name,
+      suite: E(h, m),
+      status: h.status ?? "idle"
     });
-    r({
+    l({
       type: "status:result",
-      tests: c
+      tests: o
     });
   }
-  function W(t) {
-    let o;
+  function L(r) {
+    let m;
     try {
-      o = JSON.parse(t.data);
+      m = JSON.parse(r.data);
     } catch {
       return;
     }
-    o.type === "run" ? (u("Received run command — running tests..."), O(Array.isArray(o.testNames) ? o.testNames : void 0)) : o.type === "status" && R();
+    m.type === "run" ? (d("Received run command — running tests..."), I(Array.isArray(m.testNames) ? m.testNames : void 0, m)) : m.type === "status" && O();
   }
-  function k() {
-    w && !y && (u(`Reconnecting in ${N}ms...`), g = setTimeout(() => {
-      C();
-    }, N));
+  function $() {
+    c && !k && (d(`Reconnecting in ${u}ms...`), N = setTimeout(() => {
+      R();
+    }, u));
   }
-  function C() {
-    n && (n.readyState === WebSocket.OPEN || n.readyState === WebSocket.CONNECTING) || (y = !1, u("Connecting to", p), n = new WebSocket(p), n.addEventListener("open", () => {
-      r({
+  function R() {
+    a && (a.readyState === WebSocket.OPEN || a.readyState === WebSocket.CONNECTING) || (k = !1, d("Connecting to", f), a = new WebSocket(f), a.addEventListener("open", () => {
+      l({
         type: "hello",
         role: "browser"
-      }), u("Connected to relay — ready to receive run/status commands");
-    }), n.addEventListener("message", W), n.addEventListener("close", (t) => {
-      if (n = null, t.reason === "Replaced by new browser") {
-        h("Another browser instance connected — this instance will not reconnect");
+      }), w.save(), w.set("connected"), d("Connected to relay — ready to receive run/status commands");
+    }), a.addEventListener("message", L), a.addEventListener("close", (r) => {
+      if (a = null, w.restore(), r.reason === "Replaced by new browser") {
+        _("Another browser instance connected — this instance will not reconnect");
         return;
       }
-      y || u("Disconnected", t.code ? `(code ${t.code})` : "", t.reason || ""), k();
-    }), n.addEventListener("error", () => {
+      k || d("Disconnected", r.code ? `(code ${r.code})` : "", r.reason || ""), $();
+    }), a.addEventListener("error", () => {
     }));
   }
-  function A() {
-    y = !0, g && (clearTimeout(g), g = null), n && (n.close(1e3, "Client disconnecting"), n = null);
+  function P() {
+    k = !0, N && (clearTimeout(N), N = null), a && (a.close(1e3, "Client disconnecting"), a = null);
   }
   return {
-    connect: C,
-    disconnect: A,
+    connect: R,
+    disconnect: P,
     get connected() {
-      return n !== null && n.readyState === WebSocket.OPEN;
+      return a !== null && a.readyState === WebSocket.OPEN;
     }
   };
 }
 export {
-  P as createBrowserClient
+  G as createBrowserClient
 };

package/dist/cli.js

@@ -10,6 +10,10 @@ function createTwdRelay(server, options) {
 	let browser = null;
 	const clients = /* @__PURE__ */ new Set();
 	let runInProgress = false;
+	let lastHeartbeat = null;
+	let heartbeatCheckTimer = null;
+	const HEARTBEAT_TIMEOUT_MS = 12e4;
+	const HEARTBEAT_CHECK_INTERVAL_MS = 1e4;
 	function sendError(ws, code, message) {
 		const msg = {
 			type: "error",
@@ -34,6 +38,28 @@ function createTwdRelay(server, options) {
 			browser: false
 		}));
 	}
+	function startHeartbeatTracking() {
+		lastHeartbeat = Date.now();
+		heartbeatCheckTimer = setInterval(() => {
+			if (runInProgress && lastHeartbeat !== null) {
+				if (Date.now() - lastHeartbeat > HEARTBEAT_TIMEOUT_MS) {
+					runInProgress = false;
+					stopHeartbeatTracking();
+					broadcastToClients(JSON.stringify({
+						type: "run:abandoned",
+						reason: "heartbeat_timeout"
+					}));
+				}
+			}
+		}, HEARTBEAT_CHECK_INTERVAL_MS);
+	}
+	function stopHeartbeatTracking() {
+		lastHeartbeat = null;
+		if (heartbeatCheckTimer !== null) {
+			clearInterval(heartbeatCheckTimer);
+			heartbeatCheckTimer = null;
+		}
+	}
 	function handleBrowserMessage(data) {
 		let parsed;
 		try {
@@ -41,7 +67,14 @@ function createTwdRelay(server, options) {
 		} catch {
 			return;
 		}
-		if (parsed.type === "run:complete") runInProgress = false;
+		if (parsed.type === "heartbeat") {
+			lastHeartbeat = Date.now();
+			return;
+		}
+		if (parsed.type === "run:complete") {
+			runInProgress = false;
+			stopHeartbeatTracking();
+		}
 		broadcastToClients(data);
 	}
 	function handleClientMessage(ws, data) {
@@ -62,10 +95,11 @@ function createTwdRelay(server, options) {
 				return;
 			}
 			if (runInProgress) {
-				sendError(ws, "RUN_IN_PROGRESS", "A test run is already in progress");
+				sendError(ws, "RUN_IN_PROGRESS", "A test run is already in progress. If the previous run appears stuck, the browser tab may be backgrounded and throttled — foreground the TWD tab (identified by the \"[TWD …]\" title prefix) or reload it. The relay also auto-clears the lock after 120s of heartbeat silence.");
 				return;
 			}
 			runInProgress = true;
+			startHeartbeatTracking();
 			browser.send(data);
 			return;
 		}
@@ -100,10 +134,12 @@ function createTwdRelay(server, options) {
 					if (browser && browser.readyState === WebSocket$1.OPEN) browser.close(1e3, "Replaced by new browser");
 					browser = ws;
 					runInProgress = false;
+					stopHeartbeatTracking();
 					ws.on("close", () => {
 						if (browser === ws) {
 							browser = null;
 							runInProgress = false;
+							stopHeartbeatTracking();
 							notifyBrowserDisconnected();
 						}
 					});
@@ -144,6 +180,7 @@ function createTwdRelay(server, options) {
 	return {
 		close() {
 			server.removeListener("upgrade", upgradeHandler);
+			stopHeartbeatTracking();
 			for (const client of clients) client.close(1e3, "Relay shutting down");
 			clients.clear();
 			if (browser && browser.readyState === WebSocket$1.OPEN) browser.close(1e3, "Relay shutting down");
@@ -162,7 +199,7 @@ function createTwdRelay(server, options) {
 //#endregion
 //#region src/cli/run.ts
 function run(options) {
-	const { port, timeout, path, host, testNames } = options;
+	const { port, timeout, path, host, testNames, maxTestDurationMs } = options;
 	const url = `ws://${host}:${port}${path}`;
 	console.log(`Connecting to ${url}...`);
 	const ws = new WebSocket(url);
@@ -192,6 +229,7 @@ function run(options) {
 						scope: "all"
 					};
 					if (testNames?.length) runMsg.testNames = testNames;
+					if (maxTestDurationMs !== void 0) runMsg.maxTestDurationMs = maxTestDurationMs;
 					ws.send(JSON.stringify(runMsg));
 				} else if (!msg.browser) console.log("Waiting for browser to connect...");
 				break;
@@ -223,6 +261,18 @@ function run(options) {
 				process.exit(failed || msg.failed > 0 ? 1 : 0);
 				break;
 			}
+			case "run:aborted": {
+				failed = true;
+				const seconds = typeof msg.durationMs === "number" ? (msg.durationMs / 1e3).toFixed(1) : "?";
+				console.error(`\nRun aborted: test "${msg.testName ?? "?"}" ran for ${seconds}s — threshold exceeded.\nThe TWD browser tab is likely backgrounded and throttled by the browser.\nForeground the TWD tab (identified by the "[TWD …]" title prefix) and keep it active, then retry.\nFor unattended runs, prefer \`twd-cli\` which drives a headless browser with no tab throttling.`);
+				break;
+			}
+			case "run:abandoned":
+				console.error("\nRun abandoned — browser tab appears frozen. Refresh the browser tab and retry.");
+				clearTimeout(timer);
+				ws.close();
+				process.exit(1);
+				break;
 			case "error":
 				console.error(`Error [${msg.code}]: ${msg.message}`);
 				break;
@@ -266,11 +316,14 @@ Options for serve:
   --path <path>   WebSocket path (default: /__twd/ws)
 
 Options for run:
-  --port <port>      Relay port to connect to (default: 5173)
-  --host <host>      Relay host to connect to (default: localhost)
-  --path <path>      WebSocket path (default: /__twd/ws)
-  --timeout <ms>     Timeout in ms (default: 180000)
-  --test <name>      Filter tests by name substring (repeatable)
+  --port <port>                   Relay port to connect to (default: 5173)
+  --host <host>                   Relay host to connect to (default: localhost)
+  --path <path>                   WebSocket path (default: /__twd/ws)
+  --timeout <ms>                  Timeout in ms (default: 180000)
+  --test <name>                   Filter tests by name substring (repeatable)
+  --max-test-duration <ms>        Abort if any single test exceeds this many
+                                  ms (default from browser client, typically
+                                  5000; 0 disables)
 
 Examples:
   twd-relay                     # start relay on port 9876
@@ -280,7 +333,9 @@ Examples:
   twd-relay run --host 192.168.1.10 --path /app/__twd/ws
   twd-relay run --timeout 30000 # custom timeout
   twd-relay run --test "login"           # run tests matching "login"
-  twd-relay run --test "login" --test "signup"  # run multiple`);
+  twd-relay run --test "login" --test "signup"  # run multiple
+  twd-relay run --max-test-duration 30000         # raise abort threshold to 30s
+  twd-relay run --max-test-duration 0             # disable abort detection`);
 }
 if (args.includes("--help") || args.includes("-h")) {
 	printHelp();
@@ -302,12 +357,22 @@ if (subcommand === "run") {
 		process.exit(1);
 	}
 	const testNames = parseFlagAll("--test");
+	const maxDurationStr = parseFlag("--max-test-duration");
+	let maxTestDurationMs;
+	if (maxDurationStr !== void 0) {
+		maxTestDurationMs = parseInt(maxDurationStr, 10);
+		if (isNaN(maxTestDurationMs)) {
+			console.error("Invalid --max-test-duration value:", maxDurationStr);
+			process.exit(1);
+		}
+	}
 	run({
 		port,
 		timeout,
 		path: pathFlag,
 		host: hostFlag,
-		testNames: testNames.length > 0 ? testNames : void 0
+		testNames: testNames.length > 0 ? testNames : void 0,
+		maxTestDurationMs
 	});
 } else if (!subcommand || subcommand === "serve") {
 	const portStr = parseFlag("--port");

package/dist/index.cjs.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./relay-CpUORBd7.cjs");exports.createTwdRelay=e.createTwdRelay;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./relay-CK82tv0w.cjs");exports.createTwdRelay=e.createTwdRelay;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Server } from 'http';
 
-export declare type BrowserEvent = ConnectedEvent | RunStartEvent | TestStartEvent | TestPassEvent | TestFailEvent | TestSkipEvent | RunCompleteEvent;
+export declare type BrowserEvent = ConnectedEvent | RunStartEvent | TestStartEvent | TestPassEvent | TestFailEvent | TestSkipEvent | RunCompleteEvent | RunAbandonedEvent | RunAbortedEvent;
 
 export declare type Command = RunCommand | StatusCommand;
 
@@ -11,6 +11,10 @@ export declare interface ConnectedEvent {
 
 export declare function createTwdRelay(server: Server, options?: TwdRelayOptions): TwdRelay;
 
+declare interface HeartbeatMessage {
+    type: 'heartbeat';
+}
+
 export declare interface HelloBrowserMessage {
     type: 'hello';
     role: 'browser';
@@ -23,12 +27,28 @@ export declare interface HelloClientMessage {
 
 export declare type HelloMessage = HelloBrowserMessage | HelloClientMessage;
 
-export declare type InboundMessage = HelloMessage | Command | BrowserEvent;
+export declare type InboundMessage = HelloMessage | Command | HeartbeatMessage | BrowserEvent;
+
+declare interface RunAbandonedEvent {
+    type: 'run:abandoned';
+    reason: 'heartbeat_timeout';
+}
+
+declare interface RunAbortedEvent {
+    type: 'run:aborted';
+    reason: 'throttled';
+    durationMs: number;
+    testName: string;
+}
 
 export declare interface RunCommand {
     type: 'run';
     scope: 'all';
     testNames?: string[];
+    /** Max wall-clock ms any single test may run before the browser aborts
+     *  the run with reason 'throttled'. 0 disables detection. Omit to let
+     *  the browser use its own default (5000). */
+    maxTestDurationMs?: number;
 }
 
 export declare interface RunCompleteEvent {

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { t as r } from "./relay-C8UTSEbG.js";
+import { t as r } from "./relay-NDt-wlXz.js";
 export {
   r as createTwdRelay
 };

package/dist/relay-CK82tv0w.cjs

@@ -0,0 +1 @@
+let o=require("ws");var P="/__twd/ws";function D(g,N){const E=N?.path??P,S=N?.onError,p=new o.WebSocketServer({noServer:!0});let t=null;const c=new Set;let l=!1,d=null,y=null;const O=12e4,m=1e4;function s(e,r,n){const a={type:"error",code:r,message:n};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(a))}function b(e){for(const r of c)r.readyState===o.WebSocket.OPEN&&r.send(e)}function T(e){const r={type:"connected",browser:t!==null&&t.readyState===o.WebSocket.OPEN};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(r))}function _(){b(JSON.stringify({type:"connected",browser:!1}))}function k(){d=Date.now(),y=setInterval(()=>{l&&d!==null&&Date.now()-d>O&&(l=!1,f(),b(JSON.stringify({type:"run:abandoned",reason:"heartbeat_timeout"})))},m)}function f(){d=null,y!==null&&(clearInterval(y),y=null)}function A(e){let r;try{r=JSON.parse(e)}catch{return}if(r.type==="heartbeat"){d=Date.now();return}r.type==="run:complete"&&(l=!1,f()),b(e)}function I(e,r){let n;try{n=JSON.parse(r)}catch{s(e,"INVALID_MESSAGE","Invalid JSON");return}if(!n.type){s(e,"INVALID_MESSAGE",'Missing "type" field');return}if(n.type==="run"){if(!t||t.readyState!==o.WebSocket.OPEN){s(e,"NO_BROWSER","No browser connected");return}if(l){s(e,"RUN_IN_PROGRESS",'A test run is already in progress. If the previous run appears stuck, the browser tab may be backgrounded and throttled — foreground the TWD tab (identified by the "[TWD …]" title prefix) or reload it. The relay also auto-clears the lock after 120s of heartbeat silence.');return}l=!0,k(),t.send(r);return}if(n.type==="status"){if(!t||t.readyState!==o.WebSocket.OPEN){s(e,"NO_BROWSER","No browser connected");return}t.send(r);return}s(e,"UNKNOWN_COMMAND",`Unknown command: ${n.type}`)}function R(e){let r=!1;const n=a=>{const W=typeof a=="string"?a:a.toString();if(!r){let u;try{u=JSON.parse(W)}catch{s(e,"INVALID_MESSAGE","Invalid JSON");return}if(u.type!=="hello"||u.role!=="browser"&&u.role!=="client"){s(e,"INVALID_MESSAGE",'First message must be a hello with role "browser" or "client"');return}r=!0,u.role==="browser"?(t&&t.readyState===o.WebSocket.OPEN&&t.close(1e3,"Replaced by new browser"),t=e,l=!1,f(),e.on("close",()=>{t===e&&(t=null,l=!1,f(),_())}),b(JSON.stringify({type:"connected",browser:!0})),e.on("message",i=>{A(typeof i=="string"?i:i.toString())})):(c.add(e),e.on("close",()=>{c.delete(e)}),T(e),e.on("message",i=>{I(e,typeof i=="string"?i:i.toString())})),e.removeListener("message",n)}};e.on("message",n),e.on("error",a=>{S&&S(a)})}const h=(e,r,n)=>{new URL(e.url??"/",`http://${e.headers.host??"localhost"}`).pathname===E&&p.handleUpgrade(e,r,n,a=>{R(a)})};return g.on("upgrade",h),p.on("error",e=>{S&&S(e)}),{close(){g.removeListener("upgrade",h),f();for(const e of c)e.close(1e3,"Relay shutting down");c.clear(),t&&t.readyState===o.WebSocket.OPEN&&t.close(1e3,"Relay shutting down"),t=null,l=!1,p.close()},get browserConnected(){return t!==null&&t.readyState===o.WebSocket.OPEN},get clientCount(){return c.size}}}Object.defineProperty(exports,"createTwdRelay",{enumerable:!0,get:function(){return D}});

package/dist/relay-NDt-wlXz.js

@@ -0,0 +1,148 @@
+import { WebSocket as a, WebSocketServer as P } from "ws";
+var C = "/__twd/ws";
+function k(N, h) {
+  const b = h?.path ?? C, y = h?.onError, g = new P({ noServer: !0 });
+  let t = null;
+  const c = /* @__PURE__ */ new Set();
+  let s = !1, f = null, S = null;
+  const O = 12e4, m = 1e4;
+  function l(e, r, n) {
+    const o = {
+      type: "error",
+      code: r,
+      message: n
+    };
+    e.readyState === a.OPEN && e.send(JSON.stringify(o));
+  }
+  function p(e) {
+    for (const r of c) r.readyState === a.OPEN && r.send(e);
+  }
+  function _(e) {
+    const r = {
+      type: "connected",
+      browser: t !== null && t.readyState === a.OPEN
+    };
+    e.readyState === a.OPEN && e.send(JSON.stringify(r));
+  }
+  function A() {
+    p(JSON.stringify({
+      type: "connected",
+      browser: !1
+    }));
+  }
+  function I() {
+    f = Date.now(), S = setInterval(() => {
+      s && f !== null && Date.now() - f > O && (s = !1, d(), p(JSON.stringify({
+        type: "run:abandoned",
+        reason: "heartbeat_timeout"
+      })));
+    }, m);
+  }
+  function d() {
+    f = null, S !== null && (clearInterval(S), S = null);
+  }
+  function T(e) {
+    let r;
+    try {
+      r = JSON.parse(e);
+    } catch {
+      return;
+    }
+    if (r.type === "heartbeat") {
+      f = Date.now();
+      return;
+    }
+    r.type === "run:complete" && (s = !1, d()), p(e);
+  }
+  function R(e, r) {
+    let n;
+    try {
+      n = JSON.parse(r);
+    } catch {
+      l(e, "INVALID_MESSAGE", "Invalid JSON");
+      return;
+    }
+    if (!n.type) {
+      l(e, "INVALID_MESSAGE", 'Missing "type" field');
+      return;
+    }
+    if (n.type === "run") {
+      if (!t || t.readyState !== a.OPEN) {
+        l(e, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      if (s) {
+        l(e, "RUN_IN_PROGRESS", 'A test run is already in progress. If the previous run appears stuck, the browser tab may be backgrounded and throttled — foreground the TWD tab (identified by the "[TWD …]" title prefix) or reload it. The relay also auto-clears the lock after 120s of heartbeat silence.');
+        return;
+      }
+      s = !0, I(), t.send(r);
+      return;
+    }
+    if (n.type === "status") {
+      if (!t || t.readyState !== a.OPEN) {
+        l(e, "NO_BROWSER", "No browser connected");
+        return;
+      }
+      t.send(r);
+      return;
+    }
+    l(e, "UNKNOWN_COMMAND", `Unknown command: ${n.type}`);
+  }
+  function D(e) {
+    let r = !1;
+    const n = (o) => {
+      const M = typeof o == "string" ? o : o.toString();
+      if (!r) {
+        let u;
+        try {
+          u = JSON.parse(M);
+        } catch {
+          l(e, "INVALID_MESSAGE", "Invalid JSON");
+          return;
+        }
+        if (u.type !== "hello" || u.role !== "browser" && u.role !== "client") {
+          l(e, "INVALID_MESSAGE", 'First message must be a hello with role "browser" or "client"');
+          return;
+        }
+        r = !0, u.role === "browser" ? (t && t.readyState === a.OPEN && t.close(1e3, "Replaced by new browser"), t = e, s = !1, d(), e.on("close", () => {
+          t === e && (t = null, s = !1, d(), A());
+        }), p(JSON.stringify({
+          type: "connected",
+          browser: !0
+        })), e.on("message", (i) => {
+          T(typeof i == "string" ? i : i.toString());
+        })) : (c.add(e), e.on("close", () => {
+          c.delete(e);
+        }), _(e), e.on("message", (i) => {
+          R(e, typeof i == "string" ? i : i.toString());
+        })), e.removeListener("message", n);
+      }
+    };
+    e.on("message", n), e.on("error", (o) => {
+      y && y(o);
+    });
+  }
+  const E = (e, r, n) => {
+    new URL(e.url ?? "/", `http://${e.headers.host ?? "localhost"}`).pathname === b && g.handleUpgrade(e, r, n, (o) => {
+      D(o);
+    });
+  };
+  return N.on("upgrade", E), g.on("error", (e) => {
+    y && y(e);
+  }), {
+    close() {
+      N.removeListener("upgrade", E), d();
+      for (const e of c) e.close(1e3, "Relay shutting down");
+      c.clear(), t && t.readyState === a.OPEN && t.close(1e3, "Relay shutting down"), t = null, s = !1, g.close();
+    },
+    get browserConnected() {
+      return t !== null && t.readyState === a.OPEN;
+    },
+    get clientCount() {
+      return c.size;
+    }
+  };
+}
+export {
+  k as t
+};

package/dist/vite.cjs.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("./relay-CpUORBd7.cjs");function n(r){let t="/";return{name:"twd-relay",configResolved(e){t=e.base},configureServer(e){if(!e.httpServer)return;const o=r?.path??t.replace(/\/$/,"")+"/__twd/ws",a=l.createTwdRelay(e.httpServer,{path:o});e.httpServer.on("close",()=>a.close())}}}exports.twdRemote=n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("./relay-CK82tv0w.cjs");function n(r){let t="/";return{name:"twd-relay",configResolved(e){t=e.base},configureServer(e){if(!e.httpServer)return;const o=r?.path??t.replace(/\/$/,"")+"/__twd/ws",a=l.createTwdRelay(e.httpServer,{path:o});e.httpServer.on("close",()=>a.close())}}}exports.twdRemote=n;

package/dist/vite.es.js

@@ -1,4 +1,4 @@
-import { t as n } from "./relay-C8UTSEbG.js";
+import { t as n } from "./relay-NDt-wlXz.js";
 function l(r) {
   let t = "/";
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twd-relay",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "WebSocket relay for TWD — enables AI agents and external tools to run and observe in-browser tests",
   "license": "MIT",
   "author": "BRIKEV",
@@ -66,6 +66,7 @@
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.0",
     "esbuild": "^0.27.4",
+    "happy-dom": "^15.11.7",
     "typescript": "^5.9.3",
     "vite": "^8.0.1",
     "vite-plugin-dts": "^4.5.4",

package/dist/relay-C8UTSEbG.js

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

package/dist/relay-CpUORBd7.cjs

@@ -1 +0,0 @@
-let o=require("ws");var R="/__twd/ws";function W(y,N){const p=N?.path??R,f=N?.onError,u=new o.WebSocketServer({noServer:!0});let t=null;const l=new Set;let a=!1;function c(e,n,r){const s={type:"error",code:n,message:r};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(s))}function S(e){for(const n of l)n.readyState===o.WebSocket.OPEN&&n.send(e)}function b(e){const n={type:"connected",browser:t!==null&&t.readyState===o.WebSocket.OPEN};e.readyState===o.WebSocket.OPEN&&e.send(JSON.stringify(n))}function O(){S(JSON.stringify({type:"connected",browser:!1}))}function E(e){let n;try{n=JSON.parse(e)}catch{return}n.type==="run:complete"&&(a=!1),S(e)}function h(e,n){let r;try{r=JSON.parse(n)}catch{c(e,"INVALID_MESSAGE","Invalid JSON");return}if(!r.type){c(e,"INVALID_MESSAGE",'Missing "type" field');return}if(r.type==="run"){if(!t||t.readyState!==o.WebSocket.OPEN){c(e,"NO_BROWSER","No browser connected");return}if(a){c(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){c(e,"NO_BROWSER","No browser connected");return}t.send(n);return}c(e,"UNKNOWN_COMMAND",`Unknown command: ${r.type}`)}function m(e){let n=!1;const r=s=>{const P=typeof s=="string"?s:s.toString();if(!n){let d;try{d=JSON.parse(P)}catch{c(e,"INVALID_MESSAGE","Invalid JSON");return}if(d.type!=="hello"||d.role!=="browser"&&d.role!=="client"){c(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,O())}),S(JSON.stringify({type:"connected",browser:!0})),e.on("message",i=>{E(typeof i=="string"?i:i.toString())})):(l.add(e),e.on("close",()=>{l.delete(e)}),b(e),e.on("message",i=>{h(e,typeof i=="string"?i:i.toString())})),e.removeListener("message",r)}};e.on("message",r),e.on("error",s=>{f&&f(s)})}const g=(e,n,r)=>{new URL(e.url??"/",`http://${e.headers.host??"localhost"}`).pathname===p&&u.handleUpgrade(e,n,r,s=>{m(s)})};return y.on("upgrade",g),u.on("error",e=>{f&&f(e)}),{close(){y.removeListener("upgrade",g);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,u.close()},get browserConnected(){return t!==null&&t.readyState===o.WebSocket.OPEN},get clientCount(){return l.size}}}Object.defineProperty(exports,"createTwdRelay",{enumerable:!0,get:function(){return W}});