@fulldotdev/scan 0.1.0

package/dist/engine/browser-inspection.js

@@ -0,0 +1,567 @@
+export async function observeRendering(page) {
+    await page.evaluateOnNewDocument(() => {
+        const state = { lcp: null, shifts: [], fontEvents: [] };
+        window.__monitorRendering = state;
+        const describe = (el) => el
+            ? {
+                tag: el.tagName,
+                id: el.id,
+                selector: el.id
+                    ? `#${CSS.escape(el.id)}`
+                    : el.tagName.toLowerCase() +
+                        [...el.classList].map((c) => `.${CSS.escape(c)}`).join(""),
+                snippet: el.outerHTML.slice(0, 1500),
+            }
+            : null;
+        new PerformanceObserver((list) => {
+            for (const e of list.getEntries()) {
+                state.lcpElement = e.element;
+                state.lcp = {
+                    time: e.renderTime || e.startTime,
+                    size: e.size,
+                    url: e.url,
+                    element: describe(e.element),
+                    loading: e.element?.getAttribute("loading"),
+                    fetchpriority: e.element?.getAttribute("fetchpriority") ?? "auto",
+                };
+            }
+        }).observe({ type: "largest-contentful-paint", buffered: true });
+        new PerformanceObserver((list) => {
+            for (const e of list.getEntries())
+                if (!e.hadRecentInput && state.shifts.length < 100)
+                    state.shifts.push({
+                        time: e.startTime,
+                        value: e.value,
+                        fontsLoading: document.fonts.status === "loading",
+                        sources: (e.sources ?? []).map((s) => ({
+                            element: describe(s.node),
+                            previousRect: {
+                                x: s.previousRect.x,
+                                y: s.previousRect.y,
+                                width: s.previousRect.width,
+                                height: s.previousRect.height,
+                            },
+                            currentRect: {
+                                x: s.currentRect.x,
+                                y: s.currentRect.y,
+                                width: s.currentRect.width,
+                                height: s.currentRect.height,
+                            },
+                            fontFamily: s.node instanceof Element
+                                ? getComputedStyle(s.node).fontFamily
+                                : null,
+                        })),
+                    });
+        }).observe({ type: "layout-shift", buffered: true });
+        for (const name of ["loading", "loadingdone", "loadingerror"])
+            document.fonts.addEventListener(name, () => state.fontEvents.push({ type: name, time: performance.now() }));
+    });
+}
+export async function stableLayout(page) {
+    return page.evaluate(async () => {
+        const started = performance.now();
+        let fontsReady = false;
+        await Promise.race([
+            document.fonts.ready.then(() => {
+                fontsReady = true;
+            }),
+            new Promise((r) => setTimeout(r, 4000)),
+        ]);
+        let last = "", equalSince = performance.now(), stable = false;
+        let samples = 0;
+        while (performance.now() - started < 6000) {
+            const signature = [
+                document.documentElement.scrollWidth,
+                document.documentElement.scrollHeight,
+                ...[...document.querySelectorAll("body *")]
+                    .slice(0, 2000)
+                    .flatMap((el) => {
+                    const r = el.getBoundingClientRect();
+                    return [
+                        Math.round(r.x),
+                        Math.round(r.y),
+                        Math.round(r.width),
+                        Math.round(r.height),
+                    ];
+                }),
+            ].join(",");
+            samples++;
+            if (signature !== last) {
+                last = signature;
+                equalSince = performance.now();
+            }
+            else if (performance.now() - equalSince >= 500) {
+                stable = true;
+                break;
+            }
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return {
+            fontsReady,
+            stable,
+            samples,
+            waitedMs: Math.round(performance.now() - started),
+            elementLimit: 2000,
+        };
+    });
+}
+export async function inspectOverflow(page) {
+    const readiness = await stableLayout(page);
+    const data = await page.evaluate(() => {
+        const width = document.documentElement.clientWidth;
+        const documentWidth = document.documentElement.scrollWidth;
+        const clipped = [], elements = [];
+        for (const el of document.querySelectorAll("body *")) {
+            const r = el.getBoundingClientRect(), style = getComputedStyle(el);
+            if (!r.width ||
+                !r.height ||
+                style.visibility === "hidden" ||
+                style.display === "none" ||
+                (r.left >= -1 && r.right <= width + 1))
+                continue;
+            let left = r.left, right = r.right;
+            let clipAncestor = null;
+            for (let p = el.parentElement; p && p !== document.documentElement; p = p.parentElement) {
+                const s = getComputedStyle(p);
+                if (/^(hidden|clip|auto|scroll)$/.test(s.overflowX) ||
+                    /paint|strict|content/.test(s.contain)) {
+                    const b = p.getBoundingClientRect();
+                    left = Math.max(left, b.left + p.clientLeft);
+                    right = Math.min(right, b.left + p.clientLeft + p.clientWidth);
+                    clipAncestor = p.id || p.className || p.tagName;
+                }
+            }
+            const item = {
+                tag: el.tagName,
+                id: el.id,
+                className: el.getAttribute("class"),
+                left: r.left,
+                right: r.right,
+                width: r.width,
+                visibleLeft: left,
+                visibleRight: right,
+                clipAncestor,
+            };
+            if (right <= left || (left >= -1 && right <= width + 1))
+                clipped.push(item);
+            else
+                elements.push(item);
+        }
+        return {
+            width,
+            documentWidth,
+            bodyWidth: document.body?.scrollWidth,
+            documentOverflow: documentWidth > width + 1,
+            elements: elements.slice(0, 100),
+            clipped: clipped.slice(0, 100),
+            elementCount: elements.length,
+            clippedCount: clipped.length,
+        };
+    });
+    return {
+        ...data,
+        readiness,
+        conclusive: readiness.fontsReady && readiness.stable,
+    };
+}
+export async function inspectRendering(page, cdp, html, responses) {
+    const readiness = await stableLayout(page);
+    const evidence = await page.evaluate((initialHtml) => {
+        const source = new DOMParser().parseFromString(initialHtml, "text/html");
+        const base = new URL(source.querySelector("base[href]")?.getAttribute("href") ?? location.href, location.href).href;
+        const absolute = (s) => {
+            try {
+                return new URL(s, base).href;
+            }
+            catch {
+                return s;
+            }
+        };
+        const candidates = (srcset) => srcset
+            .split(/,\s*/)
+            .filter((s) => s.trim())
+            .map((s) => {
+            const [url, descriptor = "1x"] = s.trim().split(/\s+/);
+            return {
+                url: absolute(url),
+                descriptor,
+                width: descriptor.endsWith("w")
+                    ? Number.parseFloat(descriptor)
+                    : null,
+                density: descriptor.endsWith("x")
+                    ? Number.parseFloat(descriptor)
+                    : null,
+            };
+        })
+            .filter((c) => c.url && !c.url.startsWith("data:"));
+        const declared = new Set([...source.querySelectorAll("img,source,link[rel=preload]")].flatMap((el) => [
+            el.getAttribute("src"),
+            el.getAttribute("href"),
+            ...candidates(el.getAttribute("srcset") ?? el.getAttribute("imagesrcset") ?? "").map((c) => c.url),
+        ]
+            .filter(Boolean)
+            .map((s) => absolute(s))));
+        const state = window.__monitorRendering ?? {
+            lcp: null,
+            shifts: [],
+            fontEvents: [],
+        };
+        const resources = performance.getEntriesByType("resource");
+        const images = [...document.images].slice(0, 500).map((img) => {
+            const r = img.getBoundingClientRect(), style = getComputedStyle(img);
+            let left = Math.max(r.left, 0), right = Math.min(r.right, innerWidth), top = Math.max(r.top, 0), bottom = Math.min(r.bottom, innerHeight);
+            let hidden = style.visibility === "hidden" ||
+                style.display === "none" ||
+                Number(style.opacity) === 0;
+            for (let p = img.parentElement; p; p = p.parentElement) {
+                const s = getComputedStyle(p), b = p.getBoundingClientRect();
+                hidden ||=
+                    s.visibility === "hidden" ||
+                        s.display === "none" ||
+                        Number(s.opacity) === 0;
+                if (/hidden|clip|auto|scroll/.test(s.overflowX)) {
+                    left = Math.max(left, b.left);
+                    right = Math.min(right, b.right);
+                }
+                if (/hidden|clip|auto|scroll/.test(s.overflowY)) {
+                    top = Math.max(top, b.top);
+                    bottom = Math.min(bottom, b.bottom);
+                }
+            }
+            const sources = [
+                ...(img.closest("picture")?.querySelectorAll("source") ?? []),
+            ].map((s) => ({
+                srcset: s.srcset,
+                sizes: s.sizes,
+                media: s.media,
+                type: s.type,
+                matches: !s.media || matchMedia(s.media).matches,
+            }));
+            const activeSource = sources.find((s) => s.matches &&
+                candidates(s.srcset).some((c) => c.url === img.currentSrc));
+            const choices = candidates(activeSource?.srcset ?? img.srcset);
+            const selected = choices.find((c) => c.url === img.currentSrc);
+            const selectedWidth = selected?.width ?? img.naturalWidth * (selected?.density ?? 1);
+            const requiredWidth = Math.ceil(r.width * devicePixelRatio);
+            const resource = resources.find((e) => e.name === img.currentSrc);
+            const visible = !hidden && right > left && bottom > top;
+            return {
+                selector: img.id
+                    ? `#${CSS.escape(img.id)}`
+                    : `img:nth-of-type(${[...img.parentElement.children].filter((e) => e.tagName === "IMG").indexOf(img) + 1})`,
+                snippet: img.outerHTML.slice(0, 1500),
+                currentSrc: img.currentSrc,
+                src: img.src,
+                srcset: img.srcset,
+                sizes: img.sizes,
+                sources,
+                choices,
+                loading: img.getAttribute("loading") ?? "auto",
+                fetchpriority: img.fetchPriority,
+                rendered: {
+                    width: r.width,
+                    height: r.height,
+                    top: r.top,
+                    left: r.left,
+                },
+                dpr: devicePixelRatio,
+                naturalWidth: img.naturalWidth,
+                selectedWidth,
+                requiredWidth,
+                widthEvidence: selected?.width
+                    ? "srcset-width-descriptor"
+                    : "natural-width-and-density",
+                oversizeRatio: requiredWidth && selectedWidth ? selectedWidth / requiredWidth : null,
+                missingIntermediate: requiredWidth > 0 &&
+                    selectedWidth > requiredWidth * 1.2 &&
+                    !choices.some((c) => c.width &&
+                        c.width >= requiredWidth &&
+                        c.width <= requiredWidth * 1.2),
+                visible,
+                position: visible
+                    ? "first-viewport"
+                    : r.top >= innerHeight
+                        ? "below-viewport"
+                        : "offscreen-or-clipped",
+                loaded: !!resource || (img.complete && img.naturalWidth > 0),
+                inInitialHtml: declared.has(img.currentSrc),
+                bytes: resource?.encodedBodySize || null,
+                transferBytes: resource?.transferSize || null,
+                isLcp: state.lcpElement === img,
+            };
+        });
+        const faces = [], unreadable = [];
+        const walk = (rules, stylesheet) => {
+            for (const rule of rules) {
+                if (rule instanceof CSSFontFaceRule)
+                    faces.push({
+                        stylesheet,
+                        family: rule.style.getPropertyValue("font-family"),
+                        weight: rule.style.getPropertyValue("font-weight"),
+                        unicodeRange: rule.style.getPropertyValue("unicode-range") || "U+0-10FFFF",
+                        src: rule.style.getPropertyValue("src"),
+                        display: rule.style.getPropertyValue("font-display"),
+                        sizeAdjust: rule.style.getPropertyValue("size-adjust"),
+                        ascentOverride: rule.style.getPropertyValue("ascent-override"),
+                        descentOverride: rule.style.getPropertyValue("descent-override"),
+                        lineGapOverride: rule.style.getPropertyValue("line-gap-override"),
+                    });
+                else if ("cssRules" in rule)
+                    walk(rule.cssRules, stylesheet);
+            }
+        };
+        for (const sheet of document.styleSheets) {
+            try {
+                walk(sheet.cssRules, sheet.href ?? location.href);
+            }
+            catch {
+                unreadable.push(sheet.href ?? "inline");
+            }
+        }
+        const samples = [...document.querySelectorAll("body *")]
+            .filter((el) => [...el.childNodes].some((n) => n.nodeType === Node.TEXT_NODE && n.textContent?.trim()) && el.getBoundingClientRect().width > 0)
+            .slice(0, 80)
+            .map((el) => {
+            const s = getComputedStyle(el), text = el.textContent?.trim().slice(0, 120) ?? "";
+            const canvas = document.createElement("canvas"), ctx = canvas.getContext("2d");
+            ctx.font = `${s.fontStyle} ${s.fontWeight} ${s.fontSize} ${s.fontFamily}`;
+            const loadedWidth = ctx.measureText(text).width;
+            const fallback = s.fontFamily.split(",").slice(1).join(",") || "serif";
+            ctx.font = `${s.fontStyle} ${s.fontWeight} ${s.fontSize} ${fallback}`;
+            const fallbackWidth = ctx.measureText(text).width;
+            return {
+                tag: el.tagName,
+                text,
+                family: s.fontFamily,
+                weight: s.fontWeight,
+                fontSize: s.fontSize,
+                lineHeight: s.lineHeight,
+                fallback,
+                loadedWidth,
+                fallbackWidth,
+                widthDifference: loadedWidth - fallbackWidth,
+            };
+        });
+        const preloads = [
+            ...document.querySelectorAll('link[rel~="preload"][as="font"],link[rel~="preload"][type^="font/"]'),
+        ].map((link) => ({
+            url: link.href,
+            as: link.as,
+            type: link.type,
+            crossorigin: link.getAttribute("crossorigin"),
+            media: link.media,
+            active: !link.media || matchMedia(link.media).matches,
+            requested: resources.some((r) => r.name === link.href),
+            declaredFace: faces.some((f) => [...f.src.matchAll(/url\(["']?([^"')]+)["']?\)/g)].some((m) => new URL(m[1], f.stylesheet).href === link.href)),
+        }));
+        return {
+            viewport: {
+                width: innerWidth,
+                height: innerHeight,
+                dpr: devicePixelRatio,
+            },
+            lcp: state.lcp
+                ? {
+                    ...state.lcp,
+                    inInitialHtml: state.lcp.url ? declared.has(state.lcp.url) : null,
+                }
+                : null,
+            images,
+            fonts: {
+                faces,
+                unreadableStylesheets: unreadable,
+                samples,
+                preloads,
+                events: state.fontEvents,
+                shifts: state.shifts.map((s) => ({
+                    ...s,
+                    fontTimingCorrelation: state.fontEvents.some((e) => e.type === "loadingdone" && Math.abs(e.time - s.time) < 150),
+                })),
+                scope: "80 text samples; fallback canvas widths, not a reflow simulation. Shift timing is correlation, not proof of font causation.",
+            },
+        };
+    }, html);
+    // The protocol reports fonts actually used for glyphs, including fallback fonts.
+    await cdp.send("DOM.enable");
+    await cdp.send("CSS.enable");
+    const doc = await cdp.send("DOM.getDocument", { depth: 0 });
+    const nodes = await cdp.send("DOM.querySelectorAll", {
+        nodeId: doc.root.nodeId,
+        selector: "body *",
+    });
+    const used = [];
+    for (const nodeId of nodes.nodeIds.slice(0, 300)) {
+        const usage = await cdp
+            .send("CSS.getPlatformFontsForNode", { nodeId })
+            .catch(() => null);
+        if (usage?.fonts.length) {
+            const computed = await cdp
+                .send("CSS.getComputedStyleForNode", { nodeId })
+                .catch(() => null);
+            used.push({
+                nodeId,
+                fonts: usage.fonts,
+                weight: computed?.computedStyle.find((s) => s.name === "font-weight")
+                    ?.value ?? null,
+                family: computed?.computedStyle.find((s) => s.name === "font-family")
+                    ?.value ?? null,
+            });
+        }
+    }
+    const cleanFamily = (family) => family.replace(/["']/g, "").trim().toLowerCase();
+    const loadedFaces = await page.evaluate(() => [...document.fonts].map((f) => ({
+        family: f.family,
+        unicodeRange: f.unicodeRange,
+        weight: f.weight,
+        status: f.status,
+    })));
+    const weightMatches = (declared, weight) => {
+        const numeric = (s) => s === "normal" ? 400 : s === "bold" ? 700 : Number(s);
+        const bounds = (declared || "400").split(/\s+/).map(numeric);
+        const value = numeric(weight);
+        return value >= bounds[0] && value <= (bounds[1] ?? bounds[0]);
+    };
+    const preloads = evidence.fonts.preloads.map((preload) => {
+        const faces = evidence.fonts.faces.filter((f) => [...f.src.matchAll(/url\(["']?([^"')]+)["']?\)/g)].some((m) => new URL(m[1], f.stylesheet).href === preload.url));
+        const usedFace = faces.some((f) => loadedFaces.some((loaded) => loaded.status === "loaded" &&
+            cleanFamily(loaded.family) === cleanFamily(f.family) &&
+            loaded.weight === (f.weight || "normal") &&
+            loaded.unicodeRange.toUpperCase() === f.unicodeRange.toUpperCase()) &&
+            used.some((node) => weightMatches(f.weight, node.weight ?? "400") &&
+                node.fonts.some((font) => font.isCustomFont &&
+                    (cleanFamily(font.familyName) === cleanFamily(f.family) ||
+                        cleanFamily((node.family ?? "").split(",")[0]) ===
+                            cleanFamily(f.family)))));
+        const response = responses.find((r) => r.url === preload.url);
+        return {
+            ...preload,
+            status: response?.status ?? null,
+            used: faces.length ? usedFace : null,
+            usageEvidence: "Loaded FontFace plus rendered glyph family and computed weight; unicode subset file attribution is not available",
+            valid: preload.as === "font" &&
+                (preload.crossorigin === "" || preload.crossorigin === "anonymous") &&
+                (!preload.type ||
+                    /^(font\/(woff2?|otf|ttf)|application\/font-woff)$/.test(preload.type)),
+            coverage: faces.length
+                ? "observed-faces-and-glyphs"
+                : "face-not-observed",
+        };
+    });
+    const imageEvidence = evidence.images.map((img) => {
+        const response = responses.find((r) => r.url === img.currentSrc);
+        return {
+            ...img,
+            mimeType: response?.mimeType ?? null,
+            bytes: response?.encodedBodySize ?? img.bytes,
+            transferBytes: response?.transferBytes ?? img.transferBytes,
+            compression: {
+                contentEncoding: response?.contentEncoding ?? null,
+                note: "Encoded bytes and Lighthouse image-delivery savings; format alone is not a failure.",
+            },
+        };
+    });
+    return {
+        ...evidence,
+        images: imageEvidence,
+        readiness,
+        fonts: {
+            ...evidence.fonts,
+            used,
+            loadedFaces,
+            preloads,
+            platformNodeLimit: 300,
+        },
+        findings: [
+            ...imageEvidence.flatMap((img) => [
+                ...(img.isLcp && img.loading === "lazy"
+                    ? [
+                        {
+                            code: "lcp-lazy",
+                            message: "Measured LCP image is lazy loaded",
+                        },
+                    ]
+                    : []),
+                ...(img.isLcp && img.fetchpriority !== "high"
+                    ? [
+                        {
+                            code: "lcp-priority",
+                            message: "Measured LCP image has no high fetch priority",
+                        },
+                    ]
+                    : []),
+                ...(img.isLcp && !img.inInitialHtml
+                    ? [
+                        {
+                            code: "lcp-discovery",
+                            message: "Measured LCP image is not declared in the initial HTML",
+                        },
+                    ]
+                    : []),
+                ...(img.missingIntermediate &&
+                    (img.bytes ?? 0) >= 20000 &&
+                    img.mimeType !== "image/svg+xml"
+                    ? [
+                        {
+                            code: "image-intermediate-size",
+                            message: `${img.selectedWidth}px selected for ${img.requiredWidth}px needed, including DPR`,
+                        },
+                    ]
+                    : []),
+                ...(img.visible && img.loading === "lazy"
+                    ? [
+                        {
+                            code: "visible-image-lazy",
+                            message: "Visible first-viewport image is lazy loaded",
+                        },
+                    ]
+                    : []),
+                ...(!img.visible && img.loaded && img.loading !== "lazy"
+                    ? [
+                        {
+                            code: "offscreen-image-eager",
+                            message: `${img.position} image loaded eagerly`,
+                        },
+                    ]
+                    : []),
+                ...(!img.visible && img.fetchpriority === "high"
+                    ? [
+                        {
+                            code: "offscreen-image-priority",
+                            message: "Offscreen image competes at high priority",
+                        },
+                    ]
+                    : []),
+            ].map((f) => ({ ...f, element: img.snippet, file: img.currentSrc }))),
+            ...(imageEvidence.filter((i) => i.fetchpriority === "high").length > 1
+                ? [
+                    {
+                        code: "competing-image-priorities",
+                        message: "Multiple images request high fetch priority",
+                        file: null,
+                        element: null,
+                    },
+                ]
+                : []),
+            ...evidence.fonts.faces
+                .filter((f) => /\.(otf|ttf)(?:["')?#]|$)/i.test(f.src))
+                .map((f) => ({
+                code: "font-format",
+                message: "Font source uses OTF/TTF",
+                file: f.src,
+                element: null,
+            })),
+            ...preloads
+                .filter((p) => p.active &&
+                (!p.valid ||
+                    !p.requested ||
+                    p.used === false ||
+                    (p.status !== null && p.status >= 400)))
+                .map((p) => ({
+                code: "font-preload",
+                message: "Font preload is invalid, failed, not requested, or unused by observed glyphs",
+                file: p.url,
+                element: null,
+            })),
+        ],
+    };
+}

package/dist/engine/browser.d.ts

@@ -0,0 +1,22 @@
+import lighthouse from "lighthouse";
+import { HttpClient } from "./network.js";
+import { type JobResult, type Scan } from "./types.js";
+export type BrowserSession = Awaited<ReturnType<typeof openBrowserSession>>;
+export declare function openBrowserSession(): Promise<{
+    proxy: {
+        port: number;
+        blocked: {
+            target: string;
+            error: string;
+        }[];
+        close: () => Promise<void>;
+    };
+    lighthouse: typeof lighthouse;
+    browser: import("puppeteer").Browser;
+    args: string[];
+    chromeVersion: string;
+    readonly connected: boolean;
+    close: () => Promise<void>;
+}>;
+export declare function screenshotSampled(url: string, rotation: number, home: string): boolean;
+export declare function collectBrowser(scan: Scan, url: string, http: HttpClient, session: BrowserSession): Promise<JobResult>;