dsh-desktop-kit 2.2.0 → 2.7.2

package/plugins/dsh-browser-qa/README.md

@@ -0,0 +1,221 @@
+# dsh-browser-qa
+
+Headless-проверка вёрстки для DSH-агента: скриншоты и адаптивный аудит
+горизонтального переполнения и ошибок консоли через протокол Chrome DevTools.
+Без Playwright и без внешних зависимостей — только встроенные модули Node.js.
+
+## Зачем
+
+Агент может сам проверить страницу перед сдачей: «нет ли горизонтального
+скролла на 390/768/1440», «какие элементы вылезают», «что пишет консоль»,
+«как это выглядит». Работает и с локальными HTML-файлами, и с http(s)-страницами.
+
+## Требования
+
+- **Chrome или Chromium-браузер**. На Windows плагин ищет:
+  `CHROME_PATH` → `%ProgramFiles%\Google\Chrome\Application\chrome.exe` →
+  `%ProgramFiles(x86)%\...` → `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe` →
+  Chrome Canary → Edge (`msedge.exe`) как Chromium-запасной вариант.
+  Путь можно задать явно: `CHROME_PATH=C:\путь\chrome.exe` (переменная окружения
+  процесса DSH).
+- **Node 22+** — нужен встроенный `WebSocket` (в Node 24 он стабилен). DSH
+  Desktop на Electron 44 запускает Node 24, отдельная установка Node не нужна.
+  Если WebSocket недоступен, `browser_qa action=status` честно сообщит об этом.
+- Работает и на macOS/Linux (стандартные пути Chrome/Chromium), но основные
+  пути и проверки — под Windows.
+
+## Инструмент `browser_qa`
+
+Регистрируется один инструмент с тремя действиями. Параметры:
+
+| Параметр | Тип | По умолчанию | Назначение |
+|---|---|---|---|
+| `action` | `"shot"` \| `"audit"` \| `"status"` | — (обязателен) | Что сделать |
+| `url` | string | — | `http(s)`-адрес, `file://` или путь к локальному HTML (относительный — от cwd сессии) |
+| `width` | integer | `1440` | Ширина viewport для `shot`, CSS px (200..3840) |
+| `height` | integer | `900` | Высота viewport, CSS px (200..2160) |
+| `widths` | integer[] | `[390, 768, 1440]` | Ширины для `audit`, CSS px (до 6 значений) |
+| `outDir` | string | `<cwd>/.dsh/browser-qa` | Куда писать PNG; для `audit` — включает скриншоты |
+| `fullPage` | boolean | `false` | Снимать всю страницу, а не viewport (высота обрезается на 16384 px) |
+| `timeoutMs` | integer | `30000` | Таймаут загрузки страницы на одну ширину (3000..120000) |
+
+### `status`
+
+Находит браузер и возвращает путь, тип (Chrome/Edge), версию (через
+`/json/version`), версию Node и наличие WebSocket. Ничего не сохраняет.
+Пробный запуск Chrome занимает ~1–2 с и кэшируется на 5 минут.
+
+### `shot`
+
+Открывает страницу, выставляет viewport, сохраняет PNG и возвращает
+`output.path`, `output.width`, `output.height`, `output.bytes`, а также
+краткую сводку overflow и ошибок консоли. По умолчанию PNG кладётся в
+`<cwd>/.dsh/browser-qa/`.
+
+### `audit`
+
+Для каждой ширины из `widths` заново открывает страницу (так корректно
+срабатывают media queries и JS-перестройка), затем измеряет:
+
+- `document.documentElement.scrollWidth` против `clientWidth` (допуск 1 px) —
+  `horizontalOverflow.hasOverflow`, `overflowPx`;
+- элементы, чей `getBoundingClientRect().right` выходит за viewport
+  (`overflowingElements`: селектор, тег, id, классы, rect, насколько вылез,
+  текст); максимум 25 в отчёте, всего просмотрено до 5000 элементов;
+- ошибки консоли: `Runtime.consoleAPICalled` с `type=error/assert`,
+  `Runtime.exceptionThrown` и `Log.entryAdded` уровня `error` (включая
+  CSP-нарушения и сетевые ошибки); дедупликация, максимум 30;
+- **разметка и доступность** (`markup`): дубли `id`, `<img>` без `alt`,
+  поля без `label`/`aria-*`, ссылки и кнопки без доступного имени,
+  пропуски уровней заголовков, несколько `h1`, отсутствие `lang`/`title`/
+  `meta viewport`, положительный `tabindex`; до 60 issues на ширину;
+- дополнительно: viewport, title, финальный URL, `loadTimedOut`, время загрузки.
+
+Сводка: `summary.widthsChecked`, `widthsWithOverflow`, `overflowingElements`,
+`consoleErrors`, `markupIssues`, `widthsWithMarkupIssues`, `failedWidths`,
+`screenshots`.
+
+**Скриншоты в audit — опционально:** они сохраняются по одной штуке на ширину
+только если передан `outDir`. Без `outDir` audit работает быстрее и не пишет
+файлов. `fullPage` действует и на audit, и на shot.
+
+## UI gate
+
+Плагин также ставит жёсткий gate на хуках:
+
+- `fs/write-intent` / `fs/edit-intent` запоминают правки `.html`, `.css`,
+  `.scss`, `.jsx`, `.tsx`, `.vue`, `.svelte`, `.astro`, `.mdx`;
+- `tools/result` читает итог `browser_qa audit` (`overflow`, console, markup);
+- на `agent/turn-stopping` грязная сессия получает `agent.steer(...)`:
+  «запусти `browser_qa audit` на 390/768/1440, исправь overflow/console/markup
+  и проверь снова»;
+- ход закрывается только после **чистого** audit (0 overflow, 0 console,
+  0 markup) или после 4 напоминаний — предохранитель от бесконечного цикла.
+
+Это не запрет записи: агент может править, но не может молча завершить ход
+после UI-правки без проверки.
+
+## Примеры вызовов
+
+```json
+{ "action": "status" }
+```
+
+```json
+{ "action": "shot", "url": "C:\\project\\dist\\index.html", "width": 390, "height": 844 }
+```
+
+```json
+{
+  "action": "audit",
+  "url": "https://example.com/pricing",
+  "widths": [390, 768, 1440],
+  "outDir": "qa/browser",
+  "timeoutMs": 45000
+}
+```
+
+```json
+{ "action": "audit", "url": "C:\\project\\index.html", "widths": [390, 1440], "fullPage": true, "outDir": "qa/browser" }
+```
+
+## Куда сохраняются PNG
+
+- `shot` без `outDir`: `<cwd-сессии>/.dsh/browser-qa/`.
+- `audit` без `outDir`: ничего не сохраняется (только отчёт).
+- `audit` с `outDir` (или `shot` с `outDir`): указанный каталог, абсолютный или
+  относительно cwd сессии; создаётся при необходимости.
+- Имя файла: `<slug>-<ширина>x<высота>[-full]-<YYYYMMDD-HHmmss>-<hex>.png`,
+  например `localhost-390x844-20261109-205501-a1b2c3.png`. `slug` берётся из
+  хоста и пути URL или из имени локального файла.
+- Размеры PNG — ровно CSS-пиксели viewport (`deviceScaleFactor=1`), поэтому
+  390-px скриншот получается 390 px шириной (а не 500, как при
+  `chrome --screenshot` на Windows).
+
+## Ограничения
+
+- **CSP.** Плагин не обходит Content-Security-Policy страницы: если CSP
+  запрещает собственные inline-скрипты/шрифты/картинки сайта, в отчёте будут
+  соответствующие console errors. Сам замер выполняется через
+  `Runtime.evaluate` DevTools и CSP страницы не блокируется.
+- **Авторизация.** Профиль браузера временный, cookies нет. Приватные
+  страницы, за логином или с SSO, вернут редирект на страницу входа — это
+  ожидаемо. Для проверки таких страниц нужен публичный staging/preview URL.
+- **`file://`.** Локальные HTML открываются (флаг
+  `--allow-file-access-from-files` включён), но Chrome ограничивает часть
+  возможностей file-страниц: ES-модули и `fetch` к локальным файлам могут
+  блокироваться CORS, часть API недоступна. Относительные `src`/`href`
+  обычно работают — `file://`, `../../`, внешние CDN подключаются.
+- **SPA и асинхронность.** Плагин ждёт `load`, `document.readyState=complete`
+  и шрифты (`document.fonts.ready`, не дольше ~1.75 с), затем снимает замер.
+  Бесконечные таймеры, ленивые секции и контент, появляющийся через 5+ секунд
+  после load, могут не попасть в кадр — это не полноценный E2E-раннер.
+- **Интерактивность.** Нет кликов, скроллинга, ввода и навигации по шагам.
+  Только загрузка страницы и измерение.
+- **Псевдоэлементы, `transform`, `position: fixed`.** Overflow считается по
+  реальным DOM-элементам; `::before/::after` не перечисляются, а элементы
+  внутри контейнеров с `overflow-x != visible` (карусели, таблицы со скроллом)
+  считаются «содержимыми» и в список вылезающих не попадают.
+- **`fullPage`.** Ограничен 16384 px по высоте и ширине (лимит поверхности
+  Chrome); при превышении `output.clipped=true`. Full-page снимок включает и
+  горизонтально переполненную область, поэтому может быть шире viewport.
+- **Антибот/headless-детект.** Некоторые сайты (Cloudflare и т.п.) отдают
+  headless-браузеру заглушку или блокируют его — аудит покажет то, что увидел.
+- **Windows.** Определение путей и очистка процессов рассчитаны в первую
+  очередь на Windows; на Linux/macOS поддерживаются базовые пути, но тесты
+  прогонялись на Windows.
+
+## Безопасность и уборка
+
+- Каждый вызов запускает отдельный Chrome с временным `--user-data-dir` и
+  случайным `--remote-debugging-port=0`; порт слушает только `127.0.0.1` и
+  живёт внутри одного вызова.
+- Профиль пользователя не затрагивается; cookies, история и расширения из
+  обычного Chrome не используются.
+- После каждого вызова (включая ошибку и отмену) браузер убивается
+  (`taskkill /T /F` при необходимости), временный профиль удаляется с
+  ретраями; на случай аварийного завершения DSH есть `exit`-guard.
+- Внешних сетевых запросов, кроме самой проверяемой страницы, нет; телеметрии
+  нет.
+
+## Тесты
+
+```bash
+node tools/browser-qa-tests.mjs
+```
+
+- Чистые хелперы (всегда): параметры инструмента, viewport/widths/timeouts,
+  нормализация URL и путей, имена файлов, PNG-заголовок, shaping overflow- и
+  console-отчётов, summary и текст.
+- Реальный Chrome smoke (если Chrome/Edge найден; иначе SKIP):
+  временный HTML с намеренным overflow 1200 px и `console.error`; проверяются
+  overflow на 390/768, отсутствие overflow на 1440, найденный элемент
+  `#wide`, пойманная ошибка консоли, PNG на каждую ширину, точные размеры
+  `shot`, fullPage выше viewport, `status` с путём/версией, вызов через
+  зарегистрированный инструмент и отсутствие оставшихся временных профилей.
+
+## Устройство
+
+```
+plugins/dsh-browser-qa/
+  index.js          — регистрация инструмента browser_qa (inject: ["tools"])
+  lib/qa.js         — чистые хелперы: URL/viewport/widths, overflow-probe,
+                      console-события, отчёты, текст
+  lib/cdp.js        — минимальный CDP-клиент на встроенном WebSocket
+  lib/chrome.js     — поиск Chrome, запуск headless с temp-профилем,
+                      /json/version|list, очистка процессов и профиля
+  lib/pages.js      — shot/audit/status: навигация, viewport, скриншоты, сборка отчёта
+  cordis.patch.yml  — host-патч для standalone-установки bundle
+```
+
+## Диагностика
+
+- `Chrome/Edge not found` — установите Chrome или задайте `CHROME_PATH`
+  (полный путь к `chrome.exe`); `status` покажет список проверенных путей.
+- `has no built-in WebSocket` — Node в рантайме DSH старше 22; нужен Node 22+
+  (в актуальном DSH Desktop уже Node 24).
+- Таймауты на медленных страницах — увеличьте `timeoutMs` (до 120000).
+- `loadTimedOut: true` в отчёте означает, что `load` не успел за таймаут, но
+  замер всё равно сделан по текущему DOM.
+- Если временный профиль не удалился (`warnings` в ответе), повторите позже:
+  обычно антивирус/индексатор Windows держит файл не больше секунды.

