apex-auditor 0.3.0 → 0.3.3

package/dist/cli.js

@@ -1,8 +1,507 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { exec } from "node:child_process";
 import { loadConfig } from "./config.js";
+import { runAccessibilityAudit } from "./accessibility.js";
+import { startSpinner, stopSpinner, updateSpinnerMessage } from "./spinner.js";
 import { runAuditsForConfig } from "./lighthouse-runner.js";
+import { postJsonWebhook } from "./webhooks.js";
+import { renderPanel } from "./ui/render-panel.js";
+import { renderTable } from "./ui/render-table.js";
+import { UiTheme } from "./ui/ui-theme.js";
+async function runCommand(command, cwd) {
+    return await new Promise((resolveCommand, rejectCommand) => {
+        exec(command, { cwd }, (error, stdout, stderr) => {
+            if (error) {
+                rejectCommand(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolveCommand(stdout);
+        });
+    });
+}
+function colorScore(score, theme) {
+    if (score === undefined) {
+        return "-";
+    }
+    if (score >= 90) {
+        return theme.green(score.toString());
+    }
+    if (score >= 50) {
+        return theme.yellow(score.toString());
+    }
+    return theme.red(score.toString());
+}
+function colorDevice(device, theme) {
+    return device === "mobile" ? theme.cyan("mobile") : theme.magenta("desktop");
+}
+function buildWebhookPayload(params) {
+    const regressions = collectRegressions(params.previous, params.current);
+    const budgetPassed = params.budgetViolations.length === 0;
+    return {
+        type: "apex-auditor",
+        buildId: params.current.meta.buildId,
+        elapsedMs: params.current.meta.elapsedMs,
+        regressions,
+        budget: {
+            passed: budgetPassed,
+            violations: params.budgetViolations.length,
+        },
+        accessibility: params.accessibility === undefined
+            ? undefined
+            : {
+                critical: params.accessibility.impactCounts.critical,
+                serious: params.accessibility.impactCounts.serious,
+                moderate: params.accessibility.impactCounts.moderate,
+                minor: params.accessibility.impactCounts.minor,
+                errored: params.accessibility.errored,
+                total: params.accessibility.total,
+            },
+        links: {
+            reportHtml: params.reportPath,
+            exportJson: params.exportPath,
+            accessibilitySummary: params.accessibilityPath,
+        },
+    };
+}
+function shouldSendWebhook(regressions, budgetViolations) {
+    return regressions.length > 0 || budgetViolations.length > 0;
+}
+function summariseAccessibility(results) {
+    const counts = {
+        critical: 0,
+        serious: 0,
+        moderate: 0,
+        minor: 0,
+    };
+    let errored = 0;
+    for (const result of results.results) {
+        if (result.runtimeErrorMessage) {
+            errored += 1;
+            continue;
+        }
+        for (const violation of result.violations) {
+            const impact = violation.impact;
+            if (impact === "critical")
+                counts.critical += 1;
+            else if (impact === "serious")
+                counts.serious += 1;
+            else if (impact === "moderate")
+                counts.moderate += 1;
+            else if (impact === "minor")
+                counts.minor += 1;
+        }
+    }
+    return { impactCounts: { ...counts }, errored, total: results.results.length };
+}
+function buildAccessibilityPanel(summary, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const headers = ["Impact", "Count"];
+    const rows = [
+        ["critical", summary.impactCounts.critical.toString()],
+        ["serious", summary.impactCounts.serious.toString()],
+        ["moderate", summary.impactCounts.moderate.toString()],
+        ["minor", summary.impactCounts.minor.toString()],
+    ];
+    const table = renderTable({ headers, rows });
+    const metaLines = [
+        `${theme.bold("Total combos")}: ${summary.total}`,
+        `${theme.bold("Errored combos")}: ${summary.errored}`,
+    ];
+    return `${table}\n${metaLines.join("\n")}`;
+}
+function buildSectionIndex(useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const lines = [
+        `${theme.bold("Sections")}:`,
+        `  1) Effective settings`,
+        `  2) Meta`,
+        `  3) Stats`,
+        `  4) Changes`,
+        `  5) Summary`,
+        `  6) Issues`,
+        `  7) Top fixes`,
+        `  8) Lowest performance`,
+        `  9) Export (regressions/issues)`,
+    ];
+    return lines.join("\n");
+}
+function selectTopViolations(result, limit) {
+    const impactRank = { critical: 1, serious: 2, moderate: 3, minor: 4 };
+    return [...result.violations]
+        .sort((a, b) => {
+        const rankA = impactRank[a.impact ?? ""] ?? 5;
+        const rankB = impactRank[b.impact ?? ""] ?? 5;
+        if (rankA !== rankB) {
+            return rankA - rankB;
+        }
+        const nodesA = a.nodes.length;
+        const nodesB = b.nodes.length;
+        return nodesB - nodesA;
+    })
+        .slice(0, limit);
+}
+function buildAccessibilityIssuesPanel(results, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    if (results.length === 0) {
+        return renderPanel({ title: theme.bold("Accessibility (top issues)"), lines: [theme.dim("No accessibility results.")] });
+    }
+    const lines = [];
+    for (const result of results) {
+        lines.push(`${theme.bold(`${result.label} ${result.path} [${result.device}]`)}`);
+        if (result.runtimeErrorMessage) {
+            lines.push(`- ${theme.red("Error")}: ${result.runtimeErrorMessage}`);
+            continue;
+        }
+        const tops = selectTopViolations(result, 3);
+        if (tops.length === 0) {
+            lines.push(theme.dim("- No violations found"));
+            continue;
+        }
+        for (const violation of tops) {
+            const impact = violation.impact ? `${violation.impact}: ` : "";
+            const title = violation.help ?? violation.id;
+            const targetSample = violation.nodes[0]?.target?.[0] ?? "";
+            const detail = targetSample ? ` (${targetSample})` : "";
+            lines.push(`- ${impact}${title}${detail}`);
+        }
+    }
+    return renderPanel({ title: theme.bold("Accessibility (top issues)"), lines });
+}
+function severityBackground(score) {
+    if (score === undefined) {
+        return "";
+    }
+    if (score >= 90) {
+        return "";
+    }
+    if (score >= 50) {
+        return "";
+    }
+    return "";
+}
+function applyRowBackground(row, score, useColor) {
+    const bg = severityBackground(score);
+    if (!useColor || bg === "") {
+        return row;
+    }
+    return row;
+}
+function formatDelta(curr, prev, theme) {
+    if (curr === undefined || prev === undefined) {
+        return "-";
+    }
+    const delta = curr - prev;
+    if (delta === 0) {
+        return theme.dim("0");
+    }
+    const text = delta > 0 ? `+${delta}` : `${delta}`;
+    return delta > 0 ? theme.green(text) : theme.red(text);
+}
+function buildSummaryPanel(params) {
+    const theme = new UiTheme({ noColor: !params.useColor });
+    const hasPrev = params.previousSummary !== undefined;
+    const headers = params.useColor
+        ? [
+            theme.bold("Label"),
+            theme.bold("Path"),
+            theme.bold("Device"),
+            theme.green("P"),
+            hasPrev ? theme.cyan("ΔP") : "",
+            theme.cyan("A"),
+            theme.magenta("BP"),
+            theme.yellow("SEO"),
+        ].filter((h) => h !== "")
+        : ["Label", "Path", "Device", "P", ...(hasPrev ? ["ΔP"] : []), "A", "BP", "SEO"];
+    const prevMap = params.previousSummary !== undefined
+        ? new Map(params.previousSummary.results.map((r) => [`${r.label}:::${r.path}:::${r.device}`, r]))
+        : undefined;
+    const filtered = params.regressionsOnly && prevMap !== undefined
+        ? params.results.filter((r) => {
+            const key = `${r.label}:::${r.path}:::${r.device}`;
+            const prev = prevMap.get(key);
+            const prevScore = prev?.scores.performance;
+            const currScore = r.scores.performance;
+            return prevScore !== undefined && currScore !== undefined && currScore < prevScore;
+        })
+        : params.results;
+    const rows = filtered.map((r) => {
+        const scores = r.scores;
+        const prevScore = prevMap?.get(`${r.label}:::${r.path}:::${r.device}`)?.scores.performance;
+        const baseRow = [
+            r.label,
+            r.path,
+            colorDevice(r.device, theme),
+            colorScore(scores.performance, theme),
+            ...(hasPrev ? [formatDelta(scores.performance, prevScore, theme)] : []),
+            colorScore(scores.accessibility, theme),
+            colorScore(scores.bestPractices, theme),
+            colorScore(scores.seo, theme),
+        ];
+        return applyRowBackground(baseRow, scores.performance, params.useColor);
+    });
+    return renderTable({ headers, rows });
+}
+function collectRegressions(previous, current) {
+    if (previous === undefined) {
+        return [];
+    }
+    const prevMap = new Map(previous.results.map((r) => [`${r.label}:::${r.path}:::${r.device}`, r]));
+    const lines = [];
+    for (const r of current.results) {
+        const key = `${r.label}:::${r.path}:::${r.device}`;
+        const prev = prevMap.get(key);
+        if (prev?.scores.performance !== undefined && r.scores.performance !== undefined) {
+            const delta = r.scores.performance - prev.scores.performance;
+            if (delta < 0) {
+                lines.push({
+                    label: r.label,
+                    path: r.path,
+                    device: r.device,
+                    previousP: prev.scores.performance,
+                    currentP: r.scores.performance,
+                    deltaP: delta,
+                });
+            }
+        }
+    }
+    return lines.sort((a, b) => a.deltaP - b.deltaP).slice(0, 10);
+}
+function collectDeepAuditTargets(results) {
+    return [...results]
+        .sort((a, b) => (a.scores.performance ?? 101) - (b.scores.performance ?? 101))
+        .slice(0, 5)
+        .map((r) => ({
+        label: r.label,
+        path: r.path,
+        device: r.device,
+        score: r.scores.performance ?? 0,
+    }));
+}
+function collectTopIssues(results) {
+    const counts = new Map();
+    for (const r of results) {
+        for (const opp of r.opportunities) {
+            const existing = counts.get(opp.title);
+            if (existing) {
+                existing.count += 1;
+                existing.totalMs += opp.estimatedSavingsMs ?? 0;
+            }
+            else {
+                counts.set(opp.title, { title: opp.title, count: 1, totalMs: opp.estimatedSavingsMs ?? 0 });
+            }
+        }
+    }
+    return [...counts.values()].sort((a, b) => b.totalMs - a.totalMs).slice(0, 5);
+}
+function buildSuggestedCommands(configPath, targets) {
+    return targets.map((t) => `pnpm tsx src/bin.ts --config ${configPath} --${t.device}-only --open-report # focus on ${t.path}`);
+}
+function buildShareableExport(params) {
+    const regressions = collectRegressions(params.previousSummary, params.current);
+    const deepAuditTargets = collectDeepAuditTargets(params.current.results);
+    const suggestedCommands = buildSuggestedCommands(params.configPath, deepAuditTargets.map((t) => ({ path: t.path, device: t.device })));
+    const budgetViolations = params.budgets === undefined
+        ? []
+        : collectBudgetViolations(params.current.results, params.budgets).map((v) => ({
+            pageLabel: v.pageLabel,
+            path: v.path,
+            device: v.device,
+            kind: v.kind,
+            id: v.id,
+            value: v.value,
+            limit: v.limit,
+        }));
+    return {
+        generatedAt: new Date().toISOString(),
+        regressions,
+        topIssues: collectTopIssues(params.current.results),
+        deepAuditTargets,
+        suggestedCommands,
+        budgets: params.budgets,
+        budgetViolations,
+        budgetPassed: budgetViolations.length === 0,
+    };
+}
+function buildExportPanel(params) {
+    const theme = new UiTheme({ noColor: !params.useColor });
+    const lines = [];
+    const width = 80;
+    const divider = () => {
+        lines.push(theme.dim("─".repeat(width)));
+    };
+    const formBorder = (label) => {
+        const labelText = ` ${label} `;
+        const remaining = Math.max(width - labelText.length - 2, 0);
+        const bar = "─".repeat(remaining);
+        return {
+            top: theme.dim(`┌${labelText}${bar}`),
+            bottom: theme.dim(`└${"─".repeat(width - 1)}`),
+        };
+    };
+    lines.push(theme.bold("Export"));
+    lines.push(theme.dim(`Path: ${params.exportPath}`));
+    lines.push(theme.dim(`Generated: ${params.share.generatedAt}`));
+    divider();
+    // Budgets
+    if (params.share.budgets !== undefined) {
+        const statusText = params.share.budgetPassed ? theme.green("passed") : theme.red("failed");
+        lines.push(`${theme.bold("Budgets")} ${statusText}`);
+        const thresholdRows = [];
+        const categories = params.share.budgets.categories;
+        if (categories !== undefined) {
+            if (categories.performance !== undefined)
+                thresholdRows.push(["category", "performance", `${categories.performance}`]);
+            if (categories.accessibility !== undefined)
+                thresholdRows.push(["category", "accessibility", `${categories.accessibility}`]);
+            if (categories.bestPractices !== undefined)
+                thresholdRows.push(["category", "bestPractices", `${categories.bestPractices}`]);
+            if (categories.seo !== undefined)
+                thresholdRows.push(["category", "seo", `${categories.seo}`]);
+        }
+        const metrics = params.share.budgets.metrics;
+        if (metrics !== undefined) {
+            if (metrics.lcpMs !== undefined)
+                thresholdRows.push(["metric", "lcpMs", `${metrics.lcpMs}ms`]);
+            if (metrics.fcpMs !== undefined)
+                thresholdRows.push(["metric", "fcpMs", `${metrics.fcpMs}ms`]);
+            if (metrics.tbtMs !== undefined)
+                thresholdRows.push(["metric", "tbtMs", `${metrics.tbtMs}ms`]);
+            if (metrics.cls !== undefined)
+                thresholdRows.push(["metric", "cls", `${metrics.cls}`]);
+            if (metrics.inpMs !== undefined)
+                thresholdRows.push(["metric", "inpMs", `${metrics.inpMs}ms`]);
+        }
+        if (thresholdRows.length > 0) {
+            lines.push(renderTable({
+                headers: ["Type", "Id", "Limit"],
+                rows: thresholdRows,
+            }));
+        }
+        if (params.share.budgetViolations.length > 0) {
+            lines.push(theme.bold("Violations"));
+            params.share.budgetViolations.forEach((v) => {
+                const valueText = v.kind === "category" ? `${Math.round(v.value)}` : `${Math.round(v.value)}ms`;
+                const limitText = v.kind === "category" ? `${Math.round(v.limit)}` : `${Math.round(v.limit)}ms`;
+                lines.push(`${v.pageLabel} ${v.path} [${colorDevice(v.device, theme)}] – ${v.kind} ${v.id}: ${valueText} vs limit ${limitText}`);
+            });
+        }
+        else {
+            lines.push(theme.dim("No violations."));
+        }
+        divider();
+    }
+    // Regressions
+    lines.push(`${theme.bold("Regressions")} ${theme.dim("(top 10 by ΔP)")}`);
+    if (params.share.regressions.length === 0) {
+        lines.push(theme.green("No regressions detected."));
+    }
+    else {
+        const regressionRows = params.share.regressions.map((r) => [
+            r.label,
+            r.path,
+            colorDevice(r.device, theme),
+            colorScore(r.currentP, theme),
+            r.deltaP >= 0 ? theme.green(`+${r.deltaP}`) : theme.red(String(r.deltaP)),
+            String(r.previousP),
+        ]);
+        lines.push(renderTable({
+            headers: ["Label", "Path", "Device", "P", "ΔP", "Prev P"],
+            rows: regressionRows,
+        }));
+    }
+    divider();
+    // Deep audit targets
+    lines.push(`${theme.bold("Deep audit targets")} ${theme.dim("(worst 5 by P)")}`);
+    const deepRows = params.share.deepAuditTargets.map((t) => [
+        t.label,
+        t.path,
+        colorDevice(t.device, theme),
+        colorScore(t.score, theme),
+    ]);
+    lines.push(renderTable({
+        headers: ["Label", "Path", "Device", "P"],
+        rows: deepRows,
+    }));
+    divider();
+    // Suggested commands
+    lines.push(`${theme.bold("Suggested commands")} ${theme.dim("(copy/paste ready)")}`);
+    if (params.share.suggestedCommands.length === 0) {
+        lines.push(theme.dim("No suggestions available."));
+    }
+    else {
+        const box = formBorder("Copy/paste");
+        lines.push(box.top);
+        params.share.suggestedCommands.forEach((cmd, index) => {
+            const prefix = `${String(index + 1).padStart(2, "0")}.`;
+            lines.push(`${theme.dim("│")} ${theme.dim(prefix)} ${cmd}`);
+        });
+        lines.push(box.bottom);
+    }
+    return lines.join("\n");
+}
+function buildIssuesPanel(results, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const reds = results.filter((r) => (r.scores.performance ?? 100) < 50);
+    if (reds.length === 0) {
+        return renderPanel({ title: theme.bold("Issues"), lines: [theme.green("No red issues.")] });
+    }
+    const lines = reds.map((r) => {
+        const top = r.opportunities[0];
+        const issue = top ? `${top.title}${top.estimatedSavingsMs ? ` (${Math.round(top.estimatedSavingsMs)}ms)` : ""}` : "No top issue reported";
+        const perfText = colorScore(r.scores.performance, theme);
+        const deviceText = colorDevice(r.device, theme);
+        return `${r.label} ${r.path} [${deviceText}] – P:${perfText} – ${issue}`;
+    });
+    return renderPanel({ title: theme.bold("Issues"), lines });
+}
+function buildTopFixesPanel(results, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const opportunityCounts = new Map();
+    for (const r of results) {
+        for (const opp of r.opportunities) {
+            const existing = opportunityCounts.get(opp.title);
+            if (existing) {
+                existing.count += 1;
+                existing.totalMs += opp.estimatedSavingsMs ?? 0;
+            }
+            else {
+                opportunityCounts.set(opp.title, { title: opp.title, count: 1, totalMs: opp.estimatedSavingsMs ?? 0 });
+            }
+        }
+    }
+    const sorted = [...opportunityCounts.values()].sort((a, b) => b.totalMs - a.totalMs).slice(0, 5);
+    if (sorted.length === 0) {
+        return renderPanel({ title: theme.bold("Top fixes"), lines: [theme.dim("No opportunities collected.")] });
+    }
+    const lines = sorted.map((o) => `- ${theme.cyan(o.title)} (seen on ${o.count} pages) (${Math.round(o.totalMs)}ms)`);
+    return renderPanel({ title: theme.bold("Top fixes"), lines });
+}
+function buildLowestPerformancePanel(results, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const sorted = [...results].sort((a, b) => (a.scores.performance ?? 101) - (b.scores.performance ?? 101)).slice(0, 5);
+    const lines = sorted.map((r) => {
+        const perfText = colorScore(r.scores.performance, theme);
+        const deviceText = colorDevice(r.device, theme);
+        return `${r.label} ${r.path} [${deviceText}] P:${perfText}`;
+    });
+    return renderPanel({ title: theme.bold("Lowest performance"), lines });
+}
+function buildBudgetsPanel(params) {
+    if (params.budgets === undefined) {
+        return undefined;
+    }
+    const theme = new UiTheme({ noColor: !params.useColor });
+    if (params.violations.length === 0) {
+        return renderPanel({ title: theme.bold("Budgets"), lines: [theme.green("All budgets passed.")] });
+    }
+    const lines = params.violations.map((v) => {
+        const valueText = v.kind === "category" ? `${Math.round(v.value)}` : `${Math.round(v.value)}ms`;
+        const limitText = v.kind === "category" ? `${Math.round(v.limit)}` : `${Math.round(v.limit)}ms`;
+        return `${v.pageLabel} ${v.path} [${v.device}] – ${v.kind} ${v.id}: ${valueText} vs limit ${limitText}`;
+    });
+    return renderPanel({ title: theme.bold("Budgets"), lines });
+}
 const ANSI_RESET = "\u001B[0m";
 const ANSI_RED = "\u001B[31m";
 const ANSI_YELLOW = "\u001B[33m";
@@ -19,19 +518,65 @@ const CLS_GOOD = 0.1;
 const CLS_WARN = 0.25;
 const INP_GOOD_MS = 200;
 const INP_WARN_MS = 500;
+const DEFAULT_MAX_STEPS = 120;
+const DEFAULT_MAX_COMBOS = 60;
+const DEFAULT_OVERVIEW_MAX_COMBOS = 10;
+async function confirmLargeRun(message) {
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode?.(true);
+    process.stdin.setEncoding("utf8");
+    process.stdout.write(message);
+    return await new Promise((resolve) => {
+        const onData = (chunk) => {
+            process.stdin.setRawMode?.(Boolean(wasRaw));
+            process.stdin.pause();
+            const raw = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            const first = raw.trim().charAt(0);
+            const yes = first === "y" || first === "Y";
+            process.stdout.write("\n");
+            resolve(yes);
+        };
+        process.stdin.once("data", onData);
+        process.stdin.resume();
+    });
+}
 function parseArgs(argv) {
     let configPath;
     let ci = false;
+    let failOnBudget = false;
     let colorMode = "auto";
     let logLevelOverride;
     let deviceFilter;
     let throttlingMethodOverride;
     let cpuSlowdownOverride;
     let parallelOverride;
+    let auditTimeoutMsOverride;
+    let plan = false;
+    let yes = false;
+    let maxSteps;
+    let maxCombos;
+    let stable = false;
     let openReport = false;
     let warmUp = false;
+    let incremental = false;
+    let buildId;
+    let runsOverride;
+    let quick = false;
+    let accurate = false;
     let jsonOutput = false;
     let showParallel = false;
+    let fast = false;
+    let overview = false;
+    let overviewCombos;
+    let regressionsOnly = false;
+    let changedOnly = false;
+    let rerunFailing = false;
+    let accessibilityPass = false;
+    let webhookUrl;
+    let webhookAlways = false;
     for (let i = 2; i < argv.length; i += 1) {
         const arg = argv[i];
         if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
@@ -41,11 +586,14 @@ function parseArgs(argv) {
         else if (arg === "--ci") {
             ci = true;
         }
+        else if (arg === "--fail-on-budget") {
+            failOnBudget = true;
+        }
         else if (arg === "--no-color") {
-            colorMode = "off";
+            colorMode = "never";
         }
         else if (arg === "--color") {
-            colorMode = "on";
+            colorMode = "always";
         }
         else if (arg === "--log-level" && i + 1 < argv.length) {
             const value = argv[i + 1];
@@ -53,7 +601,7 @@ function parseArgs(argv) {
                 logLevelOverride = value;
             }
             else {
-                throw new Error(`Invalid --log-level value: ${value}`);
+                throw new Error(`Unknown argument: ${arg}`);
             }
             i += 1;
         }
@@ -95,44 +643,490 @@ function parseArgs(argv) {
             parallelOverride = value;
             i += 1;
         }
-        else if (arg === "--open") {
+        else if (arg === "--audit-timeout-ms" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value <= 0) {
+                throw new Error(`Invalid --audit-timeout-ms value: ${argv[i + 1]}. Expected a positive integer (milliseconds).`);
+            }
+            auditTimeoutMsOverride = value;
+            i += 1;
+        }
+        else if (arg === "--plan") {
+            plan = true;
+        }
+        else if (arg === "--regressions-only") {
+            regressionsOnly = true;
+        }
+        else if (arg === "--changed-only") {
+            changedOnly = true;
+        }
+        else if (arg === "--rerun-failing") {
+            rerunFailing = true;
+        }
+        else if (arg === "--accessibility-pass") {
+            accessibilityPass = true;
+        }
+        else if (arg === "--webhook-url" && i + 1 < argv.length) {
+            webhookUrl = argv[i + 1];
+            i += 1;
+        }
+        else if (arg === "--webhook-always") {
+            webhookAlways = true;
+        }
+        else if (arg === "--max-steps" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value <= 0) {
+                throw new Error(`Invalid --max-steps value: ${argv[i + 1]}. Expected a positive integer.`);
+            }
+            maxSteps = value;
+            i += 1;
+        }
+        else if (arg === "--max-combos" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value <= 0) {
+                throw new Error(`Invalid --max-combos value: ${argv[i + 1]}. Expected a positive integer.`);
+            }
+            maxCombos = value;
+            i += 1;
+        }
+        else if (arg === "--yes" || arg === "-y") {
+            yes = true;
+        }
+        else if (arg.startsWith("--parallel=")) {
+            parallelOverride = Number(arg.split("=")[1]);
+            if (Number.isNaN(parallelOverride)) {
+                parallelOverride = undefined;
+            }
+        }
+        else if (arg === "--stable") {
+            stable = true;
+        }
+        else if (arg === "--open" || arg === "--open-report") {
             openReport = true;
         }
         else if (arg === "--warm-up") {
             warmUp = true;
         }
+        else if (arg === "--incremental") {
+            incremental = true;
+        }
+        else if (arg === "--build-id" && i + 1 < argv.length) {
+            buildId = argv[i + 1];
+            i += 1;
+        }
+        else if (arg === "--runs" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value !== 1) {
+                throw new Error(`Multi-run mode is no longer supported. Received --runs ${argv[i + 1]}. ` +
+                    "Run the same command multiple times instead (more stable).");
+            }
+            runsOverride = value;
+            i += 1;
+        }
+        else if (arg === "--overview-combos" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value <= 0 || value > 200) {
+                throw new Error(`Invalid --overview-combos value: ${argv[i + 1]}. Expected integer between 1 and 200.`);
+            }
+            overviewCombos = value;
+            i += 1;
+        }
+        else if (arg === "--quick") {
+            quick = true;
+        }
+        else if (arg === "--accurate") {
+            accurate = true;
+        }
         else if (arg === "--json") {
             jsonOutput = true;
         }
         else if (arg === "--show-parallel") {
             showParallel = true;
         }
+        else if (arg === "--fast") {
+            fast = true;
+        }
+        else if (arg === "--overview") {
+            overview = true;
+        }
+    }
+    const presetCount = [fast, quick, accurate, overview].filter((flag) => flag).length;
+    if (presetCount > 1) {
+        throw new Error("Choose only one preset: --overview, --fast, --quick, or --accurate");
     }
     const finalConfigPath = configPath ?? "apex.config.json";
