apex-auditor 0.2.7 → 0.2.9

package/README.md

@@ -2,144 +2,151 @@
 
 ApexAuditor is a small, framework-agnostic Lighthouse runner that gives you **fast, structured insights** across multiple pages and devices.
 
-It is designed to:
+It focuses on:
 
-- **Run anywhere**: attach to an existing Chrome instance (remote debugging) on Windows, macOS, or Linux.
-- **Work with any web stack**: Next.js, Vite, Rails, static sites, etc. – as long as there is an HTTP server.
-- **Summarize multiple pages at once**: homepage, blog, auth, search, and more.
-- **Output developer-friendly reports**: one Markdown table + JSON, ready to paste into PRs or chat.
-
-> V1 focuses on a solid, single-project core. Route auto-detection and monorepo orchestration will land in later versions.
+- **Multi-page, multi-device audits**: run Lighthouse across your key flows in one shot.
+- **Framework flexibility**: works with any stack that serves HTTP (Next.js, Remix, Vite/React, SvelteKit, Rails, static sites, etc.).
+- **Smart route discovery**: auto-detects routes for Next.js (App/Pages), Remix, SvelteKit, and can crawl generic SPAs.
+- **Developer-friendly reports**: readable console output, Markdown tables, HTML reports, and JSON summaries for CI.
+- **Configurable throttling**: tune CPU/network throttling for accuracy vs speed trade-offs.
+- **Parallel execution**: speed up batch testing with multiple Chrome instances.
 
 ---
 
-## Quick start (single project)
+## Example output
 
-### 1. Install dependencies
+Terminal summary:
 
-From the `apex-auditor` directory:
+![Example terminal output 1](./public/example_output_1.png)
 
-```bash
-pnpm install
-```
+![Example terminal output 2](./public/example_output_2.png)
 
-### 2. Start your web app
+Wizard route selection:
 
-In your application repo (for example, a Next.js app running on port 3000):
+![Wizard screenshot](./public/wizard_1.png)
 
-```bash
-pnpm start
-# or: pnpm dev, npm run dev, etc.
-```
+---
+
+## Installation
 
-Make sure the app is reachable at the `baseUrl` you will configure (default example: `http://localhost:3000`).
+Install as a dev dependency (recommended):
 
-### 3. Start Chrome with remote debugging
+```bash
+pnpm add -D apex-auditor
+# or
+npm install --save-dev apex-auditor
+```
 
-ApexAuditor connects to an existing Chrome instance instead of launching its own. Start Chrome once with a debugging port (example for Windows):
+You can also run it without installing by using your package manager's "dlx"/"npx" style command, for example:
 
 ```bash
-"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" \
-  --remote-debugging-port=9222 \
-  --user-data-dir="%LOCALAPPDATA%\\ChromeApex"
+pnpm dlx apex-auditor@latest wizard
 ```
 
-On macOS or Linux the flags are the same; only the Chrome path changes.
+---
+
+## Common commands
 
-### 4. Configure pages (wizard-friendly)
+All commands are available as a CLI named `apex-auditor` once installed.
 
-Run the guided wizard to scaffold `apex.config.json` and optionally auto-discover routes:
+### Quickstart (auto-detect routes and run a one-off audit)
 
 ```bash
-pnpm wizard
+apex-auditor quickstart --base-url http://localhost:3000
 ```
 
-The wizard asks for the base URL, optional query string, desired Chrome port, run count, and can crawl popular frameworks (Next.js app/pages) to prefill routes before you fine-tune the list. You can still edit the file manually afterwards:
+### Wizard (interactive config with route auto-detection)
 
-```jsonc
-{
-  "baseUrl": "http://localhost:3000",
-  "query": "?lhci=1",
-  "chromePort": 9222,
-  "runs": 1,
-  "pages": [
-    { "path": "/", "label": "home", "devices": ["mobile", "desktop"] },
-    { "path": "/blog", "label": "blog", "devices": ["mobile", "desktop"] },
-    { "path": "/contact", "label": "contact", "devices": ["mobile"] }
-  ]
-}
+```bash
+apex-auditor wizard
 ```
 
-> Tip: rerun `pnpm wizard -- --config custom/path.json` to regenerate configs for multiple projects, or pass a different `--project-root` when prompted to detect routes from another app.
+The wizard can detect routes for:
 
-- `baseUrl`: root URL of your running app.
-- `query` (optional): query string appended to every URL (for example `?lhci=1` to disable analytics).
-- `chromePort` (optional): remote debugging port (defaults to `9222`).
-- `runs` (optional): how many times to run Lighthouse per page/device (results are averaged).
-- `pages`: list of paths and devices to audit.
+- Next.js (App Router / Pages Router)
+- Remix
+- SvelteKit
+- Single Page Apps (Vite/CRA/etc., via HTML crawl)
 
-### 5. Run an audit
+### Audit (run using an existing config)
 
 ```bash
