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

package/dist/core/html/text.js

@@ -0,0 +1,149 @@
+/** Text analysis helpers: word counts, readability, placeholder detection. */
+const WORD_RE = /[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu;
+export function words(text) {
+    return text.match(WORD_RE) ?? [];
+}
+export function wordCount(text) {
+    return words(text).length;
+}
+export function collapseWhitespace(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+export function sentenceCount(text) {
+    const parts = text.split(/[.!?]+(?:\s+|$)/).filter((s) => s.trim().length > 0);
+    return Math.max(1, parts.length);
+}
+/** English syllable heuristic: vowel groups minus silent trailing e, min 1. */
+export function syllables(word) {
+    const w = word.toLowerCase().replace(/[^a-z]/g, '');
+    if (!w)
+        return 0;
+    if (w.length <= 3)
+        return 1;
+    let count = (w.replace(/e$/, '').match(/[aeiouy]+/g) ?? []).length;
+    if (/le$/.test(w) && !/[aeiouy]le$/.test(w))
+        count++;
+    return Math.max(1, count);
+}
+/**
+ * Flesch Reading Ease (English formula). Returns null when there is not enough text.
+ * 90-100 very easy, 60-70 plain English, 30-50 difficult, <30 very difficult.
+ */
+export function fleschReadingEase(text) {
+    const ws = words(text);
+    if (ws.length < 100)
+        return null;
+    const sentences = sentenceCount(text);
+    const syl = ws.reduce((sum, w) => sum + syllables(w), 0);
+    const score = 206.835 - 1.015 * (ws.length / sentences) - 84.6 * (syl / ws.length);
+    return Math.round(score * 10) / 10;
+}
+const PLACEHOLDER_RE = /lorem ipsum|dolor sit amet|consectetur adipiscing/i;
+export function hasPlaceholderText(text) {
+    return PLACEHOLDER_RE.test(text);
+}
+export const GENERIC_TITLES = new Set([
+    'home',
+    'homepage',
+    'index',
+    'untitled',
+    'untitled page',
+    'untitled document',
+    'document',
+    'new page',
+    'page',
+    'title',
+    'welcome',
+    'react app',
+    'vite app',
+    'vite + react',
+    'vite + react + ts',
+    'vite + vue',
+    'vite + svelte',
+    'create next app',
+    'next app',
+    'nuxt app',
+    'nuxt',
+    'astro',
+    'my app',
+    'my site',
+    'my website',
+    'website',
+    'default',
+    'test',
+    'hello world',
+    'svelte app',
+    'angular app',
+    'gatsby default starter',
+    'remix app',
+    'tanstack start starter',
+    'example',
+]);
+export function isGenericTitle(title) {
+    return GENERIC_TITLES.has(collapseWhitespace(title).toLowerCase());
+}
+export const GENERIC_ANCHORS = new Set([
+    'click here',
+    'here',
+    'read more',
+    'learn more',
+    'more',
+    'link',
+    'this',
+    'this page',
+    'continue',
+    'continue reading',
+    'details',
+    'more info',
+    'info',
+    'go',
+    'page',
+    'article',
+    'website',
+    'url',
+    'www',
+]);
+export function isGenericAnchor(text) {
+    const t = collapseWhitespace(text).toLowerCase().replace(/[.!…»›>]+$/, '').trim();
+    return GENERIC_ANCHORS.has(t);
+}
+export function normalizeForComparison(text) {
+    return collapseWhitespace(text).toLowerCase();
+}
+export function includesKeyword(haystack, keyword) {
+    if (!haystack)
+        return false;
+    return normalizeForComparison(haystack).includes(normalizeForComparison(keyword));
+}
+export function keywordOccurrences(text, keyword) {
+    const hay = normalizeForComparison(text);
+    const needle = normalizeForComparison(keyword);
+    if (!needle)
+        return 0;
+    let count = 0;
+    let idx = hay.indexOf(needle);
+    while (idx !== -1) {
+        count++;
+        idx = hay.indexOf(needle, idx + needle.length);
+    }
+    return count;
+}
+/** 5-word shingles for near-duplicate detection. */
+export function shingles(text, size = 5) {
+    const ws = words(normalizeForComparison(text));
+    const out = new Set();
+    for (let i = 0; i + size <= ws.length; i++)
+        out.add(ws.slice(i, i + size).join(' '));
+    return out;
+}
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    const [small, large] = a.size < b.size ? [a, b] : [b, a];
+    for (const s of small)
+        if (large.has(s))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+//# sourceMappingURL=text.js.map

package/dist/core/html/text.js.map

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

package/dist/core/lighthouse.d.ts

@@ -0,0 +1,49 @@
+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).";
+type LhrLike = {
+    lighthouseVersion: string;
+    requestedUrl?: string;
+    finalDisplayedUrl?: string;
+    finalUrl?: string;
+    runtimeError?: {
+        code: string;
+        message: string;
+    };
+    categories: Record<string, {
+        score: number | null;
+        auditRefs: {
+            id: string;
+            weight: number;
+            group?: string;
+        }[];
+    } | undefined>;
+    audits: Record<string, LhAudit | undefined>;
+};
+type 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;
+    };
+};
+export declare function runLighthouse(url: string, options?: LighthouseRunOptions): Promise<PerformanceResult>;
+export declare function summarize(lhr: LhrLike, requestedUrl: string, formFactor: 'mobile' | 'desktop'): PerformanceResult;
+export {};

