dsh-desktop-kit 2.2.1 → 2.7.3

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

@@ -0,0 +1,552 @@
+/**
+ * Page orchestration for browser_qa: one headless Chrome per tool call.
+ *
+ * `shot` opens one viewport and writes one PNG; `audit` reloads the page at
+ * every requested width and measures horizontal overflow plus console errors,
+ * optionally saving one PNG per width. All Chrome state is torn down in
+ * `finally`, including on abort/error.
+ */
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { ChromeSession, detectChrome, probeChrome } from "./chrome.js";
+import {
+  LIMITS,
+  MAX_SCREENSHOT_HEIGHT,
+  MARKUP_EXPRESSION,
+  OVERFLOW_EXPRESSION,
+  PAGE_INFO_EXPRESSION,
+  SETTLE_EXPRESSION,
+  abortError,
+  consoleEventFromCdp,
+  errorMessage,
+  formatAuditText,
+  formatShotText,
+  formatStatusText,
+  isAbortError,
+  normalizeTarget,
+  normalizeViewport,
+  parseTimeout,
+  parseWidths,
+  pngSize,
+  resolveOutDir,
+  screenshotFileName,
+  shapeConsoleEvents,
+  shapeMarkupReport,
+  shapeOverflowReport,
+  summarizeAudit,
+} from "./qa.js";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const MAX_RAW_CONSOLE_EVENTS = 200;
+const AUDIT_BUDGET_MS = 150_000;
+
+class ConsoleCollector {
+  constructor(cdp) {
+    this.events = [];
+    this.dropped = 0;
+    this.unsubscribe = [
+      cdp.on("Runtime.consoleAPICalled", (params) => this.push("Runtime.consoleAPICalled", params)),
+      cdp.on("Runtime.exceptionThrown", (params) => this.push("Runtime.exceptionThrown", params)),
+      cdp.on("Log.entryAdded", (params) => this.push("Log.entryAdded", params)),
+    ];
+  }
+
+  push(method, params) {
+    if (this.events.length >= MAX_RAW_CONSOLE_EVENTS) {
+      this.dropped += 1;
+      return;
+    }
+    const event = consoleEventFromCdp(method, params);
+    if (event !== null) this.events.push(event);
+  }
+
+  reset() {
+    this.events = [];
+    this.dropped = 0;
+  }
+
+  list() {
+    return shapeConsoleEvents(this.events);
+  }
+
+  dispose() {
+    for (const off of this.unsubscribe) {
+      try {
+        off();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.unsubscribe = [];
+  }
+}
+
+class PageSession {
+  constructor(cdp) {
+    this.cdp = cdp;
+    this.console = new ConsoleCollector(cdp);
+  }
+
+  async init() {
+    await this.cdp.send("Page.enable", {}, 10_000);
+    await this.cdp.send("Runtime.enable", {}, 10_000);
+    try {
+      await this.cdp.send("Log.enable", {}, 10_000);
+    } catch {
+      /* Log domain is optional */
+    }
+    try {
+      await this.cdp.send("Page.setLifecycleEventsEnabled", { enabled: true }, 5_000);
+    } catch {
+      /* optional */
+    }
+    return this;
+  }
+
+  async evaluate(expression, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const awaitPromise = options.awaitPromise !== false;
+    const result = await this.cdp.send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise }, timeoutMs);
+    if (result?.exceptionDetails) {
+      const details = result.exceptionDetails;
+      throw new Error(details.exception?.description ?? details.text ?? "page evaluation failed");
+    }
+    return result?.result?.value;
+  }
+
+  async setViewport(width, height) {
+    await this.cdp.send(
+      "Emulation.setDeviceMetricsOverride",
+      { width, height, deviceScaleFactor: 1, mobile: false, screenWidth: width, screenHeight: height },
+      10_000,
+    );
+  }
+
+  async navigate(targetUrl, options = {}) {
+    const timeoutMs = options.timeoutMs ?? LIMITS.defaultTimeoutMs;
+    const signal = options.signal;
+    if (signal?.aborted) throw abortError();
+    this.console.reset();
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    const loaded = this.cdp
+      .once("Page.loadEventFired", timeoutMs)
+      .then(() => true)
+      .catch(() => false);
+    let navigation;
+    try {
+      navigation = await this.cdp.send("Page.navigate", { url: targetUrl }, Math.min(15_000, timeoutMs));
+    } catch (error) {
+      await loaded;
+      throw error;
+    }
+    if (typeof navigation?.errorText === "string" && navigation.errorText.length > 0) {
+      throw new Error(`navigation failed: ${navigation.errorText}`);
+    }
+    const loadEventFired = await loaded;
+    const readyDeadline = Math.min(deadline, Date.now() + 5_000);
+    let readyState = "";
+    while (Date.now() < readyDeadline) {
+      if (signal?.aborted) throw abortError();
+      try {
+        readyState = String((await this.evaluate("document.readyState", { timeoutMs: 2_000, awaitPromise: false })) ?? "");
+      } catch {
+        if (signal?.aborted) throw abortError();
+        /* page may be between documents */
+      }
+      if (readyState === "complete") break;
+      await sleep(100);
+    }
+    const settleBudget = Math.max(250, Math.min(2_000, deadline - Date.now()));
+    try {
+      await this.evaluate(SETTLE_EXPRESSION, { timeoutMs: settleBudget, awaitPromise: true });
+    } catch {
+      if (signal?.aborted) throw abortError();
+      /* fonts/settle is best effort */
+    }
+    const info = await this.pageInfo();
+    return {
+      finalUrl: info.url ?? targetUrl,
+      title: info.title ?? "",
+      readyState: readyState || info.readyState || "",
+      loadMs: Date.now() - startedAt,
+      loadTimedOut: loadEventFired !== true,
+    };
+  }
+
+  async pageInfo() {
+    try {
+      const raw = await this.evaluate(PAGE_INFO_EXPRESSION, { timeoutMs: 4_000, awaitPromise: false });
+      if (typeof raw === "string") {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") return parsed;
+      }
+    } catch {
+      /* page may have crashed or be navigating */
+    }
+    return {};
+  }
+
+  async overflowReport(options = {}) {
+    const raw = await this.evaluate(OVERFLOW_EXPRESSION, {
+      timeoutMs: options.timeoutMs ?? 10_000,
+      awaitPromise: false,
+    });
+    let parsed = {};
+    if (typeof raw === "string") {
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        parsed = {};
+      }
+    } else if (raw && typeof raw === "object") {
+      parsed = raw;
+    }
+    return shapeOverflowReport(parsed);
+  }
+
+  async markupReport(options = {}) {
+    const raw = await this.evaluate(MARKUP_EXPRESSION, {
+      timeoutMs: options.timeoutMs ?? 10_000,
+      awaitPromise: false,
+    });
+    let parsed = {};
+    if (typeof raw === "string") {
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        parsed = {};
+      }
+    } else if (raw && typeof raw === "object") {
+      parsed = raw;
+    }
+    return shapeMarkupReport(parsed);
+  }
+
+  async screenshot(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const fullPage = options.fullPage === true;
+    if (!fullPage) {
+      const shot = await this.cdp.send(
+        "Page.captureScreenshot",
+        { format: "png", fromSurface: true, captureBeyondViewport: false },
+        timeoutMs,
+      );
+      if (typeof shot?.data !== "string" || shot.data.length === 0) throw new Error("Chrome returned an empty screenshot");
+      return { base64: shot.data, fullPage: false, clipped: false };
+    }
+    let content = null;
+    try {
+      const metrics = await this.cdp.send("Page.getLayoutMetrics", {}, 10_000);
+      content = metrics?.cssContentSize ?? metrics?.contentSize ?? null;
+    } catch {
+      content = null;
+    }
+    const contentWidth = Number(content?.width);
+    const contentHeight = Number(content?.height);
+    if (!Number.isFinite(contentWidth) || !Number.isFinite(contentHeight) || contentWidth <= 0 || contentHeight <= 0) {
+      const shot = await this.cdp.send(
+        "Page.captureScreenshot",
+        { format: "png", fromSurface: true, captureBeyondViewport: true },
+        timeoutMs,
+      );
+      if (typeof shot?.data !== "string" || shot.data.length === 0) throw new Error("Chrome returned an empty screenshot");
+      return { base64: shot.data, fullPage: false, clipped: true, fallback: "layout-metrics-unavailable" };
+    }
+    const clipWidth = Math.max(1, Math.min(MAX_SCREENSHOT_HEIGHT, Math.ceil(contentWidth)));
+    const clipHeight = Math.max(1, Math.min(MAX_SCREENSHOT_HEIGHT, Math.ceil(contentHeight)));
+    const shot = await this.cdp.send(
+      "Page.captureScreenshot",
+      {
+        format: "png",
+        fromSurface: true,
+        captureBeyondViewport: true,
+        clip: { x: 0, y: 0, width: clipWidth, height: clipHeight, scale: 1 },
+      },
+      timeoutMs,
+    );
+    if (typeof shot?.data !== "string" || shot.data.length === 0) throw new Error("Chrome returned an empty screenshot");
+    return {
+      base64: shot.data,
+      fullPage: true,
+      clipped: contentWidth > clipWidth || contentHeight > clipHeight,
+      contentWidth: Math.ceil(contentWidth),
+      contentHeight: Math.ceil(contentHeight),
+    };
+  }
+
+  dispose() {
+    this.console.dispose();
+  }
+}
+
+async function writeScreenshot(file, base64) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const buffer = Buffer.from(base64, "base64");
+  await fsp.writeFile(file, buffer);
+  const dimensions = pngSize(buffer);
+  const stats = await fsp.stat(file);
+  return { path: file, format: "png", width: dimensions.width, height: dimensions.height, bytes: stats.size };
+}
+
+function signalCleanupAttach(signal, callback) {
+  if (!signal || typeof signal.addEventListener !== "function") return () => {};
+  signal.addEventListener("abort", callback, { once: true });
+  return () => {
+    try {
+      signal.removeEventListener("abort", callback);
+    } catch {
+      /* ignore */
+    }
+  };
+}
+
+/**
+ * Run `fn` with a booted Chrome session. Always kills Chrome and removes the
+ * temp profile afterwards; cleanup warnings are appended to the result.
+ */
+async function withSession(options, fn) {
+  if (options.signal?.aborted) throw abortError();
+  const detected = options.executablePath
+    ? { found: true, path: options.executablePath, kind: options.kind ?? "custom", source: "explicit" }
+    : detectChrome();
+  if (detected.found !== true) {
+    const error = new Error(
+      "Chrome/Edge not found. Install Google Chrome or set CHROME_PATH to a Chromium-based browser executable.",
+    );
+    error.code = "CHROME_NOT_FOUND";
+    error.candidates = detected.candidates ?? [];
+    throw error;
+  }
+  const session = await ChromeSession.start({
+    executablePath: detected.path,
+    kind: detected.kind,
+    timeoutMs: options.launchTimeoutMs ?? 15_000,
+  });
+  const detach = signalCleanupAttach(options.signal, () => {
+    session.close().catch(() => {});
+  });
+  let result;
+  try {
+    const page = await new PageSession(session.cdp).init();
+    try {
+      result = await fn({ session, page });
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError();
+      throw error;
+    } finally {
+      page.dispose();
+    }
+  } finally {
+    detach();
+    await session.close();
+    if (result !== null && typeof result === "object" && typeof session.cleanupWarning === "string") {
+      result.warnings = [...(Array.isArray(result.warnings) ? result.warnings : []), session.cleanupWarning];
+    }
+  }
+  return result;
+}
+
+function normalizeOptions(options = {}) {
+  const cwd = typeof options.cwd === "string" && options.cwd.length > 0 ? options.cwd : process.cwd();
+  const target = normalizeTarget(options.target ?? options.url, { cwd });
+  if (target.kind === "file" && options.validateFile !== false) {
+    let stats;
+    try {
+      stats = fs.statSync(target.file);
+    } catch {
+      throw new Error(`local file not found: ${target.file}`);
+    }
+    if (!stats.isFile()) throw new Error(`not a file: ${target.file}`);
+  }
+  return { cwd, target };
+}
+
+/** Single-viewport screenshot. */
+export async function captureShot(options = {}) {
+  const { cwd, target } = normalizeOptions(options);
+  const viewport = normalizeViewport(options);
+  const timeoutMs = parseTimeout(options.timeoutMs);
+  const fullPage = options.fullPage === true;
+  const outDir = resolveOutDir(options.outDir, cwd);
+  await fsp.mkdir(outDir, { recursive: true });
+  return withSession(options, async ({ session, page }) => {
+    await page.setViewport(viewport.width, viewport.height);
+    const navigation = await page.navigate(target.url, { timeoutMs, signal: options.signal });
+    const overflow = await page.overflowReport();
+    const consoleErrors = page.console.list();
+    const screenshot = await page.screenshot({ fullPage, timeoutMs: Math.min(30_000, Math.max(5_000, timeoutMs)) });
+    const file = path.join(
+      outDir,
+      screenshotFileName({ target: target.url, width: viewport.width, height: viewport.height, fullPage }),
+    );
+    const output = await writeScreenshot(file, screenshot.base64);
+    output.fullPage = screenshot.fullPage === true;
+    output.clipped = screenshot.clipped === true;
+    const result = {
+      ok: true,
+      action: "shot",
+      target: {
+        input: target.input,
+        url: target.url,
+        finalUrl: navigation.finalUrl,
+        kind: target.kind,
+      },
+      chrome: session.chromeInfo(),
+      viewport: { width: viewport.width, height: viewport.height },
+      output,
+      horizontalOverflow: overflow.horizontalOverflow,
+      consoleErrors,
+      page: { title: navigation.title, readyState: navigation.readyState },
+      loadMs: navigation.loadMs,
+      loadTimedOut: navigation.loadTimedOut,
+    };
+    result.text = formatShotText(result);
+    return result;
+  });
+}
+
+/**
+ * Responsive audit: navigate once per width, measure `documentElement`
+ * scrollWidth/clientWidth, list overflowing elements and console errors.
+ * PNGs are written only when `screenshots` is true (outDir then defaults to
+ * `<cwd>/.dsh/browser-qa`).
+ */
+export async function auditPages(options = {}) {
+  const { cwd, target } = normalizeOptions(options);
+  const widths = parseWidths(options.widths);
+  const { height } = normalizeViewport(options);
+  const timeoutMs = parseTimeout(options.timeoutMs);
+  const screenshots = options.screenshots === true || (typeof options.outDir === "string" && options.outDir.trim().length > 0);
+  const outDir = screenshots ? resolveOutDir(options.outDir, cwd) : null;
+  if (outDir !== null) await fsp.mkdir(outDir, { recursive: true });
+  const budgetMs = Math.min(AUDIT_BUDGET_MS, timeoutMs * widths.length + 25_000);
+  return withSession(options, async ({ session, page }) => {
+    const deadline = Date.now() + budgetMs;
+    const reports = [];
+    for (const width of widths) {
+      if (options.signal?.aborted) throw abortError();
+      if (Date.now() >= deadline) {
+        reports.push({ width, height, skipped: true, reason: "time budget exhausted" });
+        continue;
+      }
+      page.console.reset();
+      try {
+        const perWidthTimeout = Math.max(3_000, Math.min(timeoutMs, deadline - Date.now()));
+        await page.setViewport(width, height);
+        const navigation = await page.navigate(target.url, { timeoutMs: perWidthTimeout, signal: options.signal });
+        const overflow = await page.overflowReport({ timeoutMs: Math.min(10_000, perWidthTimeout) });
+        let markup = null;
+        let markupError = null;
+        try {
+          markup = await page.markupReport({ timeoutMs: Math.min(6_000, perWidthTimeout) });
+        } catch (error) {
+          markupError = errorMessage(error);
+        }
+        const consoleErrors = page.console.list();
+        let screenshot = null;
+        if (outDir !== null) {
+          const shot = await page.screenshot({
+            fullPage: options.fullPage === true,
+            timeoutMs: Math.min(30_000, perWidthTimeout),
+          });
+          const file = path.join(
+            outDir,
+            screenshotFileName({ target: target.url, width, height, fullPage: options.fullPage === true }),
+          );
+          screenshot = await writeScreenshot(file, shot.base64);
+          screenshot.fullPage = shot.fullPage === true;
+          screenshot.clipped = shot.clipped === true;
+        }
+        reports.push({
+          width,
+          height,
+          viewport: overflow.viewport,
+          horizontalOverflow: overflow.horizontalOverflow,
+          overflowingElements: overflow.overflowingElements,
+          overflowingTotal: overflow.overflowingTotal,
+          overflowingTruncated: overflow.overflowingTruncated,
+          markup,
+          ...(markupError ? { markupError } : {}),
+          consoleErrors,
+          page: { finalUrl: navigation.finalUrl, title: navigation.title, readyState: navigation.readyState },
+          loadMs: navigation.loadMs,
+          loadTimedOut: navigation.loadTimedOut,
+          screenshot,
+        });
+      } catch (error) {
+        if (isAbortError(error) || options.signal?.aborted) throw abortError();
+        reports.push({ width, height, error: errorMessage(error) });
+      }
+    }
+    const result = {
+      ok: true,
+      action: "audit",
+      target: {
+        input: target.input,
+        url: target.url,
+        finalUrl: reports.find((report) => typeof report.page?.finalUrl === "string")?.page.finalUrl ?? target.url,
+        kind: target.kind,
+      },
+      chrome: session.chromeInfo(),
+      outDir,
+      widths,
+      height,
+      reports,
+      summary: summarizeAudit(reports),
+    };
+    result.text = formatAuditText(result);
+    return result;
+  });
+}
+
+/** Detect Chrome and read its version (launches a short-lived probe). */
+export async function statusReport(options = {}) {
+  const cwd = typeof options.cwd === "string" && options.cwd.length > 0 ? options.cwd : process.cwd();
+  const detected = detectChrome();
+  const status = {
+    ok: false,
+    action: "status",
+    chrome: {
+      found: detected.found === true,
+      path: detected.path,
+      kind: detected.kind,
+      source: detected.source,
+      product: null,
+      version: null,
+      protocolVersion: null,
+      probeError: null,
+    },
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      webSocket: typeof WebSocket === "function",
+    },
+    candidates: Array.isArray(detected.candidates) ? detected.candidates : [],
+    defaultOutDir: resolveOutDir(undefined, cwd),
+  };
+  if (detected.found !== true) {
+    status.chrome.probeError = "Chrome/Edge executable not found";
+    status.text = formatStatusText(status);
+    return status;
+  }
+  if (typeof WebSocket !== "function") {
+    status.chrome.probeError = "This Node.js runtime has no built-in WebSocket (Node 22+ is required)";
+    status.text = formatStatusText(status);
+    return status;
+  }
+  try {
+    const probe = await probeChrome(detected.path, { kind: detected.kind, timeoutMs: options.timeoutMs ?? 8_000 });
+    status.chrome.product = probe.product ?? null;
+    status.chrome.version = probe.version ?? null;
+    status.chrome.protocolVersion = probe.protocolVersion ?? null;
+    status.chrome.cached = probe.cached === true;
+    status.ok = true;
+  } catch (error) {
+    status.chrome.probeError = errorMessage(error);
+  }
+  status.text = formatStatusText(status);
+  return status;
+}