@rivi-software/agentic-seo-check 0.0.0-stage → 0.1.1

package/dist/core/lighthouse.d.ts

@@ -0,0 +1,50 @@
+import type { PerformanceResult } from "./types.js";
+export declare class LighthouseUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface LighthouseRunOptions {
+    formFactor?: "mobile" | "desktop";
+    timeoutMs?: number;
+    chromePath?: string;
+    userAgent?: string;
+    headers?: Record<string, string>;
+}
+export declare const LIGHTHOUSE_INSTALL_HINT = "Install Lighthouse and a Chrome: `pnpm add -D lighthouse chrome-launcher` plus Google Chrome, or `pnpm exec playwright install chromium` (the Playwright Chromium is used automatically when found).";
+interface LhCategory {
+    score: number | null;
+    auditRefs: {
+        id: string;
+        weight: number;
+        group?: string;
+    }[];
+}
+interface LhAudit {
+    id: string;
+    title: string;
+    description: string;
+    score: number | null;
+    scoreDisplayMode: string;
+    numericValue?: number;
+    displayValue?: string;
+    metricSavings?: Record<string, number | undefined>;
+    details?: {
+        type?: string;
+        overallSavingsMs?: number;
+        overallSavingsBytes?: number;
+    };
+}
+interface LhrLike {
+    lighthouseVersion: string;
+    requestedUrl?: string;
+    finalDisplayedUrl?: string;
+    finalUrl?: string;
+    runtimeError?: {
+        code: string;
+        message: string;
+    };
+    categories: Record<string, LhCategory | undefined>;
+    audits: Record<string, LhAudit | undefined>;
+}
+export declare const summarize: (lhr: LhrLike, requestedUrl: string, formFactor: "mobile" | "desktop") => PerformanceResult;
+export declare const runLighthouse: (url: string, options?: LighthouseRunOptions) => Promise<PerformanceResult>;
+export {};

package/dist/core/lighthouse.js

