tracereports 0.1.0 → 0.1.2

package/README.es.md

@@ -1,13 +1,12 @@
-# tracereports (cliente JavaScript)
-
-🌐 [English](README.md) · **Español**
-
-Cliente del servidor [TraceReports](../../README.es.md): Playwright Test (reporter + fixtures),
-Selenium WebDriver y cualquier runner. Node 18+, sin dependencias.
-
-```bash
-npm install --save-dev ../ruta/a/tracereports/client/js
-npm test                        # pruebas del cliente (node:test)
-```
-
-Documentación completa: [docs/es/javascript.md](../../docs/es/javascript.md).
+# tracereports (cliente JavaScript)
+
+🌐 [English](README.md) · **Español**
+
+Cliente del servidor [TraceReports](https://github.com/josemiguellopez/tracereports): Playwright Test (reporter + fixtures),
+Selenium WebDriver y cualquier runner. Node 18+, sin dependencias.
+
+```bash
+npm install --save-dev tracereports
+```
+
+Documentación completa: [docs/es/javascript.md](https://github.com/josemiguellopez/tracereports/blob/main/docs/es/javascript.md).

package/README.md

@@ -1,13 +1,12 @@
-# tracereports (JavaScript client)
-
-🌐 **English** · [Español](README.es.md)
-
-Client for the [TraceReports](../../README.md) server: Playwright Test (reporter + fixtures),
-Selenium WebDriver and any runner. Node 18+, no dependencies.
-
-```bash
-npm install --save-dev ../path/to/tracereports/client/js
-npm test                        # client tests (node:test)
-```
-
-Full documentation: [docs/en/javascript.md](../../docs/en/javascript.md).
+# tracereports (JavaScript client)
+
+🌐 **English** · [Español](README.es.md)
+
+Client for the [TraceReports](https://github.com/josemiguellopez/tracereports) server: Playwright Test (reporter + fixtures),
+Selenium WebDriver and any runner. Node 18+, no dependencies.
+
+```bash
+npm install --save-dev tracereports
+```
+
+Full documentation: [docs/en/javascript.md](https://github.com/josemiguellopez/tracereports/blob/main/docs/en/javascript.md).

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "tracereports",
-  "version": "0.1.0",
-  "description": "Cliente de TraceReports para JavaScript/TypeScript: Playwright Test (reporter + fixtures), Selenium WebDriver y cualquier runner.",
-  "keywords": [
-    "testing",
-    "test-reporting",
-    "playwright",
-    "selenium",
-    "e2e",
-    "qa",
-    "reporter",
-    "ai"
-  ],
-  "homepage": "https://github.com/josemiguellopez/tracereports#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/josemiguellopez/tracereports.git",
-    "directory": "client/js"
-  },
-  "bugs": {
-    "url": "https://github.com/josemiguellopez/tracereports/issues"
-  },
-  "author": "Jose Lopez",
-  "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "default": "./src/index.js"
-    },
-    "./reporter": "./src/reporter.js",
-    "./playwright": "./src/playwright.js",
-    "./selenium": "./src/selenium.js"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "README.es.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test \"test/*.test.js\""
-  },
-  "peerDependencies": {
-    "@playwright/test": ">=1.40"
-  },
-  "peerDependenciesMeta": {
-    "@playwright/test": {
-      "optional": true
-    }
-  },
-  "license": "Apache-2.0"
-}
+{
+  "name": "tracereports",
+  "version": "0.1.2",
+  "description": "TraceReports client for JavaScript/TypeScript: Playwright Test reporter and fixtures, Selenium WebDriver helpers and a client for any runner.",
+  "keywords": [
+    "testing",
+    "test-reporting",
+    "playwright",
+    "selenium",
+    "e2e",
+    "qa",
+    "reporter",
+    "ai"
+  ],
+  "homepage": "https://github.com/josemiguellopez/tracereports#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josemiguellopez/tracereports.git",
+    "directory": "client/js"
+  },
+  "bugs": {
+    "url": "https://github.com/josemiguellopez/tracereports/issues"
+  },
+  "author": "Jose Lopez",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./reporter": "./src/reporter.js",
+    "./playwright": "./src/playwright.js",
+    "./selenium": "./src/selenium.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.es.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "license": "Apache-2.0"
+}

