browxai 0.7.0

package/dist/page/perf-audit-analysers.js

@@ -0,0 +1,369 @@
+// perf_audit category analysers — the eight `AuditCategoryAnalyser` functions
+// and the `ANALYSERS` registry that maps each category to its analyser. Split
+// out of perf-audit.ts so the analysers (the bulk of the file) live apart from
+// the report composer; re-exported through `./perf-audit.js`.
+//
+// RFC 0004 P4 / D6 — `ANALYSERS` is the SINGLE source of truth for the audit
+// category set: an add-only registry (one entry per category). The
+// `AuditCategory` union and the `ALL_AUDIT_CATEGORIES` array are DERIVED from
+// its keys, so adding a category is ONE edit (a new `ANALYSERS` entry) and a
+// typo'd category string is a compile error, not a silently-dropped key. This
+// makes the perf-audit registry — the doctrine's own cited OCP exemplar
+// (architecture-principles §2) — genuinely exemplary.
+/** The audit category registry — the ONE place a category is declared. Each
+ *  key is a category name; each value is its analyser. `as const satisfies`
+ *  pins the keys as string literals (so `AuditCategory` derives a closed union)
+ *  while still type-checking every value against the analyser signature.
+ *
+ *  Order is meaningful — issues are surfaced in this order when severity ties. */
+export const ANALYSERS = {
+    "render-blocking": analyseRenderBlocking,
+    "unused-code": analyseUnusedCode,
+    "oversize-images": analyseOversizeImages,
+    "layout-thrashing": analyseLayoutThrashing,
+    "long-tasks": analyseLongTasks,
+    "leak-suspects": analyseLeakSuspects,
+    "cache-opportunities": analyseCacheOpportunities,
+    "font-loading": analyseFontLoading,
+};
+/** Every audit category, in declaration order — DERIVED from `ANALYSERS`. The
+ *  `Object.keys` cast is sound because the keys ARE the `AuditCategory` union. */
+export const ALL_AUDIT_CATEGORIES = Object.keys(ANALYSERS);
+// ---------------------------------------------------------------------------
+// Category analysers
+// ---------------------------------------------------------------------------
+/** render-blocking — `ParseHTML`/`Layout` events with VeryHigh-priority
+ *  resources blocking first paint. Heuristic: any `ResourceSendRequest`
+ *  with `args.data.renderBlocking == "blocking"` or
+ *  `args.data.priority == "VeryHigh"` BEFORE the first `firstPaint` event. */
+/** Detect whether a `ResourceSendRequest` event (before first paint) is a render
+ *  blocker, returning its `{url, priority}` or null. */
+function renderBlocker(e, firstPaintTs) {
+    if (e.name !== "ResourceSendRequest")
+        return null;
+    const ts = typeof e.ts === "number" ? e.ts : 0;
+    if (ts >= firstPaintTs)
+        return null;
+    const data = ((e.args ?? {}).data ?? {});
+    const url = typeof data.url === "string" ? data.url : "";
+    const blocking = typeof data.renderBlocking === "string" ? data.renderBlocking : "";
+    const priority = typeof data.priority === "string" ? data.priority : "";
+    if (!url)
+        return null;
+    const isBlocker = blocking === "blocking" || blocking === "in_body_parser_blocking" || priority === "VeryHigh";
+    return isBlocker ? { url, priority: priority || blocking } : null;
+}
+export function analyseRenderBlocking(ctx) {
+    let firstPaintTs = Infinity;
+    for (const e of ctx.trace) {
+        if (e.name === "firstPaint" && typeof e.ts === "number") {
+            firstPaintTs = e.ts;
+            break;
+        }
+    }
+    const blockers = [];
+    for (const e of ctx.trace) {
+        const b = renderBlocker(e, firstPaintTs);
+        if (b)
+            blockers.push(b);
+    }
+    const issues = blockers.map((b) => ({
+        category: "render-blocking",
+        severity: b.priority === "VeryHigh" || b.priority === "blocking"
+            ? "high"
+            : "medium",
+        title: `Render-blocking resource: ${b.url}`,
+        details: { url: b.url, priority: b.priority },
+    }));
+    const remediations = blockers.map((b) => ({
+        category: "render-blocking",
+        action: b.url.endsWith(".css")
+            ? "Inline critical CSS in <head>; defer the rest with rel=preload + onload."
+            : "Add `defer` or `async` to the script tag, or move below the fold.",
+        target: b.url,
+    }));
+    return { issues, remediations };
+}
+/** unused-code — scripts + CSS files with `usagePercent < 30`. Severity tied
+ *  to absolute waste (bytes), not percent, because a 90%-dead 2KB file
+ *  doesn't matter. */
+export function analyseUnusedCode(ctx) {
+    const issues = [];
+    const remediations = [];
+    for (const js of ctx.jsCoverage ?? []) {
+        if (js.usagePercent >= 30)
+            continue;
+        const wasted = js.totalBytes - js.usedBytes;
+        if (wasted < 5000)
+            continue;
+        issues.push({
+            category: "unused-code",
+            severity: wasted > 100_000 ? "high" : wasted > 20_000 ? "medium" : "low",
+            title: `Unused JS in ${js.url}: ${Math.round(wasted / 1024)}KB dead (${js.usagePercent}% used)`,
+            details: {
+                url: js.url,
+                totalBytes: js.totalBytes,
+                usedBytes: js.usedBytes,
+                usagePercent: js.usagePercent,
+            },
+        });
+        remediations.push({
+            category: "unused-code",
+            action: "Tree-shake / code-split this bundle; dead code is the largest opportunity.",
+            target: js.url,
+        });
+    }
+    for (const css of ctx.cssCoverage ?? []) {
+        if (css.usagePercent >= 30)
+            continue;
+        const wasted = css.totalBytes - css.usedBytes;
+        if (wasted < 5000)
+            continue;
+        issues.push({
+            category: "unused-code",
+            severity: wasted > 50_000 ? "high" : wasted > 10_000 ? "medium" : "low",
+            title: `Unused CSS in ${css.url}: ${Math.round(wasted / 1024)}KB dead (${css.usagePercent}% used)`,
+            details: {
+                url: css.url,
+                totalBytes: css.totalBytes,
+                usedBytes: css.usedBytes,
+                usagePercent: css.usagePercent,
+            },
+        });
+        remediations.push({
+            category: "unused-code",
+            action: "PurgeCSS / Tailwind-style on-demand generation; ship only selectors the page uses.",
+            target: css.url,
+        });
+    }
+    return { issues, remediations };
+}
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "gif", "webp", "avif", "svg"]);
+/** Record one oversize image (deduped) into the issue/remediation accumulators. */
+function pushOversizeImage(acc, url, bytes, action, extraDetails = {}) {
+    if (acc.seen.has(url))
+        return;
+    acc.seen.add(url);
+    acc.issues.push({
+        category: "oversize-images",
+        severity: bytes > 2_000_000 ? "high" : "medium",
+        title: `Oversize image: ${url} (${Math.round(bytes / 1024)}KB)`,
+        details: { url, bytes, ...extraDetails },
+    });
+    acc.remediations.push({ category: "oversize-images", action, target: url });
+}
+/** oversize-images — images > 500KB. */
+export function analyseOversizeImages(ctx) {
+    const acc = {
+        issues: [],
+        remediations: [],
+        seen: new Set(),
+    };
+    // Prefer network responses metadata; fall back to ResourceFinish events.
+    for (const r of ctx.responses ?? []) {
+        if (!r.mimeType?.startsWith("image/"))
+            continue;
+        const bytes = r.encodedDataLength ?? 0;
+        if (bytes < 500_000)
+            continue;
+        pushOversizeImage(acc, r.url, bytes, "Compress + resize to displayed dimensions; switch to AVIF/WebP; add srcset for responsive sizing.", { mimeType: r.mimeType });
+    }
+    for (const e of ctx.trace) {
+        const img = oversizeImageFromTrace(e);
+        if (img) {
+            pushOversizeImage(acc, img.url, img.bytes, "Compress + resize to displayed dimensions; switch to AVIF/WebP.");
+        }
+    }
+    return { issues: acc.issues, remediations: acc.remediations };
+}
+/** Pull an oversize-image `{url, bytes}` out of a `ResourceFinish` trace event
+ *  (image extension + ≥500KB), or null. */
+function oversizeImageFromTrace(e) {
+    if (e.name !== "ResourceFinish")
+        return null;
+    const data = ((e.args ?? {}).data ?? {});
+    const url = typeof data.url === "string" ? data.url : "";
+    const bytes = typeof data.encodedDataLength === "number" ? data.encodedDataLength : 0;
+    if (!url || bytes < 500_000)
+        return null;
+    const ext = url.split("?")[0]?.split(".").pop()?.toLowerCase() ?? "";
+    return IMAGE_EXTENSIONS.has(ext) ? { url, bytes } : null;
+}
+/** layout-thrashing — > 5 forced sync layouts. */
+export function analyseLayoutThrashing(ctx) {
+    let forcedCount = 0;
+    let shiftCount = 0;
+    for (const e of ctx.trace) {
+        if (e.name === "LayoutShift")
+            shiftCount++;
+        if (e.name === "ForcedSyncLayout")
+            forcedCount++;
+        if (e.name === "Layout" && hasForcedFlag(e))
+            forcedCount++;
+    }
+    const issues = [];
+    const remediations = [];
+    if (forcedCount > 5) {
+        issues.push({
+            category: "layout-thrashing",
+            severity: forcedCount > 50 ? "high" : forcedCount > 20 ? "medium" : "low",
+            title: `${forcedCount} forced synchronous layouts in window`,
+            details: { forcedCount, layoutShiftCount: shiftCount },
+        });
+        remediations.push({
+            category: "layout-thrashing",
+            action: "Batch DOM reads + writes; avoid alternating offsetWidth/offsetHeight measurements with style writes.",
+        });
+    }
+    return { issues, remediations };
+}
+function hasForcedFlag(e) {
+    const args = e.args;
+    if (!args)
+        return false;
+    const data = args.data ?? args.beginData ?? {};
+    return Array.isArray(data.stackTrace) && data.stackTrace.length > 0;
+}
+/** long-tasks — `RunTask` events > 50ms. */
+export function analyseLongTasks(ctx) {
+    const tasks = [];
+    for (const e of ctx.trace) {
+        if (e.name !== "RunTask" && e.name !== "LongTask")
+            continue;
+        const dur = typeof e.dur === "number" ? e.dur / 1000 : 0;
+        if (dur >= 50)
+            tasks.push({ durationMs: dur });
+    }
+    tasks.sort((a, b) => b.durationMs - a.durationMs);
+    const issues = tasks.map((t) => ({
+        category: "long-tasks",
+        severity: t.durationMs > 200
+            ? "high"
+            : t.durationMs > 100
+                ? "medium"
+                : "low",
+        title: `Long task: ${Math.round(t.durationMs)}ms blocking main thread`,
+        details: { durationMs: t.durationMs },
+    }));
+    const remediations = tasks.length > 0
+        ? [
+            {
+                category: "long-tasks",
+                action: "Yield to the event loop with scheduler.postTask() or requestIdleCallback; move heavy work to a Web Worker.",
+            },
+        ]
+        : [];
+    return { issues, remediations };
+}
+/** leak-suspects — retainer-growth rows with deltaPercent > 10. */
+export function analyseLeakSuspects(ctx) {
+    const issues = [];
+    const remediations = [];
+    if (!ctx.memoryDiff)
+        return { issues, remediations };
+    for (const row of ctx.memoryDiff.retainerGrowth) {
+        const pct = row.deltaPercent === "+inf" ? Infinity : row.deltaPercent;
+        if (pct <= 10)
+            continue;
+        if (row.deltaBytes <= 0)
+            continue;
+        issues.push({
+            category: "leak-suspects",
+            severity: row.deltaBytes > 1_000_000 ? "high" : row.deltaBytes > 100_000 ? "medium" : "low",
+            title: `Retainer growth: ${row.node} +${Math.round(row.deltaBytes / 1024)}KB (${row.deltaPercent}%)`,
+            details: {
+                node: row.node,
+                type: row.type,
+                deltaBytes: row.deltaBytes,
+                deltaPercent: row.deltaPercent,
+            },
+        });
+        remediations.push({
+            category: "leak-suspects",
+            action: "Check listeners + cached references on this type; pair with heap_retainers({snapshotPath, query:{name}}) for the retention path.",
+            target: row.node,
+        });
+    }
+    return { issues, remediations };
+}
+/** cache-opportunities — static assets missing `Cache-Control` header. */
+export function analyseCacheOpportunities(ctx) {
+    const issues = [];
+    const remediations = [];
+    const seen = new Set();
+    for (const r of ctx.responses ?? []) {
+        if (r.status !== 200)
+            continue;
+        const ext = r.url.split("?")[0]?.split(".").pop()?.toLowerCase() ?? "";
+        const isStatic = [
+            "js",
+            "css",
+            "png",
+            "jpg",
+            "jpeg",
+            "gif",
+            "webp",
+            "avif",
+            "svg",
+            "woff",
+            "woff2",
+            "ttf",
+        ].includes(ext);
+        if (!isStatic)
+            continue;
+        if (r.cacheControl && /max-age=\d+/i.test(r.cacheControl))
+            continue;
+        if (seen.has(r.url))
+            continue;
+        seen.add(r.url);
+        issues.push({
+            category: "cache-opportunities",
+            severity: "medium",
+            title: `Missing/short Cache-Control on static asset: ${r.url}`,
+            details: { url: r.url, cacheControl: r.cacheControl ?? null },
+        });
+        remediations.push({
+            category: "cache-opportunities",
+            action: "Add Cache-Control: public, max-age=31536000, immutable on content-hashed static assets.",
+            target: r.url,
+        });
+    }
+    return { issues, remediations };
+}
+/** font-loading — fonts loaded > 200ms after document start. */
+export function analyseFontLoading(ctx) {
+    let docStartMs = 0;
+    for (const e of ctx.trace) {
+        if (e.name === "navigationStart" && typeof e.ts === "number") {
+            docStartMs = e.ts / 1000;
+            break;
+        }
+    }
+    const fontLoads = [];
+    for (const e of ctx.trace) {
+        if (e.name !== "ResourceFinish")
+            continue;
+        const args = e.args ?? {};
+        const data = (args.data ?? {});
+        const url = typeof data.url === "string" ? data.url : "";
+        const ext = url.split("?")[0]?.split(".").pop()?.toLowerCase() ?? "";
+        if (!["woff", "woff2", "ttf", "otf"].includes(ext))
+            continue;
+        const ts = typeof e.ts === "number" ? e.ts / 1000 : 0;
+        const offset = ts - docStartMs;
+        if (offset > 200)
+            fontLoads.push({ url, offsetMs: offset });
+    }
+    const issues = fontLoads.map((f) => ({
+        category: "font-loading",
+        severity: f.offsetMs > 1000 ? "high" : "medium",
+        title: `Font loaded ${Math.round(f.offsetMs)}ms after document start: ${f.url}`,
+        details: { url: f.url, offsetMs: f.offsetMs },
+    }));
+    const remediations = fontLoads.map((f) => ({
+        category: "font-loading",
+        action: "<link rel=preload as=font crossorigin> in <head>, or self-host with font-display: swap.",
+        target: f.url,
+    }));
+    return { issues, remediations };
+}