-pnpm audit
+apex-auditor audit --config apex.config.json
 ```
 
-This will:
+**CLI flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--ci` | Enable CI mode with budgets and non-zero exit codes |
+| `--no-color` / `--color` | Control ANSI colours in console output |
+| `--log-level <level>` | Override Lighthouse log level (`silent`, `error`, `info`, `verbose`) |
+| `--throttling <method>` | Throttling method: `simulate` (fast) or `devtools` (accurate) |
+| `--cpu-slowdown <n>` | CPU slowdown multiplier (1-20, default: 4) |
+| `--parallel <n>` | Number of pages to audit in parallel (1-10) |
+| `--warm-up` | Perform warm-up requests before auditing |
+| `--open` | Auto-open HTML report in browser after audit |
+| `--json` | Output JSON to stdout (for piping) |
+| `--mobile-only` | Only audit mobile device configurations |
+| `--desktop-only` | Only audit desktop device configurations |
 
-- Run Lighthouse for every `page × device` defined in `apex.config.json`.
-- Write structured results to `.apex-auditor/summary.json`.
-- Write a human-readable table to `.apex-auditor/summary.md`.
-- Print the same table to the terminal.
+---
 
-Example output:
+## Output files
 
-```text
-| Label | Path | Device  | P  | A  | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS   | Top issues |
-|-------|------|---------|----|----|----|-----|---------|---------|----------|-------|-----------|
-| home  | /    | mobile  | 95 |100 |100 |100  | 2.9     | 0.9     |   160    | 0.002 | render-blocking-resources (140ms); unused-javascript (55KB) |
-| home  | /    | desktop |100 |100 |100 |100  | 0.6     | 0.4     |     0    | 0.016 | unused-javascript (55KB) |
-```
+After each audit, results are saved to `.apex-auditor/`:
 
-You can paste this table directly into PRs, tickets, or chat to discuss optimizations.
+- `summary.json` – structured JSON results
+- `summary.md` – Markdown table
+- `report.html` – visual HTML report with score circles and metrics
 
 ---
 
-## Configuration reference (V1)
+## Configuration
 
-```ts
-// apex.config.json (TypeScript shape)
-interface ApexPageConfig {
-  path: string;          // URL path, must start with "/"
-  label: string;         // short label for reports
-  devices: ("mobile" | "desktop")[];
-}
+Example `apex.config.json`:
 
-interface ApexConfig {
-  baseUrl: string;       // e.g. "http://localhost:3000"
-  query?: string;        // e.g. "?lhci=1"
-  chromePort?: number;   // default: 9222
-  runs?: number;         // default: 1
-  pages: ApexPageConfig[];
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "runs": 3,
+  "throttlingMethod": "devtools",
+  "cpuSlowdownMultiplier": 4,
+  "parallel": 2,
+  "warmUp": true,
+  "pages": [
+    { "path": "/", "label": "home", "devices": ["mobile", "desktop"] },
+    { "path": "/docs", "label": "docs", "devices": ["mobile"] }
+  ],
+  "budgets": {
+    "categories": { "performance": 80, "accessibility": 90 },
+    "metrics": { "lcpMs": 2500, "inpMs": 200 }
+  }
 }
 ```
 
-Future versions will add:
+---
 
-- Automatic route discovery (for example, from Next.js `app/` routes or a crawler).
-- Workspace-level configs for monorepos.
-- CI integration recipes and HTML dashboards.
+## Metrics tracked
+
+- **LCP** (Largest Contentful Paint)
+- **FCP** (First Contentful Paint)
+- **TBT** (Total Blocking Time)
+- **CLS** (Cumulative Layout Shift)
+- **INP** (Interaction to Next Paint) - Core Web Vital
 
 ---
 
-## Code structure (V1)
+## Further documentation
+
+For detailed guides, configuration options, and CI examples, see the `docs/` directory:
 
-The codebase is intentionally small and modular:
+- `docs/getting-started.md` – installation, quickstart, wizard, and audit flows.
+- `docs/configuration-and-routes.md` – `apex.config.json` schema and route detection details.
+- `docs/cli-and-ci.md` – CLI flags, CI mode, budgets, and example workflows.
 
-- `src/types.ts` – shared type definitions for config and results.
-- `src/config.ts` – loads and validates `apex.config.json`.
-- `src/lighthouse-runner.ts` – runs Lighthouse for each page/device and normalises results.
-- `src/cli.ts` – CLI entry point; orchestrates config + runner, writes JSON/Markdown.
+---
 
-All public modules use explicit TypeScript types and are written to be reusable in future integrations (route detectors, monorepo orchestration, CI adapters).
+## License
 
-See `ROADMAP.md` for planned features and phases.
+MIT

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { exec } from "node:child_process";
 import { loadConfig } from "./config.js";
 import { runAuditsForConfig } from "./lighthouse-runner.js";
 const ANSI_RESET = "\u001B[0m";
@@ -16,12 +17,20 @@ const TBT_GOOD_MS = 200;
 const TBT_WARN_MS = 600;
 const CLS_GOOD = 0.1;
 const CLS_WARN = 0.25;