@@ -0,0 +1,216 @@
+export class LighthouseUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LighthouseUnavailableError";
+    }
+}
+export const LIGHTHOUSE_INSTALL_HINT = "Install Lighthouse and a Chrome: `pnpm add -D lighthouse chrome-launcher` plus Google Chrome, or `pnpm exec playwright install chromium` (the Playwright Chromium is used automatically when found).";
+/** Audits we already cover with our own rules; Lighthouse duplicates are suppressed. */
+const COVERED_SEO_AUDITS = new Set([
+    "document-title",
+    "meta-description",
+    "image-alt",
+    "canonical",
+    "hreflang",
+    "link-text",
+    "http-status-code",
+    "is-crawlable",
+    "structured-data",
+    "viewport",
+]);
+/** The metrics whose savings Lighthouse reports in milliseconds. */
+const MS_SAVINGS_METRICS = ["LCP", "FCP", "TBT", "INP", "SI"];
+const stripMarkdownLinks = (text) => text
+    .replaceAll(/\[(?<text>[^\]]+)\]\((?<href>https?:[^)]+)\)/gu, "$<text> ($<href>)")
+    .trim();
+const percent = (score) => score === null || score === undefined ? null : Math.round(score * 100);
+/** An audit in the performance category as an opportunity, or null when it saves nothing. */
+const opportunityOf = (audit) => {
+    const savings = audit.metricSavings ?? {};
+    const msValues = MS_SAVINGS_METRICS.flatMap((metric) => {
+        const value = savings[metric];
+        return value !== undefined && value > 0 ? [value] : [];
+    });
+    const savingsMs = audit.details?.overallSavingsMs ??
+        (msValues.length > 0 ? Math.max(...msValues) : null);
+    const savingsBytes = audit.details?.overallSavingsBytes ?? null;
+    const hasSavings = (savingsMs ?? 0) > 0 ||
+        (savingsBytes ?? 0) > 0 ||
+        (savings["CLS"] ?? 0) > 0 ||
+        audit.details?.type === "opportunity";
+    if (!hasSavings) {
+        return null;
+    }
+    return {
+        id: audit.id,
+        title: audit.title,
+        description: stripMarkdownLinks(audit.description),
+        score: audit.score,
+        savingsMs: savingsMs ?? null,
+        savingsBytes,
+    };
+};
+const opportunitiesOf = (lhr) => {
+    const perfRefs = lhr.categories["performance"]?.auditRefs ?? [];
+    const opportunities = [];
+    for (const ref of perfRefs) {
+        const audit = lhr.audits[ref.id];
+        if (!audit || audit.score === null || audit.score >= 0.9) {
+            continue;
+        }
+        if (ref.group === "metrics" || ref.group === "hidden") {
+            continue;
+        }
+        const opportunity = opportunityOf(audit);
+        if (opportunity) {
+            opportunities.push(opportunity);
+        }
+    }
+    opportunities.sort((a, b) => (b.savingsMs ?? 0) - (a.savingsMs ?? 0) ||
+        (b.savingsBytes ?? 0) - (a.savingsBytes ?? 0));
+    return opportunities;
+};
+const failedAudits = (lhr, category, skip) => {
+    const refs = lhr.categories[category]?.auditRefs ?? [];
+    const out = [];
+    for (const ref of refs) {
+        const audit = lhr.audits[ref.id];
+        if (!audit || skip.has(audit.id)) {
+            continue;
+        }
+        if (!["binary", "numeric", "metricSavings"].includes(audit.scoreDisplayMode)) {
+            continue;
+        }
+        if (audit.score === null || audit.score >= 1) {
+            continue;
+        }
+        out.push({
+            id: audit.id,
+            title: audit.title,
+            description: stripMarkdownLinks(audit.description),
+            score: audit.score,
+            displayValue: audit.displayValue ?? null,
+        });
+    }
+    return out;
+};
+export const summarize = (lhr, requestedUrl, formFactor) => {
+    const numeric = (id) => {
+        const value = lhr.audits[id]?.numericValue;
+        return value !== undefined && Number.isFinite(value) ? value : null;
+    };
+    return {
+        tool: "lighthouse",
+        lighthouseVersion: lhr.lighthouseVersion,
+        formFactor,
+        requestedUrl,
+        finalUrl: lhr.finalDisplayedUrl ?? lhr.finalUrl ?? requestedUrl,
+        metrics: {
+            performanceScore: percent(lhr.categories["performance"]?.score),
+            seoScore: percent(lhr.categories["seo"]?.score),
+            agenticBrowsingScore: percent(lhr.categories["agentic-browsing"]?.score),
+            lcpMs: numeric("largest-contentful-paint"),
+            cls: numeric("cumulative-layout-shift"),
+            tbtMs: numeric("total-blocking-time"),
+            fcpMs: numeric("first-contentful-paint"),
+            speedIndexMs: numeric("speed-index"),
+            ttfbMs: numeric("server-response-time"),
+            inpMs: numeric("interaction-to-next-paint"),
+        },
+        opportunities: opportunitiesOf(lhr),
+        failedSeoAudits: failedAudits(lhr, "seo", COVERED_SEO_AUDITS),
+        agenticBrowsingAudits: failedAudits(lhr, "agentic-browsing", new Set()),
+    };
+};
+const playwrightChromiumPath = async () => {
+    try {
+        const pw = await import("playwright");
+        const p = pw.chromium.executablePath();
+        const { promises: fs } = await import("node:fs");
+        await fs.access(p);
+        return p;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Lighthouse and chrome-launcher are optional peers, so they load only when a run asks for them. */
+const loadLighthouse = async () => {
+    try {
+        const lighthouseModule = await import("lighthouse");
+        const chromeLauncher = await import("chrome-launcher");
+        return {
+            lighthouse: lighthouseModule.default,
+            launch: chromeLauncher.launch,
+        };
+    }
+    catch {
+        throw new LighthouseUnavailableError(`Lighthouse or chrome-launcher is not installed. ${LIGHTHOUSE_INSTALL_HINT}`);
+    }
+};
+export const runLighthouse = async (url, options = {}) => {
+    const formFactor = options.formFactor ?? "mobile";
+    const { lighthouse, launch } = await loadLighthouse();
+    const chromePath = options.chromePath ??
+        process.env["CHROME_PATH"] ??
+        (await playwrightChromiumPath());
+    const launchOptions = {
+        chromeFlags: [
+            "--headless=new",
+            "--no-first-run",
+            "--disable-gpu",
+            "--no-default-browser-check",
+        ],
+        logLevel: "silent",
+    };
+    if (chromePath) {
+        launchOptions.chromePath = chromePath;
+    }
+    let chrome;
+    try {
+        chrome = await launch(launchOptions);
+    }
+    catch (error) {
+        throw new LighthouseUnavailableError(`Could not launch Chrome: ${error instanceof Error ? error.message : String(error)}. ${LIGHTHOUSE_INSTALL_HINT}`);
+    }
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    let timer;
+    try {
+        let config;
+        if (formFactor === "desktop") {
+            const desktop = await import("lighthouse/core/config/desktop-config.js");
+            config = desktop.default;
+        }
+        const flags = {
+            port: chrome.port,
+            output: "json",
+            logLevel: "silent",
+            onlyCategories: ["performance", "seo", "agentic-browsing"],
+            extraHeaders: options.headers,
+        };
+        if (options.userAgent) {
+            flags.emulatedUserAgent = options.userAgent;
+        }
+        const run = lighthouse(url, flags, config);
+        // oxlint-disable-next-line promise/avoid-new -- setTimeout has no promise form that can be cleared without settling it
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error(`Lighthouse timed out after ${timeoutMs} ms`)), timeoutMs);
+        });
+        const result = await Promise.race([run, timeout]);
+        if (!result) {
+            throw new Error("Lighthouse returned no result");
+        }
+        const lhr = result.lhr;
+        if (lhr.runtimeError && lhr.runtimeError.code !== "NO_ERROR") {
+            throw new Error(`Lighthouse runtime error ${lhr.runtimeError.code}: ${lhr.runtimeError.message}`);
+        }
+        return summarize(lhr, url, formFactor);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        chrome.kill();
+    }
+};
+//# sourceMappingURL=lighthouse.js.map

