audit0 0.1.0

package/dist/engine/page-diagnostics.mjs

@@ -0,0 +1,997 @@
+import { randomUUID } from "node:crypto";
+const LIMITS = {
+    requests: 2000,
+    resources: 2000,
+    priorities: 32,
+    paints: 16,
+    longTasks: 500,
+    images: 100,
+    imagePreloads: 100,
+    imageElements: 5000,
+    elements: 5000,
+    fonts: 200,
+    fontCssRules: 10000,
+    fontStyleSheets: 200,
+    fontEvents: 200,
+    scripts: 200,
+};
+const MAX_URL_LENGTH = 16384;
+const CACHE_HEADERS = new Set(["cache-control", "age", "x-vercel-cache", "x-matched-path"]);
+export function sanitizeUrl(raw) {
+    if (typeof raw !== "string" || !raw || raw.length > MAX_URL_LENGTH)
+        return "[invalid-url]";
+    try {
+        const relative = !/^[a-z][a-z\d+.-]*:/i.test(raw) && !raw.startsWith("//");
+        const url = new URL(raw, "https://diagnostics.invalid");
+        if (!["http:", "https:"].includes(url.protocol))
+            return `${url.protocol}[redacted]`;
+        url.username = "";
+        url.password = "";
+        url.hash = "";
+        const imageParams = [...url.searchParams].filter(([key, content]) => ["w", "q"].includes(key) && /^\d{1,5}$/.test(content));
+        url.search = "";
+        for (const [key, content] of imageParams)
+            url.searchParams.append(key, content);
+        return relative ? `${url.pathname}${url.search}` : url.href;
+    }
+    catch {
+        return "[invalid-url]";
+    }
+}
+export function responseTiming(timing) {
+    if (!timing)
+        return { ttfbMs: null, source: "unavailable" };
+    const headers = timing.receiveHeadersStart >= 0 ? timing.receiveHeadersStart : timing.receiveHeadersEnd;
+    if (headers >= 0 && timing.sendEnd >= 0 && headers >= timing.sendEnd) {
+        return {
+            ttfbMs: headers - timing.sendEnd,
+            source: timing.receiveHeadersStart >= 0
+                ? "cdp.receiveHeadersStart-sendEnd"
+                : "cdp.receiveHeadersEnd-sendEnd",
+        };
+    }
+    return { ttfbMs: null, source: "unavailable" };
+}
+export function classifyResourceTiming(entry, documentUrl, cdpType) {
+    let crossOrigin = false;
+    try {
+        crossOrigin = new URL(entry.name).origin !== new URL(documentUrl).origin;
+    }
+    catch {
+        return { timingAvailability: "unavailable", ttfbMs: null, renderBlockingScript: false };
+    }
+    const detailedTiming = Number.isFinite(entry.requestStart) && Number.isFinite(entry.responseStart);
+    const hiddenTiming = entry.requestStart === 0 && entry.responseStart === 0;
+    const timingAvailability = !detailedTiming || hiddenTiming
+        ? crossOrigin
+            ? "unavailable-cross-origin"
+            : "unavailable"
+        : "available";
+    return {
+        timingAvailability,
+        ttfbMs: timingAvailability === "available" && entry.responseStart >= entry.requestStart
+            ? entry.responseStart - entry.requestStart
+            : null,
+        renderBlockingScript: entry.renderBlockingStatus === "blocking" &&
+            (entry.initiatorType === "script" || cdpType === "Script"),
+    };
+}
+export function classifyFontFace(face) {
+    return {
+        ...face,
+        sourceType: face.sourceType ?? "unknown",
+        potentialInvisibleTextRisk: face.sourceType !== "local-only" && ["auto", "block"].includes(face.display),
+        blockingProven: false,
+    };
+}
+function installObservers(key, limits, maxUrlLength) {
+    if (window !== window.top || window[key])
+        return;
+    const state = {
+        timeOrigin: performance.timeOrigin,
+        documentUrl: location.href.slice(0, maxUrlLength),
+        paints: [],
+        lcp: null,
+        resources: [],
+        longTasks: [],
+        fontEvents: [],
+        fontsAtFcp: [],
+        fontSetStatusAtFcp: null,
+        fontsAtFcpObservedMs: null,
+        early: null,
+        domContentLoadedMs: null,
+        loadMs: null,
+        unsupported: [],
+        truncated: {},
+    };
+    const observers = [];
+    let raf = null;
+    let stopped = false;
+    const boundedUrl = (raw) => (raw && raw.length <= maxUrlLength ? raw : "");
+    const append = (list, entry, cap, name) => {
+        if (list.length < cap)
+            list.push(entry);
+        else
+            state.truncated[name] = true;
+    };
+    const fontFaces = (selectedFaces = document.fonts) => {
+        const sources = new Map();
+        const faceCounts = new Map();
+        const pending = [];
+        const seenSheets = new Set();
+        let complete = true;
+        let ruleCount = 0;
+        const signature = (family, style, weight) => JSON.stringify([
+            family
+                .trim()
+                .replace(/^(["'])(.*)\1$/, "$2")
+                .toLowerCase(),
+            (style || "normal").trim().toLowerCase(),
+            weight === "bold" ? "700" : !weight || weight === "normal" ? "400" : weight.trim(),
+        ]);
+        const inspectSheet = (sheet) => {
+            if (!sheet || sheet.disabled || seenSheets.has(sheet))
+                return;
+            if (sheet.media.mediaText && !matchMedia(sheet.media.mediaText).matches)
+                return;
+            if (seenSheets.size >= limits.fontStyleSheets) {
+                state.truncated.fontStyleSheets = true;
+                complete = false;
+                return;
+            }
+            seenSheets.add(sheet);
+            try {
+                if (sheet.href && new URL(sheet.href).origin !== location.origin) {
+                    complete = false;
+                    return;
+                }
+                pending.push(sheet.cssRules[Symbol.iterator]());
+            }
+            catch {
+                complete = false;
+            }
+        };
+        for (const sheet of document.styleSheets)
+            inspectSheet(sheet);
+        for (const sheet of document.adoptedStyleSheets)
+            inspectSheet(sheet);
+        while (pending.length && ruleCount < limits.fontCssRules) {
+            const next = pending.at(-1).next();
+            if (next.done) {
+                pending.pop();
+                continue;
+            }
+            ruleCount++;
+            const rule = next.value;
+            if (rule.type === CSSRule.FONT_FACE_RULE) {
+                const src = rule.style.getPropertyValue("src");
+                const functions = src.length <= maxUrlLength
+                    ? src.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '""').match(/\b[a-z-]+\s*\(/gi) ||
+                        []
+                    : [];
+                const local = functions.some((token) => /^local\s*\($/i.test(token));
+                const network = functions.some((token) => /^url\s*\($/i.test(token));
+                let sourceType = "unknown";
+                if (functions.every((token) => /^(local|url|format|tech)\s*\($/i.test(token))) {
+                    if (local && network)
+                        sourceType = "mixed";
+                    else if (local)
+                        sourceType = "local-only";
+                    else if (network)
+                        sourceType = "network";
+                }
+                const key = signature(rule.style.getPropertyValue("font-family"), rule.style.getPropertyValue("font-style"), rule.style.getPropertyValue("font-weight"));
+                if (!sources.has(key))
+                    sources.set(key, []);
+                sources.get(key).push(sourceType);
+            }
+            else if (rule.type === CSSRule.IMPORT_RULE)
+                inspectSheet(rule.styleSheet);
+            else if (rule.cssRules) {
+                if (rule.type === CSSRule.MEDIA_RULE && !matchMedia(rule.conditionText).matches)
+                    continue;
+                if (rule.type === CSSRule.SUPPORTS_RULE && !CSS.supports(rule.conditionText))
+                    continue;
+                pending.push(rule.cssRules[Symbol.iterator]());
+            }
+        }
+        if (pending.length) {
+            state.truncated.fontCssRules = true;
+            complete = false;
+        }
+        let countedFaces = 0;
+        for (const face of document.fonts) {
+            if (countedFaces++ === limits.fonts) {
+                complete = false;
+                break;
+            }
+            const key = signature(face.family, face.style, face.weight);
+            faceCounts.set(key, (faceCounts.get(key) || 0) + 1);
+        }
+        const faces = [];
+        for (const face of selectedFaces) {
+            if (faces.length === limits.fonts) {
+                state.truncated.fonts = true;
+                break;
+            }
+            const key = signature(face.family, face.style, face.weight);
+            const candidates = sources.get(key) || [];
+            const sourceType = complete &&
+                candidates.length > 0 &&
+                candidates.length === faceCounts.get(key) &&
+                candidates.every((type) => type === candidates[0])
+                ? candidates[0]
+                : "unknown";
+            faces.push({
+                family: face.family.slice(0, 500),
+                display: face.display,
+                status: face.status,
+                style: face.style,
+                weight: face.weight,
+                sourceType,
+            });
+        }
+        return faces;
+    };
+    const snapshot = () => {
+        const images = [];
+        const backgrounds = [];
+        const preloads = [];
+        const scripts = [];
+        const inlineRenderBlockers = [];
+        const geometryFor = (element) => {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return null;
+            let visible;
+            if (typeof element.checkVisibility === "function") {
+                visible = element.checkVisibility({
+                    opacityProperty: true,
+                    visibilityProperty: true,
+                    contentVisibilityAuto: true,
+                });
+            }
+            else {
+                const style = getComputedStyle(element);
+                visible =
+                    style.visibility !== "hidden" &&
+                        style.visibility !== "collapse" &&
+                        style.display !== "none" &&
+                        Number(style.opacity) !== 0;
+            }
+            const intersectionWidth = Math.max(0, Math.min(rect.right, innerWidth) - Math.max(rect.left, 0));
+            const intersectionHeight = Math.max(0, Math.min(rect.bottom, innerHeight) - Math.max(rect.top, 0));
+            return {
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+                intersectionArea: intersectionWidth * intersectionHeight,
+                intersectsViewport: intersectionWidth > 0 && intersectionHeight > 0,
+                visible,
+            };
+        };
+        const imageCount = document.images.length;
+        const imagesScanned = Math.min(imageCount, limits.imageElements);
+        for (let i = 0; i < imagesScanned; i++) {
+            const image = document.images[i];
+            const geometry = geometryFor(image);
+            if (!geometry?.visible)
+                continue;
+            images.push({
+                url: boundedUrl(image.currentSrc || image.src),
+                alt: image.alt.slice(0, 200),
+                ...geometry,
+                naturalWidth: image.naturalWidth,
+                naturalHeight: image.naturalHeight,
+                complete: image.complete,
+                loading: image.loading,
+                fetchPriority: image.fetchPriority || image.getAttribute("fetchpriority") || "auto",
+            });
+        }
+        if (imageCount > imagesScanned)
+            state.truncated.imageElements = true;
+        const walker = document.createTreeWalker(document.documentElement, NodeFilter.SHOW_ELEMENT);
+        let element = walker.currentNode;
+        let scanned = 0;
+        while (element && scanned < limits.elements) {
+            scanned++;
+            if (element.tagName === "LINK" &&
+                element.relList.contains("preload") &&
+                element.as === "image") {
+                const responsive = Boolean(element.getAttribute("imagesrcset")?.trim());
+                append(preloads, {
+                    href: element.hasAttribute("href") ? boundedUrl(element.href) : null,
+                    responsive,
+                    hasImageSizes: Boolean(element.getAttribute("imagesizes")?.trim()),
+                    status: responsive ? "responsive-unverified" : "declaration-only",
+                }, limits.imagePreloads, "imagePreloads");
+            }
+            if (element.tagName === "SCRIPT") {
+                const script = {
+                    url: boundedUrl(element.src),
+                    async: element.async,
+                    defer: element.defer,
+                    type: element.type,
+                    fetchPriority: element.fetchPriority || element.getAttribute("fetchpriority") || "auto",
+                    blocking: element.getAttribute("blocking"),
+                };
+                if (element.hasAttribute("src")) {
+                    append(scripts, script, limits.scripts, "scripts");
+                }
+                else if (element.getAttribute("blocking")?.split(/\s+/).includes("render")) {
+                    append(inlineRenderBlockers, {
+                        type: element.type,
+                        blocking: "render",
+                        observedDeclarationOnly: true,
+                    }, limits.scripts, "inlineRenderBlockers");
+                }
+            }
+            const geometry = geometryFor(element);
+            if (geometry?.visible && geometry.intersectsViewport) {
+                const backgroundImage = getComputedStyle(element).backgroundImage;
+                if (backgroundImage !== "none") {
+                    for (const match of backgroundImage.matchAll(/url\((?:"([^"]*)"|'([^']*)'|([^)]*))\)/g)) {
+                        if (backgrounds.length >= limits.images) {
+                            state.truncated.backgrounds = true;
+                            break;
+                        }
+                        backgrounds.push({ url: boundedUrl(match[1] ?? match[2] ?? match[3]), ...geometry });
+                    }
+                }
+            }
+            element = walker.nextNode();
+        }
+        if (element)
+            state.truncated.elements = true;
+        images.sort((a, b) => Number(b.visible && b.intersectsViewport) - Number(a.visible && a.intersectsViewport) ||
+            b.intersectionArea - a.intersectionArea ||
+            b.width * b.height - a.width * a.height);
+        if (images.length > limits.images)
+            state.truncated.images = true;
+        return {
+            observedMs: performance.now(),
+            viewport: { width: innerWidth, height: innerHeight, scrollX, scrollY },
+            imageScan: {
+                total: imageCount,
+                scanned: imagesScanned,
+                truncated: imageCount > imagesScanned,
+            },
+            visibilityMethod: typeof Element.prototype.checkVisibility === "function"
+                ? "checkVisibility"
+                : "computed-style-fallback",
+            images: images.slice(0, limits.images),
+            backgrounds,
+            preloads,
+            scripts,
+            inlineRenderBlockers,
+        };
+    };
+    const consume = (type, entries) => {
+        for (const entry of entries) {
+            if (type === "paint") {
+                append(state.paints, { name: entry.name, startTime: entry.startTime }, limits.paints, "paints");
+                if (entry.name === "first-contentful-paint" && state.fontsAtFcpObservedMs === null) {
+                    state.fontsAtFcp = fontFaces();
+                    state.fontSetStatusAtFcp = document.fonts.status;
+                    state.fontsAtFcpObservedMs = performance.now();
+                    raf = requestAnimationFrame(() => {
+                        state.early = snapshot();
+                        raf = null;
+                    });
+                }
+            }
+            else if (type === "largest-contentful-paint") {
+                state.lcp = {
+                    startTime: entry.startTime,
+                    renderTime: entry.renderTime,
+                    loadTime: entry.loadTime,
+                    size: entry.size,
+                    url: boundedUrl(entry.url),
+                    tagName: entry.element?.tagName ?? null,
+                };
+            }
+            else if (type === "resource") {
+                append(state.resources, {
+                    name: boundedUrl(entry.name),
+                    initiatorType: entry.initiatorType,
+                    startTime: entry.startTime,
+                    duration: entry.duration,
+                    fetchStart: entry.fetchStart,
+                    requestStart: entry.requestStart,
+                    responseStart: entry.responseStart,
+                    responseEnd: entry.responseEnd,
+                    transferSize: entry.transferSize,
+                    encodedBodySize: entry.encodedBodySize,
+                    decodedBodySize: entry.decodedBodySize,
+                    renderBlockingStatus: entry.renderBlockingStatus ?? null,
+                }, limits.resources, "resources");
+            }
+            else if (type === "longtask") {
+                append(state.longTasks, {
+                    startTime: entry.startTime,
+                    duration: entry.duration,
+                    name: entry.name,
+                }, limits.longTasks, "longTasks");
+            }
+        }
+    };
+    for (const type of ["paint", "largest-contentful-paint", "resource", "longtask"]) {
+        if (!PerformanceObserver.supportedEntryTypes.includes(type)) {
+            state.unsupported.push(type);
+            continue;
+        }
+        const observer = new PerformanceObserver((list) => consume(type, list.getEntries()));
+        observer.observe({ type, buffered: true });
+        observers.push({ type, observer });
+    }
+    const fontEvent = (event) => append(state.fontEvents, {
+        type: event.type,
+        observedMs: performance.now(),
+        status: document.fonts.status,
+        faces: state.fontEvents.length < limits.fontEvents ? fontFaces(event.fontfaces || []) : [],
+    }, limits.fontEvents, "fontEvents");
+    for (const type of ["loading", "loadingdone", "loadingerror"])
+        document.fonts.addEventListener(type, fontEvent);
+    const domReady = () => {
+        state.domContentLoadedMs = performance.now();
+    };
+    const loaded = () => {
+        state.loadMs = performance.now();
+    };
+    document.addEventListener("DOMContentLoaded", domReady, { once: true });
+    window.addEventListener("load", loaded, { once: true });
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        for (const { type, observer } of observers) {
+            consume(type, observer.takeRecords());
+            observer.disconnect();
+        }
+        if (raf !== null)
+            cancelAnimationFrame(raf);
+        for (const type of ["loading", "loadingdone", "loadingerror"])
+            document.fonts.removeEventListener(type, fontEvent);
+        document.removeEventListener("DOMContentLoaded", domReady);
+        window.removeEventListener("load", loaded);
+    };
+    window[key] = {
+        finish() {
+            stop();
+            const navigation = performance.getEntriesByType("navigation")[0];
+            return {
+                ...state,
+                finalUrl: boundedUrl(location.href),
+                finishedMs: performance.now(),
+                final: snapshot(),
+                faces: fontFaces(),
+                fontSetStatus: document.fonts.status,
+                navigation: navigation
+                    ? {
+                        name: boundedUrl(navigation.name),
+                        type: navigation.type,
+                        startTime: navigation.startTime,
+                        requestStart: navigation.requestStart,
+                        responseStart: navigation.responseStart,
+                        responseEnd: navigation.responseEnd,
+                        domContentLoadedEventEnd: navigation.domContentLoadedEventEnd,
+                        loadEventEnd: navigation.loadEventEnd,
+                        transferSize: navigation.transferSize,
+                    }
+                    : null,
+            };
+        },
+        dispose() {
+            stop();
+            delete window[key];
+        },
+    };
+}
+export async function startPageDiagnostics(page) {
+    const key = `__pageDiagnostics_${randomUUID().replaceAll("-", "")}`;
+    const session = await page.context().newCDPSession(page);
+    const requests = [];
+    const active = new Map();
+    const listeners = [];
+    const notes = new Set([
+        "Chromium CDP network events cover this target; out-of-process frames and worker requests may be absent. Browser observations cover the top document only.",
+        "Query parameters are removed except numeric w/q; credentials, fragments and non-HTTP URL payloads are removed. URL paths and allowlisted cache headers may still contain application identifiers.",
+        "FCP font status is sampled in the observer callback; early image geometry is sampled in its next animation frame, not at the exact paint instant.",
+        "Image snapshots are DOM geometry, not screenshots. Visibility does not prove lack of occlusion or account for every ancestor effect. CSS backgrounds exclude pseudo-elements.",
+        `Images scan document.images independently (up to ${LIMITS.imageElements}), prioritizing visible viewport images before the ${LIMITS.images}-record cap. CSS backgrounds and script declarations still scan only the first ${LIMITS.elements} DOM elements and can miss later elements.`,
+        "DOM geometry/style scans add measurement overhead. Script hints and inline declarations reflect elements still present at the early/final snapshots.",
+        "Matching uses unredacted URLs internally, with nearest request start for Resource Timing and latest request before image snapshots. Repeated identical URLs can be ambiguous. Early image final priorities/status reflect the finish cutoff, not FCP.",
+        "Image sourceUrl unwraps one url query parameter via URLSearchParams and sanitizes it, without recursive decoding. A not-observed network or priority status means unknown, not proof of no request or low priority.",
+        "Image requestStartMs is relative to document timeOrigin: CDP response timing requestTime+sendStart, then matched detailed Resource Timing requestStart, then CDP requestWillBeSent as a discovery-time fallback. requestStartAfterTtfbMs subtracts navigation.responseStart and may be negative; missing timing is null.",
+        "Image fetchStartMs measures fetch discovery/initiation relative to document timeOrigin using CDP requestWillBeSent, or matched Resource Timing startTime as a fallback. Unlike detailed requestStartMs (HTTP send), it does not wait for queueing, DNS or TLS to complete. fetchStartAfterTtfbMs subtracts document navigation.responseStart; negative values are preserved and unavailable timing is null.",
+        "Image requestOrder is a 1-based chronological ordinal of observed main-frame subresource requestWillBeSent timestamps for this document, excluding Document and including redirect hops and pending requests. It is not a priority rank; collection caps can omit requests.",
+        "Image initiatorType prefers CDP initiator.type, falling back to matched Resource Timing initiatorType. isLcpCandidate matches the raw URL to the last observed LCP URL, not a finalized LCP or element identity.",
+        "Preload evidence reports only CDP request.isLinkPreload, CDP initiator.type=preload, matched Image Resource Timing initiatorType=link, or exact raw DOM preload href matches without imagesrcset. High priority is never preload evidence; DOM matches are declarations, not proof of use.",
+        "Preload evidence may be missing or unsupported; absence is not proof of no preload. HTTP Link headers and early-hints declarations are not collected. DOM preloads use bounded early/final element scans and can miss removed links. Responsive declarations are unverified and excluded from DOM matched evidence; only imagesrcset/imagesizes presence is exposed, not their contents.",
+        "Font auto/block indicates potential invisible text risk only; no font display mode or font request duration proves text blocked rendering.",
+        "Font sourceType matches normalized family/style/weight against accessible same-origin CSS rules. Inaccessible/truncated CSS, unmatched/programmatic faces or ambiguous matches remain unknown; unknown does not rule out network use. Network/mixed describe declared URL sources, not confirmed downloads. Only proven local-only faces suppress the display-mode risk.",
+        "Render-blocking scripts require Resource Timing renderBlockingStatus=blocking plus script evidence. Inline blocking=render declarations are reported separately, not proven blockers.",
+        "Missing detailed cross-origin Resource Timing can reflect Timing-Allow-Origin restrictions. Zero byte sizes alone do not prove a cache hit.",
+        "finish() takes a bounded snapshot without waiting for network idle, fonts, LCP finalization or live streams. Call before navigation to preserve a baseline; full navigations replace browser observations.",
+    ]);
+    let scriptIdentifier;
+    let mainFrameId;
+    let disposed = false;
+    let finishPromise;
+    let disposePromise;
+    const listen = (name, callback) => {
+        session.on(name, callback);
+        listeners.push([name, callback]);
+    };
+    const eventEpoch = (request, timestamp) => request.startEpochMs + (timestamp - request.timestamp) * 1000;
+    const applyResponse = (request, response, observedEpochMs) => {
+        request.responseObservedEpochMs = observedEpochMs;
+        request.statusCode = response.status;
+        request.cache = {
+            fromDiskCache: response.fromDiskCache ?? false,
+            fromPrefetchCache: response.fromPrefetchCache ?? false,
+            fromServiceWorker: response.fromServiceWorker ?? false,
+            headers: {},
+        };
+        for (const [name, content] of Object.entries(response.headers || {})) {
+            if (CACHE_HEADERS.has(name.toLowerCase())) {
+                request.cache.headers[name.toLowerCase()] = String(content).slice(0, 2048);
+            }
+        }
+        const timing = responseTiming(response.timing);
+        request.ttfbMs = timing.ttfbMs;
+        request.ttfbSource = timing.source;
+        if (response.timing?.sendStart >= 0 && Number.isFinite(response.timing.requestTime)) {
+            request.requestStartEpochMs = eventEpoch(request, response.timing.requestTime + response.timing.sendStart / 1000);
+        }
+        const headersStart = response.timing?.receiveHeadersStart;
+        if (headersStart >= 0 && Number.isFinite(response.timing.requestTime)) {
+            request.firstByteEpochMs = eventEpoch(request, response.timing.requestTime + headersStart / 1000);
+        }
+    };
+    listen("Network.requestWillBeSent", (event) => {
+        if (disposed)
+            return;
+        const previous = active.get(event.requestId);
+        if (previous && event.redirectResponse) {
+            applyResponse(previous, event.redirectResponse, eventEpoch(previous, event.timestamp));
+            previous.status = "redirected";
+            previous.endEpochMs = eventEpoch(previous, event.timestamp);
+        }
+        active.delete(event.requestId);
+        if (requests.length >= LIMITS.requests) {
+            notes.add(`CDP request collection capped at ${LIMITS.requests}; subsequent requests omitted.`);
+            return;
+        }
+        const priority = event.request.initialPriority ?? null;
+        const request = {
+            id: `${event.requestId}:${requests.length}`,
+            rawUrl: event.request.url.length <= MAX_URL_LENGTH ? event.request.url : "",
+            frameId: event.frameId,
+            loaderId: event.loaderId,
+            timestamp: event.timestamp,
+            startEpochMs: event.wallTime * 1000,
+            resourceType: event.type ?? "Other",
+            initiatorType: event.initiator?.type ?? null,
+            isLinkPreload: event.request.isLinkPreload === true,
+            initialPriority: priority,
+            finalPriority: priority,
+            priorityTimeline: priority
+                ? [{ priority, epochMs: event.wallTime * 1000, source: "initial" }]
+                : [],
+            status: "pending",
+            ttfbMs: null,
+            ttfbSource: "unavailable",
+        };
+        requests.push(request);
+        active.set(event.requestId, request);
+    });
+    listen("Network.resourceChangedPriority", (event) => {
+        const request = active.get(event.requestId);
+        if (!request || disposed)
+            return;
+        request.finalPriority = event.newPriority;
+        if (request.priorityTimeline.length < LIMITS.priorities) {
+            request.priorityTimeline.push({
+                priority: event.newPriority,
+                epochMs: eventEpoch(request, event.timestamp),
+                source: "changed",
+            });
+        }
+        else {
+            request.priorityTimelineTruncated = true;
+            notes.add(`Priority timelines capped at ${LIMITS.priorities}; finalPriority still tracks the last event.`);
+        }
+    });
+    listen("Network.responseReceived", (event) => {
+        const request = active.get(event.requestId);
+        if (!request || disposed)
+            return;
+        request.resourceType = event.type ?? request.resourceType;
+        applyResponse(request, event.response, eventEpoch(request, event.timestamp));
+    });
+    for (const eventName of ["loadingFinished", "loadingFailed"]) {
+        listen(`Network.${eventName}`, (event) => {
+            const request = active.get(event.requestId);
+            if (!request || disposed)
+                return;
+            request.endEpochMs = eventEpoch(request, event.timestamp);
+            request.status = eventName === "loadingFinished" ? "finished" : "failed";
+            if (eventName === "loadingFinished")
+                request.encodedDataLength = event.encodedDataLength;
+            else {
+                request.canceled = event.canceled ?? false;
+                request.blockedReason = event.blockedReason ?? null;
+            }
+            active.delete(event.requestId);
+        });
+    }
+    async function dispose() {
+        if (disposePromise)
+            return disposePromise;
+        disposed = true;
+        disposePromise = (async () => {
+            for (const [name, callback] of listeners)
+                session.off(name, callback);
+            const cleanup = await Promise.allSettled([
+                page.evaluate((key) => window[key]?.dispose(), key),
+                scriptIdentifier
+                    ? session.send("Page.removeScriptToEvaluateOnNewDocument", {
+                        identifier: scriptIdentifier,
+                    })
+                    : Promise.resolve(),
+            ]);
+            if (cleanup.some((operation) => operation.status === "rejected")) {
+                notes.add("Some browser cleanup was unavailable, usually because the page closed or navigated.");
+            }
+            try {
+                await session.detach();
+            }
+            catch {
+                notes.add("CDP detach was unavailable; the target may already be closed.");
+            }
+            active.clear();
+            requests.length = 0;
+        })();
+        return disposePromise;
+    }
+    try {
+        await session.send("Page.enable");
+        const { frameTree } = await session.send("Page.getFrameTree");
+        mainFrameId = frameTree.frame.id;
+        await session.send("Network.enable", { maxPostDataSize: 0 });
+        const source = `(${installObservers.toString()})(${JSON.stringify(key)}, ${JSON.stringify(LIMITS)}, ${MAX_URL_LENGTH})`;
+        const installed = await session.send("Page.addScriptToEvaluateOnNewDocument", { source });
+        scriptIdentifier = installed.identifier;
+        await page.evaluate(source);
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+    async function collect() {
+        let browser = null;
+        try {
+            browser = await page.evaluate((key) => window[key]?.finish() ?? null, key);
+        }
+        catch {
+            notes.add("Browser snapshot unavailable: the page closed or its execution context changed during finish().");
+        }
+        if (!browser)
+            notes.add("No browser observations available; navigation and paint measurements may be unavailable.");
+        const origin = browser?.timeOrigin ?? requests[0]?.startEpochMs ?? null;
+        const relative = (epoch) => (Number.isFinite(epoch) && origin !== null ? epoch - origin : null);
+        const matchingUrl = (raw) => {
+            try {
+                const url = new URL(raw);
+                url.hash = "";
+                return url.href;
+            }
+            catch {
+                return null;
+            }
+        };
+        const index = new Map();
+        for (const request of requests) {
+            const url = matchingUrl(request.rawUrl);
+            if (!url)
+                continue;
+            if (!index.has(url))
+                index.set(url, []);
+            index.get(url).push(request);
+        }
+        const match = (raw, atMs, type, completedResource = false) => {
+            const candidates = (index.get(matchingUrl(raw)) || []).filter((request) => (!type || request.resourceType === type) &&
+                (!request.frameId || request.frameId === mainFrameId) &&
+                (!browser || request.startEpochMs >= browser.timeOrigin - 100) &&
+                (completedResource || atMs === undefined || relative(request.startEpochMs) <= atMs + 2));
+            if (!candidates.length)
+                return null;
+            if (completedResource) {
+                return candidates.reduce((closest, request) => Math.abs(relative(request.startEpochMs) - atMs) <
+                    Math.abs(relative(closest.startEpochMs) - atMs)
+                    ? request
+                    : closest);
+            }
+            return candidates.at(-1);
+        };
+        const serialize = (request) => ({
+            id: request.id,
+            url: sanitizeUrl(request.rawUrl),
+            resourceType: request.resourceType,
+            isMainDocument: request.resourceType === "Document" && request.frameId === mainFrameId,
+            status: request.status,
+            startEpochMs: request.startEpochMs,
+            startMs: relative(request.startEpochMs),
+            responseObservedMs: relative(request.responseObservedEpochMs),
+            firstByteMs: relative(request.firstByteEpochMs),
+            requestToFirstByteMs: Number.isFinite(request.firstByteEpochMs)
+                ? request.firstByteEpochMs - request.startEpochMs
+                : null,
+            endMs: relative(request.endEpochMs),
+            ttfbMs: request.ttfbMs,
+            ttfbSource: request.ttfbSource,
+            statusCode: request.statusCode ?? null,
+            cache: request.cache ?? null,
+            encodedDataLength: request.encodedDataLength ?? null,
+            canceled: request.canceled ?? null,
+            blockedReason: request.blockedReason ?? null,
+            initialPriority: request.initialPriority,
+            finalPriority: request.finalPriority,
+            priorityStatus: request.finalPriority === null ? "not-observed" : "observed",
+            finalPriorityStatus: request.finalPriority === null
+                ? "not-observed"
+                : request.status === "pending"
+                    ? "pending"
+                    : "complete",
+            priorityTimeline: request.priorityTimeline.map(({ epochMs, ...event }) => ({
+                ...event,
+                atMs: relative(epochMs),
+            })),
+            priorityTimelineTruncated: request.priorityTimelineTruncated ?? false,
+        });
+        const network = requests.map(serialize);
+        const resources = (browser?.resources || []).map((entry) => {
+            const request = match(entry.name, entry.startTime, undefined, true);
+            const { name, ...timing } = entry;
+            return {
+                ...timing,
+                url: sanitizeUrl(name),
+                ...classifyResourceTiming(entry, browser.documentUrl, request?.resourceType),
+                networkId: request?.id ?? null,
+                networkMatch: request ? "url-and-nearest-start" : "not-observed",
+                resourceType: request?.resourceType ?? null,
+            };
+        });
+        const mainRequests = network.filter((request) => request.isMainDocument);
+        const documentRequest = browser?.navigation
+            ? match(browser.navigation.name, browser.navigation.startTime, "Document", true)
+            : null;
+        const documentNetwork = documentRequest && documentRequest.frameId === mainFrameId ? serialize(documentRequest) : null;
+        const navigation = browser?.navigation;
+        const navigationTimingAvailable = navigation && navigation.responseStart > 0;
+        const requestOrders = new Map(requests
+            .filter((request) => request.frameId === mainFrameId &&
+            request.resourceType !== "Document" &&
+            (!documentRequest?.loaderId || request.loaderId === documentRequest.loaderId) &&
+            (!browser || request.startEpochMs >= browser.timeOrigin - 100))
+            .sort((a, b) => a.timestamp - b.timestamp)
+            .map((request, i) => [request.id, i + 1]));
+        const preloads = [browser?.early, browser?.final].filter(Boolean).flatMap((snapshot) => (snapshot.preloads || []).map((preload) => ({
+            ...preload,
+            observedMs: snapshot.observedMs,
+            snapshot: snapshot === browser.early ? "early" : "final",
+        })));
+        const imageSnapshot = (snapshot, field) => (snapshot?.[field] || []).map((image) => {
+            const request = match(image.url, snapshot.observedMs, "Image");
+            const resource = request ? resources.find((entry) => entry.networkId === request.id) : null;
+            const fetchResource = request
+                ? resource
+                : browser?.resources.findLast((entry) => image.url &&
+                    matchingUrl(entry.name) === matchingUrl(image.url) &&
+                    entry.startTime <= snapshot.observedMs + 2);
+            const fetchStartMs = relative(request?.startEpochMs) ?? fetchResource?.startTime ?? null;
+            const requestStartMs = request
+                ? (relative(request.requestStartEpochMs) ??
+                    (resource?.timingAvailability === "available" ? resource.requestStart : null) ??
+                    relative(request.startEpochMs))
+                : null;
+            const preloadEvidence = [];
+            if (request?.isLinkPreload)
+                preloadEvidence.push("cdp.request.isLinkPreload");
+            if (request?.initiatorType === "preload")
+                preloadEvidence.push("cdp.initiator.type=preload");
+            if (resource?.initiatorType === "link")
+                preloadEvidence.push("resourceTiming.initiatorType=link");
+            if (image.url &&
+                preloads.some((preload) => !preload.responsive &&
+                    preload.href &&
+                    preload.observedMs <= snapshot.observedMs &&
+                    matchingUrl(preload.href) === matchingUrl(image.url))) {
+                preloadEvidence.push("dom.link[rel~=preload][as=image].href");
+            }
+            let sourceUrl = null;
+            try {
+                const source = new URL(image.url).searchParams.get("url");
+                if (source) {
+                    if (!source.startsWith("/"))
+                        new URL(source);
+                    sourceUrl = sanitizeUrl(source);
+                }
+            }
+            catch {
+                sourceUrl = null;
+            }
+            return {
+                ...image,
+                url: sanitizeUrl(image.url),
+                sourceUrl,
+                networkId: request?.id ?? null,
+                networkMatch: request ? "url-before-snapshot" : "not-observed",
+                requestStatus: request?.status ?? "not-observed",
+                fetchStartMs,
+                fetchStartAfterTtfbMs: fetchStartMs !== null && navigationTimingAvailable
+                    ? fetchStartMs - navigation.responseStart
+                    : null,
+                requestStartMs,
+                requestStartAfterTtfbMs: requestStartMs !== null && navigationTimingAvailable
+                    ? requestStartMs - navigation.responseStart
+                    : null,
+                requestOrder: requestOrders.get(request?.id) ?? null,
+                isLcpCandidate: Boolean(image.url &&
+                    browser?.lcp?.url &&
+                    matchingUrl(image.url) === matchingUrl(browser.lcp.url)),
+                preloadEvidence,
+                initiatorType: request?.initiatorType ?? resource?.initiatorType ?? null,
+                initialPriority: request?.initialPriority ?? null,
+                finalPriority: request?.finalPriority ?? null,
+                finalPriorityStatus: request ? serialize(request).finalPriorityStatus : "not-observed",
+                priorityTimeline: request ? serialize(request).priorityTimeline : [],
+            };
+        });
+        const scriptSnapshots = [browser?.early, browser?.final].filter(Boolean);
+        const scriptHints = (resource) => {
+            for (const snapshot of scriptSnapshots) {
+                const script = snapshot.scripts.find((script) => matchingUrl(script.url) === matchingUrl(resource));
+                if (script)
+                    return {
+                        async: script.async,
+                        defer: script.defer,
+                        type: script.type,
+                        fetchPriority: script.fetchPriority,
+                        blocking: script.blocking,
+                    };
+            }
+            return null;
+        };
+        const renderBlockingScripts = resources
+            .filter((resource) => resource.renderBlockingScript)
+            .map((resource) => {
+            const entry = browser.resources[resources.indexOf(resource)];
+            const request = network.find((request) => request.id === resource.networkId);
+            return {
+                ...resource,
+                hints: scriptHints(entry.name),
+                initialPriority: request?.initialPriority ?? null,
+                finalPriority: request?.finalPriority ?? null,
+            };
+        });
+        if (browser) {
+            for (const unsupported of browser.unsupported)
+                notes.add(`PerformanceObserver ${unsupported} is unsupported.`);
+            for (const name of Object.keys(browser.truncated))
+                notes.add(`Browser ${name} collection was truncated by its configured limit.`);
+            if (!browser.early)
+                notes.add("Early image snapshot not observed: FCP or its following animation frame had not run at finish().");
+            if (browser.final?.visibilityMethod === "computed-style-fallback")
+                notes.add("checkVisibility unavailable; fallback visibility checks do not exclude opacity-zero ancestors or skipped content-visibility layers.");
+            if (browser.resources.some((entry) => entry.renderBlockingStatus === null))
+                notes.add("renderBlockingStatus unavailable for some resources; they are not classified as render blockers.");
+        }
+        const report = {
+            timeOriginEpochMs: origin,
+            finishedMs: browser?.finishedMs ?? null,
+            documentUrl: browser ? sanitizeUrl(browser.documentUrl) : null,
+            finalUrl: browser ? sanitizeUrl(browser.finalUrl) : null,
+            navigation: {
+                type: navigation?.type ?? null,
+                documentRequestId: documentNetwork?.id ?? null,
+                ttfbMs: documentNetwork?.ttfbMs ?? null,
+                ttfbSource: documentNetwork?.ttfbSource ?? "unavailable",
+                requestToFirstByteMs: documentNetwork?.requestToFirstByteMs ?? null,
+                browserRequestToFirstByteMs: navigationTimingAvailable
+                    ? navigation.responseStart - navigation.requestStart
+                    : null,
+                navigationToFirstByteMs: navigationTimingAvailable
+                    ? navigation.responseStart - navigation.startTime
+                    : null,
+                requestStartMs: navigationTimingAvailable ? navigation.requestStart : null,
+                responseStartMs: navigationTimingAvailable ? navigation.responseStart : null,
+                responseEndMs: navigation?.responseEnd > 0 ? navigation.responseEnd : null,
+                domContentLoadedMs: navigation?.domContentLoadedEventEnd > 0 ? navigation.domContentLoadedEventEnd : null,
+                loadMs: navigation?.loadEventEnd > 0 ? navigation.loadEventEnd : null,
+                clientObserved: {
+                    domContentLoadedMs: browser?.domContentLoadedMs ?? null,
+                    loadMs: browser?.loadMs ?? null,
+                    responseReceivedMs: documentNetwork?.responseObservedMs ?? null,
+                },
+                cache: documentNetwork?.cache ?? null,
+                documentRequests: mainRequests,
+            },
+            paints: {
+                entries: browser?.paints ?? [],
+                fcpMs: browser?.paints.find((paint) => paint.name === "first-contentful-paint")?.startTime ??
+                    null,
+                lcp: browser?.lcp
+                    ? {
+                        ...browser.lcp,
+                        url: browser.lcp.url ? sanitizeUrl(browser.lcp.url) : null,
+                        isFinal: false,
+                    }
+                    : null,
+            },
+            images: {
+                preloads: preloads.map((preload) => ({
+                    ...preload,
+                    href: preload.href ? sanitizeUrl(preload.href) : null,
+                })),
+                early: imageSnapshot(browser?.early, "images"),
+                final: imageSnapshot(browser?.final, "images"),
+                earlyObservedMs: browser?.early?.observedMs ?? null,
+                finalObservedMs: browser?.final?.observedMs ?? null,
+                earlyViewport: browser?.early?.viewport ?? null,
+                finalViewport: browser?.final?.viewport ?? null,
+                earlyScan: browser?.early?.imageScan ?? null,
+                finalScan: browser?.final?.imageScan ?? null,
+                visibilityMethod: browser?.final?.visibilityMethod ?? "not-observed",
+                backgrounds: {
+                    early: imageSnapshot(browser?.early, "backgrounds"),
+                    final: imageSnapshot(browser?.final, "backgrounds"),
+                },
+            },
+            fonts: {
+                faces: (browser?.faces ?? []).map(classifyFontFace),
+                events: (browser?.fontEvents ?? []).map((event) => ({
+                    ...event,
+                    faces: event.faces.map(classifyFontFace),
+                })),
+                resources: network
+                    .filter((request) => request.resourceType === "Font")
+                    .map((request) => ({
+                    ...request,
+                    performanceTimings: resources.filter((resource) => resource.networkId === request.id),
+                })),
+                atFcp: (browser?.fontsAtFcp ?? []).map(classifyFontFace),
+                atFcpObservedMs: browser?.fontsAtFcpObservedMs ?? null,
+                statusAtFcp: browser?.fontSetStatusAtFcp ?? "not-observed",
+                statusAtFinish: browser?.fontSetStatus ?? "not-observed",
+            },
+            renderBlockingScripts,
+            explicitInlineRenderBlockers: scriptSnapshots.flatMap((snapshot) => snapshot.inlineRenderBlockers.map((script) => ({
+                ...script,
+                observedMs: snapshot.observedMs,
+                snapshot: snapshot === browser.early ? "early" : "final",
+            }))),
+            resources,
+            network,
+            longTasks: browser?.longTasks ?? [],
+            collectionLimits: { ...LIMITS },
+            measurementNotes: [],
+        };
+        await dispose();
+        report.measurementNotes = [...notes];
+        return report;
+    }
+    return {
+        async finish() {
+            if (finishPromise)
+                return finishPromise;
+            if (disposed)
+                throw new Error("Page diagnostics already disposed");
+            finishPromise = collect().finally(dispose);
+            return finishPromise;
+        },
+        dispose,
+    };
+}