package/plugins/dsh-browser-qa/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Host half of the browser-QA plugin.
+- insert:
+    - id: dsh-browser-qa
+      name: dsh-browser-qa

package/plugins/dsh-browser-qa/index.js

@@ -0,0 +1,165 @@
+/**
+ * dsh-browser-qa — headless-Chrome quality checks for DSH agents.
+ *
+ * One tool, three actions:
+ *   status — detect Chrome/Edge and report its path/version;
+ *   shot   — open a URL or local HTML file, set a viewport, save a PNG;
+ *   audit  — at responsive widths measure horizontal overflow, list the
+ *            overflowing elements and console errors, optionally save PNGs.
+ *
+ * Everything is Node-built-ins only: the DevTools protocol is spoken over the
+ * WebSocket client built into Node 22+/24, so there is no Playwright dependency.
+ */
+import { auditPages, captureShot, statusReport } from "./lib/pages.js";
+import { createUiGate } from "./lib/ui-gate.js";
+import { errorMessage, normalizeViewport, parseTimeout, parseWidths } from "./lib/qa.js";
+
+export const inject = ["tools"];
+
+const TOOL_NAME = "browser_qa";
+const TOOL_TIMEOUT_MS = 240_000;
+const MAX_RENDER_CHARS = 24_000;
+
+function sessionCwd(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd;
+  return typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+}
+
+function sessionSignal(exec) {
+  const signal = exec?.signal ?? exec?.abortSignal;
+  return signal && typeof signal.addEventListener === "function" ? signal : undefined;
+}
+
+function failure(prefix, error) {
+  const message = errorMessage(error);
+  const result = { ok: false, error: message, text: message.startsWith(prefix) ? message : `${prefix}: ${message}` };
+  if (error && typeof error.code === "string") result.code = error.code;
+  if (error && Array.isArray(error.candidates)) result.candidates = error.candidates;
+  return result;
+}
+
+function missingUrl(action) {
+  return {
+    ok: false,
+    error: "url is required",
+    text: `browser_qa ${action}: нужен параметр url — http(s)-адрес, file:// или путь к локальному HTML-файлу`,
+  };
+}
+
+function makeToolDefinition() {
+  return {
+    name: TOOL_NAME,
+    description:
+      "Headless-Chrome quality checks without Playwright. status: detect Chrome and its version. shot: open an http(s) URL or local HTML file, set the viewport, save a PNG and return its path/size. audit: load the page at responsive widths (default 390/768/1440) and report horizontal overflow (documentElement.scrollWidth vs clientWidth), the overflowing elements, console errors, markup/accessibility issues (missing alt, unlabeled fields, nameless links/buttons, duplicate ids, heading order, lang/title/viewport, positive tabindex), and optionally one PNG per width (pass outDir). Uses the Chrome DevTools protocol over a temporary profile; no external network calls beyond the page itself.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: "string",
+          enum: ["shot", "audit", "status"],
+          description: "shot: one viewport PNG | audit: overflow/console report at responsive widths | status: Chrome path/version",
+        },
+        url: {
+          type: "string",
+          description: "http(s) URL, file:// URL or local HTML file path (relative paths resolve from the Session cwd).",
+        },
+        width: { type: "integer", description: "Viewport width for shot, in CSS px (default 1440, range 200..3840)." },
+        height: { type: "integer", description: "Viewport height, in CSS px (default 900, range 200..2160)." },
+        widths: {
+          type: "array",
+          items: { type: "integer" },
+          description: "Audit widths in CSS px (default [390, 768, 1440], at most 6 values).",
+        },
+        outDir: {
+          type: "string",
+          description:
+            "Directory for PNGs. shot default: <cwd>/.dsh/browser-qa. audit saves one PNG per width only when outDir is given.",
+        },
+        fullPage: { type: "boolean", description: "Capture the full page instead of the viewport (height capped at 16384 px)." },
+        timeoutMs: { type: "integer", description: "Page load timeout per width in ms (default 30000, range 3000..120000)." },
+      },
+      required: ["action"],
+    },
+    timeoutMs: TOOL_TIMEOUT_MS,
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render(_args, value) {
+        const text =
+          value !== null && typeof value === "object" && typeof value.text === "string"
+            ? value.text
+            : JSON.stringify(value);
+        return [{ type: "text", text: text.length <= MAX_RENDER_CHARS ? text : `${text.slice(0, MAX_RENDER_CHARS)}\n…` }];
+      },
+    },
+    async execute(args, exec) {
+      const action = String(args?.action ?? "").trim().toLowerCase();
+      const cwd = sessionCwd(exec);
+      const signal = sessionSignal(exec);
+      try {
+        if (action === "status") {
+          const status = await statusReport({ cwd });
+          if (status.ok !== true) {
+            status.error = status.chrome?.probeError ?? "Chrome is not available";
+          }
+          return status;
+        }
+        if (action === "shot") {
+          if (typeof args?.url !== "string" || args.url.trim().length === 0) return missingUrl("shot");
+          const viewport = normalizeViewport(args);
+          return await captureShot({
+            target: args.url,
+            width: viewport.width,
+            height: viewport.height,
+            fullPage: args?.fullPage === true,
+            outDir: args?.outDir,
+            timeoutMs: parseTimeout(args?.timeoutMs),
+            cwd,
+            signal,
+          });
+        }
+        if (action === "audit") {
+          if (typeof args?.url !== "string" || args.url.trim().length === 0) return missingUrl("audit");
+          const widths = parseWidths(args?.widths);
+          const viewport = normalizeViewport(args);
+          const hasOutDir = typeof args?.outDir === "string" && args.outDir.trim().length > 0;
+          return await auditPages({
+            target: args.url,
+            widths,
+            height: viewport.height,
+            fullPage: args?.fullPage === true,
+            outDir: hasOutDir ? args.outDir : null,
+            screenshots: hasOutDir,
+            timeoutMs: parseTimeout(args?.timeoutMs),
+            cwd,
+            signal,
+          });
+        }
+        return {
+          ok: false,
+          error: `unknown action: ${action || "(empty)"}`,
+          text: `browser_qa: неизвестное действие «${action || "(пусто)"}». Доступно: shot, audit, status.`,
+        };
+      } catch (error) {
+        return failure("browser_qa", error);
+      }
+    },
+  };
+}
+
+export function apply(ctx) {
+  const tool = makeToolDefinition();
+  const register = () => ctx.tools.register(tool);
+  if (typeof ctx.effect === "function") {
+    ctx.effect(register, "dsh-browser-qa: tool");
+  } else {
+    register();
+  }
+  try {
+    const gate = createUiGate(ctx);
+    if (typeof ctx.effect === "function") ctx.effect(() => () => gate.dispose(), "dsh-browser-qa: ui gate");
+  } catch (error) {
+    ctx.logger?.warn?.(`[browser-qa] ui gate skipped: ${errorMessage(error)}`);
+  }
+  ctx.logger?.info?.("[browser-qa] tool ready");
+}