package/dist/core/lighthouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighthouse.js","sourceRoot":"","sources":["../../src/core/lighthouse.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAUD,MAAM,CAAC,MAAM,uBAAuB,GAClC,sMAAsM,CAAC;AAEzM,wFAAwF;AACxF,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,gBAAgB;IAChB,kBAAkB;IAClB,WAAW;IACX,WAAW;IACX,UAAU;IACV,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,iBAAiB;IACjB,UAAU;CACX,CAAC,CAAC;AAiCH,oEAAoE;AACpE,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AAE9D,MAAM,kBAAkB,GAAG,CAAC,IAAY,EAAU,EAAE,CAClD,IAAI;KACD,UAAU,CACT,gDAAgD,EAChD,mBAAmB,CACpB;KACA,IAAI,EAAE,CAAC;AAEZ,MAAM,OAAO,GAAG,CAAC,KAAgC,EAAiB,EAAE,CAClE,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;AAEzE,6FAA6F;AAC7F,MAAM,aAAa,GAAG,CAAC,KAAc,EAAgC,EAAE;IACrE,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;IAE1C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAE9B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GACb,KAAK,CAAC,OAAO,EAAE,gBAAgB;QAC/B,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAEvD,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,EAAE,mBAAmB,IAAI,IAAI,CAAC;IAEhE,MAAM,UAAU,GACd,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC;QACpB,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC;QACvB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;QACzB,KAAK,CAAC,OAAO,EAAE,IAAI,KAAK,aAAa,CAAC;IAExC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,WAAW,EAAE,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC;QAClD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,SAAS,IAAI,IAAI;QAC5B,YAAY;KACb,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,GAAY,EAA2B,EAAE;IAChE,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAChE,MAAM,aAAa,GAA4B,EAAE,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEjC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC;YACzD,SAAS;QACX,CAAC;QAED,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACtD,SAAS;QACX,CAAC;QAED,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAEzC,IAAI,WAAW,EAAE,CAAC;YAChB,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,aAAa,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,CAChD,CAAC;IAEF,OAAO,aAAa,CAAC;AACvB,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CACnB,GAAY,EACZ,QAAgB,EAChB,IAAiB,EACS,EAAE;IAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACvD,MAAM,GAAG,GAA6B,EAAE,CAAC;IAEzC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEjC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YACjC,SAAS;QACX,CAAC;QAED,IACE,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,EACxE,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7C,SAAS;QACX,CAAC;QAED,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC;YAClD,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;SACzC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,GAAY,EACZ,YAAoB,EACpB,UAAgC,EACb,EAAE;IACrB,MAAM,OAAO,GAAG,CAAC,EAAU,EAAiB,EAAE;QAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC;QAE3C,OAAO,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;QACxC,UAAU;QACV,YAAY;QACZ,QAAQ,EAAE,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,QAAQ,IAAI,YAAY;QAC/D,OAAO,EAAE;YACP,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC;YAC/D,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;YAC/C,oBAAoB,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC;YACxE,KAAK,EAAE,OAAO,CAAC,0BAA0B,CAAC;YAC1C,GAAG,EAAE,OAAO,CAAC,yBAAyB,CAAC;YACvC,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC;YACrC,KAAK,EAAE,OAAO,CAAC,wBAAwB,CAAC;YACxC,YAAY,EAAE,OAAO,CAAC,aAAa,CAAC;YACpC,MAAM,EAAE,OAAO,CAAC,sBAAsB,CAAC;YACvC,KAAK,EAAE,OAAO,CAAC,2BAA2B,CAAC;SAC5C;QACD,aAAa,EAAE,eAAe,CAAC,GAAG,CAAC;QACnC,eAAe,EAAE,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,kBAAkB,CAAC;QAC7D,qBAAqB,EAAE,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,GAAG,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,sBAAsB,GAAG,KAAK,IAAiC,EAAE;IACrE,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC;QACvC,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAEnB,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF,qGAAqG;AACrG,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE;IAChC,IAAI,CAAC;QACH,MAAM,gBAAgB,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACpD,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAEvD,OAAO;YACL,UAAU,EAAE,gBAAgB,CAAC,OAAO;YACpC,MAAM,EAAE,cAAc,CAAC,MAAM;SAC9B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,0BAA0B,CAClC,mDAAmD,uBAAuB,EAAE,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,GAAW,EACX,OAAO,GAAyB,EAAE,EACN,EAAE;IAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;IAEtD,MAAM,UAAU,GACd,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1B,CAAC,MAAM,sBAAsB,EAAE,CAAC,CAAC;IAEnC,MAAM,aAAa,GAAwB;QACzC,WAAW,EAAE;YACX,gBAAgB;YAChB,gBAAgB;YAChB,eAAe;YACf,4BAA4B;SAC7B;QACD,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF,IAAI,UAAU,EAAE,CAAC;QACf,aAAa,CAAC,UAAU,GAAG,UAAU,CAAC;IACxC,CAAC;IAED,IAAI,MAA0C,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,0BAA0B,CAClC,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,uBAAuB,EAAE,CACjH,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;IAC/C,IAAI,KAAiC,CAAC;IAEtC,IAAI,CAAC;QACH,IAAI,MAAM,CAAC;QAEX,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,0CAA0C,CAAC,CAAC;YACzE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;QAC3B,CAAC;QAED,MAAM,KAAK,GAAoB;YAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM;YACd,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,CAAC,aAAa,EAAE,KAAK,EAAE,kBAAkB,CAAC;YAC1D,YAAY,EAAE,OAAO,CAAC,OAAO;SAC9B,CAAC;QAEF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,KAAK,CAAC,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;QAC9C,CAAC;QAED,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAE3C,uHAAuH;QACvH,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACtD,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,SAAS,KAAK,CAAC,CAAC,EACrE,SAAS,CACV,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;QAElD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,GAAG,GAAY,MAAM,CAAC,GAAG,CAAC;QAEhC,IAAI,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CACb,4BAA4B,GAAG,CAAC,YAAY,CAAC,IAAI,KAAK,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,CACjF,CAAC;QACJ,CAAC;QAED,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACzC,CAAC;YAAS,CAAC;QACT,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,MAAM,CAAC,IAAI,EAAE,CAAC;IAChB,CAAC;AACH,CAAC,CAAC"}