package/dist/core/lighthouse.js

@@ -0,0 +1,140 @@
+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']);
+export async function runLighthouse(url, options = {}) {
+    const formFactor = options.formFactor ?? 'mobile';
+    let lighthouse;
+    let launch;
+    try {
+        lighthouse = (await import('lighthouse')).default;
+        launch = (await import('chrome-launcher')).launch;
+    }
+    catch {
+        throw new LighthouseUnavailableError(`Lighthouse or chrome-launcher is not installed. ${LIGHTHOUSE_INSTALL_HINT}`);
+    }
+    const chromePath = options.chromePath ?? process.env['CHROME_PATH'] ?? (await playwrightChromiumPath());
+    let chrome;
+    try {
+        chrome = await launch({
+            chromeFlags: ['--headless=new', '--no-first-run', '--disable-gpu', '--no-default-browser-check'],
+            ...(chromePath ? { chromePath } : {}),
+            logLevel: 'silent',
+        });
+    }
+    catch (err) {
+        throw new LighthouseUnavailableError(`Could not launch Chrome: ${err.message}. ${LIGHTHOUSE_INSTALL_HINT}`);
+    }
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    let timer;
+    try {
+        const config = formFactor === 'desktop' ? (await import('lighthouse/core/config/desktop-config.js')).default : undefined;
+        const flags = {
+            port: chrome.port,
+            output: 'json',
+            logLevel: 'silent',
+            onlyCategories: ['performance', 'seo', 'agentic-browsing'],
+            extraHeaders: options.headers,
+            ...(options.userAgent ? { emulatedUserAgent: options.userAgent } : {}),
+        };
+        const run = lighthouse(url, flags, config);
+        const timeout = new Promise((_, 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();
+    }
+}
+async function playwrightChromiumPath() {
+    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;
+    }
+}
+export function summarize(lhr, requestedUrl, formFactor) {
+    const numeric = (id) => {
+        const v = lhr.audits[id]?.numericValue;
+        return typeof v === 'number' && Number.isFinite(v) ? v : null;
+    };
+    const pct = (score) => (typeof score === 'number' ? Math.round(score * 100) : null);
+    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 savings = audit.metricSavings ?? {};
+        const msValues = ['LCP', 'FCP', 'TBT', 'INP', 'SI'].map((k) => savings[k]).filter((v) => typeof v === 'number' && v > 0);
+        const savingsMs = audit.details?.overallSavingsMs ?? (msValues.length ? Math.max(...msValues) : null);
+        const savingsBytes = audit.details?.overallSavingsBytes ?? null;
+        const hasSavings = (savingsMs ?? 0) > 0 || (savingsBytes ?? 0) > 0 || (typeof savings['CLS'] === 'number' && savings['CLS'] > 0) || audit.details?.type === 'opportunity';
+        if (!hasSavings)
+            continue;
+        opportunities.push({ id: audit.id, title: audit.title, description: stripMarkdownLinks(audit.description), score: audit.score, savingsMs: savingsMs ?? null, savingsBytes });
+    }
+    opportunities.sort((a, b) => (b.savingsMs ?? 0) - (a.savingsMs ?? 0) || (b.savingsBytes ?? 0) - (a.savingsBytes ?? 0));
+    const failed = (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;
+    };
+    return {
+        tool: 'lighthouse',
+        lighthouseVersion: lhr.lighthouseVersion,
+        formFactor,
+        requestedUrl,
+        finalUrl: lhr.finalDisplayedUrl ?? lhr.finalUrl ?? requestedUrl,
+        metrics: {
+            performanceScore: pct(lhr.categories['performance']?.score),
+            seoScore: pct(lhr.categories['seo']?.score),
+            agenticBrowsingScore: pct(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,
+        failedSeoAudits: failed('seo', COVERED_SEO_AUDITS),
+        agenticBrowsingAudits: failed('agentic-browsing', new Set()),
+    };
+}
+function stripMarkdownLinks(text) {
+    return text.replace(/\[([^\]]+)\]\((https?:[^)]+)\)/g, '$1 ($2)').trim();
+}
+//# 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":"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"}

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 function performanceFindings(result: PerformanceResult): Finding[];

