argusqa-os 9.2.0

package/src/utils/memory-analyzer.js

@@ -0,0 +1,270 @@
+/**
+ * ARGUS Memory Analyzer (v3 Phase B1)
+ *
+ * Two detection surfaces:
+ *   1. Detached DOM nodes — via take_memory_snapshot (saves snapshot to disk, parsed here)
+ *      Nodes removed from the live DOM but still referenced in JS are retained
+ *      in the V8 heap as "Detached HTMLXxx" objects, causing memory pressure.
+ *   2. Heap size growth — via performance.memory across navigate-away + navigate-back
+ *      Significant heap growth after a round-trip indicates a per-load leak.
+ *
+ * Called as a standalone function after crawlRoute, like analyzeResponsive.
+ * The function always leaves the browser navigated to the target URL.
+ *
+ * Note: take_memory_snapshot requires a filePath argument — it writes the V8
+ * heap snapshot JSON to disk. We read and parse it, then delete the temp file.
+ */
+
+import fs   from 'fs';
+import os   from 'os';
+import path from 'path';
+import { unwrapEval }        from './mcp-client.js';
+import { registerExpensive } from '../registry.js';
+import { thresholds }        from '../config/targets.js';
+import { childLogger }       from './logger.js';
+
+const logger = childLogger('memory-analyzer');
+
+// ── Scripts ────────────────────────────────────────────────────────────────────
+
+/**
+ * Reads performance.memory from the page context.
+ * Chrome-only non-standard API, always present in Chrome/headless Chrome.
+ */
+const HEAP_SIZE_SCRIPT = `() => {
+  var m = window.performance && window.performance.memory;
+  if (!m) return JSON.stringify({ usedJSHeapSize: null });
+  return JSON.stringify({
+    usedJSHeapSize:  m.usedJSHeapSize,
+    totalJSHeapSize: m.totalJSHeapSize,
+    jsHeapSizeLimit: m.jsHeapSizeLimit,
+  });
+}`;
+
+// ── Snapshot Parsing ───────────────────────────────────────────────────────────
+
+/**
+ * Walk a flat V8 heap snapshot nodes array and count detached DOM nodes.
+ *
+ * The nodes array is a flat int array: each record has nodeFields.length entries.
+ * The "name" field indexes into the strings table; Chrome serializes detached
+ * DOM elements with "Detached " prepended to their class name (e.g.
+ * "Detached HTMLDivElement"). If the `detachedness` field is present (Chrome 90+),
+ * value 2 = detached — checked as a secondary signal.
+ *
+ * @param {object} snapshot - Parsed V8 heap snapshot ({ snapshot, nodes, strings })
+ * @returns {{ detachedNodeCount: number, totalNodeCount: number|null }}
+ */
+function parseV8Snapshot(snapshot) {
+  const strings    = Array.isArray(snapshot.strings) ? snapshot.strings : [];
+  const meta       = snapshot.snapshot?.meta ?? {};
+  const nodeFields = Array.isArray(meta.node_fields) ? meta.node_fields : [];
+
+  let detachedCount = 0;
+  const nameIdx         = nodeFields.indexOf('name');
+  const detachednessIdx = nodeFields.indexOf('detachedness');
+
+  if (Array.isArray(snapshot.nodes) && snapshot.nodes.length > 0 &&
+      (nameIdx !== -1 || detachednessIdx !== -1)) {
+    const stride = nodeFields.length;
+    const nodes  = snapshot.nodes;
+
+    for (let i = 0; i < nodes.length; i += stride) {
+      // Primary: "Detached " prefix in node name string (all Chrome versions)
+      if (nameIdx !== -1) {
+        const strIdx = nodes[i + nameIdx];
+        if (strIdx < strings.length && /^Detached /.test(strings[strIdx])) {
+          detachedCount++;
+          continue;
+        }
+      }
+      // Secondary: detachedness field value 2 = detached (Chrome 90+)
+      if (detachednessIdx !== -1 && nodes[i + detachednessIdx] === 2) {
+        detachedCount++;
+      }
+    }
+  } else if (strings.length > 0) {
+    // Structural fields not found — use string presence as a lower-bound indicator
+    detachedCount = strings.filter(s => /^Detached (HTML|SVG|Text|Document)/.test(s)).length;
+  }
+
+  return {
+    detachedNodeCount: detachedCount,
+    totalNodeCount:    snapshot.snapshot?.node_count ?? null,
+  };
+}
+
+// ── Heap Size Helper ───────────────────────────────────────────────────────────
+
+/**
+ * Read usedJSHeapSize from the currently-loaded page via evaluate_script.
+ * Returns null if performance.memory is unavailable.
+ */
+async function getHeapSize(browser) {
+  try {
+    const raw    = await browser.evaluate(HEAP_SIZE_SCRIPT);
+    const val    = unwrapEval(raw);
+    const parsed = typeof val === 'string' ? JSON.parse(val) : val;
+    return typeof parsed?.usedJSHeapSize === 'number' ? parsed.usedJSHeapSize : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Snapshot Capture ───────────────────────────────────────────────────────────
+
+/**
+ * Take a V8 heap snapshot, save it to a temp file, parse it, and delete the file.
+ * take_memory_snapshot writes the snapshot JSON to disk (filePath is required).
+ *
+ * @param {object} browser - CdpBrowserAdapter
+ * @returns {Promise<{ detachedNodeCount: number, totalNodeCount: number|null } | null>}
+ */
+async function captureAndParseSnapshot(browser) {
+  // Include PID + random suffix — Date.now() alone can collide when two parallel
+  // shard workers both enter captureAndParseSnapshot within the same millisecond.
+  const filePath = path.join(os.tmpdir(), `argus-heap-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.heapsnapshot`);
+  try {
+    await browser.heapSnapshot({ filePath });
+
+    let raw;
+    try {
+      raw = await fs.promises.readFile(filePath, 'utf8');
+    } catch (readErr) {
+      if (readErr.code === 'ENOENT') {
+        logger.warn(`[ARGUS] Snapshot file not written at ${filePath}`);
+        return null;
+      }
+      throw readErr;
+    }
+    const snapshot = JSON.parse(raw);
+    return parseV8Snapshot(snapshot);
+  } catch (err) {
+    logger.warn(`[ARGUS] Snapshot capture/parse error: ${err.message}`);
+    return null;
+  } finally {
+    try { fs.unlinkSync(filePath); } catch { /* best-effort cleanup */ }
+  }
+}
+
+// ── Main Analysis ──────────────────────────────────────────────────────────────
+
+/**
+ * Analyse a URL for memory leaks.
+ *
+ * Detection 1 — Detached DOM nodes (hard, deterministic):
+ *   Navigate to url → wait → take_memory_snapshot to disk → parse for "Detached Xxx" nodes.
+ *   Detached nodes are DOM elements removed from the live tree but still referenced
+ *   in JS (e.g. stashed in a closure, array, or event handler), preventing GC.
+ *
+ * Detection 2 — Heap growth across navigate-away + back (soft, GC-dependent):
+ *   Record baseline heap size → navigate to awayUrl → wait → navigate back → compare.
+ *   A growing heap across identical page loads indicates a per-load leak.
+ *   Tagged with soft:true so the harness can treat them as non-blocking.
+ *
+ * The function always ends with the browser on `url`.
+ *
+ * @param {object} browser  - CdpBrowserAdapter
+ * @param {string} url      - URL to analyse
+ * @param {string} [awayUrl='about:blank'] - Neutral URL for the navigate-away step
+ * @returns {Promise<object[]>} Memory findings (same shape as crawlRoute errors)
+ */
+export async function analyzeMemory(browser, url, awayUrl = 'about:blank') {
+  const findings = [];
+
+  // ── 1. Navigate to the target page ──────────────────────────────────────────
+  try {
+    await browser.navigate(url);
+    await new Promise(r => setTimeout(r, 1500)); // let JS run, detached nodes accumulate
+  } catch (err) {
+    logger.warn(`[ARGUS] Memory analysis navigation failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  // ── 2. Detached DOM node detection via heap snapshot ─────────────────────────
+  try {
+    const parsed = await captureAndParseSnapshot(browser);
+
+    if (parsed !== null) {
+      const { detachedNodeCount: count, totalNodeCount } = parsed;
+
+      if (count > thresholds.memory.detachedCritical) {
+        findings.push({
+          type:       'memory_detached_dom_nodes',
+          count,
+          totalNodes: totalNodeCount,
+          message:    `${count} detached DOM node(s) in heap — severe leak (threshold: >${thresholds.memory.detachedCritical})`,
+          severity:   'critical',
+          url,
+        });
+      } else if (count > thresholds.memory.detachedWarning) {
+        findings.push({
+          type:       'memory_detached_dom_nodes',
+          count,
+          totalNodes: totalNodeCount,
+          message:    `${count} detached DOM node(s) in heap — probable leak (threshold: >${thresholds.memory.detachedWarning})`,
+          severity:   'warning',
+          url,
+        });
+      }
+    }
+  } catch (err) {
+    logger.warn(`[ARGUS] Detached node detection skipped for ${url}: ${err.message}`);
+  }
+
+  // ── 3. Heap growth — navigate-away + navigate-back ────────────────────────────
+  // GC timing makes this non-deterministic; findings are tagged soft:true.
+  try {
+    const baseline = await getHeapSize(browser);
+
+    if (baseline !== null) {
+      await browser.navigate(awayUrl);
+      await new Promise(r => setTimeout(r, 2000)); // allow GC pass
+
+      await browser.navigate(url);
+      await new Promise(r => setTimeout(r, 1500));
+
+      const post = await getHeapSize(browser);
+
+      if (post !== null) {
+        const growth = post - baseline;
+
+        if (growth > thresholds.memory.heapGrowthCritical) {
+          findings.push({
+            type:          'memory_heap_growth',
+            baselineBytes: baseline,
+            postBytes:     post,
+            growthBytes:   growth,
+            message:       `Heap grew ${Math.round(growth / 1024)} KB after navigate-away + back — probable leak (baseline ${Math.round(baseline / 1024)} KB → post ${Math.round(post / 1024)} KB)`,
+            severity:      'critical',
+            soft:          true,
+            url,
+          });
+        } else if (growth > thresholds.memory.heapGrowthWarning) {
+          findings.push({
+            type:          'memory_heap_growth',
+            baselineBytes: baseline,
+            postBytes:     post,
+            growthBytes:   growth,
+            message:       `Heap grew ${Math.round(growth / 1024)} KB after navigate-away + back (baseline ${Math.round(baseline / 1024)} KB → post ${Math.round(post / 1024)} KB)`,
+            severity:      'warning',
+            soft:          true,
+            url,
+          });
+        }
+      }
+    }
+  } catch (err) {
+    logger.warn(`[ARGUS] Heap growth check skipped for ${url}: ${err.message}`);
+  }
+
+  return findings;
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'memory',
+  async analyze(browser, url) {
+    return analyzeMemory(browser, url);
+  },
+});

package/src/utils/network-timing-analyzer.js

@@ -0,0 +1,76 @@
+/**
+ * ARGUS Network HAR Timing Analyzer
+ *
+ * Reads per-request TTFB (timing.wait) from list_network_requests HAR output.
+ * Detects third-party resources that block page load — cross-origin requests
+ * have 0ms in window.performance.getEntriesByType('resource') when the server
+ * omits Timing-Allow-Origin, so PerformanceResourceTiming (NETWORK_PERF_SCRIPT)
+ * is blind to them. Chrome DevTools HAR timing is always accurate.
+ *
+ * Same-origin slow requests are covered by the existing NETWORK_PERF_SCRIPT
+ * approach in crawlRouteExpensive — this module focuses exclusively on cross-
+ * origin (third-party) blocking resources.
+ *
+ * Detections:
+ *   slow_third_party_blocking — cross-origin resource with timing.wait > 2000 ms
+ */
+
+// Cross-origin slow-resource threshold (ms)
+const THIRD_PARTY_WARNING_MS = 2000;
+
+// Static asset extensions — focus analysis on scripts/XHR/fetch, not images/fonts
+const STATIC_ASSET_EXT = /\.(png|jpg|jpeg|gif|webp|avif|svg|ico|woff2?|ttf|otf|eot)(\?.*)?$/i;
+
+/**
+ * Extract wait time (ms) from a HAR timing object.
+ * HAR 1.2 uses req.timings.wait; chrome-devtools-mcp uses req.timing.wait.
+ */
+function getWaitMs(req) {
+  if (req.timing  && typeof req.timing.wait  === 'number') return req.timing.wait;
+  if (req.timings && typeof req.timings.wait === 'number') return req.timings.wait;
+  // req.time/req.duration represent total request duration (not TTFB) — omitted to
+  // avoid flagging large-payload responses as slow when server response was fast.
+  return null;
+}
+
+function isStaticAsset(url) {
+  try { return STATIC_ASSET_EXT.test(new URL(url).pathname); } catch { return false; }
+}
+
+function isSameOrigin(reqUrl, pageUrl) {
+  try { return new URL(reqUrl).origin === new URL(pageUrl).origin; } catch { return true; }
+}
+
+/**
+ * Pure: analyse sliced list_network_requests results for slow third-party resources.
+ *
+ * @param {object[]} reqs    - sliced array of network request HAR objects
+ * @param {string}   pageUrl - URL of the page being analysed (for origin comparison)
+ * @returns {object[]}       - array of slow_third_party_blocking finding objects
+ */
+export function parseNetworkTiming(reqs, pageUrl) {
+  const findings = [];
+  for (const req of reqs) {
+    if (!req.url) continue;
+    if (isStaticAsset(req.url)) continue;
+    if (isSameOrigin(req.url, pageUrl)) continue;  // covered by NETWORK_PERF_SCRIPT
+
+    // Skip failed/aborted requests — status errors are caught by classifyNetworkRequest
+    const status = req.status ?? 0;
+    if (status === 0) continue; // aborted or in-flight — timing fields are unreliable
+    if (status < 200 || status >= 400) continue;
+
+    const waitMs = getWaitMs(req);
+    if (waitMs == null || waitMs < THIRD_PARTY_WARNING_MS) continue;
+
+    findings.push({
+      type:       'slow_third_party_blocking',
+      requestUrl: req.url,
+      waitMs:     Math.round(waitMs),
+      message:    `Slow third-party resource: ${req.method ?? 'GET'} ${req.url} — ${Math.round(waitMs)}ms server wait may block page render (threshold: ${THIRD_PARTY_WARNING_MS}ms)`,
+      severity:   'warning',
+      url:        pageUrl,
+    });
+  }
+  return findings;
+}

package/src/utils/parallel-crawler.js

@@ -0,0 +1,28 @@
+/**
+ * Argus D7.3 — Parallel route crawling: chunkArray utility.
+ * Exported separately so test-harness/validate.js can exercise it without
+ * importing crawl-and-report.js (which has heavyweight module-level side effects).
+ */
+
+/**
+ * Split arr into at most n non-empty chunks of roughly equal size.
+ *
+ * Uses ceiling division so earlier chunks are at most 1 element larger than
+ * later ones. If arr.length < n only arr.length chunks are returned (no empty
+ * chunks). If arr is empty, returns [].
+ *
+ * @param {Array}  arr - Source array (not mutated)
+ * @param {number} n   - Target number of chunks (must be > 0)
+ * @returns {Array[]}
+ */
+export function chunkArray(arr, n) {
+  // Validate inputs — arr.length throws on undefined; non-integer n produces
+  // fractional chunk sizes that silently skip elements or create unexpected extra chunks.
+  if (!Array.isArray(arr)) throw new TypeError('chunkArray: arr must be an array');
+  if (!Number.isInteger(n) || n <= 0) throw new RangeError('chunkArray: n must be a positive integer');
+  if (arr.length === 0) return [];
+  const size = Math.ceil(arr.length / Math.min(n, arr.length));
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) chunks.push(arr.slice(i, i + size));
+  return chunks;
+}

package/src/utils/responsive-analyzer.js

@@ -0,0 +1,253 @@
+/**
+ * ARGUS Responsive Analyzer (v3 Phase A6)
+ *
+ * Checks layout at four breakpoints: 375, 768, 1024, 1440 px
+ *   - Horizontal overflow at ≤768 px → critical; at wider viewports → warning
+ *   - Touch target size < 44×44 px at 375 px → warning
+ *
+ * Must be called as a standalone function — NOT inside crawlFixture/crawlRoute.
+ * Viewport changes would corrupt subsequent tests if called mid-pipeline.
+ * The function always restores the viewport to 1280×900 before returning.
+ */
+
+import { registerExpensive } from '../registry.js';
+import { childLogger }       from './logger.js';
+
+const logger = childLogger('responsive-analyzer');
+
+const BREAKPOINTS = [
+  { width: 375,  height: 812,  label: 'mobile'  },
+  { width: 768,  height: 1024, label: 'tablet'  },
+  { width: 1024, height: 768,  label: 'laptop'  },
+  { width: 1440, height: 900,  label: 'desktop' },
+];
+
+const RESTORE_VIEWPORT = { width: 1280, height: 900 };
+
+/**
+ * Injected into the page to detect horizontal overflow.
+ *
+ * Uses clientWidth (visual viewport, excludes scrollbar) rather than window.innerWidth
+ * (layout viewport). With Chrome mobile emulation the layout viewport can be 952 px
+ * (legacy mobile default) even when the visual viewport is 375 px — clientWidth
+ * always reflects the correct visual width.
+ *
+ * Returns JSON string for safe serialisation through the MCP transport.
+ */
+export const OVERFLOW_CHECK_SCRIPT = `() => JSON.stringify({
+  overflows: document.documentElement.scrollWidth > document.documentElement.clientWidth,
+  scrollWidth: document.documentElement.scrollWidth,
+  clientWidth: document.documentElement.clientWidth
+})`;
+
+/**
+ * Injected into the page at 375px to find interactive elements smaller than 44×44 px.
+ * Excludes hidden inputs and zero-size elements (e.g. display:none).
+ */
+export const TOUCH_TARGET_SCRIPT = `() => {
+  var sel = 'button, a[href], input:not([type=hidden]), select, textarea, [role="button"], [onclick]';
+  var MIN = 44;
+  var small = [];
+  Array.prototype.forEach.call(document.querySelectorAll(sel), function(el) {
+    var r = el.getBoundingClientRect();
+    var w = Math.round(r.width);
+    var h = Math.round(r.height);
+    if (w > 0 && h > 0 && (w < MIN || h < MIN)) {
+      small.push({
+        tag: el.tagName.toLowerCase(),
+        id: el.id || null,
+        className: (el.className || '').slice(0, 60),
+        width: w,
+        height: h,
+        text: (el.innerText || el.value || '').slice(0, 40).trim()
+      });
+    }
+  });
+  return JSON.stringify(small);
+}`;
+
+/**
+ * Parse an evaluate_script result that should be a JSON object.
+ * Handles pre-parsed object, { result: ... } wrapper, or raw JSON string.
+ */
+function parseEvalObject(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    const inner = raw.result !== undefined ? raw.result : raw;
+    if (typeof inner === 'object' && !Array.isArray(inner)) return inner;
+    if (typeof inner === 'string') {
+      // Log parse failures so a broken evaluate_script response is diagnosable.
+      try { return JSON.parse(inner); } catch (e) {
+        logger.warn('[ARGUS] parseEvalObject: JSON.parse failed —', e.message, '— raw type:', typeof raw);
+        return null;
+      }
+    }
+  }
+  if (typeof raw === 'string') {
+    try { return JSON.parse(raw); } catch (e) {
+      logger.warn('[ARGUS] parseEvalObject: JSON.parse failed —', e.message);
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse an evaluate_script result that should be a JSON array.
+ */
+function parseEvalArray(raw) {
+  if (raw == null) return [];
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === 'object') {
+    // Use raw as fallback (not raw.value) — MCP responses use .result consistently;
+    // .value is not part of the MCP wrapper schema.
+    const inner = raw.result !== undefined ? raw.result : raw;
+    if (Array.isArray(inner)) return inner;
+    if (typeof inner === 'string') {
+      // Log parse failures.
+      try { const p = JSON.parse(inner); return Array.isArray(p) ? p : []; } catch (e) {
+        logger.warn('[ARGUS] parseEvalArray: JSON.parse failed —', e.message, '— raw type:', typeof raw);
+        return [];
+      }
+    }
+    const vals = Object.values(raw);
+    if (vals.length === 1 && Array.isArray(vals[0])) return vals[0];
+    return [];
+  }
+  if (typeof raw === 'string') {
+    try { const p = JSON.parse(raw); return Array.isArray(p) ? p : []; } catch (e) {
+      logger.warn('[ARGUS] parseEvalArray: JSON.parse failed —', e.message);
+      return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * Build the emulate viewport string for chrome-devtools-mcp's emulate tool.
+ * Format: '<width>x<height>x<dpr>[,mobile][,touch]'
+ * mobile+touch enables Emulation.setDeviceMetricsOverride with mobile=true.
+ * After emulation, window.innerWidth reflects the legacy layout viewport (~952px),
+ * NOT the device width. Use document.documentElement.clientWidth for the actual
+ * visual viewport width (see OVERFLOW_CHECK_SCRIPT and its comment above).
+ */
+function viewportString(width, height) {
+  const mobile = width <= 768 ? ',mobile,touch' : '';
+  return `${width}x${height}x1${mobile}`;
+}
+
+/**
+ * Analyse a URL at four responsive breakpoints.
+ *
+ * Uses browser.emulate({ viewport }) rather than resize_page because resize_page only
+ * resizes the browser window — it does not update the CSS viewport that JS reads
+ * via window.innerWidth. emulate() calls Emulation.setDeviceMetricsOverride which
+ * properly sets both the layout viewport and window.innerWidth.
+ *
+ * @param {object} browser - CdpBrowserAdapter
+ * @param {string} url - Page URL to analyse
+ * @returns {Promise<{ findings: object[], screenshots: object }>}
+ *   findings — array of responsive bug entries (same shape as crawlRoute errors)
+ *   screenshots — map of "WIDTHxHEIGHT" → base64 PNG data
+ */
+export async function analyzeResponsive(browser, url) {
+  const findings    = [];
+  const screenshots = {};
+
+  try {
+    for (const bp of BREAKPOINTS) {
+      // Apply 4× CPU throttle for mobile/tablet breakpoints to expose JS-heavy
+      // layout issues that only manifest under realistic mobile device load.
+      // Reset to 1× for desktop breakpoints to avoid slowing subsequent analyses.
+      try {
+        await browser.emulateCpu(bp.width <= 768 ? 4 : 1);
+      } catch { /* emulateCpu is best-effort — proceed without throttle if unavailable */ }
+
+      try {
+        await browser.emulate(viewportString(bp.width, bp.height));
+        await browser.navigate(url);
+        await new Promise(r => setTimeout(r, 1000));
+
+        // ── Overflow check ──────────────────────────────────────────────────
+        try {
+          const raw         = await browser.evaluate(OVERFLOW_CHECK_SCRIPT);
+          const overflowData = parseEvalObject(raw);
+
+          if (overflowData?.overflows) {
+            const isMobile = bp.width <= 768;
+            findings.push({
+              type:        'responsive_overflow',
+              viewport:    bp.width,
+              label:       bp.label,
+              scrollWidth: overflowData.scrollWidth,
+              clientWidth: overflowData.clientWidth,
+              message:     `Horizontal overflow at ${bp.width}px (${bp.label}): scrollWidth ${overflowData.scrollWidth}px > viewport ${overflowData.clientWidth}px`,
+              severity:    isMobile ? 'critical' : 'warning',
+              url,
+            });
+          }
+        } catch (err) {
+          logger.warn(`[ARGUS] Overflow check failed at ${bp.width}px: ${err.message}`);
+        }
+
+        // ── Touch target check — at 375 px (mobile) and 768 px (tablet) ──────
+        if (bp.width === 375 || bp.width === 768) {
+          try {
+            const raw         = await browser.evaluate(TOUCH_TARGET_SCRIPT);
+            const smallTargets = parseEvalArray(raw);
+
+            if (smallTargets.length > 0) {
+              findings.push({
+                type:     'responsive_small_touch_target',
+                viewport:  bp.width,
+                label:     bp.label,
+                count:     smallTargets.length,
+                targets:   smallTargets.slice(0, 10),
+                message:   `${smallTargets.length} interactive element(s) smaller than 44×44 px at ${bp.width}px (${bp.label}): ${
+                  smallTargets.map(t => `<${t.tag}${t.id ? '#' + t.id : ''}> ${t.width}×${t.height}px`).join(', ')
+                }`,
+                severity:  'warning',
+                url,
+              });
+            }
+          } catch (err) {
+            logger.warn(`[ARGUS] Touch target check failed at ${bp.width}px: ${err.message}`);
+          }
+        }
+
+        // ── Screenshot ──────────────────────────────────────────────────────
+        try {
+          const shot = await browser.screenshot({ format: 'png' });
+          // Cap at 5 MB base64 — a 1440×900 PNG can exceed this on complex pages;
+          // storing unbounded data across 4 breakpoints × N routes risks OOM.
+          if (shot?.data && shot.data.length < 5_000_000) {
+            screenshots[`${bp.width}x${bp.height}`] = shot.data;
+          } else if (shot?.data) {
+            // Record omission metadata so operators know which breakpoints were
+            // skipped and can investigate rather than silently missing screenshot data.
+            screenshots[`${bp.width}x${bp.height}`] = { omitted: true, reason: 'size_cap', bytes: shot.data.length };
+          }
+        } catch { /* screenshots are optional */ }
+
+      } catch (err) {
+        logger.warn(`[ARGUS] Responsive analysis failed at ${bp.width}px: ${err.message}`);
+      }
+    }
+  } finally {
+    // ── Always restore viewport and CPU throttle ─────────────────────────
+    try { await browser.emulateCpu(1); } catch { /* best-effort */ }
+    try {
+      await browser.emulate(viewportString(RESTORE_VIEWPORT.width, RESTORE_VIEWPORT.height));
+    } catch { /* best-effort restore */ }
+  }
+
+  return { findings, screenshots };
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'responsive',
+  async analyze(browser, url) {
+    return analyzeResponsive(browser, url);
+  },
+});

package/src/utils/retry.js

@@ -0,0 +1,36 @@
+import { childLogger } from './logger.js';
+
+const logger = childLogger('retry');
+
+/**
+ * withRetry — exponential-backoff retry wrapper for transient CDP failures.
+ *
+ * Applied in CdpBrowserAdapter to navigate() and fill() — idempotent operations
+ * most likely to fail transiently under load. click() is intentionally excluded
+ * (not idempotent — a retry could submit forms or trigger deletions twice).
+ *
+ * Set ARGUS_RETRY_ATTEMPTS=1 to disable retries (e.g. CI).
+ * Non-numeric values fall back to 3 silently.
+ *
+ * @param {() => Promise<*>} fn       - Async function to call
+ * @param {object}           opts
+ * @param {number}           opts.attempts  - Max total attempts (default: ARGUS_RETRY_ATTEMPTS ?? 3)
+ * @param {number}           opts.delayMs   - Base delay in ms; doubles each attempt (default: 400)
+ * @param {string}           opts.label     - Human-readable label for debug logging
+ * @returns {Promise<*>} Result of fn on success
+ * @throws  Last error if all attempts fail
+ */
+export async function withRetry(fn, { attempts, delayMs = 400, label = '' } = {}) {
+  const parsed = parseInt(process.env.ARGUS_RETRY_ATTEMPTS ?? '3', 10);
+  const maxAttempts = attempts ?? (Number.isFinite(parsed) && parsed >= 1 ? parsed : 3);
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (i === maxAttempts - 1) throw err;
+      const wait = delayMs * Math.pow(2, i);
+      logger.debug(`[ARGUS] ${label ? label + ': ' : ''}retry ${i + 1}/${maxAttempts - 1} after ${wait}ms — ${err.message}`);
+      await new Promise(r => setTimeout(r, wait));
+    }
+  }
+}