-    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride, deviceFilter, throttlingMethodOverride, cpuSlowdownOverride, parallelOverride, openReport, warmUp, jsonOutput, showParallel };
+    return {
+        configPath: finalConfigPath,
+        ci,
+        failOnBudget,
+        colorMode,
+        logLevelOverride,
+        deviceFilter,
+        throttlingMethodOverride,
+        cpuSlowdownOverride,
+        parallelOverride,
+        auditTimeoutMsOverride,
+        plan,
+        yes,
+        maxSteps,
+        maxCombos,
+        stable,
+        openReport,
+        warmUp,
+        incremental,
+        buildId,
+        runsOverride,
+        quick,
+        accurate,
+        jsonOutput,
+        showParallel,
+        fast,
+        overview,
+        overviewCombos,
+        regressionsOnly,
+        changedOnly,
+        rerunFailing,
+        accessibilityPass,
+        webhookUrl,
+        webhookAlways,
+    };
+}
+function printPlan(params) {
+    const lines = [];
+    lines.push(`Config: ${params.configPath}`);
+    lines.push(`Parallel: ${params.resolvedConfig.parallel ?? "auto"}`);
+    lines.push(`Throttling: ${params.resolvedConfig.throttlingMethod ?? "simulate"}`);
+    lines.push(`CPU slowdown: ${params.resolvedConfig.cpuSlowdownMultiplier ?? 4}`);
+    lines.push(`Warm-up: ${params.resolvedConfig.warmUp === true ? "yes" : "no"}`);
+    lines.push(`Incremental: ${params.resolvedConfig.incremental === true ? "yes" : "no"}`);
+    lines.push(`Build ID: ${params.resolvedConfig.buildId ?? "-"}`);
+    lines.push(`Runs per combo: 1`);
+    lines.push(`Planned combos: ${params.plannedCombos}`);
+    lines.push(`Planned Lighthouse runs (steps): ${params.plannedSteps}`);
+    if (params.sampled) {
+        lines.push(`Overview sampling: yes (${params.sampledCombos} combos)`);
+    }
+    lines.push(`Guardrails: combos<=${params.maxCombos}, steps<=${params.maxSteps}`);
+    printSectionHeader("Plan", params.useColor);
+    printDivider();
+    // eslint-disable-next-line no-console
+    console.log(boxifyWithSeparators(lines));
+    printDivider();
+}
+function sampleConfigForOverview(config, maxCombos) {
+    const nextPages = [];
+    let combos = 0;
+    for (const page of config.pages) {
+        if (combos >= maxCombos) {
+            break;
+        }
+        const remaining = maxCombos - combos;
+        const devices = page.devices.slice(0, remaining);
+        if (devices.length === 0) {
+            continue;
+        }
+        nextPages.push({ ...page, devices });
+        combos += devices.length;
+    }
+    const sampled = combos < config.pages.reduce((acc, p) => acc + p.devices.length, 0);
+    return { config: { ...config, pages: nextPages }, sampled, sampledCombos: combos };
+}
+async function resolveAutoBuildId(configPath) {
+    const startDir = dirname(configPath);
+    const tryReadText = async (absolutePath) => {
+        try {
+            const raw = await readFile(absolutePath, "utf8");
+            const trimmed = raw.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const findUp = async (relativePath) => {
+        let currentDir = startDir;
+        while (true) {
+            const candidate = resolve(currentDir, relativePath);
+            const value = await tryReadText(candidate);
+            if (value !== undefined) {
+                return value;
+            }
+            const parent = dirname(currentDir);
+            if (parent === currentDir) {
+                return undefined;
+            }
+            currentDir = parent;
+        }
+    };
+    const nextBuildId = await findUp(".next/BUILD_ID");
+    if (nextBuildId !== undefined) {
+        return `next:${nextBuildId}`;
+    }
+    const gitHead = await findUp(".git/HEAD");
+    if (gitHead === undefined) {
+        return undefined;
+    }
+    if (gitHead.startsWith("ref:")) {
+        const refPath = gitHead.replace("ref:", "").trim();
+        const refValue = await findUp(`.git/${refPath}`);
+        return refValue !== undefined ? `git:${refValue}` : undefined;
+    }
+    return `git:${gitHead}`;
+}
+async function loadPreviousSummary() {
+    const previousPath = resolve(".apex-auditor", "summary.json");
+    try {
+        const raw = await readFile(previousPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function computeAvgScores(results) {
+    const sums = results.reduce((acc, r) => {
+        return {
+            performance: acc.performance + (r.scores.performance ?? 0),
+            accessibility: acc.accessibility + (r.scores.accessibility ?? 0),
+            bestPractices: acc.bestPractices + (r.scores.bestPractices ?? 0),
+            seo: acc.seo + (r.scores.seo ?? 0),
+            count: acc.count + 1,
+        };
+    }, { performance: 0, accessibility: 0, bestPractices: 0, seo: 0, count: 0 });
+    const count = Math.max(1, sums.count);
+    return {
+        performance: Math.round(sums.performance / count),
+        accessibility: Math.round(sums.accessibility / count),
+        bestPractices: Math.round(sums.bestPractices / count),
+        seo: Math.round(sums.seo / count),
+    };
+}
+function buildEffectiveSettingsPanel(params) {
+    const theme = new UiTheme({ noColor: !params.useColor });
+    const buildIdText = params.config.buildId ?? "-";
+    const throttlingText = params.config.throttlingMethod ?? "simulate";
+    const cpuText = String(params.config.cpuSlowdownMultiplier ?? 4);
+    const parallelText = String(params.config.parallel ?? 4);
+    const warmUpText = params.config.warmUp ? "yes" : "no";
+    const incrementalText = params.config.incremental ? "on" : "off";
+    const lines = [];
+    lines.push(`${theme.dim("Config")}: ${params.configPath}`);
+    lines.push(`${theme.dim("Build ID")}: ${buildIdText}`);
+    lines.push(`${theme.dim("Incremental")}: ${incrementalText}`);
+    lines.push(`${theme.dim("Warm-up")}: ${warmUpText}`);
+    lines.push(`${theme.dim("Throttling")}: ${throttlingText}`);
+    lines.push(`${theme.dim("CPU slowdown")}: ${cpuText}`);
+    lines.push(`${theme.dim("Parallel")}: ${parallelText}`);
+    return renderPanel({ title: theme.bold("Effective settings"), lines });
+}
+function buildMetaPanel(meta, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    const cacheSummary = meta.incremental
+        ? `${meta.executedCombos} executed / ${meta.cachedCombos} cached (steps: ${meta.executedSteps}/${meta.cachedSteps})`
+        : "No";
+    const lines = [
+        `${theme.dim("Build ID")}: ${meta.buildId ?? "-"}`,
+        `${theme.dim("Incremental")}: ${meta.incremental ? "Yes" : "No"}`,
+        `${theme.dim("Resolved parallel")}: ${meta.resolvedParallel}`,
+        `${theme.dim("Warm-up")}: ${meta.warmUp ? "Yes" : "No"}`,
+        `${theme.dim("Throttling")}: ${meta.throttlingMethod}`,
+        `${theme.dim("CPU slowdown")}: ${meta.cpuSlowdownMultiplier}`,
+        `${theme.dim("Combos")}: ${meta.comboCount}`,
+        `${theme.dim("Cache")}: ${cacheSummary}`,
+        `${theme.dim("Runs per combo")}: ${meta.runsPerCombo}`,
+        `${theme.dim("Total steps")}: ${meta.totalSteps}`,
+        `${theme.dim("Elapsed")}: ${formatElapsedTime(meta.elapsedMs)}`,
+        `${theme.dim("Avg / step")}: ${formatElapsedTime(meta.averageStepMs)}`,
+    ];
+    return renderPanel({ title: theme.bold("Meta"), lines });
+}
+function buildStatsPanel(results, useColor) {
+    const theme = new UiTheme({ noColor: !useColor });
+    let pSum = 0;
+    let aSum = 0;
+    let bpSum = 0;
+    let seoSum = 0;
+    let count = 0;
+    let green = 0;
+    let yellow = 0;
+    let red = 0;
+    for (const r of results) {
+        const p = r.scores.performance;
+        if (p !== undefined) {
+            count += 1;
+            pSum += p;
+            if (p >= 90) {
+                green += 1;
+            }
+            else if (p >= 50) {
+                yellow += 1;
+            }
+            else {
+                red += 1;
+            }
+        }
+        if (r.scores.accessibility !== undefined)
+            aSum += r.scores.accessibility;
+        if (r.scores.bestPractices !== undefined)
+            bpSum += r.scores.bestPractices;
+        if (r.scores.seo !== undefined)
+            seoSum += r.scores.seo;
+    }
+    const avgP = count > 0 ? Math.round(pSum / count) : 0;
+    const avgA = results.length > 0 ? Math.round(aSum / results.length) : 0;
+    const avgBP = results.length > 0 ? Math.round(bpSum / results.length) : 0;
+    const avgSEO = results.length > 0 ? Math.round(seoSum / results.length) : 0;
+    const lines = [
+        `${theme.dim("Summary")}: Avg P:${avgP} A:${avgA} BP:${avgBP} SEO:${avgSEO}`,
+        `${theme.dim("Scores")}: ${theme.green(`${green} green (90+)`)} | ${theme.yellow(`${yellow} yellow (50-89)`)} | ${theme.red(`${red} red (<50)`)} of ${count} total`,
+    ];
+    return renderPanel({ title: theme.bold("Stats"), lines });
+}
+function buildChangesBox(previous, current, useColor) {
+    const prevAvg = computeAvgScores(previous.results);
+    const currAvg = computeAvgScores(current.results);
+    const avgDelta = {
+        performance: currAvg.performance - prevAvg.performance,
+        accessibility: currAvg.accessibility - prevAvg.accessibility,
+        bestPractices: currAvg.bestPractices - prevAvg.bestPractices,
+        seo: currAvg.seo - prevAvg.seo,
+    };
+    const prevMap = new Map(previous.results.map((r) => [`${r.label}:::${r.path}:::${r.device}`, r]));
+    const currMap = new Map(current.results.map((r) => [`${r.label}:::${r.path}:::${r.device}`, r]));
+    const allKeys = new Set([...prevMap.keys(), ...currMap.keys()]);
+    const deltas = [];
+    let added = 0;
+    let removed = 0;
+    for (const key of allKeys) {
+        const prev = prevMap.get(key);
+        const curr = currMap.get(key);
+        if (!prev && curr) {
+            added += 1;
+            continue;
+        }
+        if (prev && !curr) {
+            removed += 1;
+            continue;
+        }
+        if (!prev || !curr) {
+            continue;
+        }
+        const deltaP = (curr.scores.performance ?? 0) - (prev.scores.performance ?? 0);
+        deltas.push({
+            key,
+            label: curr.label,
+            path: curr.path,
+            device: curr.device,
+            deltaP,
+        });
+    }
+    deltas.sort((a, b) => a.deltaP - b.deltaP);
+    const regressions = deltas.slice(0, 5);
+    const improvements = [...deltas].reverse().slice(0, 5);
+    const formatDelta = (value) => {
+        const sign = value > 0 ? "+" : "";
+        if (!useColor) {
+            return `${sign}${value}`;
+        }
+        if (value > 0) {
+            return `${ANSI_GREEN}${sign}${value}${ANSI_RESET}`;
+        }
+        if (value < 0) {
+            return `${ANSI_RED}${sign}${value}${ANSI_RESET}`;
+        }
+        return `${ANSI_CYAN}${sign}${value}${ANSI_RESET}`;
+    };
+    const lines = [];
+    lines.push(`Avg deltas: P ${formatDelta(avgDelta.performance)} | A ${formatDelta(avgDelta.accessibility)} | BP ${formatDelta(avgDelta.bestPractices)} | SEO ${formatDelta(avgDelta.seo)}`);
+    lines.push(`Combos: +${added} added, -${removed} removed`);
+    lines.push("");
+    lines.push("Top regressions (Performance):");
+    for (const r of regressions) {
+        lines.push(`- ${r.label} ${r.path} [${r.device}] ΔP:${formatDelta(r.deltaP)}`);
+    }
+    lines.push("");
+    lines.push("Top improvements (Performance):");
+    for (const r of improvements) {
+        lines.push(`- ${r.label} ${r.path} [${r.device}] ΔP:${formatDelta(r.deltaP)}`);
+    }
+    return boxifyWithSeparators(lines);
 }
 /**
  * Runs the ApexAuditor audit CLI.
  *
  * @param argv - The process arguments array.
  */
-export async function runAuditCli(argv) {
+export async function runAuditCli(argv, options) {
     const args = parseArgs(argv);
     const startTimeMs = Date.now();
     const { configPath, config } = await loadConfig({ configPath: args.configPath });
+    const previousSummary = await loadPreviousSummary();
+    const presetThrottling = args.accurate ? "devtools" : undefined;
+    const presetWarmUp = args.accurate ? true : args.overview ? false : undefined;
+    const presetParallel = args.accurate ? 1 : undefined;
+    const DEFAULT_PARALLEL = 4;
+    const DEFAULT_WARM_UP = true;
     const effectiveLogLevel = args.logLevelOverride ?? config.logLevel;
-    const effectiveThrottling = args.throttlingMethodOverride ?? config.throttlingMethod;
+    const effectiveThrottling = args.fast ? "simulate" : args.throttlingMethodOverride ?? presetThrottling ?? config.throttlingMethod;
     const effectiveCpuSlowdown = args.cpuSlowdownOverride ?? config.cpuSlowdownMultiplier;
-    const effectiveParallel = args.parallelOverride ?? config.parallel;
-    const effectiveWarmUp = args.warmUp || config.warmUp === true;
-    const effectiveConfig = {
+    const effectiveParallel = args.stable ? 1 : args.parallelOverride ?? presetParallel ?? config.parallel ?? DEFAULT_PARALLEL;
+    const effectiveAuditTimeoutMs = args.auditTimeoutMsOverride ?? config.auditTimeoutMs;
+    const warmUpDefaulted = presetWarmUp ?? config.warmUp ?? DEFAULT_WARM_UP;
+    const effectiveWarmUp = args.warmUp ? true : warmUpDefaulted;
+    const effectiveIncremental = args.incremental;
+    if (!effectiveIncremental && config.incremental === true) {
+        // eslint-disable-next-line no-console
+        console.log("Note: incremental caching is now opt-in. Pass --incremental to enable it for this run.");
+    }
+    const candidateBuildId = args.buildId ?? config.buildId;
+    const autoBuildId = effectiveIncremental && candidateBuildId === undefined
+        ? await resolveAutoBuildId(configPath)
+        : undefined;
+    const effectiveBuildId = candidateBuildId ?? autoBuildId;
+    const finalIncremental = effectiveIncremental && effectiveBuildId !== undefined;
+    if (effectiveIncremental && !finalIncremental) {
+        // eslint-disable-next-line no-console
+        console.log("Incremental mode requested, but no buildId could be resolved. Running a full audit. Tip: pass --build-id or set buildId in apex.config.json");
+    }
+    const effectiveRuns = 1;
+    const onlyCategories = args.fast ? ["performance"] : undefined;
+    let effectiveConfig = {
         ...config,
+        buildId: effectiveBuildId,
         logLevel: effectiveLogLevel,
         throttlingMethod: effectiveThrottling,
         cpuSlowdownMultiplier: effectiveCpuSlowdown,
         parallel: effectiveParallel,
+        auditTimeoutMs: effectiveAuditTimeoutMs,
         warmUp: effectiveWarmUp,
+        incremental: finalIncremental,
+        runs: effectiveRuns,
     };
+    if (args.changedOnly) {
+        const changedFiles = await getChangedFiles();
+        const changedConfig = filterConfigChanged(effectiveConfig, changedFiles);
+        if (changedConfig.pages.length === 0) {
+            // eslint-disable-next-line no-console
+            console.error("Changed-only mode: no pages matched git diff. Nothing to run.");
+            process.exitCode = 0;
+            return;
+        }
+        effectiveConfig = changedConfig;
+    }
+    if (args.rerunFailing) {
+        const rerunConfig = filterConfigFailing(previousSummary, effectiveConfig);
+        if (rerunConfig.pages.length === 0) {
+            // eslint-disable-next-line no-console
+            console.log("Rerun-failing mode: no failing combos found in previous summary. Nothing to run.");
+            process.exitCode = 0;
+            return;
+        }
+        effectiveConfig = rerunConfig;
+    }
     const filteredConfig = filterConfigDevices(effectiveConfig, args.deviceFilter);
     if (filteredConfig.pages.length === 0) {
         // eslint-disable-next-line no-console
@@ -140,7 +1134,144 @@ export async function runAuditCli(argv) {
         process.exitCode = 1;
         return;
     }
-    const summary = await runAuditsForConfig({ config: filteredConfig, configPath, showParallel: args.showParallel });
+    const overviewMaxCombos = args.overviewCombos ?? DEFAULT_OVERVIEW_MAX_COMBOS;
+    const overviewSample = args.overview && !args.yes ? sampleConfigForOverview(filteredConfig, overviewMaxCombos) : { config: filteredConfig, sampled: false, sampledCombos: 0 };
+    const plannedCombos = overviewSample.config.pages.reduce((acc, p) => acc + p.devices.length, 0);
+    const plannedRuns = overviewSample.config.runs ?? 1;
+    const plannedSteps = plannedCombos * plannedRuns;
+    const maxSteps = args.maxSteps ?? DEFAULT_MAX_STEPS;
+    const maxCombos = args.maxCombos ?? DEFAULT_MAX_COMBOS;
+    const isTty = typeof process !== "undefined" && process.stdout?.isTTY === true;
+    const exceeds = plannedSteps > maxSteps || plannedCombos > maxCombos;
+    const useColor = shouldUseColor(args.ci, args.colorMode);
+    if (args.plan) {
+        printPlan({
+            configPath,
+            resolvedConfig: overviewSample.config,
+            plannedCombos,
+            plannedSteps,
+            sampled: overviewSample.sampled,
+            sampledCombos: overviewSample.sampledCombos,
+            maxCombos,
+            maxSteps,
+            useColor,
+        });
+        return;
+    }
+    if (isTty && !args.ci && !args.jsonOutput) {
+        const tipLines = [
+            "Tip: use --plan to preview run size before starting.",
+            "Note: runs-per-combo is always 1; rerun the same command to compare results.",
+            "If parallel mode flakes (worker disconnects), retry with --stable (forces parallel=1).",
+        ];
+        // eslint-disable-next-line no-console
+        console.log(boxifyWithSeparators(tipLines));
+        printDivider();
+    }
+    if (overviewSample.sampled) {
+        // eslint-disable-next-line no-console
+        console.log(`Overview mode: sampling ${plannedCombos} combos (pass --yes for full suite or --overview-combos <n> to adjust).`);
+    }
+    if (exceeds && !args.yes) {
+        const limitText = `limits combos<=${maxCombos}, steps<=${maxSteps}`;
+        const planText = `Planned run: ${plannedCombos} combos x ${plannedRuns} runs = ${plannedSteps} Lighthouse runs.`;
+        if (args.ci || !isTty) {
+            // eslint-disable-next-line no-console
+            console.error(`${planText} Refusing to start because it exceeds default ${limitText}. Use --yes to proceed or adjust with --max-steps/--max-combos.`);
+            process.exitCode = 1;
+            return;
+        }
+        // eslint-disable-next-line no-console
+        console.log(`${planText} This exceeds default ${limitText}.`);
+        const ok = await confirmLargeRun("Continue? (y/N) ");
+        if (!ok) {
+            // eslint-disable-next-line no-console
+            console.log("Cancelled.");
+            return;
+        }
+    }
+    let summary;
+    const abortController = new AbortController();
+    if (options?.signal?.aborted === true) {
+        abortController.abort();
+    }
+    else if (options?.signal) {
+        const externalSignal = options.signal;
+        const onExternalAbort = () => abortController.abort();
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+        abortController.signal.addEventListener("abort", () => {
+            externalSignal.removeEventListener("abort", onExternalAbort);
+        });
+    }
+    const onSigInt = () => {
+        abortController.abort();
+    };
+    process.once("SIGINT", onSigInt);
+    let spinnerStarted = false;
+    let lastProgressLine;
+    const formatEtaText = (etaMs) => {
+        if (etaMs === undefined) {
+            return "";
+        }
+        const seconds = Math.max(0, Math.round(etaMs / 1000));
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = seconds % 60;
+        if (minutes === 0) {
+            return `${remainingSeconds}s`;
+        }
+        return `${minutes}m ${remainingSeconds}s`;
+    };
+    const startAuditSpinner = () => {
+        if (spinnerStarted) {
+            return;
+        }
+        startSpinner("Running audit (Lighthouse)");
+        spinnerStarted = true;
+    };
+    if (!filteredConfig.warmUp) {
+        startAuditSpinner();
+    }
+    try {
+        summary = await runAuditsForConfig({
+            config: overviewSample.config,
+            configPath,
+            showParallel: args.showParallel,
+            onlyCategories,
+            signal: abortController.signal,
+            onAfterWarmUp: startAuditSpinner,
+            onProgress: ({ completed, total, path, device, etaMs }) => {
+                if (!process.stdout.isTTY) {
+                    return;
+                }
+                const etaText = etaMs !== undefined ? ` | ETA ${formatEtaText(etaMs)}` : "";
+                const message = `* Running audit (Lighthouse) page ${completed}/${total} — ${path} [${device}]${etaText}`;
+                const padded = message.padEnd(lastProgressLine?.length ?? message.length, " ");
+                process.stdout.write(`\r${padded}`);
+                lastProgressLine = padded;
+                updateSpinnerMessage(`Running audit (Lighthouse) page ${completed}/${total}`);
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        if (abortController.signal.aborted || message.includes("Aborted")) {
+            // eslint-disable-next-line no-console
+            console.log("Audit cancelled.");
+            process.exitCode = 130;
+            return;
+        }
+        handleFriendlyError(error);
+        process.exitCode = 1;
+        return;
+    }
+    finally {
+        process.removeListener("SIGINT", onSigInt);
+        if (lastProgressLine !== undefined) {
+            process.stdout.write("\n");
+            lastProgressLine = undefined;
+        }
+        stopSpinner();
+    }
     const outputDir = resolve(".apex-auditor");
     await mkdir(outputDir, { recursive: true });
     await writeFile(resolve(outputDir, "summary.json"), JSON.stringify(summary, null, 2), "utf8");
@@ -149,6 +1280,24 @@ export async function runAuditCli(argv) {
     const html = buildHtmlReport(summary);
     const reportPath = resolve(outputDir, "report.html");
     await writeFile(reportPath, html, "utf8");
+    const budgetViolations = effectiveConfig.budgets === undefined ? [] : collectBudgetViolations(summary.results, effectiveConfig.budgets);
+    const shareable = buildShareableExport({
+        configPath,
+        previousSummary,
+        current: summary,
+        budgets: effectiveConfig.budgets,
+    });
+    const exportPath = resolve(outputDir, "export.json");
+    await writeFile(exportPath, JSON.stringify(shareable, null, 2), "utf8");
+    const accessibilityArtifacts = resolve(outputDir, "accessibility");
+    const accessibilitySummary = await runAccessibilityAudit({
+        config: filteredConfig,
+        configPath,
+        artifactsDir: accessibilityArtifacts,
+    });
+    const accessibilitySummaryPath = resolve(outputDir, "accessibility-summary.json");
+    await writeFile(accessibilitySummaryPath, JSON.stringify(accessibilitySummary, null, 2), "utf8");
+    const accessibilityAggregated = accessibilitySummary === undefined ? undefined : summariseAccessibility(accessibilitySummary);
     // Open HTML report in browser if requested
     if (args.openReport) {
         openInBrowser(reportPath);
@@ -159,24 +1308,110 @@ export async function runAuditCli(argv) {
         console.log(JSON.stringify(summary, null, 2));
         return;
     }
+    printReportLink(reportPath);
+    if (isTty && !args.ci) {
+        // eslint-disable-next-line no-console
+        console.log(buildEffectiveSettingsPanel({ configPath, config: effectiveConfig, useColor }));
+        // eslint-disable-next-line no-console
+        console.log(buildSectionIndex(useColor));
+    }
     // Also echo a compact, colourised table to stdout for quick viewing.
-    const useColor = shouldUseColor(args.ci, args.colorMode);
-    const consoleTable = buildConsoleTable(summary.results, useColor);
+    // Structured panels
+    // eslint-disable-next-line no-console
+    console.log(buildMetaPanel(summary.meta, useColor));
+    // eslint-disable-next-line no-console
+    console.log(buildStatsPanel(summary.results, useColor));
+    if (previousSummary !== undefined) {
+        printSectionHeader("Changes", useColor);
+        printDivider();
+        // eslint-disable-next-line no-console
+        console.log(buildChangesBox(previousSummary, summary, useColor));
+        printDivider();
+    }
+    printSectionHeader("Summary", useColor);
+    // eslint-disable-next-line no-console
+    console.log(buildSummaryPanel({
+        results: summary.results,
+        useColor,
+        regressionsOnly: args.regressionsOnly,
+        previousSummary,
+    }));
+    printSectionHeader("Issues", useColor);
+    // eslint-disable-next-line no-console
+    console.log(buildIssuesPanel(summary.results, useColor));
+    printSectionHeader("Top fixes", useColor);
+    // eslint-disable-next-line no-console
+    console.log(buildTopFixesPanel(summary.results, useColor));
+    const budgetsPanel = buildBudgetsPanel({
+        budgets: effectiveConfig.budgets,
+        violations: budgetViolations,
+        useColor,
+    });
+    if (budgetsPanel !== undefined) {
+        printSectionHeader("Budgets", useColor);
+        // eslint-disable-next-line no-console
+        console.log(budgetsPanel);
+    }
+    printSectionHeader("Accessibility (fast pass)", useColor);
+    // eslint-disable-next-line no-console
+    console.log(buildAccessibilityPanel(summariseAccessibility(accessibilitySummary), useColor));
+    // eslint-disable-next-line no-console
+    console.log(buildAccessibilityIssuesPanel(accessibilitySummary.results, useColor));
+    if (args.webhookUrl) {
+        const regressions = collectRegressions(previousSummary, summary);
+        if (args.webhookAlways || shouldSendWebhook(regressions, budgetViolations)) {
+            const payload = buildWebhookPayload({
+                current: summary,
+                previous: previousSummary,
+                budgetViolations,
+                accessibility: accessibilityAggregated,
+                reportPath,
+                exportPath,
+                accessibilityPath: accessibilitySummaryPath,
+            });
+            try {
+                await postJsonWebhook({ url: args.webhookUrl, payload });
+                // eslint-disable-next-line no-console
+                console.log(`Sent webhook to ${args.webhookUrl}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // eslint-disable-next-line no-console
+                console.error(`Failed to send webhook: ${message}`);
+            }
+        }
+    }
+    printCiSummary({ isCi: args.ci, failOnBudget: args.failOnBudget, violations: budgetViolations });
+    printSectionHeader("Lowest performance", useColor);
     // eslint-disable-next-line no-console
-    console.log(consoleTable);
-    printRunMeta(summary.meta, useColor);
-    printSummaryStats(summary.results, useColor);
-    printRedIssues(summary.results);
-    printCiSummary(args, summary.results, effectiveConfig.budgets);
-    printLowestPerformancePages(summary.results, useColor);
+    console.log(buildLowestPerformancePanel(summary.results, useColor));
+    printSectionHeader("Export", useColor);
+    // eslint-disable-next-line no-console
+    console.log(buildExportPanel({ exportPath, useColor, share: shareable }));
     const elapsedMs = Date.now() - startTimeMs;
     const elapsedText = formatElapsedTime(elapsedMs);
     const elapsedDisplay = useColor ? `${ANSI_CYAN}${elapsedText}${ANSI_RESET}` : elapsedText;
     const runsPerTarget = effectiveConfig.runs ?? 1;
     const comboCount = summary.results.length;
     const totalRuns = comboCount * runsPerTarget;
+    const cacheNote = summary.meta.incremental
+        ? ` Cache: ${summary.meta.executedCombos} executed / ${summary.meta.cachedCombos} cached (steps: ${summary.meta.executedSteps} executed, ${summary.meta.cachedSteps} cached).`
+        : "";
     // eslint-disable-next-line no-console
-    console.log(`\nCompleted in ${elapsedDisplay} (${comboCount} page/device combinations x ${runsPerTarget} runs = ${totalRuns} Lighthouse runs).`);
+    console.log(`\nCompleted in ${elapsedDisplay} (${comboCount} page/device combinations x ${runsPerTarget} runs = ${totalRuns} Lighthouse runs).${cacheNote}`);
+}
+async function getChangedFiles() {
+    try {
+        const diffOutput = await runCommand("git diff --name-only", process.cwd());
+        const files = diffOutput
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        return files;
+    }
+    catch {
+        return [];
+    }
 }
 function filterConfigDevices(config, deviceFilter) {
     if (deviceFilter === undefined) {
@@ -190,6 +1425,39 @@ function filterConfigDevices(config, deviceFilter) {
         pages: filteredPages,
     };
 }
+function filterConfigChanged(config, changedFiles) {
+    if (changedFiles.length === 0) {
+        return config;
+    }
+    const pageMatches = (pagePath) => {
+        const segment = pagePath.replace(/^\//, "");
+        return changedFiles.some((file) => file.includes(segment));
+    };
+    const pages = config.pages.filter((page) => pageMatches(page.path));
+    return { ...config, pages };
+}
+function filterConfigFailing(previous, config) {
+    if (previous === undefined) {
+        return config;
+    }
+    const failing = new Set();
+    for (const result of previous.results) {
+        const runtimeFailed = Boolean(result.runtimeErrorMessage);
+        const perfScore = result.scores.performance;
+        const failedScore = typeof perfScore === "number" && perfScore < 90;
+        if (runtimeFailed || failedScore) {
+            failing.add(`${result.label}:::${result.path}:::${result.device}`);
+        }
+    }
+    const pages = config.pages.flatMap((page) => {
+        const devices = page.devices.filter((device) => failing.has(`${page.label}:::${page.path}:::${device}`));
+        if (devices.length === 0) {
+            return [];
+        }
+        return [{ ...page, devices }];
+    });
+    return { ...config, pages };
+}
 function filterPageDevices(page, deviceFilter) {
     const devices = page.devices.filter((device) => device === deviceFilter);
     if (devices.length === 0) {
@@ -206,13 +1474,19 @@ function buildMarkdown(summary) {
         "| Field | Value |",
         "|-------|-------|",
         `| Config | ${meta.configPath} |`,
+        `| Build ID | ${meta.buildId ?? "-"} |`,
+        `| Incremental | ${meta.incremental ? "yes" : "no"} |`,
         `| Resolved parallel | ${meta.resolvedParallel} |`,
         `| Warm-up | ${meta.warmUp ? "yes" : "no"} |`,
         `| Throttling | ${meta.throttlingMethod} |`,
         `| CPU slowdown | ${meta.cpuSlowdownMultiplier} |`,
         `| Combos | ${meta.comboCount} |`,
+        `| Executed combos | ${meta.executedCombos} |`,
+        `| Cached combos | ${meta.cachedCombos} |`,
         `| Runs per combo | ${meta.runsPerCombo} |`,
         `| Total steps | ${meta.totalSteps} |`,
+        `| Executed steps | ${meta.executedSteps} |`,
+        `| Cached steps | ${meta.cachedSteps} |`,
         `| Started | ${meta.startedAt} |`,
         `| Completed | ${meta.completedAt} |`,
         `| Elapsed | ${formatElapsedTime(meta.elapsedMs)} |`,
@@ -230,6 +1504,9 @@ function buildHtmlReport(summary) {
     const meta = summary.meta;
     const timestamp = new Date().toISOString();
     const rows = results.map((result) => buildHtmlRow(result)).join("\n");
+    const cacheSummary = meta.incremental
+        ? `${meta.executedCombos} executed / ${meta.cachedCombos} cached`
+        : "disabled";
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -237,57 +1514,139 @@ function buildHtmlReport(summary) {
   <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; }
+    :root {
+      --green: #0cce6b;
+      --yellow: #ffa400;
+      --red: #ff4e42;
+      --bg: #0f172a;
+      --panel: #0b1224;
+      --card: #111a33;
+      --border: #27324d;
+      --text: #e8edf7;
+      --muted: #93a4c3;
+      --accent: #7c3aed;
+    }
     * { 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; }
-    .meta-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
-    .meta-card { background: #16213e; border-radius: 10px; padding: 1rem; border: 1px solid #23304f; }
-    .meta-label { font-size: 0.8rem; color: #9ca3af; text-transform: uppercase; letter-spacing: 0.04em; }
-    .meta-value { font-size: 1rem; font-weight: 600; color: #e5e7eb; }
+    body {
+      font-family: "Inter", "IBM Plex Sans", "Segoe UI", system-ui, -apple-system, sans-serif;
+      background: radial-gradient(circle at 20% 20%, #122042, #0a1020 45%), #0a0f1f;
+      color: var(--text);
+      padding: 2rem;
+      line-height: 1.5;
+    }
+    h1 { margin-bottom: 0.5rem; letter-spacing: 0.02em; }
+    .meta { color: var(--muted); margin-bottom: 2rem; font-size: 0.95rem; }
+    .meta-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+      gap: 1rem;
+      margin-bottom: 2rem;
+    }
+    .meta-card {
+      background: linear-gradient(135deg, var(--panel), #0f1a33);
+      border-radius: 12px;
+      padding: 1rem;
+      border: 1px solid var(--border);
+      box-shadow: 0 10px 40px rgba(0, 0, 0, 0.35);
+    }
+    .meta-label { font-size: 0.78rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; }
+    .meta-value { font-size: 1.05rem; font-weight: 650; color: var(--text); }
     .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; }
+    .card {
+      background: linear-gradient(180deg, var(--card), #0e1a31);
+      border-radius: 14px;
+      padding: 1.5rem;
+      border: 1px solid var(--border);
+      box-shadow: 0 14px 45px rgba(0, 0, 0, 0.35), inset 0 1px 0 rgba(255, 255, 255, 0.04);
+    }
+    .card-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 1rem;
+      border-bottom: 1px solid var(--border);
+      padding-bottom: 1rem;
+    }
+    .card-title { font-size: 1.1rem; font-weight: 650; }
+    .card-title span { color: var(--muted); font-weight: 500; }
+    .device-badge {
+      font-size: 0.78rem;
+      padding: 0.35rem 0.65rem;
+      border-radius: 999px;
+      background: #1f2937;
+      border: 1px solid var(--border);
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+    }
+    .device-badge.mobile { background: linear-gradient(135deg, #0ea5e9, #0891b2); color: #e6f6ff; border-color: #0ea5e9; }
+    .device-badge.desktop { background: linear-gradient(135deg, #8b5cf6, #7c3aed); color: #f5efff; border-color: #8b5cf6; }
+    .scores { display: grid; grid-template-columns: repeat(auto-fit, minmax(90px, 1fr)); gap: 0.75rem; margin-bottom: 1rem; }
+    .score-item { text-align: center; }
+    .score-circle {
+      width: 64px;
+      height: 64px;
+      border-radius: 12px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 1.25rem;
+      font-weight: 700;
+      margin: 0 auto 0.35rem;
+      border: 2px solid var(--border);
+      background: #0c152a;
+      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.04);
+    }
+    .score-circle.green { border-color: var(--green); color: var(--green); box-shadow: 0 0 0 1px rgba(12, 206, 107, 0.15), inset 0 1px 0 rgba(255, 255, 255, 0.05); }
+    .score-circle.yellow { border-color: var(--yellow); color: var(--yellow); box-shadow: 0 0 0 1px rgba(255, 164, 0, 0.15), inset 0 1px 0 rgba(255, 255, 255, 0.05); }
+    .score-circle.red { border-color: var(--red); color: var(--red); box-shadow: 0 0 0 1px rgba(255, 78, 66, 0.15), inset 0 1px 0 rgba(255, 255, 255, 0.05); }
+    .score-label { font-size: 0.78rem; color: var(--muted); }
+    .metrics { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 0.85rem; }
+    .metric {
+      background: #0c152a;
+      padding: 0.85rem;
+      border-radius: 10px;
+      text-align: center;
+      border: 1px solid var(--border);
+      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.03);
+    }
+    .metric-value { font-size: 1.05rem; font-weight: 650; }
     .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; }
+    .metric-label { font-size: 0.72rem; color: var(--muted); margin-top: 0.25rem; letter-spacing: 0.04em; }
+    .issues {
+      margin-top: 1rem;
+      padding: 1rem;
+      border-radius: 10px;
+      border: 1px solid var(--border);
+      background: #0c152a;
+      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.03);
+    }
+    .issues-title { font-size: 0.85rem; color: var(--muted); margin-bottom: 0.5rem; letter-spacing: 0.05em; text-transform: uppercase; }
+    .issue {
+      font-size: 0.88rem;
+      color: var(--text);
+      padding: 0.35rem 0.25rem;
+      border-bottom: 1px dashed var(--border);
+    }
+    .issue:last-child { border-bottom: none; }
   </style>
 </head>
 <body>
   <h1>ApexAuditor Report</h1>
   <p class="meta">Generated: ${timestamp}</p>
   <div class="meta-grid">
-    ${buildMetaCard("Config", escapeHtml(meta.configPath))}
+    ${buildMetaCard("Build ID", meta.buildId ?? "-")}
+    ${buildMetaCard("Incremental", meta.incremental ? "Yes" : "No")}
+    ${buildMetaCard("Cache", cacheSummary)}
     ${buildMetaCard("Resolved parallel", meta.resolvedParallel.toString())}
-    ${buildMetaCard("Warm-up", meta.warmUp ? "Yes" : "No")}
-    ${buildMetaCard("Throttling", meta.throttlingMethod)}
-    ${buildMetaCard("CPU slowdown", meta.cpuSlowdownMultiplier.toString())}
-    ${buildMetaCard("Combos", meta.comboCount.toString())}
-    ${buildMetaCard("Runs per combo", meta.runsPerCombo.toString())}
-    ${buildMetaCard("Total steps", meta.totalSteps.toString())}
     ${buildMetaCard("Elapsed", formatElapsedTime(meta.elapsedMs))}
     ${buildMetaCard("Avg / step", formatElapsedTime(meta.averageStepMs))}
-    ${buildMetaCard("Started", meta.startedAt)}
-    ${buildMetaCard("Completed", meta.completedAt)}
+    ${buildMetaCard("Combos", meta.comboCount.toString())}
+    ${buildMetaCard("Runs per combo", meta.runsPerCombo.toString())}
+    ${buildMetaCard("Throttling", meta.throttlingMethod)}
+    ${buildMetaCard("CPU slowdown", meta.cpuSlowdownMultiplier.toString())}
+    ${buildMetaCard("Warm-up", meta.warmUp ? "Yes" : "No")}
   </div>
   <div class="cards">
 ${rows}
@@ -337,12 +1696,18 @@ function buildMetaCard(label, value) {
     return `<div class="meta-card"><div class="meta-label">${escapeHtml(label)}</div><div class="meta-value">${escapeHtml(value)}</div></div>`;
 }
 function printRunMeta(meta, useColor) {
+    const incrementalSummary = meta.incremental
+        ? `${meta.executedCombos} executed / ${meta.cachedCombos} cached (${meta.executedSteps} executed steps, ${meta.cachedSteps} cached steps)`
+        : "No";
     const rows = [
+        { label: "Build ID", value: meta.buildId ?? "-" },
+        { label: "Incremental", value: meta.incremental ? "Yes" : "No" },
         { label: "Resolved parallel", value: meta.resolvedParallel.toString() },
         { label: "Warm-up", value: meta.warmUp ? "Yes" : "No" },
         { label: "Throttling", value: meta.throttlingMethod },
         { label: "CPU slowdown", value: meta.cpuSlowdownMultiplier.toString() },
         { label: "Combos", value: meta.comboCount.toString() },
+        { label: "Cache", value: incrementalSummary },
         { label: "Runs per combo", value: meta.runsPerCombo.toString() },
         { label: "Total steps", value: meta.totalSteps.toString() },
         { label: "Elapsed", value: formatElapsedTime(meta.elapsedMs) },
@@ -480,6 +1845,52 @@ function formatOpportunityLabel(opportunity) {
     const suffix = parts.length > 0 ? ` (${parts.join(", ")})` : "";
     return `${opportunity.id}${suffix}`;
 }
+function printTopFixes(results) {
+    const map = new Map();
+    for (const result of results) {
+        for (const opp of result.opportunities) {
+            if (!hasMeaningfulSavings(opp)) {
+                continue;
+            }
+            const key = opp.id;
+            const previous = map.get(key);
+            map.set(key, {
+                title: previous?.title ?? opp.title,
+                count: (previous?.count ?? 0) + 1,
+                totalMs: (previous?.totalMs ?? 0) + (opp.estimatedSavingsMs ?? 0),
+                totalBytes: (previous?.totalBytes ?? 0) + (opp.estimatedSavingsBytes ?? 0),
+            });
+        }
+    }
+    const aggregates = Array.from(map.entries()).map(([id, v]) => {
+        return { id, title: v.title, count: v.count, totalMs: v.totalMs, totalBytes: v.totalBytes };
+    });
+    if (aggregates.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log(boxifyWithSeparators(["No actionable opportunities found in this sample."]));
+        return;
+    }
+    aggregates.sort((a, b) => {
+        if (a.count !== b.count) {
+            return b.count - a.count;
+        }
+        if (a.totalMs !== b.totalMs) {
+            return b.totalMs - a.totalMs;
+        }
+        return b.totalBytes - a.totalBytes;
+    });
+    const top = aggregates.slice(0, 8);
+    const lines = ["Most common opportunities:"];
+    for (const entry of top) {
+        const ms = entry.totalMs > 0 ? `${Math.round(entry.totalMs)}ms` : "";
+        const kb = entry.totalBytes > 0 ? `${Math.round(entry.totalBytes / 1024)}KB` : "";
+        const parts = [ms, kb].filter((p) => p.length > 0);
+        const suffix = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+        lines.push(`- ${entry.id} – ${entry.title} (seen on ${entry.count} pages)${suffix}`);
+    }
+    // eslint-disable-next-line no-console
+    console.log(boxifyWithSeparators(lines));
+}
 function formatMetricSeconds(valueMs, goodThresholdMs, warnThresholdMs, useColor) {
     if (valueMs === undefined) {
         return "-";
@@ -599,10 +2010,11 @@ function printRedIssues(results) {
             isRedScore(scores.seo));
     });
     if (redResults.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log(boxify(["No red issues."]));
         return;
     }
-    // eslint-disable-next-line no-console
-    console.log("\nRed issues (scores below 50):");
+    const lines = ["Red issues (scores below 50):"];
     for (const result of redResults) {
         const scores = result.scores;
         const badParts = [];
@@ -619,15 +2031,16 @@ function printRedIssues(results) {
             badParts.push(`SEO:${scores.seo}`);
         }
         const issues = formatTopIssues(result.opportunities);
-        // eslint-disable-next-line no-console
-        console.log(`- ${result.label} ${result.path} [${result.device}] – ${badParts.join(", ")} – ${issues}`);
+        lines.push(`- ${result.label} ${result.path} [${result.device}] – ${badParts.join(", ")} – ${issues}`);
     }
+    // eslint-disable-next-line no-console
+    console.log(boxifyWithSeparators(lines));
 }
 function shouldUseColor(ci, colorMode) {
-    if (colorMode === "on") {
+    if (colorMode === "always") {
         return true;
     }
-    if (colorMode === "off") {
+    if (colorMode === "never") {
         return false;
     }
     if (ci) {
@@ -635,24 +2048,20 @@ function shouldUseColor(ci, colorMode) {
     }
     return typeof process !== "undefined" && Boolean(process.stdout && process.stdout.isTTY);
 }
-function printCiSummary(args, results, budgets) {
-    if (!args.ci) {
+function printCiSummary(params) {
+    if (!params.isCi && !params.failOnBudget) {
         return;
     }
-    if (!budgets) {
-        // eslint-disable-next-line no-console
-        console.log("\nCI mode: no budgets configured. Skipping threshold checks.");
-        return;
-    }
-    const violations = collectBudgetViolations(results, budgets);
-    if (violations.length === 0) {
-        // eslint-disable-next-line no-console
-        console.log("\nCI budgets PASSED.");
+    if (params.violations.length === 0) {
+        if (params.isCi) {
+            // eslint-disable-next-line no-console
+            console.log("\nCI budgets PASSED.");
+        }
         return;
     }
     // eslint-disable-next-line no-console
-    console.log(`\nCI budgets FAILED (${violations.length} violations):`);
-    for (const violation of violations) {
+    console.log(`\nBudgets FAILED (${params.violations.length} violations):`);
+    for (const violation of params.violations) {
         // eslint-disable-next-line no-console
         console.log(`- ${violation.pageLabel} ${violation.path} [${violation.device}] – ${violation.kind} ${violation.id}: ${violation.value} vs limit ${violation.limit}`);
     }
@@ -721,16 +2130,16 @@ function printLowestPerformancePages(results, useColor) {
     if (worst.length === 0) {
         return;
     }
-    // eslint-disable-next-line no-console
-    console.log("\nLowest Performance pages:");
+    const lines = ["Lowest Performance pages:"];
     for (const entry of worst) {
         const perfText = colourScore(entry.performance, useColor);
         const label = entry.result.label;
         const path = entry.result.path;
         const device = entry.result.device;
-        // eslint-disable-next-line no-console
-        console.log(`- ${label} ${path} [${device}] P:${perfText}`);
+        lines.push(`- ${label} ${path} [${device}] P:${perfText}`);
     }
+    // eslint-disable-next-line no-console
+    console.log(boxifyWithSeparators(lines));
 }
 function collectMetricViolations(result, metricsBudgets, allViolations) {
     const metrics = result.metrics;
@@ -776,3 +2185,61 @@ function openInBrowser(filePath) {
         }
     });
 }
+function printReportLink(reportPath) {
+    const fileUrl = `file://${reportPath.replace(/\\/g, "/")}`;
+    // eslint-disable-next-line no-console
+    console.log(`\nReport saved to: ${reportPath}`);
+    // eslint-disable-next-line no-console
+    console.log(`Open report: ${fileUrl}`);
+}
+function printSectionHeader(label, useColor) {
+    const decorated = useColor ? `${ANSI_BLUE}${label}${ANSI_RESET}` : label;
+    // eslint-disable-next-line no-console
+    console.log(`\n┌─ ${decorated} ${"─".repeat(Math.max(0, 30 - label.length))}`);
+}
+function printDivider() {
+    // eslint-disable-next-line no-console
+    console.log("├" + "─".repeat(40));
+}
+function boxify(lines) {
+    if (lines.length === 0) {
+        return "";
+    }
+    const maxWidth = Math.max(...lines.map((line) => line.length));
+    const top = `┌${"─".repeat(maxWidth + 2)}┐`;
+    const bottom = `└${"─".repeat(maxWidth + 2)}┘`;
+    const body = lines.map((line) => `│ ${line.padEnd(maxWidth, " ")} │`);
+    return [top, ...body, bottom].join("\n");
+}
+function boxifyWithSeparators(lines) {
+    if (lines.length === 0) {
+        return "";
+    }
+    const maxWidth = Math.max(...lines.map((line) => line.length));
+    const top = `┌${"─".repeat(maxWidth + 2)}┐`;
+    const bottom = `└${"─".repeat(maxWidth + 2)}┘`;
+    const sep = `├${"─".repeat(maxWidth + 2)}┤`;
+    const body = lines.flatMap((line, index) => {
+        const row = `│ ${line.padEnd(maxWidth, " ")} │`;
+        if (index === lines.length - 1) {
+            return [row];
+        }
+        return [row, sep];
+    });
+    return [top, ...body, bottom].join("\n");
+}
+function handleFriendlyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("Could not reach")) {
+        // eslint-disable-next-line no-console
+        console.error("Cannot reach the target URL. Is your dev server running and accessible from this machine?");
+        return;
+    }
+    if (message.includes("LanternError")) {
+        // eslint-disable-next-line no-console
+        console.error("Lighthouse trace analysis failed (Lantern). Try: reduce parallelism, set --throttling devtools, or rerun with fewer pages.");
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.error(message);
+}