package/dist/core/performance-rules.js

@@ -0,0 +1,53 @@
+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) => byId.get(id);
+export function performanceFindings(result) {
+    const out = [];
+    const url = result.finalUrl || result.requestedUrl;
+    const add = (f) => out.push({ ...f, url });
+    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) } }));
+    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 } }));
+    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;
+}
+//# 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,7 @@
+import type { ExtractedPage, Finding, RenderComparison, RenderSnapshot, ResponseInfo, RuleMeta } from './types.js';
+export declare const RENDER_RULES: RuleMeta[];
+export declare function snapshot(page: ExtractedPage, response?: ResponseInfo): RenderSnapshot;
+export declare function compareRender(raw: ExtractedPage, rendered: ExtractedPage, renderedUrl: string, consoleErrors: string[], rawResponse?: ResponseInfo): {
+    comparison: RenderComparison;
+    findings: Finding[];
+};

package/dist/core/render-rules.js

@@ -0,0 +1,77 @@
+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) => byId.get(id);
+export function snapshot(page, response) {
+    return {
+        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,
+    };
+}
+export function compareRender(raw, rendered, renderedUrl, consoleErrors, rawResponse) {
+    const a = snapshot(raw, rawResponse);
+    const b = snapshot(rendered);
+    const findings = [];
+    const url = rawResponse?.finalUrl ?? raw.url;
+    const add = (f) => findings.push({ ...f, url });
+    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 } }));
+    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 { 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 function renderPage(url: string, options?: RenderOptions): Promise<RenderOutput>;

package/dist/core/render.js

@@ -0,0 +1,73 @@
+import { DEFAULT_USER_AGENT } from './fetch.js';
+export class RenderUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RenderUnavailableError';
+    }
+}
+export const RENDER_INSTALL_HINT = 'Install Playwright to enable rendering: `pnpm add -D playwright && pnpm exec playwright install chromium` (or npm/npx equivalents).';
+async function launchSystemBrowser(playwright) {
+    for (const channel of ['chrome', 'msedge']) {
+        try {
+            return await playwright.chromium.launch({ headless: true, channel });
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+function firstLine(message) {
+    return message.split('\n')[0] ?? message;
+}
+/** Load the page in headless Chromium and return the rendered DOM. */
+export async function renderPage(url, options = {}) {
+    let playwright;
+    try {
+        playwright = await import('playwright');
+    }
+    catch {
+        throw new RenderUnavailableError(`Playwright is not installed. ${RENDER_INSTALL_HINT}`);
+    }
+    let browser;
+    try {
+        browser = await playwright.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        // No downloaded Playwright browser: fall back to an installed Google Chrome / Edge.
+        const fallback = await launchSystemBrowser(playwright);
+        if (!fallback)
+            throw new RenderUnavailableError(`Could not launch Chromium: ${firstLine(err.message)}. ${RENDER_INSTALL_HINT}`);
+        browser = fallback;
+    }
+    const timeout = options.timeoutMs ?? 30_000;
+    const consoleErrors = [];
+    try {
+        const context = await browser.newContext({
+            userAgent: options.userAgent ?? DEFAULT_USER_AGENT,
+            viewport: options.viewport ?? { width: 1366, height: 900 },
+            extraHTTPHeaders: options.headers,
+        });
+        const page = await context.newPage();
+        page.on('console', (msg) => {
+            if (msg.type() === 'error')
+                consoleErrors.push(msg.text().slice(0, 300));
+        });
+        page.on('pageerror', (err) => consoleErrors.push(err.message.slice(0, 300)));
+        try {
+            await page.goto(url, { waitUntil: options.waitUntil ?? 'networkidle', timeout });
+        }
+        catch (err) {
+            // networkidle can time out on pages with long-polling; fall back to whatever has loaded.
+            if (!(err instanceof Error) || !/Timeout/i.test(err.message))
+                throw err;
+        }
+        await page.waitForTimeout(250);
+        const html = await page.content();
+        return { html, finalUrl: page.url(), consoleErrors };
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=render.js.map