package/dist/page/perf-audit-runner.d.ts

@@ -0,0 +1,20 @@
+import type { CDPSession } from "playwright-core";
+import { type AuditCategory, type AuditReport } from "./perf-audit.js";
+export interface RunPerfAuditOptions {
+    categories?: string[];
+    durationMs?: number;
+    format?: "summary" | "full";
+}
+export interface RunPerfAuditResult {
+    report: AuditReport;
+    evidence: {
+        tracePath: string;
+        coveragePath?: string;
+        memoryPath?: string;
+    };
+    durationMs: number;
+    categoriesRun: AuditCategory[];
+}
+/** Default trace filename under `<workspace>/perf/<sessionId>-audit-<ts>.json`. */
+export declare function defaultAuditTracePath(workspaceRoot: string, sessionId: string): string;
+export declare function runPerfAudit(cdp: CDPSession, workspaceRoot: string, sessionId: string, opts?: RunPerfAuditOptions): Promise<RunPerfAuditResult>;

package/dist/page/perf-audit-runner.js

@@ -0,0 +1,195 @@
+// perf_audit runner — orchestrates trace collection + coverage capture +
+// network-response gathering for the duration of the audit window, then
+// hands the assembled context to `composeReport`.
+//
+// Kept separate from `perf-audit.ts` (analysers) so the analysers stay
+// pure-function + unit-testable, and the runner can be replaced /
+// stubbed without dragging the registry along.
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { CoverageTrackerState } from "./coverage.js";
+import { composeReport, resolveCategories, } from "./perf-audit.js";
+const DEFAULT_DURATION_MS = 5_000;
+const MAX_DURATION_MS = 30_000;
+/** Same broad category set used by the audit's standalone trace window — we
+ *  want everything render/loading/longtask-related so the analysers have
+ *  enough to look at. */
+const AUDIT_TRACE_CATEGORIES = [
+    "devtools.timeline",
+    "loading",
+    "blink.user_timing",
+    "disabled-by-default-devtools.timeline",
+    "disabled-by-default-devtools.timeline.frame",
+    "latencyInfo",
+];
+function clampDuration(d) {
+    if (typeof d !== "number" || !Number.isFinite(d) || d <= 0)
+        return DEFAULT_DURATION_MS;
+    if (d > MAX_DURATION_MS)
+        return MAX_DURATION_MS;
+    return Math.floor(d);
+}
+function resolveAuditPath(workspaceRoot, p, tool) {
+    const resolved = resolve(workspaceRoot, p);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: \`path\` must resolve inside $BROWX_WORKSPACE — got "${p}".`);
+    }
+    return resolved;
+}
+/** Default trace filename under `<workspace>/perf/<sessionId>-audit-<ts>.json`. */
+export function defaultAuditTracePath(workspaceRoot, sessionId) {
+    const safe = (sessionId || "default").replace(/[^A-Za-z0-9._-]/g, "_");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(workspaceRoot, "perf", `${safe}-audit-${ts}.json`);
+}
+function defaultCoveragePath(workspaceRoot, sessionId) {
+    const safe = (sessionId || "default").replace(/[^A-Za-z0-9._-]/g, "_");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(workspaceRoot, "perf", `${safe}-coverage-${ts}.json`);
+}
+/** Build the CDP network-response listeners, accumulating `responses[]` from
+ *  `responseReceived` (+ a best-effort `loadingFinished` size patch). Returns the
+ *  listeners + the shared accumulator. */
+function makeNetworkListeners(responses) {
+    const responseHeaders = new Map();
+    return {
+        onResponseReceived: (raw) => {
+            const e = raw;
+            const r = e?.response;
+            if (!r || typeof r.url !== "string")
+                return;
+            const headers = r.headers ?? {};
+            responseHeaders.set(e.requestId, headers);
+            responses.push({
+                url: r.url,
+                status: r.status ?? 0,
+                mimeType: r.mimeType,
+                encodedDataLength: r.encodedDataLength,
+                cacheControl: headers["cache-control"] ?? headers["Cache-Control"],
+            });
+        },
+        onLoadingFinished: (raw) => {
+            const e = raw;
+            if (typeof e.encodedDataLength !== "number" || !responseHeaders.has(e.requestId))
+                return;
+            for (let i = responses.length - 1; i >= 0; i--) {
+                if (responses[i].encodedDataLength == null || responses[i].encodedDataLength === 0) {
+                    responses[i].encodedDataLength = e.encodedDataLength;
+                    break;
+                }
+            }
+        },
+    };
+}
+/** Run the trace + coverage + network collection window, detaching all listeners
+ *  in `finally`. */
+async function collectAuditData(cdp, durationMs) {
+    const traceEvents = [];
+    let traceComplete = null;
+    const onData = (e) => {
+        if (Array.isArray(e?.value))
+            for (const ev of e.value)
+                traceEvents.push(ev);
+    };
+    const onTraceComplete = () => {
+        if (traceComplete)
+            traceComplete();
+    };
+    const responses = [];
+    const net = makeNetworkListeners(responses);
+    const coverage = new CoverageTrackerState();
+    cdp.on("Tracing.dataCollected", onData);
+    cdp.on("Tracing.tracingComplete", onTraceComplete);
+    cdp.on("Network.responseReceived", net.onResponseReceived);
+    cdp.on("Network.loadingFinished", net.onLoadingFinished);
+    const data = { traceEvents, responses };
+    try {
+        await cdp.send("Network.enable").catch(() => undefined);
+        await cdp.send("Tracing.start", {
+            transferMode: "ReportEvents",
+            traceConfig: { recordMode: "recordContinuously", includedCategories: AUDIT_TRACE_CATEGORIES },
+        });
+        await coverage.start(cdp).catch(() => undefined);
+        await new Promise((res) => setTimeout(res, durationMs));
+        const traceCompletePromise = new Promise((res) => {
+            traceComplete = res;
+        });
+        await cdp.send("Tracing.end").catch(() => undefined);
+        await Promise.race([traceCompletePromise, new Promise((res) => setTimeout(res, 30_000))]);
+        const covResult = await coverage.stop(cdp).catch(() => undefined);
+        if (covResult && !covResult.notRunning) {
+            data.jsCoverage = covResult.jsCoverage;
+            data.cssCoverage = covResult.cssCoverage;
+        }
+    }
+    finally {
+        for (const [event, h] of [
+            ["Tracing.dataCollected", onData],
+            ["Tracing.tracingComplete", onTraceComplete],
+            ["Network.responseReceived", net.onResponseReceived],
+            ["Network.loadingFinished", net.onLoadingFinished],
+        ]) {
+            try {
+                cdp.off(event, h);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    return data;
+}
+/** Write the trace + coverage evidence files (workspace-rooted) and return their
+ *  resolved paths. */
+function writeAuditEvidence(workspaceRoot, sessionId, durationMs, data) {
+    const resolvedTrace = resolveAuditPath(workspaceRoot, defaultAuditTracePath(workspaceRoot, sessionId), "perf_audit");
+    const traceParent = dirname(resolvedTrace);
+    if (traceParent && !existsSync(traceParent))
+        mkdirSync(traceParent, { recursive: true });
+    // ws.root-rooted path — resolveAuditPath guards the escape.
+    writeFileSync(resolvedTrace, JSON.stringify({
+        traceEvents: data.traceEvents,
+        metadata: {
+            source: "browxai",
+            sessionId,
+            categories: AUDIT_TRACE_CATEGORIES,
+            durationMs,
+            eventCount: data.traceEvents.length,
+            capturedAt: new Date().toISOString(),
+            kind: "perf-audit",
+        },
+    }), "utf8");
+    if (!data.jsCoverage || !data.cssCoverage)
+        return { tracePath: resolvedTrace };
+    const resolvedCov = resolveAuditPath(workspaceRoot, defaultCoveragePath(workspaceRoot, sessionId), "perf_audit");
+    writeFileSync(resolvedCov, JSON.stringify({
+        jsCoverage: data.jsCoverage,
+        cssCoverage: data.cssCoverage,
+        durationMs,
+        capturedAt: new Date().toISOString(),
+    }), "utf8");
+    return { tracePath: resolvedTrace, coveragePath: resolvedCov };
+}
+export async function runPerfAudit(cdp, workspaceRoot, sessionId, opts = {}) {
+    const durationMs = clampDuration(opts.durationMs);
+    const format = opts.format === "full" ? "full" : "summary";
+    const categoriesRun = resolveCategories(opts.categories);
+    const data = await collectAuditData(cdp, durationMs);
+    const evidencePaths = writeAuditEvidence(workspaceRoot, sessionId, durationMs, data);
+    const ctx = {
+        trace: data.traceEvents,
+        jsCoverage: data.jsCoverage,
+        cssCoverage: data.cssCoverage,
+        responses: data.responses,
+    };
+    const report = composeReport(ctx, categoriesRun, format);
+    return {
+        report,
+        evidence: {
+            tracePath: evidencePaths.tracePath,
+            ...(evidencePaths.coveragePath ? { coveragePath: evidencePaths.coveragePath } : {}),
+        },
+        durationMs,
+        categoriesRun,
+    };
+}

package/dist/page/perf-audit-types.d.ts

@@ -0,0 +1,41 @@
+import type { TraceEvent } from "./perf.js";
+import type { JsCoverageEntry, CssCoverageEntry } from "./coverage.js";
+import type { MemoryDiffResult } from "./memory-diff.js";
+import type { AuditCategory } from "./perf-audit-analysers.js";
+export type { AuditCategory } from "./perf-audit-analysers.js";
+export type IssueSeverity = "high" | "medium" | "low";
+export interface AuditIssue {
+    category: AuditCategory;
+    severity: IssueSeverity;
+    title: string;
+    /** Free-form additional context, structured per category. */
+    details?: Record<string, unknown>;
+}
+export interface AuditRemediation {
+    category: AuditCategory;
+    /** Imperative one-liner: "Defer non-critical CSS in <head>". */
+    action: string;
+    /** Optional URL pointing at the offending resource the remediation applies
+     *  to (when the analyser identified a specific target). */
+    target?: string;
+}
+export interface CategoryResult {
+    issues: AuditIssue[];
+    remediations: AuditRemediation[];
+}
+export interface AuditContext {
+    trace: TraceEvent[];
+    jsCoverage?: JsCoverageEntry[];
+    cssCoverage?: CssCoverageEntry[];
+    memoryDiff?: MemoryDiffResult;
+    /** Network response metadata, when available, for cache-opportunities
+     *  + oversize-images + font-loading categories. */
+    responses?: Array<{
+        url: string;
+        status: number;
+        mimeType?: string;
+        encodedDataLength?: number;
+        cacheControl?: string;
+    }>;
+}
+export type AuditCategoryAnalyser = (ctx: AuditContext) => CategoryResult;

package/dist/page/perf-audit-types.js

@@ -0,0 +1,5 @@
+// perf_audit type vocabulary — the audit category union, issue/remediation/
+// result shapes, and the analyser context. Split out of perf-audit.ts so the
+// analysers and the report composer share one type home without either file
+// exceeding the size budget. Re-exported through `./perf-audit.js`.
+export {};

package/dist/page/perf-audit.d.ts

@@ -0,0 +1,37 @@
+import { type IssueSeverity, type AuditContext, type CategoryResult } from "./perf-audit-types.js";
+import { type AuditCategory } from "./perf-audit-analysers.js";
+export type { IssueSeverity, AuditIssue, AuditRemediation, CategoryResult, AuditContext, AuditCategoryAnalyser, } from "./perf-audit-types.js";
+export { ANALYSERS, ALL_AUDIT_CATEGORIES, type AuditCategory, analyseRenderBlocking, analyseUnusedCode, analyseOversizeImages, analyseLayoutThrashing, analyseLongTasks, analyseLeakSuspects, analyseCacheOpportunities, analyseFontLoading, } from "./perf-audit-analysers.js";
+export interface AuditReport {
+    summary: {
+        score: number;
+        topIssues: Array<{
+            category: AuditCategory;
+            severity: IssueSeverity;
+            title: string;
+        }>;
+    };
+    byCategory: Record<string, CategoryResult>;
+    warnings: string[];
+}
+export declare const SUMMARY_TOKEN_BUDGET = 2000;
+export declare const SUMMARY_BUDGET_CEILING_FACTOR = 2.5;
+export declare const SUMMARY_TOKEN_HARD_CEILING: number;
+/** Compose an audit report from already-collected context. The category set
+ *  is the categories the caller asked for (default = all). `format`
+ *  controls whether each category's `issues`/`remediations` are capped at
+ *  3 (summary mode) or unbounded (full mode). The summary itself (the
+ *  short `summary.topIssues` list + score) always exists; in summary mode
+ *  the per-category bodies are also capped.
+ *
+ *  Token-budget enforcement: when `format:"summary"`, the function checks
+ *  estimated token count and drops lowest-severity issues + remediations
+ *  until under 2000. If even after total trimming the body exceeds the
+ *  cap, a `warnings[]` entry surfaces it. */
+export declare function composeReport(ctx: AuditContext, categories: AuditCategory[], format: "summary" | "full"): AuditReport;
+/** Drop lowest-severity issues across all categories until estimated tokens
+ *  are within the summary budget. Adds a warnings[] entry if the cap binds. */
+export declare function enforceSummaryBudget(report: AuditReport): AuditReport;
+/** Resolve the requested category set — empty/undefined → all. Unknown
+ *  category names are dropped silently. */
+export declare function resolveCategories(requested?: string[]): AuditCategory[];