argusqa-os 9.2.0

package/src/utils/html-reporter.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * ARGUS HTML Report Generator — D7.1
+ *
+ * Converts the latest (or a specified) JSON report into a single self-contained
+ * report.html with screenshots inlined as base64 data URIs.  No external
+ * dependencies — the output file opens correctly offline.
+ *
+ * Usage:
+ *   node src/utils/html-reporter.js                  # auto-picks latest report
+ *   node src/utils/html-reporter.js path/to/report.json
+ *   npm run report:html
+ *
+ * Output: <reports-dir>/report.html  (overwrites on each run)
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('html-reporter');
+
+const __dirname   = path.dirname(fileURLToPath(import.meta.url));
+const REPORTS_DIR = path.resolve(__dirname, '../../reports');
+
+// ── Severity helpers ──────────────────────────────────────────────────────────
+
+const SEV_COLOR = {
+  critical: { bg: '#fef2f2', border: '#fca5a5', text: '#991b1b', badge: '#dc2626', label: 'CRITICAL' },
+  warning:  { bg: '#fffbeb', border: '#fcd34d', text: '#92400e', badge: '#d97706', label: 'WARNING'  },
+  info:     { bg: '#eff6ff', border: '#93c5fd', text: '#1e40af', badge: '#2563eb', label: 'INFO'     },
+};
+
+function sevStyle(sev) {
+  const c = SEV_COLOR[sev] ?? SEV_COLOR.info;
+  return `background:${c.bg};border-left:4px solid ${c.border};color:${c.text}`;
+}
+
+function sevBadge(sev) {
+  const c = SEV_COLOR[sev] ?? SEV_COLOR.info;
+  return `<span style="background:${c.badge};color:#fff;border-radius:3px;font-size:11px;font-weight:700;padding:2px 7px;letter-spacing:.5px;white-space:nowrap">${c.label}</span>`;
+}
+
+function esc(str) {
+  return String(str ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function safeHref(url) {
+  const s = String(url ?? '');
+  return /^https?:\/\//i.test(s) ? esc(s) : '#';
+}
+
+// ── Screenshot embedding ──────────────────────────────────────────────────────
+
+function imgTag(filePath, alt = 'Screenshot', style = '') {
+  if (!filePath) return '';
+  try {
+    const buf = fs.readFileSync(filePath);
+    const ext = path.extname(filePath).slice(1).toLowerCase() || 'png';
+    const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
+    return `<img src="data:${mime};base64,${buf.toString('base64')}" alt="${esc(alt)}" style="max-width:100%;border-radius:6px;border:1px solid #e5e7eb;${style}">`;
+  } catch {
+    return `<p style="color:#6b7280;font-size:13px">Screenshot not found: ${esc(path.basename(filePath))}</p>`;
+  }
+}
+
+// ── Finding renderer ──────────────────────────────────────────────────────────
+
+function renderFinding(e) {
+  const sev  = e.severity ?? 'info';
+  const type = esc(e.type ?? 'unknown');
+  const msg  = esc(e.message ?? e.description ?? (e.requestUrl ? `HTTP ${e.status ?? '?'} ${e.requestUrl}` : ''));
+  const flaky = e.flaky ? ' <span style="color:#6b7280;font-size:11px">⚡ flaky</span>' : '';
+  const isNew = e.isNew  ? ' <span style="color:#059669;font-size:11px">★ new</span>'  : '';
+  return `
+    <div style="${sevStyle(sev)};padding:10px 14px;margin:6px 0;border-radius:0 4px 4px 0;font-size:13px;line-height:1.5">
+      <div style="display:flex;align-items:flex-start;gap:10px;flex-wrap:wrap">
+        ${sevBadge(sev)}
+        <code style="background:rgba(0,0,0,.06);border-radius:3px;padding:1px 6px;font-size:12px;white-space:nowrap">${type}</code>
+        ${flaky}${isNew}
+      </div>
+      <div style="margin-top:6px;word-break:break-word">${msg}</div>
+      ${e.requestUrl ? `<div style="margin-top:3px;font-size:11px;opacity:.8">URL: ${esc(e.requestUrl)}</div>` : ''}
+    </div>`;
+}
+
+// ── Route card ────────────────────────────────────────────────────────────────
+
+function renderRoute(route) {
+  const errors    = route.errors ?? [];
+  const criticals = errors.filter(e => e.severity === 'critical');
+  const warnings  = errors.filter(e => e.severity === 'warning');
+  const infos     = errors.filter(e => e.severity === 'info');
+
+  const headerColor = criticals.length > 0 ? '#dc2626'
+    : warnings.length  > 0 ? '#d97706'
+    : '#16a34a';
+  const headerBg = criticals.length > 0 ? '#fef2f2'
+    : warnings.length  > 0 ? '#fffbeb'
+    : '#f0fdf4';
+
+  // Summary pill row
+  const pills = [
+    criticals.length > 0 ? `<span style="background:#dc2626;color:#fff;border-radius:12px;padding:2px 10px;font-size:12px;font-weight:600">${criticals.length} critical</span>` : '',
+    warnings.length  > 0 ? `<span style="background:#d97706;color:#fff;border-radius:12px;padding:2px 10px;font-size:12px;font-weight:600">${warnings.length} warning</span>`  : '',
+    infos.length     > 0 ? `<span style="background:#2563eb;color:#fff;border-radius:12px;padding:2px 10px;font-size:12px;font-weight:600">${infos.length} info</span>`         : '',
+    errors.length   === 0 ? `<span style="background:#16a34a;color:#fff;border-radius:12px;padding:2px 10px;font-size:12px;font-weight:600">✓ clean</span>`                      : '',
+  ].filter(Boolean).join(' ');
+
+  // Screenshot
+  const shot = imgTag(route.screenshot, `${route.route} screenshot`);
+
+  // Responsive screenshots grid
+  let responsiveGrid = '';
+  if (route.responsiveScreenshots && Object.keys(route.responsiveScreenshots).length > 0) {
+    const viewports = Object.entries(route.responsiveScreenshots)
+      .sort(([a], [b]) => Number(a) - Number(b))
+      .map(([vp, fp]) => `
+        <div style="text-align:center">
+          <div style="font-size:11px;color:#6b7280;margin-bottom:4px">${esc(String(vp))}px</div>
+          ${imgTag(fp, `${route.route} at ${vp}px`, 'width:100%')}
+        </div>`).join('');
+    responsiveGrid = `
+      <div style="margin-top:16px">
+        <h4 style="margin:0 0 8px;font-size:13px;color:#374151">Responsive snapshots</h4>
+        <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:10px">${viewports}</div>
+      </div>`;
+  }
+
+  // Findings list
+  const findingRows = errors.length > 0
+    ? errors.map(renderFinding).join('')
+    : `<p style="color:#16a34a;margin:8px 0;font-size:13px">✓ No issues detected on this route.</p>`;
+
+  return `
+  <div style="border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;margin-bottom:24px;box-shadow:0 1px 3px rgba(0,0,0,.06)">
+    <!-- route header -->
+    <div style="background:${headerBg};border-bottom:1px solid #e5e7eb;padding:14px 20px;display:flex;align-items:flex-start;justify-content:space-between;flex-wrap:wrap;gap:8px">
+      <div>
+        <h3 style="margin:0;font-size:16px;color:${headerColor}">${esc(route.route)}</h3>
+        <a href="${safeHref(route.url)}" style="font-size:12px;color:#6b7280;word-break:break-all">${esc(route.url)}</a>
+      </div>
+      <div style="display:flex;gap:6px;flex-wrap:wrap;align-items:center">${pills}</div>
+    </div>
+    <!-- route body -->
+    <div style="padding:16px 20px">
+      ${shot ? `<div style="margin-bottom:16px">${shot}</div>` : ''}
+      ${responsiveGrid}
+      <div style="margin-top:${shot || responsiveGrid ? '16px' : '0'}">
+        <h4 style="margin:0 0 8px;font-size:13px;color:#374151">Findings</h4>
+        ${findingRows}
+      </div>
+    </div>
+  </div>`;
+}
+
+// ── Flow card ─────────────────────────────────────────────────────────────────
+
+function renderFlow(flow) {
+  const status   = flow.status ?? 'unknown';
+  const findings = flow.findings ?? [];
+  const statusColor = status === 'pass' ? '#16a34a' : '#dc2626';
+  const findingRows = findings.length > 0
+    ? findings.map(renderFinding).join('')
+    : '<p style="color:#16a34a;margin:8px 0;font-size:13px">✓ All assertions passed.</p>';
+
+  return `
+  <div style="border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;margin-bottom:16px">
+    <div style="background:#f9fafb;border-bottom:1px solid #e5e7eb;padding:12px 20px;display:flex;align-items:center;justify-content:space-between">
+      <span style="font-weight:600;font-size:15px">${esc(flow.flowName ?? flow.name ?? 'Flow')}</span>
+      <span style="font-size:13px;font-weight:600;color:${statusColor}">${status.toUpperCase()} (${flow.stepsCompleted ?? '?'}/${flow.totalSteps ?? '?'} steps)</span>
+    </div>
+    <div style="padding:14px 20px">${findingRows}</div>
+  </div>`;
+}
+
+// ── Full HTML document ────────────────────────────────────────────────────────
+
+function buildHtml(report) {
+  const { generatedAt, baseUrl, summary, routes = [], flows = [] } = report;
+  const runDate = new Date(generatedAt).toLocaleString(undefined, { dateStyle: 'long', timeStyle: 'short' });
+
+  const totalBg = summary.critical > 0 ? '#dc2626' : summary.warning > 0 ? '#d97706' : '#16a34a';
+
+  const summaryCards = `
+    <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(130px,1fr));gap:14px;margin-bottom:32px">
+      ${[
+        ['Total',    summary.total    ?? 0, '#374151', '#f3f4f6'],
+        ['Critical', summary.critical ?? 0, '#991b1b', '#fef2f2'],
+        ['Warning',  summary.warning  ?? 0, '#92400e', '#fffbeb'],
+        ['Info',     summary.info     ?? 0, '#1e40af', '#eff6ff'],
+      ].map(([label, count, color, bg]) => `
+        <div style="background:${bg};border:1px solid #e5e7eb;border-radius:8px;padding:18px;text-align:center">
+          <div style="font-size:32px;font-weight:700;color:${color}">${count}</div>
+          <div style="font-size:12px;color:#6b7280;margin-top:4px;text-transform:uppercase;letter-spacing:.5px">${label}</div>
+        </div>`).join('')}
+    </div>`;
+
+  const routeSections = routes.map(renderRoute).join('');
+
+  const flowSection = flows.length > 0 ? `
+    <h2 style="font-size:18px;color:#111827;border-bottom:2px solid #e5e7eb;padding-bottom:8px;margin:32px 0 16px">User Flows (${flows.length})</h2>
+    ${flows.map(renderFlow).join('')}` : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Argus Report — ${esc(runDate)}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f9fafb; color: #111827; }
+    a { color: inherit; }
+  </style>
+</head>
+<body>
+  <!-- top bar -->
+  <div style="background:${totalBg};padding:14px 32px;display:flex;align-items:center;justify-content:space-between;flex-wrap:wrap;gap:8px">
+    <span style="color:#fff;font-weight:700;font-size:20px;letter-spacing:-.3px">🛡 Argus Report</span>
+    <span style="color:rgba(255,255,255,.85);font-size:13px">${esc(runDate)} · ${esc(baseUrl)}</span>
+  </div>
+
+  <div style="max-width:1100px;margin:0 auto;padding:32px 24px">
+    ${summaryCards}
+
+    <h2 style="font-size:18px;color:#111827;border-bottom:2px solid #e5e7eb;padding-bottom:8px;margin:0 0 16px">Routes (${routes.length})</h2>
+    ${routeSections}
+
+    ${flowSection}
+
+    <p style="text-align:center;font-size:12px;color:#9ca3af;margin-top:32px">Generated by <strong>Argus</strong> · ${esc(generatedAt)}</p>
+  </div>
+</body>
+</html>`;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a JSON report file into a self-contained HTML file.
+ *
+ * Reads the JSON at `reportPath`, renders the full HTML dashboard (screenshots
+ * inlined as base64), and writes `report.html` alongside the source JSON.
+ * Called automatically by crawl-and-report.js when Slack is not configured (D7.7).
+ *
+ * @param {string} reportPath - Absolute or relative path to the JSON report file
+ * @returns {string} Absolute path to the written report.html
+ */
+export function generateHtmlReport(reportPath) {
+  let report;
+  try {
+    report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`[ARGUS] Failed to parse report JSON at ${reportPath}: ${err.message}`);
+  }
+  const html    = buildHtml(report);
+  const outPath = path.join(path.dirname(path.resolve(reportPath)), 'report.html');
+
+  fs.writeFileSync(outPath, html, 'utf8');
+
+  const kb = Math.round(Buffer.byteLength(html, 'utf8') / 1024);
+  logger.info(`[ARGUS] HTML report written: ${outPath} (${kb} KB)`);
+  return outPath;
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────────────────
+
+function findLatestReport(dir) {
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Reports directory not found: ${dir}\nRun "npm run crawl" first to generate a report.`);
+  }
+  const files = fs.readdirSync(dir)
+    .filter(f => f.startsWith('error-report-') && f.endsWith('.json'))
+    .map(f => ({ name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  if (files.length === 0) {
+    throw new Error(`No error-report-*.json files found in ${dir}\nRun "npm run crawl" first.`);
+  }
+  return path.join(dir, files[0].name);
+}
+
+// Only runs when invoked directly (npm run report:html or node src/utils/html-reporter.js)
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  const arg        = process.argv[2];
+  const reportPath = arg ? path.resolve(arg) : findLatestReport(REPORTS_DIR);
+
+  if (!fs.existsSync(reportPath)) {
+    logger.error(`Error: report not found — ${reportPath}`);
+    process.exit(1);
+  }
+
+  generateHtmlReport(reportPath);
+  logger.info(`[ARGUS] Source report: ${reportPath}`);
+}

package/src/utils/issues-analyzer.js

@@ -0,0 +1,171 @@
+/**
+ * ARGUS Chrome DevTools Issues Analyzer
+ *
+ * Queries the Chrome DevTools Issues panel via
+ * list_console_messages({ types: ['issue'] }). The Issues panel is a
+ * completely separate namespace from the console — it surfaces CORS
+ * violations, CSP blocks, mixed content, cookie misconfiguration,
+ * deprecated API use, and native low-contrast findings. None of these
+ * appear in list_console_messages({ types: ['error'] }).
+ *
+ * Detections:
+ *   cors_violation           — Cross-origin request blocked by CORS policy
+ *   csp_violation            — Resource/script blocked by Content-Security-Policy
+ *   mixed_content            — HTTP resource loaded on HTTPS page
+ *   cookie_attribute_missing — SameSite or Secure attribute missing/incorrect
+ *   deprecated_api_use       — Use of a deprecated browser API
+ *   low_contrast_native      — Text with insufficient color contrast (native check)
+ *   permission_policy_violation — Feature blocked by Permissions-Policy header
+ *
+ * Two surfaces:
+ *   parseIssues(issues, url, isCritical) — pure function for use in crawlRouteCheap
+ *     after the D5 baseline-slice has already been applied.
+ *   analyzeIssues(browser, url, isCritical) — standalone navigator for direct harness use.
+ */
+
+import { normalizeArray } from './flow-runner.js';
+
+// ── Issue classifiers ─────────────────────────────────────────────────────────
+
+const CLASSIFIERS = [
+  {
+    type:             'cors_violation',
+    issueTypePattern: /cors/i,
+    textPattern:      /cors policy|cross.origin.*blocked|access.control.allow.origin/i,
+    severity:         (isCritical) => isCritical ? 'critical' : 'warning',
+  },
+  {
+    type:             'csp_violation',
+    issueTypePattern: /ContentSecurityPolicy|content.security|csp/i,
+    textPattern:      /content.security.policy|refused to (execute|load|apply|connect|frame)|violates.*csp/i,
+    severity:         () => 'critical',
+  },
+  {
+    type:             'mixed_content',
+    issueTypePattern: /mixed.content/i,
+    textPattern:      /mixed content|http resource.*https|loaded over https.*http/i,
+    severity:         () => 'warning',
+  },
+  {
+    type:             'cookie_attribute_missing',
+    issueTypePattern: /cookie/i,
+    textPattern:      /samesite|secure attribute|partitioned|cookie.*rejected|set-cookie.*blocked/i,
+    severity:         () => 'warning',
+  },
+  {
+    type:             'deprecated_api_use',
+    issueTypePattern: /deprecat/i,
+    textPattern:      /deprecated|will be removed|no longer supported|mutation.event|document\.domain/i,
+    severity:         () => 'info',
+  },
+  {
+    type:             'low_contrast_native',
+    issueTypePattern: /contrast/i,
+    textPattern:      /contrast ratio|insufficient.*contrast|contrast.*insufficient/i,
+    severity:         () => 'warning',
+  },
+  {
+    type:             'permission_policy_violation',
+    issueTypePattern: /permission.policy|feature.policy/i,
+    textPattern:      /permission.policy|feature policy|not allowed in this document/i,
+    severity:         () => 'info',
+  },
+];
+
+function classifyIssue(issue, url, isCritical) {
+  const text = (issue.text ?? issue.message ?? issue.description ?? '').toString();
+  // chrome-devtools-mcp may expose a structured type identifier
+  const structuredType = (issue.issueType ?? issue.code ?? issue.kind ?? '').toString();
+  // Skip only when both text AND structured type are absent — structured-type-only
+  // issues (e.g. ContentSecurityPolicyIssue with no text body) must not be dropped.
+  if (!text && !structuredType) return null;
+
+  for (const c of CLASSIFIERS) {
+    const matchesType = structuredType && c.issueTypePattern.test(structuredType);
+    const matchesText = c.textPattern.test(text);
+    if (matchesType || matchesText) {
+      return {
+        type:     c.type,
+        message:  text.slice(0, 300),
+        severity: c.severity(isCritical),
+        url,
+      };
+    }
+  }
+
+  // Catch-all: emit unclassified issues so novel Chrome issue types are never silently dropped
+  if (text) {
+    return {
+      type:     'unclassified_devtools_issue',
+      message:  `Unclassified DevTools issue: ${text.slice(0, 200)}`,
+      severity: 'info',
+      url,
+    };
+  }
+
+  return null;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a pre-fetched, already-baseline-sliced issues array into findings.
+ * Pure function — used by crawlRouteCheap after the D5 baseline-slice.
+ *
+ * @param {object[]} issues    - Issues from list_console_messages({ types: ['issue'] })
+ * @param {string}   url       - Page URL (used as finding context)
+ * @param {boolean}  isCritical
+ * @returns {object[]}
+ */
+export function parseIssues(issues, url, isCritical = false) {
+  const findings = [];
+  for (const issue of issues) {
+    const finding = classifyIssue(issue, url, isCritical);
+    if (finding) findings.push(finding);
+  }
+  return findings.slice(0, 20);
+}
+
+/**
+ * Standalone issues analyzer — navigates to a URL, baselines the current
+ * Issues count, queries the panel after load, and returns findings.
+ *
+ * Used by the test harness and any standalone caller. Baselines before
+ * navigation (D5 pattern) so pre-existing issues from prior pages are excluded.
+ *
+ * @param {object}  browser
+ * @param {string}  url
+ * @param {boolean} isCritical
+ * @returns {Promise<object[]>}
+ */
+export async function analyzeIssues(browser, url, isCritical = false) {
+  const findings = [];
+
+  let baseline = 0;
+  try {
+    const priorRaw = await browser.listConsoleRaw({ types: ['issue'], includePreservedMessages: true });
+    baseline = normalizeArray(priorRaw).length;
+  } catch {
+    // Issues API may not be available — baseline stays 0
+  }
+
+  try {
+    await browser.navigate(url);
+    await new Promise(r => setTimeout(r, 1000));
+  } catch {
+    return findings;
+  }
+
+  try {
+    const raw    = await browser.listConsoleRaw({
+      types: ['issue'],
+      includePreservedMessages: true,
+    });
+    const issues = normalizeArray(raw).slice(baseline);
+    findings.push(...parseIssues(issues, url, isCritical));
+  } catch {
+    // Issues API not available in this chrome-devtools-mcp build — silent skip
+  }
+
+  return findings;
+}

package/src/utils/keyboard-analyzer.js

@@ -0,0 +1,141 @@
+/**
+ * ARGUS Keyboard Navigation Analyzer
+ *
+ * Tab-walks the page using press_key({ key: 'Tab' }) and evaluates
+ * document.activeElement after each step to detect focus management issues.
+ * take_snapshot() is called to satisfy the D8 tool-coverage requirement.
+ *
+ * Detections:
+ *   focus_visible_missing — interactive element receives Tab focus but has no
+ *                           visible focus indicator (outline:0 with no box-shadow)
+ *   focus_lost            — Tab lands on document.body instead of an interactive
+ *                           element (focus escapes the page's expected tab order)
+ *
+ * Tab-walk is capped at 20 steps to bound runtime. Duplicate elements (cycle
+ * complete) short-circuit the walk early.
+ */
+
+import { registerExpensive } from '../registry.js';
+
+const MAX_TAB_STEPS = 20;
+
+// Evaluate the currently focused element's visibility and position in tab order.
+const FOCUS_INFO_SCRIPT = `() => {
+  var el = document.activeElement;
+  if (!el || el === document.body || el === document.documentElement) {
+    return JSON.stringify({ lost: true });
+  }
+  var style = window.getComputedStyle(el);
+  var outlineWidth = parseFloat(style.outlineWidth) || 0;
+  var outlineStyle = style.outlineStyle || 'none';
+  var boxShadow    = style.boxShadow || 'none';
+  var noOutline    = (outlineWidth === 0 || outlineStyle === 'none') && boxShadow === 'none';
+  return JSON.stringify({
+    tag:       el.tagName.toLowerCase(),
+    id:        el.id || null,
+    role:      el.getAttribute('role') || null,
+    tabIndex:  el.tabIndex,
+    snippet:   el.outerHTML.slice(0, 100),
+    noOutline: noOutline,
+    lost:      false,
+  });
+}`;
+
+function parseJson(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    const inner = raw.result !== undefined ? raw.result : raw;
+    if (typeof inner === 'string') { try { return JSON.parse(inner); } catch { return null; } }
+    return typeof inner === 'object' ? inner : null;
+  }
+  if (typeof raw === 'string') { try { return JSON.parse(raw); } catch { return null; } }
+  return null;
+}
+
+/**
+ * Walk focus via Tab key and detect visibility and order issues.
+ *
+ * @param {object} browser - CdpBrowserAdapter
+ * @param {string} url - Fully-qualified URL to analyse
+ * @returns {Promise<object[]>} Array of finding objects
+ */
+export async function analyzeKeyboard(browser, url) {
+  const findings = [];
+
+  try {
+    await browser.navigate(url);
+    await new Promise(r => setTimeout(r, 800));
+  } catch {
+    return findings;
+  }
+
+  // Satisfy D8 tool-coverage requirement.
+  try { await browser.snapshot(); } catch {}
+
+  // Reset focus to body for consistent Tab-walk start state across all pages
+  await browser.evaluate('() => { document.body.click(); document.body.focus(); }').catch(() => {});
+
+  const seen         = new Set();
+  const focusLostAt  = [];
+  const noOutlineEls = [];
+
+  for (let step = 0; step < MAX_TAB_STEPS; step++) {
+    try {
+      await browser.pressKey('Tab');
+      await new Promise(r => setTimeout(r, 80));
+
+      const raw  = await browser.evaluate(FOCUS_INFO_SCRIPT);
+      const info = parseJson(raw);
+      if (!info) continue;
+
+      if (info.lost) {
+        focusLostAt.push(step + 1);
+        continue;
+      }
+
+      // Dedup by stable element identity — use tag/id/role rather than outerHTML
+      // which can include dynamic aria-expanded/counter attributes that change on focus
+      const key = `${info.tag}|${info.id ?? ''}|${info.role ?? ''}|${info.tabIndex}`;
+      if (seen.has(key)) break;
+      seen.add(key);
+
+      if (info.noOutline) {
+        noOutlineEls.push({ tag: info.tag, id: info.id, snippet: info.snippet });
+      }
+    } catch {
+      break;
+    }
+  }
+
+  for (const step of focusLostAt) {
+    findings.push({
+      type:     'focus_lost',
+      step,
+      message:  `Tab focus escapes to document.body at step ${step} — check tabindex assignments and focus traps`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  for (const item of noOutlineEls) {
+    findings.push({
+      type:     'focus_visible_missing',
+      tag:      item.tag,
+      id:       item.id,
+      snippet:  item.snippet,
+      message:  `<${item.tag}${item.id ? '#' + item.id : ''}> receives Tab focus but has no visible focus indicator (outline:0 and no box-shadow) — add :focus-visible styles`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  return findings;
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'keyboard',
+  async analyze(browser, url) {
+    return analyzeKeyboard(browser, url);
+  },
+});