+const INP_GOOD_MS = 200;
+const INP_WARN_MS = 500;
 function parseArgs(argv) {
     let configPath;
     let ci = false;
     let colorMode = "auto";
     let logLevelOverride;
     let deviceFilter;
+    let throttlingMethodOverride;
+    let cpuSlowdownOverride;
+    let parallelOverride;
+    let openReport = false;
+    let warmUp = false;
+    let jsonOutput = false;
     for (let i = 2; i < argv.length; i += 1) {
         const arg = argv[i];
         if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
@@ -59,9 +68,44 @@ function parseArgs(argv) {
             }
             deviceFilter = "desktop";
         }
+        else if (arg === "--throttling" && i + 1 < argv.length) {
+            const value = argv[i + 1];
+            if (value === "simulate" || value === "devtools") {
+                throttlingMethodOverride = value;
+            }
+            else {
+                throw new Error(`Invalid --throttling value: ${value}. Expected "simulate" or "devtools".`);
+            }
+            i += 1;
+        }
+        else if (arg === "--cpu-slowdown" && i + 1 < argv.length) {
+            const value = parseFloat(argv[i + 1]);
+            if (Number.isNaN(value) || value <= 0 || value > 20) {
+                throw new Error(`Invalid --cpu-slowdown value: ${argv[i + 1]}. Expected number between 0 and 20.`);
+            }
+            cpuSlowdownOverride = value;
+            i += 1;
+        }
+        else if (arg === "--parallel" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value < 1 || value > 10) {
+                throw new Error(`Invalid --parallel value: ${argv[i + 1]}. Expected integer between 1 and 10.`);
+            }
+            parallelOverride = value;
+            i += 1;
+        }
+        else if (arg === "--open") {
+            openReport = true;
+        }
+        else if (arg === "--warm-up") {
+            warmUp = true;
+        }
+        else if (arg === "--json") {
+            jsonOutput = true;
+        }
     }
     const finalConfigPath = configPath ?? "apex.config.json";