package/dist/core/performance-rules.d.ts

@@ -0,0 +1,3 @@
+import type { Finding, PerformanceResult, RuleMeta } from "./types.js";
+export declare const PERFORMANCE_RULES: RuleMeta[];
+export declare const performanceFindings: (result: PerformanceResult) => Finding[];

package/dist/core/performance-rules.js

@@ -0,0 +1,125 @@
+import { finding, GOOGLE_DOCS } from "./rules/rule.js";
+const meta = (id, severity, description, recommendation, docs = GOOGLE_DOCS.cwv) => ({
+    id,
+    category: "performance",
+    severity,
+    description,
+    recommendation,
+    docs,
+    requires: "lighthouse",
+});
+export const PERFORMANCE_RULES = [
+    meta("perf.lcp-slow", "warning", "Largest Contentful Paint above 2.5 s (poor above 4 s). Lab measurement from Lighthouse.", "Preload the LCP image/font, serve it from a CDN in a modern format, inline critical CSS, and cut server response time."),
+    meta("perf.cls-high", "warning", "Cumulative Layout Shift above 0.1 (poor above 0.25).", "Reserve space for images, ads and embeds with width/height or aspect-ratio; avoid inserting content above existing content; use font-display: optional or size-adjusted fallbacks."),
+    meta("perf.tbt-high", "warning", "Total Blocking Time above 200 ms (poor above 600 ms). Lab proxy for Interaction to Next Paint.", "Split long JavaScript tasks, defer non-critical scripts, remove unused JavaScript, and move work off the main thread."),
+    meta("perf.fcp-slow", "info", "First Contentful Paint above 1.8 s (poor above 3 s).", "Eliminate render-blocking resources, inline critical CSS, and reduce server response time."),
+    meta("perf.ttfb-slow", "warning", "Server response time (TTFB) above 800 ms.", "Cache HTML at the edge, avoid slow data fetches during render, and use a nearby region/CDN."),
+    meta("perf.score-low", "warning", "Lighthouse performance score below 50.", "Work through the opportunities listed in the performance result, biggest savings first."),
+    meta("perf.opportunity", "info", "A Lighthouse opportunity with measurable estimated savings.", "Apply the Lighthouse recommendation described in the finding."),
+    meta("lighthouse.seo-audit-failed", "warning", "A Lighthouse SEO audit failed (rendered-DOM checks such as crawlable anchors, robots.txt validity).", "Follow the Lighthouse audit description in the finding.", "https://developer.chrome.com/docs/lighthouse/seo/"),
+    meta("lighthouse.agentic-audit-failed", "info", "A Lighthouse agentic-browsing audit failed (llms.txt, accessibility tree quality, WebMCP). Experimental.", "Follow the Lighthouse audit description. These checks reflect how well AI agents can use the site and are not classic ranking factors.", "https://developer.chrome.com/docs/lighthouse/"),
+];
+const byId = new Map(PERFORMANCE_RULES.map((r) => [r.id, r]));
+const m = (id) => {
+    const rule = byId.get(id);
+    if (!rule) {
+        throw new Error(`Unknown performance rule: ${id}`);
+    }
+    return rule;
+};
+/** LCP, CLS and TBT against the Core Web Vitals thresholds. */
+const vitalsFindings = (result) => {
+    const out = [];
+    const add = (f) => out.push(f);
+    const { metrics } = result;
+    if (metrics.lcpMs !== null && metrics.lcpMs > 2500) {
+        add(finding(m("perf.lcp-slow"), `LCP is ${(metrics.lcpMs / 1000).toFixed(1)} s (${metrics.lcpMs > 4000 ? "poor" : "needs improvement"}).`, {
+            severity: metrics.lcpMs > 4000 ? "error" : "warning",
+            evidence: {
+                lcpMs: Math.round(metrics.lcpMs),
+                formFactor: result.formFactor,
+            },
+        }));
+    }
+    if (metrics.cls !== null && metrics.cls > 0.1) {
+        add(finding(m("perf.cls-high"), `CLS is ${metrics.cls.toFixed(3)} (${metrics.cls > 0.25 ? "poor" : "needs improvement"}).`, {
+            severity: metrics.cls > 0.25 ? "error" : "warning",
+            evidence: { cls: Number(metrics.cls.toFixed(3)) },
+        }));
+    }
+    if (metrics.tbtMs !== null && metrics.tbtMs > 200) {
+        add(finding(m("perf.tbt-high"), `TBT is ${Math.round(metrics.tbtMs)} ms (${metrics.tbtMs > 600 ? "poor" : "needs improvement"}).`, {
+            severity: metrics.tbtMs > 600 ? "error" : "warning",
+            evidence: { tbtMs: Math.round(metrics.tbtMs) },
+        }));
+    }
+    return out;
+};
+/** FCP, server response time and the overall Lighthouse score. */
+const timingFindings = (result) => {
+    const out = [];
+    const add = (f) => out.push(f);
+    const { metrics } = result;
+    if (metrics.fcpMs !== null && metrics.fcpMs > 1800) {
+        add(finding(m("perf.fcp-slow"), `FCP is ${(metrics.fcpMs / 1000).toFixed(1)} s.`, {
+            severity: metrics.fcpMs > 3000 ? "warning" : "info",
+            evidence: { fcpMs: Math.round(metrics.fcpMs) },
+        }));
+    }
+    if (metrics.ttfbMs !== null && metrics.ttfbMs > 800) {
+        add(finding(m("perf.ttfb-slow"), `Server response time is ${Math.round(metrics.ttfbMs)} ms.`, { evidence: { ttfbMs: Math.round(metrics.ttfbMs) } }));
+    }
+    if (metrics.performanceScore !== null && metrics.performanceScore < 50) {
+        add(finding(m("perf.score-low"), `Lighthouse performance score is ${metrics.performanceScore}/100.`, {
+            evidence: {
+                performanceScore: metrics.performanceScore,
+                formFactor: result.formFactor,
+            },
+        }));
+    }
+    return out;
+};
+/** Lighthouse opportunities and failed SEO and agentic-browsing audits. */
+const auditFindings = (result) => {
+    const out = [];
+    const add = (f) => out.push(f);
+    for (const opp of result.opportunities.slice(0, 8)) {
+        const savings = [
+            opp.savingsMs ? `${Math.round(opp.savingsMs)} ms` : null,
+            opp.savingsBytes ? `${Math.round(opp.savingsBytes / 1024)} KiB` : null,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        add(finding(m("perf.opportunity"), `${opp.title}${savings ? ` (est. savings ${savings})` : ""}.`, {
+            recommendation: opp.description,
+            evidence: {
+                auditId: opp.id,
+                savingsMs: opp.savingsMs,
+                savingsBytes: opp.savingsBytes,
+                score: opp.score,
+            },
+        }));
+    }
+    for (const audit of result.failedSeoAudits) {
+        add(finding(m("lighthouse.seo-audit-failed"), `Lighthouse SEO audit "${audit.title}" failed${audit.displayValue ? `: ${audit.displayValue}` : ""}.`, {
+            recommendation: audit.description,
+            evidence: { auditId: audit.id, score: audit.score },
+        }));
+    }
+    for (const audit of result.agenticBrowsingAudits) {
+        add(finding(m("lighthouse.agentic-audit-failed"), `Lighthouse agentic-browsing audit "${audit.title}" failed${audit.displayValue ? `: ${audit.displayValue}` : ""}.`, {
+            recommendation: audit.description,
+            evidence: { auditId: audit.id, score: audit.score },
+        }));
+    }
+    return out;
+};
+export const performanceFindings = (result) => {
+    const url = result.finalUrl || result.requestedUrl;
+    return [
+        ...vitalsFindings(result),
+        ...timingFindings(result),
+        ...auditFindings(result),
+    ].map((f) => ({ ...f, url }));
+};
+//# sourceMappingURL=performance-rules.js.map

package/dist/core/performance-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-rules.js","sourceRoot":"","sources":["../../src/core/performance-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/render-rules.d.ts

@@ -0,0 +1,8 @@
+import type { ExtractedPage, Finding, RenderComparison, RenderSnapshot, ResponseInfo, RuleMeta } from "./types.js";
+export declare const RENDER_RULES: RuleMeta[];
+export declare const snapshot: (page: ExtractedPage, response?: ResponseInfo) => RenderSnapshot;
+export interface RenderCompareResult {
+    comparison: RenderComparison;
+    findings: Finding[];
+}
+export declare const compareRender: (raw: ExtractedPage, rendered: ExtractedPage, renderedUrl: string, consoleErrors: string[], rawResponse?: ResponseInfo) => RenderCompareResult;

package/dist/core/render-rules.js

@@ -0,0 +1,144 @@
+import { robotsDirectives } from "./rules/indexing.js";
+import { finding, GOOGLE_DOCS } from "./rules/rule.js";
+const meta = (id, severity, description, recommendation) => ({
+    id,
+    category: "rendering",
+    severity,
+    description,
+    recommendation,
+    docs: GOOGLE_DOCS.javascript,
+    requires: "render",
+});
+const SSR_FIX = "Render this in the server HTML (SSR/SSG/prerender). Googlebot queues JavaScript rendering separately and other crawlers and link previews never run it.";
+export const RENDER_RULES = [
+    meta("rendering.title-client-only", "warning", "The <title> only exists after JavaScript runs.", SSR_FIX),
+    meta("rendering.title-changed", "info", "JavaScript changes the <title> after load.", "Make the server HTML title match the final title so both agree."),
+    meta("rendering.description-client-only", "warning", "The meta description only exists after JavaScript runs.", SSR_FIX),
+    meta("rendering.canonical-client-only", "warning", "The canonical link only exists after JavaScript runs.", SSR_FIX),
+    meta("rendering.canonical-changed", "warning", "JavaScript changes the canonical URL after load, sending conflicting signals.", "Emit the final canonical in the server HTML and do not modify it client-side."),
+    meta("rendering.noindex-client-only", "error", "A noindex directive is injected by JavaScript. Google applies it when it renders the page, which removes the page from the index.", "Remove the client-side noindex (often a framework/head-manager default or an auth guard) or move the decision to the server."),
+    meta("rendering.noindex-removed-by-js", "warning", "The server HTML says noindex but JavaScript removes it. Google honours the server noindex and skips rendering, so the page stays out of the index.", "Remove noindex from the server HTML if the page should be indexed."),
+    meta("rendering.h1-client-only", "warning", "The <h1> only exists after JavaScript runs.", SSR_FIX),
+    meta("rendering.content-client-only", "warning", "Most of the body text only exists after JavaScript runs.", SSR_FIX),
+    meta("rendering.links-client-only", "warning", "Most internal links only exist after JavaScript runs, delaying discovery of the linked pages.", `${SSR_FIX} At minimum, render the main navigation and content links server-side.`),
+    meta("rendering.structured-data-client-only", "info", "Structured data is only added by JavaScript.", "Google processes JSON-LD injected by JavaScript, but other consumers do not. Prefer emitting it in the server HTML."),
+    meta("rendering.console-errors", "info", "The page logged JavaScript errors while rendering.", "Fix runtime errors; a failing script can leave crawlers with an incomplete page."),
+];
+const byId = new Map(RENDER_RULES.map((r) => [r.id, r]));
+const m = (id) => {
+    const rule = byId.get(id);
+    if (!rule) {
+        throw new Error(`Unknown rendering rule: ${id}`);
+    }
+    return rule;
+};
+export const snapshot = (page, response) => ({
+    title: page.title,
+    metaDescription: page.metaDescription,
+    canonical: page.canonical,
+    robots: robotsDirectives(page, response).directives,
+    h1Count: page.h1s.filter(Boolean).length,
+    wordCount: page.wordCount,
+    internalLinks: page.links.filter((l) => l.internal).length,
+    structuredDataCount: page.structuredData.length,
+});
+/** Title, description, canonical and robots: what the head says before and after JavaScript runs. */
+const headFindings = (a, b) => {
+    const findings = [];
+    const add = (f) => findings.push(f);
+    if (!a.title && b.title) {
+        add(finding(m("rendering.title-client-only"), `Title "${b.title}" is only present after rendering.`, {
+            selector: "head > title",
+            evidence: { raw: a.title, rendered: b.title },
+        }));
+    }
+    else if (a.title && b.title && a.title !== b.title) {
+        add(finding(m("rendering.title-changed"), "Title differs between server HTML and rendered DOM.", {
+            selector: "head > title",
+            evidence: { raw: a.title, rendered: b.title },
+        }));
+    }
+    if (!a.metaDescription && b.metaDescription) {
+        add(finding(m("rendering.description-client-only"), "Meta description is only present after rendering.", {
+            selector: 'head > meta[name="description"]',
+            evidence: { rendered: b.metaDescription },
+        }));
+    }
+    if (!a.canonical && b.canonical) {
+        add(finding(m("rendering.canonical-client-only"), `Canonical ${b.canonical} is only present after rendering.`, {
+            selector: 'head > link[rel="canonical"]',
+            evidence: { rendered: b.canonical },
+        }));
+    }
+    else if (a.canonical && b.canonical && a.canonical !== b.canonical) {
+        add(finding(m("rendering.canonical-changed"), "Canonical differs between server HTML and rendered DOM.", {
+            selector: 'head > link[rel="canonical"]',
+            evidence: { raw: a.canonical, rendered: b.canonical },
+        }));
+    }
+    const rawNoindex = a.robots.some((d) => d === "noindex" || d === "none");
+    const renderedNoindex = b.robots.some((d) => d === "noindex" || d === "none");
+    if (!rawNoindex && renderedNoindex) {
+        add(finding(m("rendering.noindex-client-only"), "noindex is added by JavaScript.", {
+            selector: 'head > meta[name="robots"]',
+            evidence: { raw: a.robots, rendered: b.robots },
+        }));
+    }
+    if (rawNoindex && !renderedNoindex) {
+        add(finding(m("rendering.noindex-removed-by-js"), "Server HTML contains noindex; JavaScript removes it.", {
+            selector: 'head > meta[name="robots"]',
+            evidence: { raw: a.robots, rendered: b.robots },
+        }));
+    }
+    return findings;
+};
+/** H1, words, links, structured data and script errors: what only the rendered body has. */
+const bodyFindings = (a, b, consoleErrors) => {
+    const findings = [];
+    const add = (f) => findings.push(f);
+    if (a.h1Count === 0 && b.h1Count > 0) {
+        add(finding(m("rendering.h1-client-only"), "The <h1> is only present after rendering.", {
+            selector: "h1",
+            evidence: { rawH1Count: a.h1Count, renderedH1Count: b.h1Count },
+        }));
+    }
+    if (b.wordCount - a.wordCount >= 100 && a.wordCount < b.wordCount * 0.5) {
+        add(finding(m("rendering.content-client-only"), `Server HTML has ${a.wordCount} words; rendered DOM has ${b.wordCount}.`, { evidence: { rawWords: a.wordCount, renderedWords: b.wordCount } }));
+    }
+    if (b.internalLinks - a.internalLinks >= 10 &&
+        a.internalLinks < b.internalLinks * 0.5) {
+        add(finding(m("rendering.links-client-only"), `Server HTML has ${a.internalLinks} internal links; rendered DOM has ${b.internalLinks}.`, {
+            evidence: {
+                rawLinks: a.internalLinks,
+                renderedLinks: b.internalLinks,
+            },
+        }));
+    }
+    if (a.structuredDataCount === 0 && b.structuredDataCount > 0) {
+        add(finding(m("rendering.structured-data-client-only"), `${b.structuredDataCount} structured data item(s) are only present after rendering.`, { evidence: { renderedCount: b.structuredDataCount } }));
+    }
+    if (consoleErrors.length) {
+        add(finding(m("rendering.console-errors"), `${consoleErrors.length} JavaScript error(s) logged during render.`, { evidence: { errors: consoleErrors.slice(0, 5) } }));
+    }
+    return findings;
+};
+export const compareRender = (raw, rendered, renderedUrl, consoleErrors, rawResponse) => {
+    const a = snapshot(raw, rawResponse);
+    const b = snapshot(rendered);
+    const url = rawResponse?.finalUrl ?? raw.url;
+    const findings = [
+        ...headFindings(a, b),
+        ...bodyFindings(a, b, consoleErrors),
+    ].map((f) => ({ ...f, url }));
+    return {
+        comparison: {
+            tool: "playwright",
+            renderedUrl,
+            consoleErrors: consoleErrors.slice(0, 20),
+            raw: a,
+            rendered: b,
+        },
+        findings,
+    };
+};
+//# sourceMappingURL=render-rules.js.map

package/dist/core/render-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-rules.js","sourceRoot":"","sources":["../../src/core/render-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/render.d.ts

@@ -0,0 +1,22 @@
+export declare class RenderUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface RenderOptions {
+    timeoutMs?: number;
+    userAgent?: string;
+    headers?: Record<string, string>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Wait condition passed to Playwright. */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle";
+}
+export interface RenderOutput {
+    html: string;
+    finalUrl: string;
+    consoleErrors: string[];
+}
+export declare const RENDER_INSTALL_HINT = "Install Playwright to enable rendering: `pnpm add -D playwright && pnpm exec playwright install chromium` (or npm/npx equivalents).";
+/** Load the page in headless Chromium and return the rendered DOM. */
+export declare const renderPage: (url: string, options?: RenderOptions) => Promise<RenderOutput>;