package/src/dom.js

@@ -1,29 +1,29 @@
-// Snapshot de la página al fallar un test: entrada del "AI Locator Recommender". No es el HTML
-// completo, sino los elementos con los que se suele interactuar, con atributos y posición en
-// pantalla. El mismo script que usan los clientes Python y Go.
-
-/** Función que corre en el navegador (máximo 1500 elementos). */
-export function domSnapshotInPage() {
-  const sel = "a,button,input,select,textarea,label,summary,[role],[data-testid],[data-test-id],[data-test],[id],[name],[aria-label],[placeholder],h1,h2,h3,h4,h5,h6";
-  const out = [];
-  for (const el of document.querySelectorAll(sel)) {
-    if (out.length >= 1500) break;
-    const r = el.getBoundingClientRect();
-    const st = getComputedStyle(el);
-    const visible = r.width > 0 && r.height > 0 && st.visibility !== "hidden" && st.display !== "none" && st.opacity !== "0";
-    const testAttr = ["data-testid", "data-test-id", "data-test"].find((a) => el.hasAttribute(a)) || "";
-    const label = el.getAttribute("aria-label") || (el.labels && el.labels[0] ? el.labels[0].innerText : "") || "";
-    const text = el.tagName === "INPUT" || el.tagName === "TEXTAREA" ? "" : (el.innerText || "").trim().replace(/\s+/g, " ");
-    out.push({
-      tag: el.tagName.toLowerCase(), id: el.id || "", name: el.getAttribute("name") || "",
-      role: el.getAttribute("role") || "", testid: testAttr ? el.getAttribute(testAttr) : "", testid_attr: testAttr,
-      label: label.trim().slice(0, 120), placeholder: (el.getAttribute("placeholder") || "").slice(0, 120),
-      type: el.getAttribute("type") || "", text: text.slice(0, 120),
-      x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height), visible,
-    });
-  }
-  return { url: location.href, title: document.title, viewport: { w: innerWidth, h: innerHeight }, elements: out };
-}
-
-/** Script como texto, para Selenium (`driver.executeScript`) y otros drivers. */
-export const DOM_SCRIPT = `return (${domSnapshotInPage.toString()})();`;
+// Snapshot de la página al fallar un test: entrada del "AI Locator Recommender". No es el HTML
+// completo, sino los elementos con los que se suele interactuar, con atributos y posición en
+// pantalla. El mismo script que usan los clientes Python y Go.
+
+/** Función que corre en el navegador (máximo 1500 elementos). */
+export function domSnapshotInPage() {
+  const sel = "a,button,input,select,textarea,label,summary,[role],[data-testid],[data-test-id],[data-test],[id],[name],[aria-label],[placeholder],h1,h2,h3,h4,h5,h6";
+  const out = [];
+  for (const el of document.querySelectorAll(sel)) {
+    if (out.length >= 1500) break;
+    const r = el.getBoundingClientRect();
+    const st = getComputedStyle(el);
+    const visible = r.width > 0 && r.height > 0 && st.visibility !== "hidden" && st.display !== "none" && st.opacity !== "0";
+    const testAttr = ["data-testid", "data-test-id", "data-test"].find((a) => el.hasAttribute(a)) || "";
+    const label = el.getAttribute("aria-label") || (el.labels && el.labels[0] ? el.labels[0].innerText : "") || "";
+    const text = el.tagName === "INPUT" || el.tagName === "TEXTAREA" ? "" : (el.innerText || "").trim().replace(/\s+/g, " ");
+    out.push({
+      tag: el.tagName.toLowerCase(), id: el.id || "", name: el.getAttribute("name") || "",
+      role: el.getAttribute("role") || "", testid: testAttr ? el.getAttribute(testAttr) : "", testid_attr: testAttr,
+      label: label.trim().slice(0, 120), placeholder: (el.getAttribute("placeholder") || "").slice(0, 120),
+      type: el.getAttribute("type") || "", text: text.slice(0, 120),
+      x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height), visible,
+    });
+  }
+  return { url: location.href, title: document.title, viewport: { w: innerWidth, h: innerHeight }, elements: out };
+}
+
+/** Script como texto, para Selenium (`driver.executeScript`) y otros drivers. */
+export const DOM_SCRIPT = `return (${domSnapshotInPage.toString()})();`;