package/plugins/dsh-browser-qa/lib/cdp.js

@@ -0,0 +1,224 @@
+/**
+ * Minimal Chrome DevTools Protocol client.
+ *
+ * Uses the WebSocket client built into Node.js (22+/24) so the plugin has no
+ * npm dependencies. Only request/response plus named events are implemented —
+ * enough for Page, Runtime, Log and Emulation domains used by browser_qa.
+ */
+export class Cdp {
+  constructor(webSocketUrl, options = {}) {
+    if (typeof webSocketUrl !== "string" || webSocketUrl.length === 0) {
+      throw new Error("CDP websocket URL is empty");
+    }
+    if (typeof WebSocket !== "function") {
+      throw new Error("This Node.js runtime has no built-in WebSocket (Node 22+ is required)");
+    }
+    this.webSocketUrl = webSocketUrl;
+    this.ws = null;
+    this.nextId = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.closeWaiters = new Set();
+    this.closed = false;
+    this.sendTimeoutMs = options.sendTimeoutMs ?? 15_000;
+  }
+
+  async connect(timeoutMs = 10_000) {
+    const ws = new WebSocket(this.webSocketUrl);
+    this.ws = ws;
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket connect timeout"));
+        }, timeoutMs);
+        if (typeof timer.unref === "function") timer.unref();
+        const cleanup = () => {
+          clearTimeout(timer);
+          ws.removeEventListener("open", onOpen);
+          ws.removeEventListener("error", onError);
+          ws.removeEventListener("close", onClose);
+        };
+        const onOpen = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve();
+        };
+        const onError = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket connection error"));
+        };
+        const onClose = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket closed before it opened"));
+        };
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("error", onError);
+        ws.addEventListener("close", onClose);
+      });
+    } catch (error) {
+      try {
+        ws.close();
+      } catch {
+        /* already closed */
+      }
+      this.ws = null;
+      this.closed = true;
+      throw error;
+    }
+    this.closed = false;
+    ws.addEventListener("message", (event) => this.handleMessage(event.data));
+    ws.addEventListener("close", () => this.handleClose());
+    ws.addEventListener("error", () => {
+      /* a close event follows; pending calls will be rejected there */
+    });
+    return this;
+  }
+
+  isClosed() {
+    return this.closed || this.ws === null;
+  }
+
+  handleMessage(raw) {
+    let text;
+    if (typeof raw === "string") text = raw;
+    else if (raw instanceof ArrayBuffer) text = Buffer.from(raw).toString("utf8");
+    else if (ArrayBuffer.isView(raw)) text = Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString("utf8");
+    else text = String(raw ?? "");
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (message === null || typeof message !== "object") return;
+    if (message.id !== undefined) {
+      const pending = this.pending.get(message.id);
+      if (pending === undefined) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(new Error(message.error.message || "CDP request failed"));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (typeof message.method !== "string") return;
+    const listeners = this.listeners.get(message.method);
+    if (!listeners || listeners.size === 0) return;
+    for (const listener of [...listeners]) {
+      try {
+        listener(message.params ?? {});
+      } catch {
+        /* a listener must never break the protocol loop */
+      }
+    }
+  }
+
+  handleClose() {
+    if (this.closed) return;
+    this.closed = true;
+    this.ws = null;
+    const error = new Error("CDP connection closed");
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+    for (const fail of [...this.closeWaiters]) {
+      try {
+        fail(error);
+      } catch {
+        /* ignore */
+      }
+    }
+    this.closeWaiters.clear();
+  }
+
+  send(method, params = {}, timeoutMs = this.sendTimeoutMs) {
+    if (this.isClosed()) return Promise.reject(new Error(`CDP connection is closed (${method})`));
+    const id = (this.nextId += 1);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method} (${timeoutMs} ms)`));
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this.pending.set(id, { resolve, reject, timer, method });
+      try {
+        this.ws.send(JSON.stringify({ id, method, params }));
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  /** Subscribe to a CDP event; returns an unsubscribe function. */
+  on(method, listener) {
+    if (typeof listener !== "function") throw new Error("CDP listener must be a function");
+    if (!this.listeners.has(method)) this.listeners.set(method, new Set());
+    this.listeners.get(method).add(listener);
+    return () => {
+      const listeners = this.listeners.get(method);
+      if (!listeners) return;
+      listeners.delete(listener);
+      if (listeners.size === 0) this.listeners.delete(method);
+    };
+  }
+
+  /** Resolve on the next event, reject on timeout or connection close. */
+  once(method, timeoutMs = 15_000) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let off = null;
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (off) off();
+        this.closeWaiters.delete(fail);
+        callback(value);
+      };
+      const fail = (error) => finish(reject, error);
+      const timer = setTimeout(() => finish(reject, new Error(`CDP event timeout: ${method} (${timeoutMs} ms)`)), timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this.closeWaiters.add(fail);
+      off = this.on(method, (params) => finish(resolve, params));
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    const error = new Error("CDP client closed");
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+    for (const fail of [...this.closeWaiters]) {
+      try {
+        fail(error);
+      } catch {
+        /* ignore */
+      }
+    }
+    this.closeWaiters.clear();
+    this.listeners.clear();
+    const ws = this.ws;
+    this.ws = null;
+    try {
+      ws?.close();
+    } catch {
+      /* already closed */
+    }
+  }
+}