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