package/src/selenium.js

@@ -1,49 +1,49 @@
-// Selenium WebDriver (selenium-webdriver) con TraceReports. Sirve con cualquier runner
-// (node:test, Mocha, Jest…): no importa selenium-webdriver, usa el `driver` que le pases.
-//
-//   import { TraceReports } from "tracereports";
-//   import { withDriver, screenshot } from "tracereports/selenium";
-//
-//   const cr = new TraceReports();
-//   await cr.startRun("Regresión web", { environment: "chrome" });
-//   await cr.test("Login correcto", withDriver(driver, { key: "login.test.js > ok" }), async (t) => {
-//     await driver.get(URL);
-//     t.screenshot(await screenshot(driver), "Formulario de login");
-//   });
-//   await cr.finishRun();
-//
-// Si el test falla, `withDriver` adjunta la captura del momento y el snapshot del DOM (con él el
-// reporte recomienda selectores cuando se rompe un locator). Selenium no expone la red del
-// navegador: para la pestaña "Red" usa Playwright o envía las llamadas con `t.network([...])`.
-
-import { DOM_SCRIPT } from "./dom.js";
-
-/** Captura de pantalla como base64 (lo que acepta `t.screenshot`), o null. */
-export async function screenshot(driver) {
-  try {
-    return await driver.takeScreenshot();
-  } catch {
-    return null;
-  }
-}
-
-/** Snapshot de los elementos de la página, o null si el navegador ya no responde. */
-export async function captureDom(driver) {
-  try {
-    return await driver.executeScript(DOM_SCRIPT);
-  } catch {
-    return null;
-  }
-}
-
-/** Opciones para `cr.test(...)` que, al fallar, adjuntan captura y DOM desde `driver`. */
-export function withDriver(driver, opts = {}) {
-  return {
-    ...opts,
-    async onFailure(t, err) {
-      t.screenshot(await screenshot(driver), "Captura al fallar", "FAIL");
-      t.dom(await captureDom(driver));
-      if (opts.onFailure) await opts.onFailure(t, err);
-    },
-  };
-}
+// Selenium WebDriver (selenium-webdriver) con TraceReports. Sirve con cualquier runner
+// (node:test, Mocha, Jest…): no importa selenium-webdriver, usa el `driver` que le pases.
+//
+//   import { TraceReports } from "tracereports";
+//   import { withDriver, screenshot } from "tracereports/selenium";
+//
+//   const cr = new TraceReports();
+//   await cr.startRun("Regresión web", { environment: "chrome" });
+//   await cr.test("Login correcto", withDriver(driver, { key: "login.test.js > ok" }), async (t) => {
+//     await driver.get(URL);
+//     t.screenshot(await screenshot(driver), "Formulario de login");
+//   });
+//   await cr.finishRun();
+//
+// Si el test falla, `withDriver` adjunta la captura del momento y el snapshot del DOM (con él el
+// reporte recomienda selectores cuando se rompe un locator). Selenium no expone la red del
+// navegador: para la pestaña "Red" usa Playwright o envía las llamadas con `t.network([...])`.
+
+import { DOM_SCRIPT } from "./dom.js";
+
+/** Captura de pantalla como base64 (lo que acepta `t.screenshot`), o null. */
+export async function screenshot(driver) {
+  try {
+    return await driver.takeScreenshot();
+  } catch {
+    return null;
+  }
+}
+
+/** Snapshot de los elementos de la página, o null si el navegador ya no responde. */
+export async function captureDom(driver) {
+  try {
+    return await driver.executeScript(DOM_SCRIPT);
+  } catch {
+    return null;
+  }
+}
+
+/** Opciones para `cr.test(...)` que, al fallar, adjuntan captura y DOM desde `driver`. */
+export function withDriver(driver, opts = {}) {
+  return {
+    ...opts,
+    async onFailure(t, err) {
+      t.screenshot(await screenshot(driver), "Captura al fallar", "FAIL");
+      t.dom(await captureDom(driver));
+      if (opts.onFailure) await opts.onFailure(t, err);
+    },
+  };
+}

package/src/transport.js

