dsh-desktop-kit 2.2.1 → 2.7.2

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

@@ -0,0 +1,827 @@
+/**
+ * dsh-browser-qa — pure helpers shared by the host tool and the tests.
+ *
+ * This module deliberately has no Chrome/DevTools side effects: target
+ * normalisation, viewport/width parsing, overflow-report shaping, console-error
+ * shaping and text formatting are all plain functions so they can be tested
+ * without launching a browser.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const DEFAULT_WIDTHS = Object.freeze([390, 768, 1440]);
+export const DEFAULT_VIEWPORT = Object.freeze({ width: 1440, height: 900 });
+
+export const LIMITS = Object.freeze({
+  minWidth: 200,
+  maxWidth: 3840,
+  minHeight: 200,
+  maxHeight: 2160,
+  maxWidths: 6,
+  minTimeoutMs: 3_000,
+  maxTimeoutMs: 120_000,
+  defaultTimeoutMs: 30_000,
+  maxOffenders: 25,
+  maxConsoleErrors: 30,
+  maxTextLength: 4_000,
+});
+
+/** Chrome refuses to rasterise surfaces above this size; full-page shots clip. */
+export const MAX_SCREENSHOT_HEIGHT = 16_384;
+
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:", "file:", "about:"]);
+
+/* ------------------------------------------------------------------ */
+/* numbers, viewports, widths, timeouts                                */
+/* ------------------------------------------------------------------ */
+
+export function clampInt(value, min, max, fallback) {
+  const number = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(number)));
+}
+
+export function normalizeViewport(args = {}) {
+  return {
+    width: clampInt(args?.width, LIMITS.minWidth, LIMITS.maxWidth, DEFAULT_VIEWPORT.width),
+    height: clampInt(args?.height, LIMITS.minHeight, LIMITS.maxHeight, DEFAULT_VIEWPORT.height),
+  };
+}
+
+/**
+ * Audit widths: integers clamped to 200..3840, de-duplicated, at most six.
+ * Invalid/empty input falls back to the responsive defaults 390/768/1440.
+ */
+export function parseWidths(widths, fallback = DEFAULT_WIDTHS) {
+  const source = Array.isArray(widths) ? widths : [];
+  const seen = new Set();
+  const result = [];
+  for (const value of source) {
+    if (result.length >= LIMITS.maxWidths) break;
+    const width = clampInt(value, LIMITS.minWidth, LIMITS.maxWidth, null);
+    if (width === null || seen.has(width)) continue;
+    seen.add(width);
+    result.push(width);
+  }
+  return result.length > 0 ? result : [...fallback];
+}
+
+export function parseTimeout(value, fallback = LIMITS.defaultTimeoutMs) {
+  return clampInt(value, LIMITS.minTimeoutMs, LIMITS.maxTimeoutMs, fallback);
+}
+
+/* ------------------------------------------------------------------ */
+/* targets and output naming                                           */
+/* ------------------------------------------------------------------ */
+
+function isWindowsAbsolute(raw) {
+  return /^[a-zA-Z]:[\\/]/u.test(raw) || raw.startsWith("\\\\");
+}
+
+/**
+ * Accept an http(s) URL, a file:// URL, an absolute local HTML path, or a path
+ * relative to `cwd`. Throws with a readable message for unsupported schemes and
+ * missing files.
+ */
+export function normalizeTarget(input, options = {}) {
+  const cwd = typeof options.cwd === "string" && options.cwd.length > 0 ? options.cwd : process.cwd();
+  const raw = String(input ?? "").trim();
+  if (raw.length === 0) {
+    throw new Error("url is required: pass an http(s) URL, file:// URL or a local HTML file path");
+  }
+  const windowsAbsolute = isWindowsAbsolute(raw);
+  const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/u.test(raw);
+  if (windowsAbsolute || !hasScheme) {
+    const file = path.resolve(cwd, raw);
+    return { input: raw, kind: "file", url: pathToFileURL(file).href, file };
+  }
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`invalid URL: ${raw}`);
+  }
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+    throw new Error(`unsupported URL scheme "${parsed.protocol}": use http(s), file:// or about:blank`);
+  }
+  if (parsed.protocol === "about:") {
+    if (parsed.href !== "about:blank") throw new Error(`unsupported about: URL "${parsed.href}": only about:blank is allowed`);
+    return { input: raw, kind: "about", url: "about:blank" };
+  }
+  if (parsed.protocol === "file:") {
+    let file;
+    try {
+      file = fileURLToPath(parsed);
+    } catch {
+      throw new Error(`unsupported file URL (network shares are not supported): ${raw}`);
+    }
+    return { input: raw, kind: "file", url: parsed.href, file };
+  }
+  return { input: raw, kind: "http", url: parsed.href };
+}
+
+/** True when the target points at an existing file; used by validate/status paths. */
+export function targetExists(target) {
+  const file = typeof target === "string" ? target : target?.file;
+  if (typeof file !== "string" || file.length === 0) return true;
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Assert that a local target really exists; http(s) targets need no check. */
+export function validateTarget(target) {
+  if (target?.kind === "file" && !targetExists(target)) {
+    throw new Error(`local file not found: ${target.file}`);
+  }
+  return target;
+}
+
+function windowsReservedName(slug) {
+  return /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu.test(slug);
+}
+
+/**
+ * Filesystem-safe, human-readable slug for screenshot names. Keeps dots so
+ * hostnames stay readable, collapses separators, caps at 60 chars.
+ */
+export function sanitizeSlug(value) {
+  let slug = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}._-]+/gu, "-")
+    .replace(/-{2,}/gu, "-")
+    .replace(/^[-._]+|[-._]+$/gu, "")
+    .slice(0, 60);
+  if (slug.length === 0) return "page";
+  if (windowsReservedName(slug)) slug = `page-${slug}`;
+  return slug;
+}
+
+export function slugForTarget(target) {
+  const raw = typeof target === "string" ? target : target?.url ?? "";
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol === "file:") {
+      return sanitizeSlug(path.basename(fileURLToPath(parsed)).replace(/\.[^.]+$/u, ""));
+    }
+    return sanitizeSlug(`${parsed.host}${parsed.pathname}`);
+  } catch {
+    return sanitizeSlug(raw);
+  }
+}
+
+function pad(number, length = 2) {
+  return String(number).padStart(length, "0");
+}
+
+/** Local timestamp `YYYYMMDD-HHmmss` used in screenshot names. */
+export function formatTimestamp(date = new Date()) {
+  const value = date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
+  return `${value.getFullYear()}${pad(value.getMonth() + 1)}${pad(value.getDate())}-${pad(value.getHours())}${pad(value.getMinutes())}${pad(value.getSeconds())}`;
+}
+
+export function screenshotFileName(options = {}) {
+  const { target, width, height, fullPage = false, at = new Date(), random } = options;
+  const nonce = String(random ?? crypto.randomBytes(3).toString("hex"))
+    .toLowerCase()
+    .replace(/[^a-z0-9]/gu, "")
+    .slice(0, 8);
+  return `${slugForTarget(target)}-${clampInt(width, 1, 99_999, DEFAULT_VIEWPORT.width)}x${clampInt(height, 1, 99_999, DEFAULT_VIEWPORT.height)}${fullPage ? "-full" : ""}-${formatTimestamp(at)}-${nonce || "0000"}.png`;
+}
+
+/** Where PNGs go: explicit outDir, otherwise `<cwd>/.dsh/browser-qa`. */
+export function resolveOutDir(outDir, cwd = process.cwd()) {
+  const base = typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+  if (typeof outDir === "string" && outDir.trim().length > 0) return path.resolve(base, outDir.trim());
+  return path.join(path.resolve(base), ".dsh", "browser-qa");
+}
+
+/** Read PNG dimensions from the IHDR header (no image library needed). */
+export function pngSize(buffer) {
+  const data = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer ?? []);
+  if (data.length < 24 || data[0] !== 0x89 || data[1] !== 0x50 || data[2] !== 0x4e || data[3] !== 0x47) {
+    throw new Error("not a PNG image");
+  }
+  return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+}
+
+/* ------------------------------------------------------------------ */
+/* in-page overflow probe                                              */
+/* ------------------------------------------------------------------ */
+
+/* Serialised with Function#toString and evaluated through Runtime.evaluate —
+   keep it dependency-free and self-contained. */
+function overflowProbe() {
+  const TOLERANCE = 1;
+  const MAX_OFFENDERS = 40;
+  const MAX_SCANNED = 5_000;
+  const docEl = document.documentElement;
+  const innerWidth = window.innerWidth;
+  const clientWidth = docEl.clientWidth;
+  const body = document.body;
+  const bodyScrollWidth = body ? body.scrollWidth : 0;
+  const scrollWidth = Math.max(docEl.scrollWidth, bodyScrollWidth);
+
+  const cssEscape = (value) => {
+    if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(value);
+    return String(value).replace(/[^a-zA-Z0-9_-]/g, (character) => "\\" + character);
+  };
+
+  const selectorFor = (element) => {
+    const parts = [];
+    let node = element;
+    for (let depth = 0; node && node.nodeType === 1 && depth < 4; depth += 1) {
+      if (node.id) {
+        parts.unshift(`#${cssEscape(node.id)}`);
+        break;
+      }
+      const tag = node.tagName.toLowerCase();
+      const className = typeof node.className === "string" ? node.className.trim() : "";
+      const classes = className ? className.split(/\s+/).filter(Boolean).slice(0, 2) : [];
+      let part = tag + (classes.length > 0 ? "." + classes.map(cssEscape).join(".") : "");
+      const parent = node.parentElement;
+      if (parent) {
+        const sameTag = Array.prototype.filter.call(parent.children, (child) => child.tagName === node.tagName);
+        if (sameTag.length > 1) part += `:nth-of-type(${sameTag.indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
+  };
+
+  const clippedHorizontally = (element) => {
+    let parent = element.parentElement;
+    while (parent && parent !== docEl) {
+      const style = getComputedStyle(parent);
+      if (style.overflowX !== "visible") return true;
+      parent = parent.parentElement;
+    }
+    return false;
+  };
+
+  const offenders = [];
+  let total = 0;
+  let scanned = 0;
+  const candidates = body ? [body, ...Array.prototype.slice.call(body.querySelectorAll("*"), 0, MAX_SCANNED - 1)] : [];
+  for (const element of candidates) {
+    scanned += 1;
+    if (element === body && element.children.length === 0 && !element.textContent) continue;
+    const style = getComputedStyle(element);
+    if (style.display === "none" || style.visibility === "hidden") continue;
+    const rect = element.getBoundingClientRect();
+    if (rect.width <= 0 && rect.height <= 0) continue;
+    const overflowRightPx = rect.right - innerWidth;
+    const overflowLeftPx = -rect.left;
+    if (overflowRightPx <= TOLERANCE && overflowLeftPx <= TOLERANCE) continue;
+    if (clippedHorizontally(element)) continue;
+    total += 1;
+    if (offenders.length >= MAX_OFFENDERS) continue;
+    offenders.push({
+      tag: element.tagName.toLowerCase(),
+      id: element.id || "",
+      classes: (typeof element.className === "string" ? element.className : "").trim().slice(0, 160),
+      selector: selectorFor(element).slice(0, 220),
+      rect: {
+        x: Math.round(rect.x),
+        y: Math.round(rect.y),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        right: Math.round(rect.right),
+      },
+      overflowRightPx: Math.round(Math.max(0, overflowRightPx)),
+      overflowLeftPx: Math.round(Math.max(0, overflowLeftPx)),
+      text: (element.textContent || "").replace(/\s+/gu, " ").trim().slice(0, 120),
+    });
+  }
+  offenders.sort(
+    (left, right) =>
+      right.overflowRightPx + right.overflowLeftPx - (left.overflowRightPx + left.overflowLeftPx),
+  );
+  return JSON.stringify({
+    url: location.href,
+    title: document.title || "",
+    readyState: document.readyState,
+    viewport: { innerWidth, innerHeight: window.innerHeight, devicePixelRatio: window.devicePixelRatio || 1 },
+    document: { scrollWidth, clientWidth, scrollHeight: docEl.scrollHeight },
+    bodyScrollWidth,
+    scannedElements: scanned,
+    overflowingTotal: total,
+    offenders,
+  });
+}
+
+export const OVERFLOW_EXPRESSION = `(${overflowProbe.toString()})()`;
+
+/**
+ * Markup/accessibility probe: duplicate ids, missing alt, unlabeled controls,
+ * nameless links/buttons, heading order, lang/title/viewport and positive
+ * tabindex. Runs in the page; returns a bounded JSON string.
+ */
+function markupProbe() {
+  const issues = [];
+  const counts = { elements: 0, images: 0, links: 0, buttons: 0, fields: 0, headings: 0 };
+  const add = (rule, severity, element, message) => {
+    if (issues.length >= 60) return;
+    let selector = "";
+    try {
+      if (element && element.id) {
+        selector = "#" + CSS.escape(element.id);
+      } else if (element && element.tagName) {
+        const parts = [];
+        let node = element;
+        for (let depth = 0; node && node.nodeType === 1 && depth < 4; depth += 1) {
+          let part = node.tagName.toLowerCase();
+          if (node.classList && node.classList.length > 0) {
+            part += "." + Array.from(node.classList).slice(0, 2).map((name) => CSS.escape(name)).join(".");
+          }
+          parts.unshift(part);
+          node = node.parentElement;
+        }
+        selector = parts.join(" > ");
+      }
+    } catch {
+      selector = "";
+    }
+    issues.push({
+      rule,
+      severity,
+      selector: selector.slice(0, 180),
+      message: String(message).slice(0, 180),
+    });
+  };
+  const visible = (element) => {
+    if (!element || element.nodeType !== 1) return false;
+    if (element.hidden === true || element.getAttribute("aria-hidden") === "true") return false;
+    const style = getComputedStyle(element);
+    if (style.display === "none" || style.visibility === "hidden") return false;
+    return element.getClientRects().length > 0 || style.position === "fixed";
+  };
+  const textOf = (element) => String((element && (element.innerText || element.textContent)) || "").replace(/\s+/gu, " ").trim();
+  const accessibleName = (element) => {
+    const aria = String(element.getAttribute("aria-label") || "").trim();
+    if (aria.length > 0) return aria;
+    const ids = String(element.getAttribute("aria-labelledby") || "").split(/\s+/u).filter(Boolean);
+    for (const id of ids) {
+      const node = document.getElementById(id);
+      if (node && textOf(node).length > 0) return textOf(node);
+    }
+    const title = String(element.getAttribute("title") || "").trim();
+    if (title.length > 0) return title;
+    const text = textOf(element);
+    if (text.length > 0) return text;
+    const image = element.querySelector && element.querySelector("img[alt]");
+    return image && String(image.getAttribute("alt") || "").trim().length > 0 ? String(image.getAttribute("alt")).trim() : "";
+  };
+
+  counts.elements = document.querySelectorAll("*").length;
+  if (!String(document.documentElement.getAttribute("lang") || "").trim()) {
+    add("html-lang", "serious", document.documentElement, "У <html> нет lang — скринридер не знает язык страницы");
+  }
+  if (textOf(document.head?.querySelector("title") || document.querySelector("title")).length === 0) {
+    add("document-title", "warning", document.documentElement, "Пустой <title> — плохо для вкладки, SEO и скринридера");
+  }
+  if (!document.querySelector('meta[name="viewport"]')) {
+    add("meta-viewport", "warning", document.documentElement, "Нет meta viewport — мобильный layout может масштабироваться неверно");
+  }
+
+  const ids = new Map();
+  for (const element of document.querySelectorAll("[id]")) {
+    const id = element.id;
+    if (id) ids.set(id, (ids.get(id) || 0) + 1);
+  }
+  for (const [id, count] of ids) {
+    if (count > 1) {
+      add("duplicate-id", "serious", document.getElementById(id), `id="${id}" встречается ${count} раз`);
+    }
+  }
+
+  for (const image of Array.from(document.images)) {
+    counts.images += 1;
+    if (!image.hasAttribute("alt")) {
+      add("image-alt", "serious", image, "У <img> нет alt; для декоративного используйте alt=\"\"");
+    }
+  }
+
+  for (const link of Array.from(document.querySelectorAll("a[href]"))) {
+    if (!visible(link)) continue;
+    counts.links += 1;
+    if (accessibleName(link).length === 0) {
+      add("link-name", "serious", link, "Ссылка без доступного имени: добавьте текст, aria-label или alt у картинки");
+    }
+  }
+
+  for (const button of Array.from(document.querySelectorAll('button, [role="button"]'))) {
+    if (!visible(button)) continue;
+    counts.buttons += 1;
+    if (accessibleName(button).length === 0) {
+      add("button-name", "serious", button, "Кнопка без доступного имени");
+    }
+  }
+
+  for (const field of Array.from(document.querySelectorAll("input, select, textarea"))) {
+    if (field.type === "hidden" || field.getAttribute("aria-hidden") === "true" || !visible(field)) continue;
+    counts.fields += 1;
+    const labelled = Boolean((field.labels && field.labels.length > 0) || field.getAttribute("aria-label") || field.getAttribute("aria-labelledby") || field.getAttribute("title"));
+    if (!labelled) {
+      add("field-label", "serious", field, "Поле без label/aria-label — непонятно, что вводить");
+    }
+  }
+
+  const headings = Array.from(document.querySelectorAll("h1, h2, h3, h4, h5, h6")).filter(visible);
+  counts.headings = headings.length;
+  let previous = 0;
+  for (const heading of headings) {
+    const level = Number(heading.tagName.slice(1));
+    if (previous > 0 && level > previous + 1) {
+      add("heading-order", "moderate", heading, `Пропущен уровень заголовка: h${previous} → h${level}`);
+    }
+    previous = level;
+  }
+  const h1Count = headings.filter((heading) => heading.tagName === "H1").length;
+  if (h1Count > 1) add("heading-h1", "warning", headings.find((heading) => heading.tagName === "H1"), `Несколько h1 (${h1Count}) — выберите один главный`);
+
+  for (const element of Array.from(document.querySelectorAll("[tabindex]"))) {
+    const value = Number(element.getAttribute("tabindex"));
+    if (Number.isFinite(value) && value > 0 && visible(element)) {
+      add("positive-tabindex", "moderate", element, `tabindex="${value}" ломает естественный порядок фокуса`);
+    }
+  }
+
+  return JSON.stringify({
+    url: location.href,
+    title: document.title || "",
+    lang: document.documentElement.getAttribute("lang") || "",
+    counts,
+    issues,
+    total: issues.length,
+  });
+}
+
+export const MARKUP_EXPRESSION = `(${markupProbe.toString()})()`;
+
+/** Waits for web fonts and lets the layout settle, bounded to ~1.75 s. */
+export const SETTLE_EXPRESSION = `(async () => {
+  try {
+    if (document.fonts && document.fonts.ready && document.fonts.status !== "loaded") {
+      await Promise.race([document.fonts.ready, new Promise((resolve) => setTimeout(resolve, 1500))]);
+    }
+  } catch {}
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  return true;
+})()`;
+
+export const PAGE_INFO_EXPRESSION =
+  'JSON.stringify({ url: location.href, title: document.title || "", readyState: document.readyState })';
+
+/* ------------------------------------------------------------------ */
+/* reports                                                             */
+/* ------------------------------------------------------------------ */
+
+function finiteInt(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.round(number) : fallback;
+}
+
+function boundedText(value, max) {
+  return String(value ?? "").replace(/\s+/gu, " ").trim().slice(0, max);
+}
+
+export function shapeOffender(raw = {}) {
+  const rect = raw?.rect ?? {};
+  return {
+    tag: boundedText(raw?.tag, 40).toLowerCase() || "unknown",
+    id: boundedText(raw?.id, 80),
+    classes: boundedText(raw?.classes, 160),
+    selector: boundedText(raw?.selector, 220) || "unknown",
+    rect: {
+      x: finiteInt(rect.x),
+      y: finiteInt(rect.y),
+      width: finiteInt(rect.width),
+      height: finiteInt(rect.height),
+      right: finiteInt(rect.right),
+    },
+    overflowRightPx: Math.max(0, finiteInt(raw?.overflowRightPx)),
+    overflowLeftPx: Math.max(0, finiteInt(raw?.overflowLeftPx)),
+    text: boundedText(raw?.text, 120),
+  };
+}
+
+/**
+ * Turn the raw in-page measurement into the bounded audit block:
+ * `documentElement.scrollWidth` vs `clientWidth`, 1 px tolerance, at most 25
+ * listed elements.
+ */
+export function shapeOverflowReport(raw = {}, options = {}) {
+  const maxOffenders = options.maxOffenders ?? LIMITS.maxOffenders;
+  const viewportRaw = raw?.viewport ?? {};
+  const documentRaw = raw?.document ?? {};
+  const innerWidth = finiteInt(viewportRaw.innerWidth, DEFAULT_VIEWPORT.width);
+  const innerHeight = finiteInt(viewportRaw.innerHeight, DEFAULT_VIEWPORT.height);
+  const clientWidth = finiteInt(documentRaw.clientWidth, innerWidth) || innerWidth;
+  const scrollWidth = Math.max(
+    finiteInt(documentRaw.scrollWidth, 0),
+    finiteInt(raw?.bodyScrollWidth, 0),
+    clientWidth,
+    innerWidth,
+  );
+  const overflowPx = Math.max(0, scrollWidth - clientWidth);
+  const offendersRaw = Array.isArray(raw?.offenders) ? raw.offenders : [];
+  const overflowingElements = offendersRaw.slice(0, maxOffenders).map(shapeOffender);
+  const overflowingTotal = Math.max(
+    finiteInt(raw?.overflowingTotal, 0),
+    offendersRaw.length,
+    overflowingElements.length,
+  );
+  return {
+    url: boundedText(raw?.url, 500),
+    title: boundedText(raw?.title, 200),
+    readyState: boundedText(raw?.readyState, 20),
+    viewport: {
+      innerWidth,
+      innerHeight,
+      devicePixelRatio: Number.isFinite(Number(viewportRaw.devicePixelRatio)) ? Number(viewportRaw.devicePixelRatio) : 1,
+    },
+    document: { scrollWidth, clientWidth, scrollHeight: finiteInt(documentRaw.scrollHeight, 0) },
+    horizontalOverflow: { hasOverflow: overflowPx > 1, overflowPx, scrollWidth, clientWidth, innerWidth },
+    overflowingElements,
+    overflowingTotal,
+    overflowingTruncated: overflowingTotal > overflowingElements.length,
+  };
+}
+
+/**
+ * Bound the in-page markup/accessibility probe. The full report keeps rule,
+ * severity and selector, so the agent can fix the exact element.
+ */
+export function shapeMarkupReport(raw = {}) {
+  const maxIssues = 80;
+  const issuesRaw = Array.isArray(raw?.issues) ? raw.issues : [];
+  const issues = issuesRaw.slice(0, maxIssues).map((issue) => ({
+    rule: boundedText(issue?.rule, 40) || "unknown",
+    severity: ["serious", "moderate", "warning"].includes(issue?.severity) ? issue.severity : "warning",
+    selector: boundedText(issue?.selector, 180),
+    message: boundedText(issue?.message, 220),
+  }));
+  const total = Math.max(finiteInt(raw?.total, 0), issuesRaw.length, issues.length);
+  return {
+    url: boundedText(raw?.url, 500),
+    title: boundedText(raw?.title, 200),
+    lang: boundedText(raw?.lang, 20),
+    counts: {
+      elements: finiteInt(raw?.counts?.elements, 0),
+      images: finiteInt(raw?.counts?.images, 0),
+      links: finiteInt(raw?.counts?.links, 0),
+      buttons: finiteInt(raw?.counts?.buttons, 0),
+      fields: finiteInt(raw?.counts?.fields, 0),
+      headings: finiteInt(raw?.counts?.headings, 0),
+    },
+    issues,
+    total,
+    truncated: total > issues.length,
+  };
+}
+
+function consoleArgText(arg) {
+  if (arg === null || arg === undefined) return "";
+  if (typeof arg === "string") return arg;
+  if ("value" in arg) {
+    const value = arg.value;
+    if (typeof value === "string") return value;
+    if (value === null) return "null";
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return "";
+      }
+    }
+    return String(value);
+  }
+  if (typeof arg.description === "string") return arg.description;
+  if (typeof arg.unserializableValue === "string") return arg.unserializableValue;
+  return "";
+}
+
+function firstStackFrame(stackTrace) {
+  const callFrames = Array.isArray(stackTrace?.callFrames) ? stackTrace.callFrames : [];
+  return callFrames.length > 0 ? callFrames[0] : null;
+}
+
+/** Normalise one of the three CDP console/error events, or return null. */
+export function consoleEventFromCdp(method, params = {}) {
+  if (method === "Runtime.consoleAPICalled") {
+    const type = String(params?.type ?? "");
+    if (type !== "error" && type !== "assert") return null;
+    const args = Array.isArray(params?.args) ? params.args : [];
+    const text = args.map(consoleArgText).filter((part) => part.trim().length > 0).join(" ");
+    const frame = firstStackFrame(params?.stackTrace);
+    return {
+      kind: "console",
+      level: type,
+      text: boundedText(text || `console.${type}`, 500),
+      url: frame?.url ?? "",
+      line: Number.isFinite(Number(frame?.lineNumber)) ? Number(frame.lineNumber) : null,
+      column: Number.isFinite(Number(frame?.columnNumber)) ? Number(frame.columnNumber) : null,
+    };
+  }
+  if (method === "Runtime.exceptionThrown") {
+    const details = params?.exceptionDetails ?? {};
+    const description = details?.exception?.description ?? details?.text ?? "uncaught exception";
+    const frame = firstStackFrame(details?.stackTrace);
+    const url = frame?.url ?? details?.url ?? "";
+    const line = Number.isFinite(Number(frame?.lineNumber ?? details?.lineNumber)) ? Number(frame?.lineNumber ?? details?.lineNumber) : null;
+    const column = Number.isFinite(Number(frame?.columnNumber ?? details?.columnNumber)) ? Number(frame?.columnNumber ?? details?.columnNumber) : null;
+    return {
+      kind: "exception",
+      level: "error",
+      text: boundedText(String(description).split("\n")[0], 500),
+      url: String(url ?? ""),
+      line,
+      column,
+    };
+  }
+  if (method === "Log.entryAdded") {
+    const entry = params?.entry ?? {};
+    if (String(entry?.level ?? "") !== "error") return null;
+    const suffix = typeof entry.url === "string" && entry.url.length > 0 ? ` (${entry.url})` : "";
+    return {
+      kind: "log",
+      level: "error",
+      text: boundedText(`${entry.text ?? ""}${suffix}`, 500),
+      url: String(entry.url ?? ""),
+      line: Number.isFinite(Number(entry.lineNumber)) ? Number(entry.lineNumber) : null,
+      column: null,
+      source: String(entry.source ?? ""),
+    };
+  }
+  return null;
+}
+
+/** De-duplicate console errors and cap the list (default 30). */
+export function shapeConsoleEvents(events = [], options = {}) {
+  const max = options.max ?? LIMITS.maxConsoleErrors;
+  const seen = new Set();
+  const result = [];
+  const source = Array.isArray(events) ? events : [];
+  for (const event of source) {
+    if (!event || typeof event !== "object") continue;
+    const text = boundedText(event.text, 500);
+    if (text.length === 0) continue;
+    const key = `${event.kind ?? "console"}|${text}|${event.url ?? ""}|${event.line ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const shaped = {
+      kind: boundedText(event.kind, 20) || "console",
+      level: boundedText(event.level, 20) || "error",
+      text,
+      url: boundedText(event.url, 500),
+      line: Number.isFinite(Number(event.line)) ? Number(event.line) : null,
+      column: Number.isFinite(Number(event.column)) ? Number(event.column) : null,
+    };
+    if (typeof event.source === "string" && event.source.length > 0) shaped.source = boundedText(event.source, 30);
+    result.push(shaped);
+    if (result.length >= max) break;
+  }
+  return result;
+}
+
+export function summarizeAudit(reports = []) {
+  const list = Array.isArray(reports) ? reports : [];
+  const measured = list.filter((report) => report && report.error === undefined && report.skipped !== true);
+  const failed = list.filter((report) => report && typeof report.error === "string");
+  return {
+    widthsRequested: list.length,
+    widthsChecked: measured.length,
+    widthsWithOverflow: measured.filter((report) => report.horizontalOverflow?.hasOverflow === true).length,
+    overflowingElements: measured.reduce((sum, report) => sum + (Number(report.overflowingTotal) || 0), 0),
+    consoleErrors: measured.reduce(
+      (sum, report) => sum + (Array.isArray(report.consoleErrors) ? report.consoleErrors.length : 0),
+      0,
+    ),
+    markupIssues: measured.reduce((sum, report) => sum + (Number(report.markup?.total) || 0), 0),
+    widthsWithMarkupIssues: measured.filter((report) => Number(report.markup?.total) > 0).length,
+    failedWidths: failed.length,
+    screenshots: measured.filter((report) => typeof report.screenshot?.path === "string").length,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* text rendering                                                      */
+/* ------------------------------------------------------------------ */
+
+export function truncateText(text, max = LIMITS.maxTextLength) {
+  const value = String(text ?? "");
+  return value.length <= max ? value : `${value.slice(0, max)}\n…`;
+}
+
+export function formatBytes(bytes) {
+  const value = Number(bytes);
+  if (!Number.isFinite(value) || value < 0) return "0 B";
+  if (value < 1024) return `${Math.round(value)} B`;
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
+  return `${(value / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function chromeLabel(chrome) {
+  if (!chrome || typeof chrome !== "object") return "Chrome";
+  const product = typeof chrome.product === "string" && chrome.product.length > 0 ? chrome.product : "Chrome";
+  const version = typeof chrome.version === "string" && chrome.version.length > 0 ? ` ${chrome.version}` : "";
+  return `${product}${version}`;
+}
+
+export function formatShotText(result = {}) {
+  const output = result.output ?? {};
+  const overflow = result.horizontalOverflow ?? {};
+  const errors = Array.isArray(result.consoleErrors) ? result.consoleErrors.length : 0;
+  const lines = [
+    `browser_qa shot: ${result.target?.finalUrl ?? result.target?.url ?? ""}`,
+    `PNG: ${output.path ?? "—"} · ${output.width ?? "?"}x${output.height ?? "?"} · ${formatBytes(output.bytes)}${output.fullPage ? " · full page" : ""}${output.clipped ? " · clipped" : ""}`,
+    `${chromeLabel(result.chrome)} · viewport ${result.viewport?.width ?? "?"}x${result.viewport?.height ?? "?"} · overflow ${overflow.hasOverflow === true ? `${overflow.overflowPx}px` : "нет"} · console errors: ${errors}`,
+  ];
+  if (result.warnings && result.warnings.length > 0) lines.push(`Предупреждения: ${result.warnings.join("; ")}`);
+  return truncateText(lines.join("\n"));
+}
+
+export function formatAuditText(report = {}) {
+  const reports = Array.isArray(report.reports) ? report.reports : [];
+  const lines = [`browser_qa audit: ${report.target?.finalUrl ?? report.target?.url ?? ""}`];
+  lines.push(`${chromeLabel(report.chrome)} · ширины: ${reports.map((item) => item.width).join(", ")}`);
+  for (const item of reports) {
+    if (typeof item.error === "string") {
+      lines.push(`- ${item.width}px: ошибка — ${item.error}`);
+      continue;
+    }
+    if (item.skipped === true) {
+      lines.push(`- ${item.width}px: пропущено — ${item.reason ?? "нет времени"}`);
+      continue;
+    }
+    const overflow = item.horizontalOverflow ?? {};
+    const markup = item.markup ?? {};
+    const bits = [
+      overflow.hasOverflow === true ? `overflow ${overflow.overflowPx}px` : "overflow нет",
+      `элементов: ${item.overflowingTotal ?? 0}`,
+      `console errors: ${Array.isArray(item.consoleErrors) ? item.consoleErrors.length : 0}`,
+      `markup: ${Number(markup.total) || 0}`,
+    ];
+    if (item.loadTimedOut === true) bits.push("load timeout");
+    if (typeof item.screenshot?.path === "string") bits.push(`PNG: ${item.screenshot.path}`);
+    lines.push(`- ${item.width}px: ${bits.join(", ")}`);
+    if (Array.isArray(markup.issues) && markup.issues.length > 0) {
+      const top = markup.issues.slice(0, 3).map((issue) => `${issue.rule}${issue.selector ? ` (${issue.selector})` : ""}`);
+      lines.push(`  markup: ${top.join("; ")}${markup.total > top.length ? `; ещё ${markup.total - top.length}` : ""}`);
+    }
+    if (typeof item.markupError === "string") lines.push(`  markup: ошибка проверки — ${item.markupError}`);
+  }
+  const summary = report.summary ?? {};
+  lines.push(
+    `Итог: overflow на ${summary.widthsWithOverflow ?? 0} из ${summary.widthsChecked ?? 0} ширин · ` +
+      `console errors: ${summary.consoleErrors ?? 0} · markup: ${summary.markupIssues ?? 0}` +
+      (report.outDir ? ` · PNG: ${report.outDir}` : ""),
+  );
+  if (report.warnings && report.warnings.length > 0) lines.push(`Предупреждения: ${report.warnings.join("; ")}`);
+  return truncateText(lines.join("\n"));
+}
+
+export function formatStatusText(status = {}) {
+  const chrome = status.chrome ?? {};
+  if (chrome.found !== true) {
+    const checked = Array.isArray(status.candidates) ? status.candidates : [];
+    const list = checked.length > 0 ? `\nПроверено: ${checked.join(", ")}` : "";
+    return truncateText(
+      `browser_qa status: Chrome/Edge не найден. Установите Chrome или задайте CHROME_PATH (полный путь к chrome.exe).${list}`,
+    );
+  }
+  const version = chrome.version ? `${chrome.product ?? "Chrome"} ${chrome.version}` : "версия не определена";
+  const lines = [`browser_qa status: Chrome найден`, `Путь: ${chrome.path}`, `Версия: ${version}`];
+  if (chrome.kind) lines.push(`Тип: ${chrome.kind}${chrome.source ? ` (${chrome.source})` : ""}`);
+  if (chrome.probeError) lines.push(`Ошибка проверки: ${chrome.probeError}`);
+  lines.push(
+    `Node ${status.runtime?.node ?? ""} · WebSocket: ${status.runtime?.webSocket === true ? "есть" : "нет"} · PNG по умолчанию: ${status.defaultOutDir ?? ""}`,
+  );
+  return truncateText(lines.join("\n"));
+}
+
+/* ------------------------------------------------------------------ */
+/* misc                                                                */
+/* ------------------------------------------------------------------ */
+
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function abortError() {
+  const error = new Error("browser_qa: операция отменена");
+  error.name = "AbortError";
+  error.code = "ABORTED";
+  return error;
+}
+
+export function isAbortError(error) {
+  return error?.name === "AbortError" || error?.code === "ABORTED";
+}