tracereports 0.1.0

package/README.es.md

@@ -0,0 +1,13 @@
+# 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).

package/README.md

@@ -0,0 +1,13 @@
+# 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).

package/package.json

@@ -0,0 +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"
+}

package/src/context.js

@@ -0,0 +1,33 @@
+// Contexto de la ejecución: rama y commit. El servidor solo compara una ejecución con otras del
+// mismo proyecto, ambiente y rama. Se leen de las variables de los CI más comunes o de git.
+
+import { execFileSync } from "node:child_process";
+
+const BRANCH_VARS = ["TRACEREPORTS_BRANCH", "GITHUB_HEAD_REF", "GITHUB_REF_NAME", "CI_COMMIT_REF_NAME", "BITBUCKET_BRANCH",
+  "BUILD_SOURCEBRANCHNAME", "BRANCH_NAME", "CIRCLE_BRANCH", "GIT_BRANCH"];
+const COMMIT_VARS = ["TRACEREPORTS_COMMIT", "GITHUB_SHA", "CI_COMMIT_SHA", "BITBUCKET_COMMIT", "BUILD_SOURCEVERSION", "CIRCLE_SHA1", "GIT_COMMIT"];
+
+function git(...args) {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function firstEnv(vars) {
+  for (const v of vars) {
+    const value = (process.env[v] || "").trim();
+    if (value) return value.replace(/^origin\//, "");
+  }
+  return "";
+}
+
+export function detectBranch() {
+  const branch = firstEnv(BRANCH_VARS) || git("rev-parse", "--abbrev-ref", "HEAD");
+  return branch === "HEAD" ? "" : branch;
+}
+
+export function detectCommit() {
+  return firstEnv(COMMIT_VARS) || git("rev-parse", "HEAD");
+}

package/src/dom.js

@@ -0,0 +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()})();`;

package/src/env.js

@@ -0,0 +1,95 @@
+// Variables de entorno del cliente: TRACEREPORTS_<NOMBRE>.
+//
+// Si la variable no está en el entorno, se busca en el archivo .env del proyecto (el mismo que lee
+// el servidor): el token vive en un solo lugar, ignorado por git, sin definirlo en cada terminal ni
+// de forma global. Las variables del entorno siempre ganan (en CI llegan como secrets). Del archivo
+// solo se usan las claves TRACEREPORTS_*.
+//
+// El .env se busca desde la carpeta actual hacia arriba, hasta la raíz del repositorio (la carpeta
+// con .git). TRACEREPORTS_ENV_FILE indica otro archivo, u "off" para no leer ninguno.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+const PREFIX = "TRACEREPORTS_";
+
+let fileValues = null;
+let filePath = null;
+
+/** Líneas KEY=VALUE con las mismas reglas que el servidor. */
+export function parseEnvFile(file) {
+  const values = {};
+  let text;
+  try {
+    text = readFileSync(file, "utf8").replace(/^/, "");
+  } catch {
+    return values;
+  }
+  for (const raw of text.split(/\r?\n/)) {
+    let line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export ")) line = line.slice("export ".length);
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key || /[ \t]/.test(key)) continue;
+    let val = line.slice(eq + 1).trim();
+    if (val.length >= 2 && val[0] === val[val.length - 1] && (val[0] === '"' || val[0] === "'")) {
+      val = val.slice(1, -1);
+    } else if (val.includes(" #")) {
+      val = val.slice(0, val.indexOf(" #")).trim();
+    }
+    values[key] = val;
+  }
+  return values;
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** El .env que corresponde, o null si no hay o está desactivado. */
+export function findEnvFile(start = process.cwd()) {
+  const explicit = process.env[`${PREFIX}ENV_FILE`];
+  if (explicit) return explicit.trim().toLowerCase() === "off" ? null : explicit;
+  let dir = path.resolve(start);
+  for (;;) {
+    const candidate = path.join(dir, ".env");
+    if (isFile(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (existsSync(path.join(dir, ".git")) || parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function fromFile() {
+  if (fileValues === null) {
+    filePath = findEnvFile();
+    const all = filePath ? parseEnvFile(filePath) : {};
+    fileValues = Object.fromEntries(Object.entries(all).filter(([k]) => k.startsWith(PREFIX)));
+  }
+  return fileValues;
+}
+
+/** Ruta del .env del que se leyó alguna variable (para los mensajes), o null. */
+export function envFileInUse() {
+  return Object.keys(fromFile()).length ? filePath : null;
+}
+
+/** Vuelve a buscar el .env en la próxima lectura (tests). */
+export function resetEnvFile() {
+  fileValues = null;
+  filePath = null;
+}
+
+/** TRACEREPORTS_<name>: primero del entorno, después del .env del proyecto. */
+export function env(name, fallback = undefined) {
+  for (const v of [process.env[PREFIX + name], fromFile()[PREFIX + name]]) {
+    if (v !== undefined && v !== "") return v;
+  }
+  return fallback;
+}

package/src/index.d.ts

@@ -0,0 +1,58 @@
+// Tipos de tracereports (cliente JavaScript).
+
+export interface Delivery {
+  sent: number; retried: number; rejected: number; dropped: number; lost: number; pending: number; unregisteredTests: number;
+  /** 1 si el servidor no confirmó el cierre de la ejecución. */
+  runNotClosed: number;
+}
+
+export interface TraceReportsOptions {
+  baseUrl?: string; token?: string; enabled?: boolean; timeoutMs?: number; uploadTimeoutMs?: number;
+  flushTimeoutMs?: number; maxQueueItems?: number; maxQueueMB?: number;
+}
+
+export interface RunOptions { environment?: string; project?: string; branch?: string; commit?: string; framework?: string }
+
+export interface TestOptions {
+  category?: string; description?: string; key?: string; suite?: string; params?: string; worker?: string | number;
+  status?: string; onFailure?: (t: TraceTest, err: unknown) => unknown | Promise<unknown>;
+}
+
+export type Status = "INFO" | "PASS" | "FAIL" | "WARNING" | "SKIP";
+
+export interface Connection {
+  method: string; url: string; status?: number; status_text?: string; mime_type?: string; resource_type?: string;
+  failed?: boolean; error_text?: string; started_at?: number; duration_ms?: number | null;
+  request_headers?: Record<string, string>; post_data?: string; response_headers?: Record<string, string>;
+  response_body?: string; body_size?: number; expected?: boolean;
+}
+
+export class TraceReports {
+  constructor(opts?: TraceReportsOptions);
+  baseUrl: string; runId: number | null; runCreated: boolean; enabled: boolean;
+  readonly delivery: Delivery;
+  readonly reportUrl: string;
+  deliveryProblems(): number;
+  startRun(name: string, opts?: RunOptions): Promise<number | null>;
+  joinRun(runId: number | string): number | null;
+  finishRun(opts?: { interrupted?: boolean }): Promise<unknown>;
+  flush(timeoutMs?: number): Promise<number>;
+  startTest(name: string, opts?: TestOptions): Promise<TraceTest>;
+  test<T>(name: string, fn: (t: TraceTest) => T | Promise<T>): Promise<T>;
+  test<T>(name: string, opts: TestOptions, fn: (t: TraceTest) => T | Promise<T>): Promise<T>;
+}
+
+export class TraceTest {
+  readonly id: number | null; readonly active: boolean; attempts: number;
+  log(status: Status, message: string, timestamp?: number): void;
+  info(message: string): void; pass(message: string): void; fail(message: string): void; warn(message: string): void; skip(message: string): void;
+  screenshot(image: Uint8Array | string | null, message?: string, status?: Status): void;
+  expectResponse(status: number | number[], opts?: { url?: string; method?: string }): void;
+  network(connections: Connection[], opts?: { maxBodyKB?: number; batchSize?: number }): { stored: number; errors: number };
+  dom(snapshot: unknown): void;
+  finish(status?: Status | "", opts?: { errorMessage?: string; errorTrace?: string; error?: unknown; attempts?: number }): void;
+}
+
+export const DOM_SCRIPT: string;
+
+export function domSnapshotInPage(): unknown;

package/src/index.js

@@ -0,0 +1,296 @@
+// Cliente de TraceReports para JavaScript/TypeScript (Node 18+, sin dependencias).
+//
+//   import { TraceReports } from "tracereports";
+//
+//   const cr = new TraceReports();                       // $TRACEREPORTS_URL o http://localhost:8080
+//   await cr.startRun("Regresión web", { environment: "staging" });
+//   const t = await cr.startTest("Login", { key: "login.spec.js > admin entra", category: "smoke" });
+//   t.info("Abrir el login");
+//   t.screenshot(await page.screenshot(), "Formulario");   // Playwright (Buffer)
+//   t.screenshot(await driver.takeScreenshot(), "Form");   // Selenium (base64)
+//   t.finish("PASS");
+//   await cr.finishRun();                                  // espera la cola y cierra la ejecución
+//
+// Nunca rompe ni frena la suite: la evidencia sale en segundo plano con reintentos e
+// Idempotency-Key (sin duplicados); si el servidor no responde, los métodos siguen funcionando
+// como no-op y `cr.delivery` dice qué no llegó.
+
+import path from "node:path";
+import { detectBranch, detectCommit } from "./context.js";
+import { env } from "./env.js";
+import { Sender } from "./transport.js";
+
+export const VERSION = "0.1.0";
+const STATUSES = new Set(["INFO", "PASS", "FAIL", "WARNING", "SKIP"]);
+const truthy = (v) => ["1", "true", "yes"].includes(String(v || "").toLowerCase());
+
+export class TraceReports {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.baseUrl]  default $TRACEREPORTS_URL o http://localhost:8080
+   * @param {string} [opts.token]    token de la API (TRACEREPORTS_TOKEN del servidor)
+   * @param {boolean} [opts.enabled] false (o $TRACEREPORTS_DISABLED=1) apaga todo
+   * @param {number} [opts.timeoutMs]       por request JSON (default 3000)
+   * @param {number} [opts.uploadTimeoutMs] por captura o lote de red (default 15000)
+   * @param {number} [opts.flushTimeoutMs]  cuánto espera finishRun la cola (default $TRACEREPORTS_FLUSH_TIMEOUT s o 30 s)
+   * @param {number} [opts.maxQueueItems]   default 5000
+   * @param {number} [opts.maxQueueMB]      default 64
+   */
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl || env("URL") || "http://localhost:8080").replace(/\/+$/, "");
+    this.token = opts.token ?? env("TOKEN", "");
+    this.enabled = (opts.enabled ?? true) && !truthy(env("DISABLED"));
+    this.timeoutMs = opts.timeoutMs ?? 3000;
+    this.uploadTimeoutMs = opts.uploadTimeoutMs ?? 15000;
+    this.flushTimeoutMs = opts.flushTimeoutMs ?? (Number(env("FLUSH_TIMEOUT")) * 1000 || 30_000);
+    this.sender = new Sender(this.baseUrl, () => this.headers(), {
+      maxItems: opts.maxQueueItems ?? 5000,
+      maxBytes: (opts.maxQueueMB ?? 64) << 20,
+    });
+    this.runId = null;
+    this.runCreated = false;
+    this.runNotClosed = false;
+    this.unregisteredTests = 0;
+  }
+
+  headers() {
+    const h = { "User-Agent": `tracereports-js/${VERSION}` };
+    if (this.token) h.Authorization = `Bearer ${this.token}`;
+    return h;
+  }
+
+  /** sent, retried, rejected (4xx), dropped (cola llena), lost, pending y unregisteredTests. */
+  /**
+   * sent, retried, rejected (4xx), dropped (cola llena), lost, pending, unregisteredTests y
+   * runNotClosed (1 si el servidor no confirmó el cierre de la ejecución: quedó abierta).
+   */
+  get delivery() {
+    return { ...this.sender.stats, pending: this.sender.pending, unregisteredTests: this.unregisteredTests,
+      runNotClosed: this.runNotClosed ? 1 : 0 };
+  }
+
+  /** Eventos que no llegaron al servidor (incluye un cierre de ejecución no confirmado). */
+  deliveryProblems() {
+    const d = this.delivery;
+    return d.rejected + d.dropped + d.lost + d.pending + d.unregisteredTests + d.runNotClosed;
+  }
+
+  get reportUrl() {
+    return this.runId ? `${this.baseUrl}/#run=${this.runId}&view=dashboard` : "";
+  }
+
+  async request(method, apiPath, payload) {
+    if (!this.enabled) return null;
+    return this.sender.sendNow(method, apiPath, JSON.stringify(payload), "application/json", this.timeoutMs);
+  }
+
+  emit(method, apiPath, body, contentType = "application/json", timeout = this.timeoutMs) {
+    if (!this.enabled) return false;
+    return this.sender.enqueue(method, apiPath, body, contentType, timeout);
+  }
+
+  // ─── ejecuciones ──────────────────────────────────────────────────────
+
+  /**
+   * Crea la ejecución. Con $TRACEREPORTS_RUN_ID se une a una ya creada (shards de CI) y no la cierra.
+   * `project` (default $TRACEREPORTS_PROJECT o la carpeta actual), `branch` y `commit` (default: CI o
+   * git) definen el contexto: historial y comparaciones solo usan ejecuciones del mismo proyecto,
+   * ambiente y rama.
+   */
+  async startRun(name, { environment = "", project, branch, commit, framework = "" } = {}) {
+    if (env("RUN_ID")) return this.joinRun(env("RUN_ID"));
+    const res = await this.request("POST", "/api/v1/runs", {
+      name,
+      environment,
+      project: project ?? env("PROJECT") ?? path.basename(process.cwd()),
+      branch: branch ?? detectBranch(),
+      commit: commit ?? detectCommit(),
+      framework,
+    });
+    this.runId = res?.run_id ?? null;
+    this.runCreated = Boolean(this.runId);
+    if (this.enabled && !this.runId) {
+      console.warn(`tracereports: no se pudo crear la ejecución en ${this.baseUrl}; los tests siguen sin reporte.`);
+    }
+    return this.runId;
+  }
+
+  /** Reporta en una ejecución creada en otro proceso; quien la creó la cierra. */
+  joinRun(runId) {
+    this.runId = runId ? Number(runId) : null;
+    this.runCreated = false;
+    return this.runId;
+  }
+
+  /** Espera la cola (flushTimeoutMs) y cierra la ejecución. interrupted: incompleta, nunca verde. */
+  async finishRun({ interrupted = false } = {}) {
+    await this.flush();
+    this.sender.abandon();
+    if (!this.runId || !this.runCreated || !this.enabled) return null; // unido a otra: la cierra su dueño
+    // el cierre importa más que un paso: más reintentos, siempre con la misma Idempotency-Key
+    const res = await this.sender.sendNow("PATCH", `/api/v1/runs/${this.runId}/finish`,
+      JSON.stringify({ interrupted }), "application/json", this.timeoutMs, 4, { ignoreCircuit: true });
+    this.runNotClosed = res == null;
+    if (this.runNotClosed) {
+      console.warn(`tracereports: el servidor no confirmó el cierre de la ejecución #${this.runId}: quedó abierta ` +
+        `(ciérrala con PATCH ${this.baseUrl}/api/v1/runs/${this.runId}/finish)`);
+    }
+    return res;
+  }
+
+  /** Espera a que la evidencia encolada se envíe. Devuelve lo que quedó pendiente. */
+  flush(timeoutMs = this.flushTimeoutMs) {
+    return this.sender.flush(timeoutMs);
+  }
+
+  // ─── tests ────────────────────────────────────────────────────────────
+
+  /**
+   * Inicia un test. `key` es su identidad estable dentro del proyecto (archivo + título): el
+   * historial y la detección de flaky la siguen. Sin key, el servidor usa el nombre.
+   * Devuelve siempre un TraceTest (no-op si el servidor no respondió).
+   */
+  async startTest(name, { category = "", description = "", key = "", suite = "", params = "", worker = "" } = {}) {
+    if (!this.runId) return new TraceTest(this, null);
+    const res = await this.request("POST", `/api/v1/runs/${this.runId}/tests`,
+      { name, category, description, key, suite, params, worker: String(worker ?? "") });
+    if (this.enabled && !res?.test_id) this.unregisteredTests++;
+    return new TraceTest(this, res?.test_id ?? null);
+  }
+
+  /**
+   * Corre `fn` como un test: lo inicia, lo cierra según el resultado y, si falla, adjunta la
+   * captura y el snapshot de `onFailure` (opcional). El error se vuelve a lanzar.
+   */
+  async test(name, opts, fn) {
+    if (typeof opts === "function") [fn, opts] = [opts, {}];
+    const t = await this.startTest(name, opts);
+    try {
+      const out = await fn(t);
+      t.finish(opts.status);
+      return out;
+    } catch (err) {
+      if (opts.onFailure) {
+        try { await opts.onFailure(t, err); } catch { /* la evidencia nunca rompe el test */ }
+      }
+      t.fail(`${err?.name || "Error"}: ${err?.message ?? err}`);
+      t.finish("FAIL", { error: err });
+      throw err;
+    }
+  }
+}
+
+export class TraceTest {
+  constructor(cr, id) {
+    this.cr = cr;
+    this.id = id;
+    this.expected = [];
+    this.attempts = 1;
+  }
+
+  get active() {
+    return Boolean(this.id && this.cr.enabled);
+  }
+
+  /** Paso del test. `timestamp` (ms) permite registrar la hora real en que ocurrió. */
+  log(status, message, timestamp = Date.now()) {
+    status = String(status || "INFO").toUpperCase();
+    if (!this.active || !STATUSES.has(status)) return;
+    this.cr.emit("POST", `/api/v1/tests/${this.id}/logs`,
+      JSON.stringify({ status, message: String(message), timestamp: Math.round(timestamp) }));
+  }
+
+  info(m) { this.log("INFO", m); }
+  pass(m) { this.log("PASS", m); }
+  fail(m) { this.log("FAIL", m); }
+  warn(m) { this.log("WARNING", m); }
+  skip(m) { this.log("SKIP", m); }
+
+  /**
+   * Captura como paso. Acepta un Buffer/Uint8Array (Playwright `page.screenshot()`) o un string
+   * base64 (Selenium `driver.takeScreenshot()`).
+   */
+  screenshot(image, message = "", status = "INFO") {
+    if (!this.active || !image) return;
+    const data = typeof image === "string" ? Buffer.from(image, "base64") : Buffer.from(image);
+    const boundary = `----tracereports${Math.random().toString(16).slice(2)}`;
+    const part = (name, value) => `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`;
+    const body = Buffer.concat([
+      Buffer.from(part("message", message) + part("status", String(status).toUpperCase())),
+      Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="screenshot.png"\r\nContent-Type: image/png\r\n\r\n`),
+      data,
+      Buffer.from(`\r\n--${boundary}--\r\n`),
+    ]);
+    this.cr.emit("POST", `/api/v1/tests/${this.id}/screenshot`, body, `multipart/form-data; boundary=${boundary}`, this.cr.uploadTimeoutMs);
+  }
+
+  /**
+   * Declara una respuesta negativa que el test verifica a propósito (p. ej. un 401 con
+   * credenciales inválidas): no cuenta como error ni como causa del fallo. `url`: texto contenido
+   * o glob con `*`.
+   */
+  expectResponse(status, { url = "", method = "" } = {}) {
+    this.expected.push({ status: [].concat(status).map(Number), url, method: method.toUpperCase() });
+  }
+
+  isExpected(c) {
+    return this.expected.some((r) => {
+      if (!r.status.includes(Number(c.status || 0))) return false;
+      if (r.method && (c.method || "").toUpperCase() !== r.method) return false;
+      if (!r.url) return true;
+      if (!r.url.includes("*")) return (c.url || "").includes(r.url);
+      const re = new RegExp("^" + r.url.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+      return re.test(c.url || "");
+    });
+  }
+
+  /** Llamadas de red del test (ver `tracereports/playwright`). Antes de finish. */
+  network(connections, { maxBodyKB = 256, batchSize = 200 } = {}) {
+    if (!this.active || !connections?.length) return { stored: 0, errors: 0 };
+    const limit = maxBodyKB * 1024;
+    const payload = connections.map((c) => {
+      const body = String(c.response_body ?? "");
+      return {
+        method: c.method || "", url: c.url || "", status: Number(c.status || 0), status_text: c.status_text || "",
+        mime_type: c.mime_type || "", resource_type: c.resource_type || "", failed: Boolean(c.failed),
+        error_text: String(c.error_text || ""), started_at: Math.round(c.started_at || 0),
+        duration_ms: c.duration_ms == null ? null : Math.round(c.duration_ms),
+        request_headers: c.request_headers || {}, post_data: String(c.post_data || ""),
+        response_headers: c.response_headers || {}, response_body: body.slice(0, limit),
+        body_size: Math.max(Number(c.body_size || 0), body.length), body_truncated: body.length > limit,
+        expected: Boolean(c.expected) || this.isExpected(c),
+      };
+    });
+    for (let i = 0; i < payload.length; i += batchSize) {
+      this.cr.emit("POST", `/api/v1/tests/${this.id}/network`, JSON.stringify({ connections: payload.slice(i, i + batchSize) }),
+        "application/json", this.cr.uploadTimeoutMs);
+    }
+    return { stored: payload.length, errors: payload.filter((p) => !p.expected && (p.failed || p.status >= 400)).length };
+  }
+
+  /** Snapshot de la página al fallar (recomendador de locators). Antes de finish. */
+  dom(snapshot) {
+    if (!this.active || !snapshot) return;
+    this.cr.emit("POST", `/api/v1/tests/${this.id}/dom`, JSON.stringify(snapshot), "application/json", this.cr.uploadTimeoutMs);
+  }
+
+  /**
+   * Cierra el test. status: PASS | FAIL | WARNING | SKIP, o vacío para deducirlo de los pasos.
+   * Un FAIL dispara el diagnóstico con IA. `attempts` > 1: reintentos (pasó tras reintento).
+   */
+  finish(status = "", { errorMessage = "", errorTrace = "", error, attempts } = {}) {
+    if (!this.active) return;
+    if (error) {
+      errorMessage ||= `${error.name || "Error"}: ${error.message ?? error}`;
+      errorTrace ||= String(error.stack || "");
+      status ||= "FAIL";
+    }
+    const payload = { status: String(status || "").toUpperCase(), error_message: errorMessage, error_trace: errorTrace };
+    const n = attempts ?? this.attempts;
+    if (n > 1) payload.attempts = n;
+    this.cr.emit("PATCH", `/api/v1/tests/${this.id}/finish`, JSON.stringify(payload));
+  }
+}
+
+export { DOM_SCRIPT, domSnapshotInPage } from "./dom.js";
+

package/src/playwright.js

@@ -0,0 +1,156 @@
+// Playwright Test: fixtures que capturan la evidencia sin cambiar los tests.
+//
+//   // en tus specs, en vez de "@playwright/test":
+//   import { test, expect } from "tracereports/playwright";
+//
+//   test("login inválido", async ({ page, tracereports }) => {
+//     tracereports.expectResponse(401, { url: "*/auth/validate*" });   // negativo esperado
+//     tracereports.info("Abrir el login");
+//     ...
+//   });
+//
+// Con la `page` del test:
+//   - captura las llamadas HTTP que hace el navegador (pestaña "Red"; es el tráfico visto desde el
+//     navegador, no los logs del backend);
+//   - si el test falla: snapshot del DOM (recomendador de locators) y una captura si el proyecto
+//     no tiene `screenshot: "only-on-failure"`.
+// Todo viaja como attachments del test; el reporter `tracereports/reporter` los sube.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { domSnapshotInPage } from "./dom.js";
+
+// @playwright/test se carga desde el proyecto que corre los tests: así hay una sola copia aunque
+// este paquete esté instalado como enlace (npm install ../tracereports/client/js).
+async function loadPlaywrightTest() {
+  try {
+    const req = createRequire(path.join(process.cwd(), "package.json"));
+    return await import(pathToFileURL(req.resolve("@playwright/test")).href);
+  } catch {
+    return import("@playwright/test");
+  }
+}
+const pw = await loadPlaywrightTest();
+const base = pw.test ?? pw.default?.test;
+const expect = pw.expect ?? pw.default?.expect;
+
+const BODY_TYPES = new Set(["xhr", "fetch"]);
+const MAX_BODY = 256 * 1024;
+
+/**
+ * Engancha la captura de red a una página (antes de navegar). Devuelve un colector con
+ * `settle(ms)` (espera los bodies en lectura) y `drain()` (conexiones nuevas desde el último drain).
+ */
+export function captureNetwork(page, { apiPatterns = ["/api/"] } = {}) {
+  const conns = [];
+  const byRequest = new Map();
+  const pending = new Set();
+  let reported = 0;
+
+  page.on("request", (req) => {
+    const c = {
+      method: req.method(), url: req.url(), resource_type: req.resourceType(),
+      request_headers: req.headers(), post_data: req.postData() || "", started_at: Date.now(), status: 0,
+    };
+    conns.push(c);
+    byRequest.set(req, c);
+  });
+  page.on("response", (res) => {
+    const c = byRequest.get(res.request());
+    if (!c) return;
+    c.status = res.status();
+    c.status_text = res.statusText();
+    c.response_headers = res.headers();
+    c.mime_type = res.headers()["content-type"] || "";
+    const isApi = BODY_TYPES.has(c.resource_type) || apiPatterns.some((p) => c.url.includes(p));
+    if (isApi || c.status >= 400) {
+      const p = res.text()
+        .then((body) => { c.body_size = body.length; c.response_body = body.slice(0, MAX_BODY); })
+        .catch(() => {})
+        .finally(() => pending.delete(p));
+      pending.add(p);
+    }
+  });
+  page.on("requestfinished", (req) => {
+    const c = byRequest.get(req);
+    if (!c) return;
+    const t = req.timing();
+    c.duration_ms = t && t.responseEnd > 0 ? Math.round(t.responseEnd) : Date.now() - c.started_at;
+  });
+  page.on("requestfailed", (req) => {
+    const c = byRequest.get(req);
+    if (!c) return;
+    c.failed = true;
+    c.error_text = req.failure()?.errorText || "";
+    c.duration_ms = Date.now() - c.started_at;
+  });
+
+  return {
+    connections: conns,
+    async settle(ms = 2000) {
+      await Promise.race([Promise.allSettled([...pending]), new Promise((r) => setTimeout(r, ms))]);
+    },
+    drain() {
+      const out = conns.slice(reported);
+      reported = conns.length;
+      return out;
+    },
+  };
+}
+
+/** Snapshot de los elementos de la página, o null si ya no está disponible. */
+export async function captureDom(page) {
+  try {
+    return await page.evaluate(domSnapshotInPage);
+  } catch {
+    return null;
+  }
+}
+
+const note = (testInfo, type, data) => testInfo.annotations.push({ type, description: JSON.stringify(data) });
+
+/**
+ * Agrega los fixtures de TraceReports a un `test` de Playwright (el tuyo, ya extendido o no):
+ *   import { test as base } from "@playwright/test";
+ *   export const test = withTraceReports(base);
+ */
+export function withTraceReports(baseTest) {
+  return baseTest.extend(fixtures);
+}
+
+const fixtures = {
+  page: async ({ page }, use, testInfo) => {
+    const net = captureNetwork(page);
+    await use(page);
+    await net.settle(2000).catch(() => {});
+    const conns = net.drain();
+    if (conns.length) {
+      await testInfo.attach("tracereports-network", { body: JSON.stringify(conns), contentType: "application/json" });
+    }
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const snap = await captureDom(page);
+      if (snap) await testInfo.attach("tracereports-dom", { body: JSON.stringify(snap), contentType: "application/json" });
+      const mode = testInfo.project.use?.screenshot;
+      const auto = mode === "on" || mode === "only-on-failure" || mode?.mode === "on" || mode?.mode === "only-on-failure";
+      if (!auto) {
+        try {
+          await testInfo.attach("Captura al fallar", { body: await page.screenshot({ timeout: 5000 }), contentType: "image/png" });
+        } catch { /* la página puede estar cerrada */ }
+      }
+    }
+  },
+
+  /** Pasos propios y respuestas esperadas (el reporter los manda a TraceReports). */
+  tracereports: async ({}, use, testInfo) => {
+    const log = (status) => (message) => note(testInfo, "tracereports-log", { status, message: String(message), timestamp: Date.now() });
+    await use({
+      info: log("INFO"), pass: log("PASS"), fail: log("FAIL"), warn: log("WARNING"),
+      expectResponse: (status, { url = "", method = "" } = {}) => note(testInfo, "tracereports-expect", { status, url, method }),
+    });
+  },
+};
+
+export const test = withTraceReports(base);
+
+export { expect };

package/src/reporter.js

@@ -0,0 +1,181 @@
+// Reporter de Playwright Test para TraceReports.
+//
+//   // playwright.config.js
+//   reporter: [["list"], ["tracereports/reporter", { runName: "Regresión web", environment: "staging" }]],
+//
+// - Una ejecución por corrida (todos los workers reportan aquí: el reporter vive en el proceso
+//   principal). Con --shard en varias máquinas, TRACEREPORTS_RUN_ID une los shards a una ejecución.
+// - Identidad estable de cada test: archivo + títulos (+ proyecto de Playwright), aparte del nombre.
+// - Reintentos (`retries`): los intentos quedan en el mismo test ("pasó tras reintento").
+// - Pasos de `test.step`, error y stack, capturas adjuntas (`screenshot: "only-on-failure"` o
+//   testInfo.attach con imagen) y, con los fixtures de `tracereports/playwright`, la red y el DOM.
+// - Al terminar espera la cola y cierra la ejecución; imprime el link. TRACEREPORTS_STRICT=1 hace fallar
+//   la corrida si parte de la evidencia no llegó al servidor.
+//
+// Opciones (o variables): url (TRACEREPORTS_URL), token (TRACEREPORTS_TOKEN), runName (TRACEREPORTS_RUN_NAME),
+// environment (TRACEREPORTS_ENV), project (TRACEREPORTS_PROJECT), strict (TRACEREPORTS_STRICT).
+
+import fs from "node:fs";
+import path from "node:path";
+import { env } from "./env.js";
+import { TraceReports } from "./index.js";
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+const truthy = (v) => ["1", "true", "yes"].includes(String(v || "").toLowerCase());
+
+export default class TraceReportsReporter {
+  constructor(options = {}) {
+    this.options = options;
+    this.cr = new TraceReports({ baseUrl: options.url, token: options.token });
+    this.tests = new Map(); // test.id -> { ct: Promise<TraceTest>, lastError }
+    this.steps = new Map(); // test.id -> intento -> pasos (test.step)
+    this.strict = options.strict ?? truthy(env("STRICT"));
+    this.chain = Promise.resolve(); // los eventos de cada test se procesan en orden
+  }
+
+  printsToStdio() {
+    return false;
+  }
+
+  onBegin(config, suite) {
+    // la carpeta del proyecto es la del playwright.config (rootDir es la de los tests)
+    this.rootDir = config.configFile ? path.dirname(config.configFile) : config.rootDir;
+    const name = this.options.runName || env("RUN_NAME") || path.basename(this.rootDir);
+    const projects = [...new Set(config.projects.map((p) => p.name).filter(Boolean))].join(", ");
+    const environment = this.options.environment ?? env("ENV") ?? projects;
+    this.started = this.cr.startRun(name, {
+      environment,
+      project: this.options.project ?? env("PROJECT") ?? path.basename(this.rootDir),
+      framework: "playwright",
+    });
+    this.total = suite.allTests().length;
+  }
+
+  identity(test) {
+    const file = path.relative(this.rootDir || process.cwd(), test.location.file).split(path.sep).join("/");
+    const titles = test.titlePath().slice(3); // ["", proyecto, archivo, ...describe, título]
+    const projectName = test.parent?.project()?.name || "";
+    return {
+      key: [file, ...titles].join(" > ") + (projectName ? ` [${projectName}]` : ""),
+      suite: [file, ...titles.slice(0, -1)].join(" > "),
+      params: projectName,
+      name: titles.map((t) => t.replace(/\s+@[\w-]+/g, "").trim()).join(" › ") || test.title, // sin los @tags
+      category: [...new Set([...(test.tags || []).map((t) => t.replace(/^@/, "")), path.basename(file).replace(/\.(spec|test)\.[cm]?[jt]sx?$/, "")])].join(", "),
+    };
+  }
+
+  onTestBegin(test, result) {
+    this.chain = this.chain.then(async () => {
+      await this.started;
+      const entry = this.tests.get(test.id);
+      if (entry) { // reintento: mismo test en TraceReports
+        const ct = await entry.ct;
+        ct.attempts = result.retry + 1;
+        ct.warn(`Reintento ${result.retry + 1}: el intento ${result.retry} falló — ${entry.lastError || "falló"}`);
+        return;
+      }
+      const id = this.identity(test);
+      const ct = this.cr.startTest(id.name, { key: id.key, suite: id.suite, params: id.params, category: id.category,
+        worker: `w${result.workerIndex}` });
+      this.tests.set(test.id, { ct });
+    }).catch(() => {});
+  }
+
+  // Los pasos se guardan hasta el final del intento: recién ahí se sabe si un error era esperado
+  // (test.fail()) y no debe mostrarse como fallo.
+  onStepEnd(test, result, step) {
+    if (step.category !== "test.step") return;
+    const steps = (this.steps.get(test.id) ?? new Map());
+    this.steps.set(test.id, steps);
+    const attempt = result?.retry ?? 0;
+    const list = steps.get(attempt) ?? [];
+    steps.set(attempt, list);
+    list.push({ title: step.title, error: step.error ? clean(step.error.message) : "", at: +step.startTime || Date.now() });
+  }
+
+  onTestEnd(test, result) {
+    this.chain = this.chain.then(async () => {
+      const entry = this.tests.get(test.id);
+      const ct = await entry?.ct;
+      if (!ct) return;
+      for (const a of result.annotations ?? test.annotations ?? []) {
+        if (a.type === "tracereports-expect") {
+          const e = JSON.parse(a.description);
+          ct.expectResponse(e.status, { url: e.url, method: e.method });
+        }
+      }
+      // Resultado observado vs. esperado: con test.fail() fallar es lo esperado (Playwright lo da
+      // por bueno) y pasar es un error ("Expected to fail, but passed").
+      const expected = test.expectedStatus ?? "passed";
+      const skipped = result.status === "skipped";
+      const asExpected = result.status === expected;
+      const unexpected = !asExpected && !skipped;
+      const expectedFailure = asExpected && expected === "failed";
+
+      const error = result.errors?.[0] || result.error;
+      const detail = error ? clean(error.message).split("\n").filter(Boolean).slice(0, 3).join(" ") : "";
+      const message = unexpected && expected === "failed" && result.status === "passed"
+        ? "Se esperaba que fallara (test.fail()), pero pasó"
+        : detail || (unexpected ? `Test ${result.status}` : "");
+
+      // pasos propios (tracereports-log) y test.step, en el orden en que ocurrieron
+      const logs = (result.annotations ?? test.annotations ?? []).filter((x) => x.type === "tracereports-log").map((a) => JSON.parse(a.description));
+      const steps = (this.steps.get(test.id)?.get(result.retry) ?? []).map((s) => ({
+        status: !s.error ? "INFO" : unexpected ? "FAIL" : "WARNING",
+        message: s.error ? `${s.title}: ${s.error}${unexpected ? "" : " (error esperado: test.fail())"}` : s.title,
+        timestamp: s.at,
+      }));
+      for (const l of [...steps, ...logs].sort((a, b) => a.timestamp - b.timestamp)) ct.log(l.status, l.message, l.timestamp);
+
+      for (const att of result.attachments) {
+        const body = att.body ?? (att.path && fs.existsSync(att.path) ? fs.readFileSync(att.path) : null);
+        if (!body) continue;
+        if (att.name === "tracereports-network") ct.network(JSON.parse(body.toString()));
+        else if (att.name === "tracereports-dom") ct.dom(JSON.parse(body.toString()));
+        else if (att.contentType?.startsWith("image/")) ct.screenshot(body, att.name === "screenshot" ? "Captura al fallar" : att.name,
+          unexpected ? "FAIL" : "INFO");
+      }
+      const final = asExpected || skipped || result.retry >= test.retries;
+      if (!final) {
+        entry.lastError = message;
+        ct.fail(message || `Intento ${result.retry + 1}: ${result.status}`);
+        return;
+      }
+      let status = skipped ? "SKIP" : unexpected ? "FAIL" : "PASS";
+      if (status === "FAIL") ct.fail(message);
+      if (expectedFailure) ct.info(`Falló como se esperaba (test.fail())${detail ? `: ${detail}` : ""}`);
+      if (skipped) {
+        const reason = (result.annotations ?? test.annotations ?? []).find((a) => a.type === "skip" || a.type === "fixme")?.description;
+        if (reason) ct.skip(reason);
+      }
+      ct.finish(status, {
+        errorMessage: status === "FAIL" ? message : "",
+        errorTrace: status === "FAIL" && error ? clean(error.stack || error.message || "") : "",
+        attempts: result.retry + 1,
+      });
+    }).catch(() => {});
+  }
+
+  async onEnd(result) {
+    await this.chain;
+    await this.started;
+    const interrupted = result.status === "interrupted" || result.status === "timedout";
+    await this.cr.finishRun({ interrupted });
+    const problems = this.cr.deliveryProblems();
+    if (this.cr.runId) console.log(`TraceReports: ${this.cr.reportUrl}`);
+    if (problems) {
+      const d = this.cr.delivery;
+      console.warn(`TraceReports: atención: ${problems - d.runNotClosed} eventos de evidencia no llegaron al servidor ` +
+        `(enviados ${d.sent}, rechazados ${d.rejected}, descartados ${d.dropped}, perdidos ${d.lost})` +
+        (d.runNotClosed ? "; el servidor no confirmó el cierre de la ejecución: quedó abierta" : "") +
+        (this.strict ? " — TRACEREPORTS_STRICT: la corrida falla" : ""));
+    }
+    if (this.strict && (problems || (this.cr.enabled && !this.cr.runId)) && result.status === "passed") {
+      return { status: "failed" };
+    }
+  }
+}
+
+function clean(s) {
+  return String(s || "").replace(ANSI, "").trim();
+}

package/src/selenium.js

@@ -0,0 +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);
+    },
+  };
+}

package/src/transport.js

@@ -0,0 +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;
+  }
+}