@@ -1,157 +1,157 @@
-// Transporte del cliente: la evidencia sale en segundo plano, sin frenar los tests.
-//
-// - Cola acotada (cantidad y bytes) que se envía en orden, de a un evento.
-// - Reintentos con backoff ante caídas de red, timeouts, 5xx, 408 y 429. Cada envío lleva una
-//   Idempotency-Key: si el servidor ya lo aplicó, el reintento no lo duplica.
-// - Circuito: si el servidor no responde, las llamadas que necesitan respuesta (crear ejecución o
-//   test) fallan al instante durante un rato en vez de esperar su timeout en cada test.
-// - Cola llena: los eventos nuevos se descartan (se conservan los ya encolados) y se cuentan.
-//
-// A diferencia del cliente Python no hay spool en disco: lo que no se pudo enviar al cerrar se
-// informa en `delivery.lost`.
-
-import { randomUUID } from "node:crypto";
-
-const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);
-export const limits = { circuitMs: 30_000, maxBackoffMs: 30_000 };
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-export class Sender {
-  /**
-   * @param {string} baseUrl
-   * @param {() => Record<string,string>} headers
-   */
-  constructor(baseUrl, headers, { maxItems = 5000, maxBytes = 64 << 20 } = {}) {
-    this.baseUrl = baseUrl;
-    this.headers = headers;
-    this.maxItems = maxItems;
-    this.maxBytes = maxBytes;
-    this.queue = [];
-    this.bytes = 0;
-    this.inflight = null;
-    this.downUntil = 0;
-    this.running = false;
-    this.waiters = [];
-    this.stats = { sent: 0, retried: 0, rejected: 0, dropped: 0, lost: 0 };
-  }
-
-  serverDown() {
-    return Date.now() < this.downUntil;
-  }
-
-  get pending() {
-    return this.queue.length + (this.inflight ? 1 : 0);
-  }
-
-  /** Un intento. Devuelve {kind: "ok"|"retry"|"reject", data}. */
-  async post(item) {
-    try {
-      const res = await fetch(this.baseUrl + item.path, {
-        method: item.method,
-        body: item.body,
-        headers: { ...this.headers(), "Content-Type": item.contentType, Accept: "application/json", "Idempotency-Key": item.key },
-        signal: AbortSignal.timeout(item.timeout),
-      });
-      const text = await res.text();
-      if (res.ok) {
-        this.downUntil = 0;
-        return { kind: "ok", data: text ? JSON.parse(text) : {} };
-      }
-      if (RETRYABLE.has(res.status)) return { kind: "retry" };
-      const hint = res.status === 401 ? " (configura el token: new TraceReports({ token }), la variable TRACEREPORTS_TOKEN o TRACEREPORTS_TOKEN en el .env del proyecto)" : "";
-      console.warn(`tracereports: ${item.method} ${item.path} -> HTTP ${res.status} ${text.slice(0, 300)}${hint}`);
-      return { kind: "reject" };
-    } catch (err) {
-      if (!this.serverDown()) console.warn(`tracereports: ${item.method} ${item.path} falló: ${err.cause?.code || err.message}`);
-      this.downUntil = Date.now() + limits.circuitMs;
-      return { kind: "retry" };
-    }
-  }
-
-  /** Llamada cuya respuesta se necesita (ids): reintentos cortos, misma Idempotency-Key. */
-  async sendNow(method, path, body, contentType, timeout, retries = 2, { ignoreCircuit = false } = {}) {
-    if (this.serverDown() && !ignoreCircuit) return null;
-    const item = { method, path, body, contentType, timeout, key: randomUUID() };
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      const { kind, data } = await this.post(item);
-      if (kind === "ok") {
-        this.stats.sent++;
-        return data;
-      }
-      if (kind === "reject" || (this.serverDown() && !ignoreCircuit) || attempt === retries) break;
-      this.stats.retried++;
-      await sleep([300, 1000, 2000][Math.min(attempt, 2)]);
-    }
-    return null;
-  }
-
-  /** Encola un evento de evidencia. false si la cola está llena (se cuenta en stats.dropped). */
-  enqueue(method, path, body, contentType, timeout) {
-    const size = body?.length ?? 0;
-    if (this.pending + 1 > this.maxItems || this.bytes + size > this.maxBytes) {
-      if (this.stats.dropped++ === 0) {
-        console.warn(`tracereports: la cola de envío está llena (${this.maxItems} eventos); se descartan los eventos nuevos`);
-      }
-      return false;
-    }
-    this.queue.push({ method, path, body, contentType, timeout, key: randomUUID(), attempts: 0, size });
-    this.bytes += size;
-    if (!this.running) this.run();
-    return true;
-  }
-
-  async run() {
-    this.running = true;
-    while (this.queue.length) {
-      const item = this.queue.shift();
-      this.inflight = item;
-      let kind;
-      try {
-        ({ kind } = await this.post(item));
-      } catch {
-        kind = "retry";
-      }
-      this.inflight = null;
-      if (item.abandoned) continue; // flush venció y se contó como perdido
-      if (kind === "retry") {
-        item.attempts++;
-        this.stats.retried++;
-        this.queue.unshift(item);
-        await sleep(Math.min(limits.maxBackoffMs, 500 * 2 ** Math.min(item.attempts, 6)));
-        continue;
-      }
-      this.bytes -= item.size;
-      this.stats[kind === "ok" ? "sent" : "rejected"]++;
-      this.notify();
-    }
-    this.running = false;
-    this.notify();
-  }
-
-  notify() {
-    if (this.pending) return;
-    for (const w of this.waiters.splice(0)) w();
-  }
-
-  /** Espera a que la cola se vacíe (máx. timeoutMs). Devuelve lo que quedó pendiente. */
-  async flush(timeoutMs) {
-    if (!this.pending) return 0;
-    await Promise.race([new Promise((r) => this.waiters.push(r)), sleep(timeoutMs)]);
-    return this.pending;
-  }
-
-  /** Descarta lo pendiente (al cerrar, tras el flush) y lo cuenta como perdido. */
-  abandon() {
-    const items = [...this.queue, ...(this.inflight ? [this.inflight] : [])];
-    for (const it of items) it.abandoned = true;
-    this.queue.length = 0;
-    this.inflight = null;
-    this.bytes = 0;
-    this.stats.lost += items.length;
-    if (items.length) {
-      console.warn(`tracereports: ${items.length} eventos de evidencia no se pudieron enviar y se perdieron`);
-    }
-    return items.length;
-  }
-}
+// Transporte del cliente: la evidencia sale en segundo plano, sin frenar los tests.
+//
+// - Cola acotada (cantidad y bytes) que se envía en orden, de a un evento.
+// - Reintentos con backoff ante caídas de red, timeouts, 5xx, 408 y 429. Cada envío lleva una
+//   Idempotency-Key: si el servidor ya lo aplicó, el reintento no lo duplica.
+// - Circuito: si el servidor no responde, las llamadas que necesitan respuesta (crear ejecución o
+//   test) fallan al instante durante un rato en vez de esperar su timeout en cada test.
+// - Cola llena: los eventos nuevos se descartan (se conservan los ya encolados) y se cuentan.
+//
+// A diferencia del cliente Python no hay spool en disco: lo que no se pudo enviar al cerrar se
+// informa en `delivery.lost`.
+
+import { randomUUID } from "node:crypto";
+
+const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);
+export const limits = { circuitMs: 30_000, maxBackoffMs: 30_000 };
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class Sender {
+  /**
+   * @param {string} baseUrl
+   * @param {() => Record<string,string>} headers
+   */
+  constructor(baseUrl, headers, { maxItems = 5000, maxBytes = 64 << 20 } = {}) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+    this.maxItems = maxItems;
+    this.maxBytes = maxBytes;
+    this.queue = [];
+    this.bytes = 0;
+    this.inflight = null;
+    this.downUntil = 0;
+    this.running = false;
+    this.waiters = [];
+    this.stats = { sent: 0, retried: 0, rejected: 0, dropped: 0, lost: 0 };
+  }
+
+  serverDown() {
+    return Date.now() < this.downUntil;
+  }
+
+  get pending() {
+    return this.queue.length + (this.inflight ? 1 : 0);
+  }
+
+  /** Un intento. Devuelve {kind: "ok"|"retry"|"reject", data}. */
+  async post(item) {
+    try {
+      const res = await fetch(this.baseUrl + item.path, {
+        method: item.method,
+        body: item.body,
+        headers: { ...this.headers(), "Content-Type": item.contentType, Accept: "application/json", "Idempotency-Key": item.key },
+        signal: AbortSignal.timeout(item.timeout),
+      });
+      const text = await res.text();
+      if (res.ok) {
+        this.downUntil = 0;
+        return { kind: "ok", data: text ? JSON.parse(text) : {} };
+      }
+      if (RETRYABLE.has(res.status)) return { kind: "retry" };
+      const hint = res.status === 401 ? " (configura el token: new TraceReports({ token }), la variable TRACEREPORTS_TOKEN o TRACEREPORTS_TOKEN en el .env del proyecto)" : "";
+      console.warn(`tracereports: ${item.method} ${item.path} -> HTTP ${res.status} ${text.slice(0, 300)}${hint}`);
+      return { kind: "reject" };
+    } catch (err) {
+      if (!this.serverDown()) console.warn(`tracereports: ${item.method} ${item.path} falló: ${err.cause?.code || err.message}`);
+      this.downUntil = Date.now() + limits.circuitMs;
+      return { kind: "retry" };
+    }
+  }
+
+  /** Llamada cuya respuesta se necesita (ids): reintentos cortos, misma Idempotency-Key. */
+  async sendNow(method, path, body, contentType, timeout, retries = 2, { ignoreCircuit = false } = {}) {
+    if (this.serverDown() && !ignoreCircuit) return null;
+    const item = { method, path, body, contentType, timeout, key: randomUUID() };
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      const { kind, data } = await this.post(item);
+      if (kind === "ok") {
+        this.stats.sent++;
+        return data;
+      }
+      if (kind === "reject" || (this.serverDown() && !ignoreCircuit) || attempt === retries) break;
+      this.stats.retried++;
+      await sleep([300, 1000, 2000][Math.min(attempt, 2)]);
+    }
+    return null;
+  }
+
+  /** Encola un evento de evidencia. false si la cola está llena (se cuenta en stats.dropped). */
+  enqueue(method, path, body, contentType, timeout) {
+    const size = body?.length ?? 0;
+    if (this.pending + 1 > this.maxItems || this.bytes + size > this.maxBytes) {
+      if (this.stats.dropped++ === 0) {
+        console.warn(`tracereports: la cola de envío está llena (${this.maxItems} eventos); se descartan los eventos nuevos`);
+      }
+      return false;
+    }
+    this.queue.push({ method, path, body, contentType, timeout, key: randomUUID(), attempts: 0, size });
+    this.bytes += size;
+    if (!this.running) this.run();
+    return true;
+  }
+
+  async run() {
+    this.running = true;
+    while (this.queue.length) {
+      const item = this.queue.shift();
+      this.inflight = item;
+      let kind;
+      try {
+        ({ kind } = await this.post(item));
+      } catch {
+        kind = "retry";
+      }
+      this.inflight = null;
+      if (item.abandoned) continue; // flush venció y se contó como perdido
+      if (kind === "retry") {
+        item.attempts++;
+        this.stats.retried++;
+        this.queue.unshift(item);
+        await sleep(Math.min(limits.maxBackoffMs, 500 * 2 ** Math.min(item.attempts, 6)));
+        continue;
+      }
+      this.bytes -= item.size;
+      this.stats[kind === "ok" ? "sent" : "rejected"]++;
+      this.notify();
+    }
+    this.running = false;
+    this.notify();
+  }
+
+  notify() {
+    if (this.pending) return;
+    for (const w of this.waiters.splice(0)) w();
+  }
+
+  /** Espera a que la cola se vacíe (máx. timeoutMs). Devuelve lo que quedó pendiente. */
+  async flush(timeoutMs) {
+    if (!this.pending) return 0;
+    await Promise.race([new Promise((r) => this.waiters.push(r)), sleep(timeoutMs)]);
+    return this.pending;
+  }
+
+  /** Descarta lo pendiente (al cerrar, tras el flush) y lo cuenta como perdido. */
+  abandon() {
+    const items = [...this.queue, ...(this.inflight ? [this.inflight] : [])];
+    for (const it of items) it.abandoned = true;
+    this.queue.length = 0;
+    this.inflight = null;
+    this.bytes = 0;
+    this.stats.lost += items.length;
+    if (items.length) {
+      console.warn(`tracereports: ${items.length} eventos de evidencia no se pudieron enviar y se perdieron`);
+    }
+    return items.length;
+  }
+}