-    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride, deviceFilter };
+    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride, deviceFilter, throttlingMethodOverride, cpuSlowdownOverride, parallelOverride, openReport, warmUp, jsonOutput };
 }
 /**
  * Runs the ApexAuditor audit CLI.
@@ -73,9 +117,17 @@ export async function runAuditCli(argv) {
     const startTimeMs = Date.now();
     const { configPath, config } = await loadConfig({ configPath: args.configPath });
     const effectiveLogLevel = args.logLevelOverride ?? config.logLevel;
+    const effectiveThrottling = args.throttlingMethodOverride ?? config.throttlingMethod;
+    const effectiveCpuSlowdown = args.cpuSlowdownOverride ?? config.cpuSlowdownMultiplier;
+    const effectiveParallel = args.parallelOverride ?? config.parallel;
+    const effectiveWarmUp = args.warmUp || config.warmUp === true;
     const effectiveConfig = {
         ...config,
         logLevel: effectiveLogLevel,
+        throttlingMethod: effectiveThrottling,
+        cpuSlowdownMultiplier: effectiveCpuSlowdown,
+        parallel: effectiveParallel,
+        warmUp: effectiveWarmUp,
     };
     const filteredConfig = filterConfigDevices(effectiveConfig, args.deviceFilter);
     if (filteredConfig.pages.length === 0) {
@@ -90,11 +142,25 @@ export async function runAuditCli(argv) {
     await writeFile(resolve(outputDir, "summary.json"), JSON.stringify(summary, null, 2), "utf8");
     const markdown = buildMarkdown(summary.results);
     await writeFile(resolve(outputDir, "summary.md"), markdown, "utf8");
+    const html = buildHtmlReport(summary.results, summary.configPath);
+    const reportPath = resolve(outputDir, "report.html");
+    await writeFile(reportPath, html, "utf8");
+    // Open HTML report in browser if requested
+    if (args.openReport) {
+        openInBrowser(reportPath);
+    }
+    // If JSON output requested, print JSON and exit early
+    if (args.jsonOutput) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
     // Also echo a compact, colourised table to stdout for quick viewing.
     const useColor = shouldUseColor(args.ci, args.colorMode);
     const consoleTable = buildConsoleTable(summary.results, useColor);
     // eslint-disable-next-line no-console
     console.log(consoleTable);
+    printSummaryStats(summary.results, useColor);
     printRedIssues(summary.results);
     printCiSummary(args, summary.results, effectiveConfig.budgets);
     printLowestPerformancePages(summary.results, useColor);
@@ -131,12 +197,108 @@ function filterPageDevices(page, deviceFilter) {
 }
 function buildMarkdown(results) {
     const header = [
-        "| Label | Path | Device | P | A | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS | Error | Top issues |",
-        "|-------|------|--------|---|---|----|-----|---------|---------|----------|-----|-------|-----------|",
+        "| Label | Path | Device | P | A | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS | INP (ms) | Error | Top issues |",
+        "|-------|------|--------|---|---|----|-----|---------|---------|----------|-----|----------|-------|-----------|",
     ].join("\n");
     const lines = results.map((result) => buildRow(result));
     return `${header}\n${lines.join("\n")}`;
 }
+function buildHtmlReport(results, configPath) {
+    const timestamp = new Date().toISOString();
+    const rows = results.map((result) => buildHtmlRow(result)).join("\n");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ApexAuditor Report</title>
+  <style>
+    :root { --green: #0cce6b; --yellow: #ffa400; --red: #ff4e42; --bg: #1a1a2e; --card: #16213e; --text: #eee; }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); padding: 2rem; }
+    h1 { margin-bottom: 0.5rem; }
+    .meta { color: #888; margin-bottom: 2rem; font-size: 0.9rem; }
+    .cards { display: grid; gap: 1.5rem; }
+    .card { background: var(--card); border-radius: 12px; padding: 1.5rem; }
+    .card-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 1rem; border-bottom: 1px solid #333; padding-bottom: 1rem; }
+    .card-title { font-size: 1.1rem; font-weight: 600; }
+    .device-badge { font-size: 0.75rem; padding: 0.25rem 0.5rem; border-radius: 4px; background: #333; }
+    .device-badge.mobile { background: #0891b2; }
+    .device-badge.desktop { background: #7c3aed; }
+    .scores { display: flex; gap: 1rem; margin-bottom: 1rem; }
+    .score-item { text-align: center; flex: 1; }
+    .score-circle { width: 60px; height: 60px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 1.25rem; font-weight: bold; margin: 0 auto 0.5rem; border: 3px solid; }
+    .score-circle.green { border-color: var(--green); color: var(--green); }
+    .score-circle.yellow { border-color: var(--yellow); color: var(--yellow); }
+    .score-circle.red { border-color: var(--red); color: var(--red); }
+    .score-label { font-size: 0.75rem; color: #888; }
+    .metrics { display: grid; grid-template-columns: repeat(auto-fit, minmax(100px, 1fr)); gap: 1rem; }
+    .metric { background: #1a1a2e; padding: 0.75rem; border-radius: 8px; text-align: center; }
+    .metric-value { font-size: 1.1rem; font-weight: 600; }
+    .metric-value.green { color: var(--green); }
+    .metric-value.yellow { color: var(--yellow); }
+    .metric-value.red { color: var(--red); }
+    .metric-label { font-size: 0.7rem; color: #888; margin-top: 0.25rem; }
+    .issues { margin-top: 1rem; padding-top: 1rem; border-top: 1px solid #333; }
+    .issues-title { font-size: 0.8rem; color: #888; margin-bottom: 0.5rem; }
+    .issue { font-size: 0.85rem; color: #ccc; padding: 0.25rem 0; }
+  </style>
+</head>
+<body>
+  <h1>ApexAuditor Report</h1>
+  <p class="meta">Generated: ${timestamp} | Config: ${escapeHtml(configPath)}</p>
+  <div class="cards">
+${rows}
+  </div>
+</body>
+</html>`;
+}
+function buildHtmlRow(result) {
+    const scores = result.scores;
+    const metrics = result.metrics;
+    const lcpSeconds = metrics.lcpMs !== undefined ? (metrics.lcpMs / 1000).toFixed(1) + "s" : "-";
+    const fcpSeconds = metrics.fcpMs !== undefined ? (metrics.fcpMs / 1000).toFixed(1) + "s" : "-";
+    const tbtMs = metrics.tbtMs !== undefined ? Math.round(metrics.tbtMs) + "ms" : "-";
+    const clsVal = metrics.cls !== undefined ? metrics.cls.toFixed(3) : "-";
+    const inpMs = metrics.inpMs !== undefined ? Math.round(metrics.inpMs) + "ms" : "-";
+    const issues = result.opportunities.slice(0, 3).map((o) => `<div class="issue">${escapeHtml(o.title)}${o.estimatedSavingsMs ? ` (${Math.round(o.estimatedSavingsMs)}ms)` : ""}</div>`).join("");
+    return `    <div class="card">
+      <div class="card-header">
+        <div class="card-title">${escapeHtml(result.label)} <span style="color:#888">${escapeHtml(result.path)}</span></div>
+        <span class="device-badge ${result.device}">${result.device}</span>
+      </div>
+      <div class="scores">
+        ${buildScoreCircle("P", scores.performance)}
+        ${buildScoreCircle("A", scores.accessibility)}
+        ${buildScoreCircle("BP", scores.bestPractices)}
+        ${buildScoreCircle("SEO", scores.seo)}
+      </div>
+      <div class="metrics">
+        ${buildMetricBox("LCP", lcpSeconds, getMetricClass(metrics.lcpMs, 2500, 4000))}
+        ${buildMetricBox("FCP", fcpSeconds, getMetricClass(metrics.fcpMs, 1800, 3000))}
+        ${buildMetricBox("TBT", tbtMs, getMetricClass(metrics.tbtMs, 200, 600))}
+        ${buildMetricBox("CLS", clsVal, getMetricClass(metrics.cls, 0.1, 0.25))}
+        ${buildMetricBox("INP", inpMs, getMetricClass(metrics.inpMs, 200, 500))}
+      </div>
+      ${issues ? `<div class="issues"><div class="issues-title">Top Issues</div>${issues}</div>` : ""}
+    </div>`;
+}
+function buildScoreCircle(label, score) {
+    const value = score !== undefined ? score.toString() : "-";
+    const colorClass = score === undefined ? "" : score >= 90 ? "green" : score >= 50 ? "yellow" : "red";
+    return `<div class="score-item"><div class="score-circle ${colorClass}">${value}</div><div class="score-label">${label}</div></div>`;
+}
+function buildMetricBox(label, value, colorClass) {
+    return `<div class="metric"><div class="metric-value ${colorClass}">${value}</div><div class="metric-label">${label}</div></div>`;
+}
+function getMetricClass(value, good, warn) {
+    if (value === undefined)
+        return "";
+    return value <= good ? "green" : value <= warn ? "yellow" : "red";
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 function buildConsoleTable(results, useColor) {
     const header = [
         "| Label | Path | Device | P | A | BP | SEO |",
@@ -161,9 +323,10 @@ function buildRow(result) {
     const fcpSeconds = metrics.fcpMs !== undefined ? (metrics.fcpMs / 1000).toFixed(1) : "-";
     const tbtMs = metrics.tbtMs !== undefined ? Math.round(metrics.tbtMs).toString() : "-";
     const cls = metrics.cls !== undefined ? metrics.cls.toFixed(3) : "-";
+    const inpMs = metrics.inpMs !== undefined ? Math.round(metrics.inpMs).toString() : "-";
     const issues = formatTopIssues(result.opportunities);
     const error = result.runtimeErrorCode ?? (result.runtimeErrorMessage !== undefined ? result.runtimeErrorMessage : "");
-    return `| ${result.label} | ${result.path} | ${result.device} | ${scores.performance ?? "-"} | ${scores.accessibility ?? "-"} | ${scores.bestPractices ?? "-"} | ${scores.seo ?? "-"} | ${lcpSeconds} | ${fcpSeconds} | ${tbtMs} | ${cls} | ${error} | ${issues} |`;
+    return `| ${result.label} | ${result.path} | ${result.device} | ${scores.performance ?? "-"} | ${scores.accessibility ?? "-"} | ${scores.bestPractices ?? "-"} | ${scores.seo ?? "-"} | ${lcpSeconds} | ${fcpSeconds} | ${tbtMs} | ${cls} | ${inpMs} | ${error} | ${issues} |`;
 }
 function buildConsoleRow(result, useColor) {
     const scoreLine = buildConsoleScoreLine(result, useColor);
@@ -194,7 +357,8 @@ function buildConsoleMetricsLine(result, useColor) {
     const fcpText = formatMetricSeconds(metrics.fcpMs, FCP_GOOD_MS, FCP_WARN_MS, useColor);
     const tbtText = formatMetricMilliseconds(metrics.tbtMs, TBT_GOOD_MS, TBT_WARN_MS, useColor);
     const clsText = formatMetricRatio(metrics.cls, CLS_GOOD, CLS_WARN, useColor);
-    const parts = [`LCP ${lcpText}`, `FCP ${fcpText}`, `TBT ${tbtText}`, `CLS ${clsText}`];
+    const inpText = formatMetricMilliseconds(metrics.inpMs, INP_GOOD_MS, INP_WARN_MS, useColor);
+    const parts = [`LCP ${lcpText}`, `FCP ${fcpText}`, `TBT ${tbtText}`, `CLS ${clsText}`, `INP ${inpText}`];
     return `  ↳ Metrics: ${parts.join("  |  ")}`;
 }
 function buildConsoleErrorLine(result, useColor) {
@@ -325,6 +489,41 @@ function colourScore(score, useColor) {
 function isRedScore(score) {
     return typeof score === "number" && score < 50;
 }
+function printSummaryStats(results, useColor) {
+    if (results.length === 0)
+        return;
+    const scores = {
+        performance: results.map((r) => r.scores.performance).filter((s) => s !== undefined),
+        accessibility: results.map((r) => r.scores.accessibility).filter((s) => s !== undefined),
+        bestPractices: results.map((r) => r.scores.bestPractices).filter((s) => s !== undefined),
+        seo: results.map((r) => r.scores.seo).filter((s) => s !== undefined),
+    };
+    const avg = (arr) => arr.length > 0 ? Math.round(arr.reduce((a, b) => a + b, 0) / arr.length) : 0;
+    const countGreen = (arr) => arr.filter((s) => s >= 90).length;
+    const countYellow = (arr) => arr.filter((s) => s >= 50 && s < 90).length;
+    const countRed = (arr) => arr.filter((s) => s < 50).length;
+    const avgP = avg(scores.performance);
+    const avgA = avg(scores.accessibility);
+    const avgBP = avg(scores.bestPractices);
+    const avgSEO = avg(scores.seo);
+    const greenCount = countGreen(scores.performance) + countGreen(scores.accessibility) + countGreen(scores.bestPractices) + countGreen(scores.seo);
+    const yellowCount = countYellow(scores.performance) + countYellow(scores.accessibility) + countYellow(scores.bestPractices) + countYellow(scores.seo);
+    const redCount = countRed(scores.performance) + countRed(scores.accessibility) + countRed(scores.bestPractices) + countRed(scores.seo);
+    const totalScores = greenCount + yellowCount + redCount;
+    const formatAvg = (val) => {
+        if (!useColor)
+            return val.toString();
+        const color = val >= 90 ? ANSI_GREEN : val >= 50 ? ANSI_YELLOW : ANSI_RED;
+        return `${color}${val}${ANSI_RESET}`;
+    };
+    // eslint-disable-next-line no-console
+    console.log(`\n📊 Summary: Avg P:${formatAvg(avgP)} A:${formatAvg(avgA)} BP:${formatAvg(avgBP)} SEO:${formatAvg(avgSEO)}`);
+    const greenText = useColor ? `${ANSI_GREEN}${greenCount}${ANSI_RESET}` : greenCount.toString();
+    const yellowText = useColor ? `${ANSI_YELLOW}${yellowCount}${ANSI_RESET}` : yellowCount.toString();
+    const redText = useColor ? `${ANSI_RED}${redCount}${ANSI_RESET}` : redCount.toString();
+    // eslint-disable-next-line no-console
+    console.log(`   Scores: ${greenText} green (90+) | ${yellowText} yellow (50-89) | ${redText} red (<50) of ${totalScores} total`);
+}
 function printRedIssues(results) {
     const redResults = results.filter((result) => {
         const scores = result.scores;
@@ -473,6 +672,7 @@ function collectMetricViolations(result, metricsBudgets, allViolations) {
     addMetricViolation("fcpMs", metrics.fcpMs, metricsBudgets.fcpMs, result, allViolations);
     addMetricViolation("tbtMs", metrics.tbtMs, metricsBudgets.tbtMs, result, allViolations);
     addMetricViolation("cls", metrics.cls, metricsBudgets.cls, result, allViolations);
+    addMetricViolation("inpMs", metrics.inpMs, metricsBudgets.inpMs, result, allViolations);
 }
 function addMetricViolation(id, actual, limit, result, allViolations) {
     if (limit === undefined || actual === undefined) {
@@ -491,3 +691,22 @@ function addMetricViolation(id, actual, limit, result, allViolations) {
         limit,
     });
 }
+function openInBrowser(filePath) {
+    const platform = process.platform;
+    let command;
+    if (platform === "win32") {
+        command = `start "" "${filePath}"`;
+    }
+    else if (platform === "darwin") {
+        command = `open "${filePath}"`;
+    }
+    else {
+        command = `xdg-open "${filePath}"`;
+    }
+    exec(command, (error) => {
+        if (error) {
+            // eslint-disable-next-line no-console
+            console.error(`Could not open report: ${error.message}`);
+        }
+    });
+}

package/dist/config.js

@@ -31,6 +31,19 @@ function normaliseConfig(input, absolutePath) {
     const logLevel = rawLogLevel === "silent" || rawLogLevel === "error" || rawLogLevel === "info" || rawLogLevel === "verbose"
         ? rawLogLevel
         : undefined;
+    const rawThrottlingMethod = maybeConfig.throttlingMethod;
+    const throttlingMethod = rawThrottlingMethod === "simulate" || rawThrottlingMethod === "devtools"
+        ? rawThrottlingMethod
+        : undefined;
+    const rawCpuSlowdown = maybeConfig.cpuSlowdownMultiplier;
+    const cpuSlowdownMultiplier = typeof rawCpuSlowdown === "number" && rawCpuSlowdown > 0 && rawCpuSlowdown <= 20
+        ? rawCpuSlowdown
+        : undefined;
+    const rawParallel = maybeConfig.parallel;
+    const parallel = typeof rawParallel === "number" && Number.isInteger(rawParallel) && rawParallel >= 1 && rawParallel <= 10
+        ? rawParallel
+        : undefined;
+    const warmUp = typeof maybeConfig.warmUp === "boolean" ? maybeConfig.warmUp : undefined;
     const budgets = normaliseBudgets(maybeConfig.budgets, absolutePath);
     return {
         baseUrl,
@@ -38,6 +51,10 @@ function normaliseConfig(input, absolutePath) {
         chromePort,
         runs,
         logLevel,
+        throttlingMethod,
+        cpuSlowdownMultiplier,
+        parallel,
+        warmUp,
         pages,
         budgets,
     };
@@ -123,7 +140,8 @@ function normaliseMetricBudgets(input, absolutePath) {
     const fcpMs = normaliseMetricBudget(maybeMetrics.fcpMs, "fcpMs", absolutePath);
     const tbtMs = normaliseMetricBudget(maybeMetrics.tbtMs, "tbtMs", absolutePath);
     const cls = normaliseMetricBudget(maybeMetrics.cls, "cls", absolutePath);
-    if (lcpMs === undefined && fcpMs === undefined && tbtMs === undefined && cls === undefined) {
+    const inpMs = normaliseMetricBudget(maybeMetrics.inpMs, "inpMs", absolutePath);
+    if (lcpMs === undefined && fcpMs === undefined && tbtMs === undefined && cls === undefined && inpMs === undefined) {
         return undefined;
     }
     return {
@@ -131,6 +149,7 @@ function normaliseMetricBudgets(input, absolutePath) {
         fcpMs,
         tbtMs,
         cls,
+        inpMs,
     };
 }
 function normaliseScoreBudget(value, key, absolutePath) {

package/dist/lighthouse-runner.js

@@ -16,6 +16,18 @@ async function createChromeSession(chromePort) {
             "--disable-default-apps",
             "--no-first-run",
             "--no-default-browser-check",
+            // Additional flags for more consistent and accurate results
+            "--disable-background-networking",
+            "--disable-background-timer-throttling",
+            "--disable-backgrounding-occluded-windows",
+            "--disable-renderer-backgrounding",
+            "--disable-client-side-phishing-detection",
+            "--disable-sync",
+            "--disable-translate",
+            "--metrics-recording-only",
+            "--safebrowsing-disable-auto-update",
+            "--password-store=basic",
+            "--use-mock-keychain",
         ],
     });
     return {
@@ -59,43 +71,117 @@ async function ensureUrlReachable(url) {
         throw error instanceof Error ? error : new Error(`URL not reachable: ${url}`);
     });
 }
+async function performWarmUp(config) {
+    // eslint-disable-next-line no-console
+    console.log("Performing warm-up requests...");
+    const uniqueUrls = new Set();
+    for (const page of config.pages) {
+        const url = buildUrl({ baseUrl: config.baseUrl, path: page.path, query: config.query });
+        uniqueUrls.add(url);
+    }
+    // Make parallel warm-up requests to all unique URLs
+    const warmUpPromises = Array.from(uniqueUrls).map(async (url) => {
+        try {
+            await fetchUrl(url);
+        }
+        catch {
+            // Ignore warm-up errors, the actual audit will catch real issues
+        }
+    });
+    await Promise.all(warmUpPromises);
+    // eslint-disable-next-line no-console
+    console.log(`Warm-up complete (${uniqueUrls.size} pages).`);
+}
+async function fetchUrl(url) {
+    const parsed = new URL(url);
+    const client = parsed.protocol === "https:" ? httpsRequest : httpRequest;
+    await new Promise((resolve, reject) => {
+        const request = client({
+            hostname: parsed.hostname,
+            port: parsed.port ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80,
+            path: `${parsed.pathname}${parsed.search}`,
+            method: "GET",
+        }, (response) => {
+            response.resume();
+            resolve();
+        });
+        request.on("error", reject);
+        request.end();
+    });
+}
 /**
  * Run audits for all pages defined in the config and return a structured summary.
  */
 export async function runAuditsForConfig({ config, configPath, }) {
     const runs = config.runs ?? 1;
-    const results = [];
+    const parallelCount = config.parallel ?? 1;
     const firstPage = config.pages[0];
     const healthCheckUrl = buildUrl({ baseUrl: config.baseUrl, path: firstPage.path, query: config.query });
     await ensureUrlReachable(healthCheckUrl);
-    const totalSteps = config.pages.reduce((sum, page) => sum + page.devices.length * runs, 0);
+    // Perform warm-up requests if enabled
+    if (config.warmUp) {
+        await performWarmUp(config);
+    }
+    const throttlingMethod = config.throttlingMethod ?? "simulate";
+    const cpuSlowdownMultiplier = config.cpuSlowdownMultiplier ?? 4;
+    const logLevel = config.logLevel ?? "error";
+    // Build list of all audit tasks
+    const tasks = [];
+    for (const page of config.pages) {
+        for (const device of page.devices) {
+            const url = buildUrl({ baseUrl: config.baseUrl, path: page.path, query: config.query });
+            tasks.push({
+                url,
+                path: page.path,
+                label: page.label,
+                device,
+                runs,
+                logLevel,
+                throttlingMethod,
+                cpuSlowdownMultiplier,
+            });
+        }
+    }
+    const totalSteps = tasks.length * runs;
     let completedSteps = 0;
-    const session = await createChromeSession(config.chromePort);
+    const progressLock = { count: 0 };
+    const updateProgress = (path, device) => {
+        progressLock.count += 1;
+        completedSteps = progressLock.count;
+        logProgress({ completed: completedSteps, total: totalSteps, path, device });
+    };
+    let results;
+    if (parallelCount <= 1 || config.chromePort !== undefined) {
+        // Sequential execution (original behavior) or using external Chrome
+        results = await runSequential(tasks, config.chromePort, updateProgress);
+    }
+    else {
+        // Parallel execution with multiple Chrome instances
+        results = await runParallel(tasks, parallelCount, updateProgress);
+    }
+    return { configPath, results };
+}
+async function runSequential(tasks, chromePort, updateProgress) {
+    const results = [];
+    const session = await createChromeSession(chromePort);
     try {
-        for (const page of config.pages) {
-            for (const device of page.devices) {
-                const url = buildUrl({ baseUrl: config.baseUrl, path: page.path, query: config.query });
-                const summaries = [];
-                for (let index = 0; index < runs; index += 1) {
-                    const summary = await runSingleAudit({
-                        url,
-                        path: page.path,
-                        label: page.label,
-                        device,
-                        port: session.port,
-                        logLevel: config.logLevel ?? "error",
-                    });
-                    summaries.push(summary);
-                    completedSteps += 1;
-                    logProgress({
-                        completed: completedSteps,
-                        total: totalSteps,
-                        path: page.path,
-                        device,
-                    });
-                }
-                results.push(aggregateSummaries(summaries));
+        for (const task of tasks) {
+            const summaries = [];
+            for (let index = 0; index < task.runs; index += 1) {
+                const summary = await runSingleAudit({
+                    url: task.url,
+                    path: task.path,
+                    label: task.label,
+                    device: task.device,
+                    port: session.port,
+                    logLevel: task.logLevel,
+                    throttlingMethod: task.throttlingMethod,
+                    cpuSlowdownMultiplier: task.cpuSlowdownMultiplier,
+                });
+                summaries.push(summary);
+                updateProgress(task.path, task.device);
             }
+            results.push(aggregateSummaries(summaries));
         }
     }
     finally {
@@ -103,7 +189,52 @@ export async function runAuditsForConfig({ config, configPath, }) {
             await session.close();
         }
     }
-    return { configPath, results };
+    return results;
+}
+async function runParallel(tasks, parallelCount, updateProgress) {
+    // Create a pool of Chrome sessions
+    const sessions = [];
+    const effectiveParallel = Math.min(parallelCount, tasks.length);
+    for (let i = 0; i < effectiveParallel; i += 1) {
+        sessions.push(await createChromeSession());
+    }
+    const results = new Array(tasks.length);
+    let taskIndex = 0;
+    const runWorker = async (session, workerIndex) => {
+        while (taskIndex < tasks.length) {
+            const currentIndex = taskIndex;
+            taskIndex += 1;
+            const task = tasks[currentIndex];
+            const summaries = [];
+            for (let run = 0; run < task.runs; run += 1) {
+                const summary = await runSingleAudit({
+                    url: task.url,
+                    path: task.path,
+                    label: task.label,
+                    device: task.device,
+                    port: session.port,
+                    logLevel: task.logLevel,
+                    throttlingMethod: task.throttlingMethod,
+                    cpuSlowdownMultiplier: task.cpuSlowdownMultiplier,
+                });
+                summaries.push(summary);
+                updateProgress(task.path, task.device);
+            }
+            results[currentIndex] = aggregateSummaries(summaries);
+        }
+    };
+    try {
+        await Promise.all(sessions.map((session, index) => runWorker(session, index)));
+    }
+    finally {
+        // Close all Chrome sessions
+        await Promise.all(sessions.map(async (session) => {
+            if (session.close) {
+                await session.close();
+            }
+        }));
+    }
+    return results;
 }
 function buildUrl({ baseUrl, path, query }) {
     const cleanBase = baseUrl.replace(/\/$/, "");
@@ -131,7 +262,22 @@ async function runSingleAudit(params) {
         output: "json",
         logLevel: params.logLevel,
         onlyCategories: ["performance", "accessibility", "best-practices", "seo"],
-        emulatedFormFactor: params.device,
+        formFactor: params.device,
+        // Throttling configuration for more accurate results
+        throttlingMethod: params.throttlingMethod,
+        throttling: {
+            // CPU throttling - adjustable via config
+            cpuSlowdownMultiplier: params.cpuSlowdownMultiplier,
+            // Network throttling (Slow 4G / Fast 3G preset - Lighthouse default)
+            rttMs: 150,
+            throughputKbps: 1638.4,
+            requestLatencyMs: 150 * 3.75,
+            downloadThroughputKbps: 1638.4,
+            uploadThroughputKbps: 750,
+        },
+        screenEmulation: params.device === "mobile"
+            ? { mobile: true, width: 412, height: 823, deviceScaleFactor: 1.75, disabled: false }
+            : { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1, disabled: false },
     };
     const runnerResult = await lighthouse(params.url, options);
     const lhrUnknown = runnerResult.lhr;
@@ -178,15 +324,18 @@ function extractMetrics(lhr) {
     const fcpAudit = audits["first-contentful-paint"];
     const tbtAudit = audits["total-blocking-time"];
     const clsAudit = audits["cumulative-layout-shift"];
+    const inpAudit = audits["interaction-to-next-paint"];
     const lcpMs = typeof lcpAudit?.numericValue === "number" ? lcpAudit.numericValue : undefined;
     const fcpMs = typeof fcpAudit?.numericValue === "number" ? fcpAudit.numericValue : undefined;
     const tbtMs = typeof tbtAudit?.numericValue === "number" ? tbtAudit.numericValue : undefined;
     const cls = typeof clsAudit?.numericValue === "number" ? clsAudit.numericValue : undefined;
+    const inpMs = typeof inpAudit?.numericValue === "number" ? inpAudit.numericValue : undefined;
     return {
         lcpMs,
         fcpMs,
         tbtMs,
         cls,
+        inpMs,
     };
 }
 function extractTopOpportunities(lhr, limit) {
@@ -223,6 +372,7 @@ function aggregateSummaries(summaries) {
         fcpMs: averageOf(summaries.map((s) => s.metrics.fcpMs)),
         tbtMs: averageOf(summaries.map((s) => s.metrics.tbtMs)),
         cls: averageOf(summaries.map((s) => s.metrics.cls)),
+        inpMs: averageOf(summaries.map((s) => s.metrics.inpMs)),
     };
     const opportunities = summaries[0].opportunities;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-auditor",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "private": false,
   "description": "CLI to run structured Lighthouse audits (Performance, Accessibility, Best Practices, SEO) across routes.",
   "type": "module",