@aexol/spectral 0.9.42 → 0.9.44

package/dist/extensions/seo/tools/keywords.js

@@ -0,0 +1,234 @@
+import { fetchPage } from "../utils/fetcher.js";
+import { parsePage, extractText } from "../utils/parser.js";
+import { analyzeKeywords, analyzeKeywordDensity } from "../analyzers/keywords.js";
+import { analyzeReadability, interpretReadability } from "../analyzers/readability.js";
+import { optimizeContent } from "../analyzers/content-optimize.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerKeywordTools(ext, config) {
+    // === seo_keywords ===
+    const keywordsTool = {
+        name: "seo_keywords",
+        label: "SEO Keyword Analysis",
+        description: "Extract keywords from page content using TF-IDF analysis. " +
+            "Returns top keywords with density scores, n-gram phrases (bigrams and trigrams), " +
+            "and search intent classification (informational, commercial, transactional). " +
+            "Detects keyword stuffing when keyword density exceeds 3%. " +
+            "All analysis is offline — no external API keys required.",
+        promptSnippet: "`seo_keywords { url? | text? }` — extract keywords, n-grams, and search intent from content",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze. If provided, text is extracted from the page." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const { url, text } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content) {
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                }
+                const analysis = analyzeKeywords(content, resolvedUrl);
+                const lines = [
+                    `✓ Keyword Analysis: ${resolvedUrl || "(text)"}`,
+                    ``,
+                    `Total words: ${analysis.totalWords}`,
+                    `Search intent: ${analysis.searchIntent} (confidence: ${(analysis.intentConfidence * 100).toFixed(0)}%)`,
+                    ``,
+                    `Top Keywords (by TF-IDF):`,
+                ];
+                for (const kw of analysis.keywords.slice(0, 15)) {
+                    lines.push(`  "${kw.keyword}" — ${kw.count}x, density ${kw.density}%, TF-IDF ${kw.tfidf}` +
+                        (kw.variants.length > 0 ? `, variants: ${kw.variants.join(", ")}` : ""));
+                }
+                if (analysis.topNgrams.length > 0) {
+                    lines.push(``, `Top Phrases (n-grams):`);
+                    for (const ng of analysis.topNgrams.slice(0, 10)) {
+                        lines.push(`  "${ng.ngram}" — ${ng.count}x`);
+                    }
+                }
+                if (analysis.keywordStuffingFlags.length > 0) {
+                    lines.push(``, `⚠ Keyword Stuffing Warnings:`);
+                    for (const flag of analysis.keywordStuffingFlags) {
+                        lines.push(`  ${flag}`);
+                    }
+                }
+                return textResult(lines.join("\n"), { analysis });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_keyword_density ===
+    const densityTool = {
+        name: "seo_keyword_density",
+        label: "SEO Keyword Density Check",
+        description: "Check the density of specific target keywords on a page. " +
+            "Provides count, density percentage, and a verdict for each keyword " +
+            "(too low, optimal, acceptable, or too high/possible stuffing). " +
+            "Use this to verify your target keywords are present at appropriate levels.",
+        promptSnippet: "`seo_keyword_density { url? | text?, keywords[] }` — check density of target keywords",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+                keywords: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Target keywords to check density for.",
+                },
+            },
+            required: ["keywords"],
+        },
+        async execute(_toolCallId, params) {
+            const { url, text, keywords } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content)
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                if (!keywords || keywords.length === 0)
+                    return errorResult("At least one keyword is required.");
+                const results = analyzeKeywordDensity(content, keywords);
+                const lines = [
+                    `✓ Keyword Density: ${resolvedUrl || "(text)"}`,
+                    ``,
+                ];
+                for (const r of results) {
+                    lines.push(`  "${r.keyword}": ${r.count}x, ${r.density}% — ${r.verdict}`);
+                }
+                return textResult(lines.join("\n"), { results });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_readability ===
+    const readabilityTool = {
+        name: "seo_readability",
+        label: "SEO Readability Analysis",
+        description: "Analyze text readability using multiple formulas: Flesch-Kincaid Grade Level, " +
+            "Flesch Reading Ease, SMOG Index, Automated Readability Index (ARI), and Coleman-Liau Index. " +
+            "Returns grade-level averages and SEO-specific readability advice. " +
+            "Helps ensure content targets the right audience level.",
+        promptSnippet: "`seo_readability { url? | text? }` — analyze content readability",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and analyze." },
+                text: { type: "string", description: "Raw text to analyze. Used if 'url' is not provided." },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const { url, text } = params;
+            try {
+                let content = text;
+                let resolvedUrl = url ?? "";
+                if (url) {
+                    const result = await fetchPage(url, config);
+                    content = extractText(result.content);
+                    resolvedUrl = result.finalUrl;
+                }
+                if (!content)
+                    return errorResult("Either 'url' or 'text' must be provided.");
+                const result = analyzeReadability(content, resolvedUrl);
+                const interpretation = interpretReadability(result);
+                const lines = [
+                    `✓ Readability Analysis: ${resolvedUrl || "(text)"}`,
+                    ``,
+                    `Words: ${content.split(/\s+/).filter(Boolean).length}`,
+                    `Sentences: ${result.sentenceCount}`,
+                    `Syllables: ${result.syllableCount}`,
+                    `Complex words (3+ syllables): ${result.complexWordCount}`,
+                    ``,
+                    `Readability Scores:`,
+                    `  Flesch Reading Ease: ${result.fleschReadingEase}`,
+                    `  Flesch-Kincaid Grade: ${result.fleschKincaid}`,
+                    `  SMOG Index: ${result.smog}`,
+                    `  ARI (Automated Readability): ${result.ari}`,
+                    `  Coleman-Liau: ${result.colemanLiau}`,
+                    `  Average Grade Level: ${result.gradeAverage}`,
+                    ``,
+                    `Interpretation: ${interpretation}`,
+                ];
+                return textResult(lines.join("\n"), { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_content_optimize ===
+    const optimizeTool = {
+        name: "seo_content_optimize",
+        label: "SEO Content Optimization",
+        description: "Analyze on-page content optimization opportunities. Checks title length (ideal 50-60 chars), " +
+            "meta description length (ideal 150-160 chars), heading hierarchy (H1→H2→H3 structure), " +
+            "content length (minimum 300 words), duplicate title/description, and suspicious headings. " +
+            "Returns a score for each category with specific, actionable recommendations.",
+        promptSnippet: "`seo_content_optimize { url }` — content optimization audit with actionable fixes",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
+                const result = optimizeContent(pageData);
+                const lines = [
+                    `✓ Content Optimization: ${result.url}`,
+                    ``,
+                    `Overall Score: ${result.overallScore}/100`,
+                    ``,
+                    `Category Scores:`,
+                    `  Title: ${result.titleScore}/100`,
+                    `  Meta Description: ${result.descriptionScore}/100`,
+                    `  Heading Structure: ${result.headingStructureScore}/100`,
+                    `  Content Length: ${result.contentLengthScore}/100`,
+                    ``,
+                ];
+                if (result.issues.length > 0) {
+                    const sorted = result.issues.sort((a, b) => {
+                        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+                        return (rank[a.severity] ?? 4) - (rank[b.severity] ?? 4);
+                    });
+                    lines.push(`Issues (${result.issues.length}):`);
+                    for (const issue of sorted) {
+                        lines.push(`  [${issue.severity.toUpperCase()}] ${issue.category}: ${issue.issue}`, `    → ${issue.recommendation}`);
+                    }
+                }
+                else {
+                    lines.push(`No issues found — content is well-optimized!`);
+                }
+                return textResult(lines.join("\n"), { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(keywordsTool);
+    ext.registerTool(densityTool);
+    ext.registerTool(readabilityTool);
+    ext.registerTool(optimizeTool);
+}

package/dist/extensions/seo/tools/parasite.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_parasite_risk tool — parasite-SEO risk scanner.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerParasiteTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=parasite.d.ts.map

package/dist/extensions/seo/tools/parasite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parasite.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/parasite.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0DhF"}

package/dist/extensions/seo/tools/parasite.js

@@ -0,0 +1,53 @@
+import { scanParasiteRisk } from "../analyzers/parasite.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerParasiteTools(ext, config) {
+    const parasiteTool = {
+        name: "seo_parasite_risk",
+        label: "SEO Parasite Risk",
+        description: "Scan a list of URLs from one host for parasite-SEO risk. Fetches each URL and classifies content " +
+            "by subfolder, flagging section-level risk via: third-party byline patterns (Partner Content, Sponsored, " +
+            "Brand Studio), commercial-intent patterns (Buy Now, Promo Code, Coupon), and affiliate link markers " +
+            "(tag=, aff_id=, ref_=). Returns per-subfolder risk classification (high/medium/low). " +
+            "Per Google's 2024-11-19 policy, section-level manual actions target this pattern.",
+        promptSnippet: "`seo_parasite_risk { urls }` — scan URLs for parasite-SEO risk per subfolder",
+        parameters: {
+            type: "object",
+            properties: {
+                urls: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "List of URLs from one host to scan. Typically obtained from sitemap sampling.",
+                },
+            },
+            required: ["urls"],
+        },
+        async execute(_toolCallId, params) {
+            const { urls } = params;
+            try {
+                if (!urls || urls.length === 0) {
+                    return errorResult("At least one URL is required.");
+                }
+                const result = await scanParasiteRisk(urls, config);
+                const sectionLines = result.sections
+                    .sort((a, b) => {
+                    const rank = { high: 0, medium: 1, low: 2 };
+                    return rank[a.risk] - rank[b.risk];
+                })
+                    .map((s) => `  [${s.risk.toUpperCase()}] ${s.section} (${s.pageCount} pages) — ` +
+                    `3rd-party: ${s.thirdPartyHitsPerPage}/page, commerce: ${s.commerceHitsPerPage}/page, ` +
+                    `affiliate: ${s.affiliateLinkHitsPerPage}/page` +
+                    (s.flags.length > 0 ? ` [${s.flags.join(", ")}]` : ""))
+                    .join("\n");
+                const summary = `✓ Parasite Risk Scan: ${result.host}\n` +
+                    `Total Pages: ${result.totalPages}\n` +
+                    `Sections Scanned: ${result.sections.length}\n\n` +
+                    `Section Risk:\n${sectionLines}`;
+                return textResult(summary, { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(parasiteTool);
+}

package/dist/extensions/seo/tools/parse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_parse_page tool — extract on-page SEO data from HTML.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerParseTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=parse.d.ts.map

package/dist/extensions/seo/tools/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0E7E"}

package/dist/extensions/seo/tools/parse.js

@@ -0,0 +1,66 @@
+import { fetchPage } from "../utils/fetcher.js";
+import { parsePage } from "../utils/parser.js";
+import { errorResult, textResult, truncate } from "./helpers.js";
+export function registerParseTools(ext, config) {
+    const parseTool = {
+        name: "seo_parse_page",
+        label: "SEO Parse Page",
+        description: "Parse HTML and extract all on-page SEO elements: title, meta description, meta robots, canonical, " +
+            "headings (H1-H6 with suspicious-heading detection), images (with lazy-loading method), links (internal/external), " +
+            "JSON-LD schema blocks, Open Graph tags, Twitter Card tags, hreflang, word count, language, and viewport. " +
+            "Accepts either a URL (fetches the page) or raw HTML.",
+        promptSnippet: "`seo_parse_page { url? | html?, baseUrl? }` — extract on-page SEO elements from HTML",
+        promptGuidelines: [
+            "When the user asks about SEO, search optimization, page audits, schema markup, sitemaps, or technical SEO for any website or URL, use the seo_* tools (seo_fetch, seo_parse_page, seo_technical_audit, seo_content_quality, seo_schema_audit, seo_image_audit, seo_preload_audit, seo_agent_ux_audit, seo_audit, etc.). These are offline-first and require no API keys.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch and parse. If provided, HTML is fetched automatically." },
+                html: { type: "string", description: "Raw HTML to parse. Used if 'url' is not provided." },
+                baseUrl: { type: "string", description: "Base URL for resolving relative links. Defaults to 'url' if provided." },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const { url, html, baseUrl } = params;
+            try {
+                let content = html ?? "";
+                let effectiveUrl = url ?? baseUrl ?? "";
+                if (url && !html) {
+                    const result = await fetchPage(url, config);
+                    if (result.error) {
+                        return errorResult(`Fetch failed: ${result.error}`);
+                    }
+                    content = result.content;
+                    effectiveUrl = result.finalUrl;
+                }
+                if (!content) {
+                    return errorResult("Either 'url' or 'html' must be provided.");
+                }
+                const pageData = parsePage(content, effectiveUrl, baseUrl);
+                const summary = `✓ Parsed: ${effectiveUrl}\n` +
+                    `Title: ${pageData.title ?? "(none)"} (${pageData.titleLength} chars)\n` +
+                    `Meta Description: ${pageData.metaDescription ? `${pageData.metaDescriptionLength} chars` : "(none)"}\n` +
+                    `Canonical: ${pageData.canonical ?? "(none)"}\n` +
+                    `Headings: H1=${pageData.h1Count}, H2=${pageData.h2Count}, H3=${pageData.h3Count}\n` +
+                    `Images: ${pageData.images.length} (${pageData.images.filter((i) => !i.alt).length} missing alt)\n` +
+                    `Links: ${pageData.internalLinkCount} internal, ${pageData.externalLinkCount} external\n` +
+                    `Schema blocks: ${pageData.schemaBlocks.length}\n` +
+                    `Hreflang: ${pageData.hreflang.length}\n` +
+                    `Word count: ${pageData.wordCount}`;
+                return textResult(summary, {
+                    ...pageData,
+                    // Truncate large arrays to avoid token bloat.
+                    headings: truncate(JSON.stringify(pageData.headings), 10_000),
+                    links: truncate(JSON.stringify(pageData.links), 10_000),
+                    images: truncate(JSON.stringify(pageData.images), 10_000),
+                    schemaBlocks: truncate(JSON.stringify(pageData.schemaBlocks), 10_000),
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(parseTool);
+}

package/dist/extensions/seo/tools/performance.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerPerformanceTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=performance.d.ts.map

package/dist/extensions/seo/tools/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/performance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAW9C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA4NnF"}

package/dist/extensions/seo/tools/performance.js

@@ -0,0 +1,201 @@
+import { fetchPage } from "../utils/fetcher.js";
+import { calculatePerformanceFromFetch, analyzePageWeight, analyzeRenderBlocking, analyzeFonts, } from "../analyzers/performance.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerPerformanceTools(ext, config) {
+    // === seo_performance ===
+    const perfTool = {
+        name: "seo_performance",
+        label: "SEO Performance Audit (Core Web Vitals)",
+        description: "Estimate Core Web Vitals metrics from page structure analysis. " +
+            "Reports LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift), TBT (Total Blocking Time), FCP, and TTFB. " +
+            "Each metric is rated: good, needs-improvement, or poor against Google's thresholds. " +
+            "Note: These are heuristic estimates based on page complexity. For accurate numbers use Lighthouse or PageSpeed Insights.",
+        promptSnippet: "`seo_performance { url }` — estimate Core Web Vitals (LCP, CLS, TBT) with ratings",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const perf = calculatePerformanceFromFetch(fetchResult, url);
+                const lines = [
+                    `✓ Performance Estimate: ${perf.url}`,
+                    ``,
+                    `Overall CWV Score: ${perf.score}/100`,
+                    ``,
+                    `Core Web Vitals:`,
+                    `  LCP: ${perf.lcp.value}ms — ${perf.lcp.rating.toUpperCase()}`,
+                    `  CLS: ${perf.cls.value} — ${perf.cls.rating.toUpperCase()}`,
+                    `  TBT: ${perf.tbt.value}ms — ${perf.tbt.rating.toUpperCase()}`,
+                    ``,
+                    `Other Metrics:`,
+                    `  FCP: ${perf.fcp}ms`,
+                    `  TTFB: ${perf.ttfb}ms`,
+                    ``,
+                    `Google Thresholds:`,
+                    `  LCP: good ≤ 2500ms, poor > 4000ms`,
+                    `  CLS: good ≤ 0.1, poor > 0.25`,
+                    `  TBT: good ≤ 200ms, poor > 600ms`,
+                ];
+                return textResult(lines.join("\n"), { perf });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_page_weight ===
+    const weightTool = {
+        name: "seo_page_weight",
+        label: "SEO Page Weight Analysis",
+        description: "Analyze total page weight and resource breakdown (HTML, CSS, JS, images, fonts). " +
+            "Identifies heavy resources that slow down page load. " +
+            "Helps find optimization opportunities: large images, bloated CSS/JS bundles, heavy fonts.",
+        promptSnippet: "`seo_page_weight { url }` — analyze page weight by resource type",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const weight = analyzePageWeight(fetchResult, url);
+                const lines = [
+                    `✓ Page Weight: ${weight.url}`,
+                    ``,
+                    `Total weight: ~${weight.totalKb} KB`,
+                    `  HTML: ${weight.htmlKb} KB`,
+                    `  CSS:  ${weight.cssKb} KB`,
+                    `  JS:   ${weight.jsKb} KB`,
+                    `  Images: ${weight.imageKb} KB`,
+                    `  Fonts: ${weight.fontKb} KB`,
+                    ``,
+                    `Resource count: ${weight.resourceCount}`,
+                ];
+                if (weight.topHeavyResources.length > 0) {
+                    lines.push(``, `Heaviest resources:`);
+                    for (const r of weight.topHeavyResources) {
+                        lines.push(`  ${r.type.toUpperCase()}: ${r.sizeKb} KB — ${r.url}`);
+                    }
+                }
+                if (weight.totalKb > 5000) {
+                    lines.push(``, `⚠ Page exceeds 5MB — may impact mobile performance.`);
+                }
+                else if (weight.totalKb > 2000) {
+                    lines.push(``, `⚡ Page weight is above average. Consider optimizing assets.`);
+                }
+                return textResult(lines.join("\n"), { weight });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_render_blocking ===
+    const blockingTool = {
+        name: "seo_render_blocking",
+        label: "SEO Render-Blocking Resource Audit",
+        description: "Detect render-blocking CSS and JavaScript in the <head> that delay First Paint. " +
+            "Lists blocking stylesheets and scripts with recommendations: inline critical CSS, " +
+            "add async/defer to scripts, code-split bundles.",
+        promptSnippet: "`seo_render_blocking { url }` — find render-blocking CSS/JS with fixes",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const blocking = analyzeRenderBlocking(fetchResult, url);
+                const lines = [
+                    `✓ Render-Blocking Resources: ${blocking.url}`,
+                    ``,
+                    `Blocking CSS: ${blocking.blockingCss.length}`,
+                    `Blocking JS: ${blocking.blockingJs.length}`,
+                    `Total blocking: ${blocking.totalBlockingUrls}`,
+                    ``,
+                ];
+                if (blocking.blockingCss.length > 0) {
+                    lines.push(`Blocking Stylesheets:`);
+                    for (const css of blocking.blockingCss) {
+                        lines.push(`  ${css.href}`);
+                    }
+                }
+                if (blocking.blockingJs.length > 0) {
+                    lines.push(`Blocking Scripts:`);
+                    for (const js of blocking.blockingJs) {
+                        lines.push(`  ${js.src}`);
+                    }
+                }
+                lines.push(``, `Recommendations:`);
+                for (const rec of blocking.recommendations) {
+                    lines.push(`  • ${rec}`);
+                }
+                return textResult(lines.join("\n"), { blocking });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // === seo_font_audit ===
+    const fontTool = {
+        name: "seo_font_audit",
+        label: "SEO Font Optimization Audit",
+        description: "Audit web fonts for performance best practices. Checks: font-display setting (prevents invisible text), " +
+            "format (WOFF2 preferred), subsetting (unicode-range), and counts Google Fonts vs self-hosted fonts. " +
+            "Fonts directly impact LCP and CLS scores.",
+        promptSnippet: "`seo_font_audit { url }` — audit font loading strategy",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const fonts = analyzeFonts(fetchResult, url);
+                const lines = [
+                    `✓ Font Audit: ${fonts.url}`,
+                    ``,
+                    `Fonts found: ${fonts.fontsFound.length}`,
+                    `Score: ${fonts.score}/100`,
+                    ``,
+                ];
+                for (const f of fonts.fontsFound) {
+                    lines.push(`  "${f.family}" — ${f.source} (${f.format})` +
+                        ` | display: ${f.hasDisplay ? "✓" : "✗"}` +
+                        ` | subset: ${f.isSubset ? "✓" : "✗"}`);
+                }
+                lines.push(``, `Recommendations:`);
+                for (const rec of fonts.recommendations) {
+                    lines.push(`  • ${rec}`);
+                }
+                return textResult(lines.join("\n"), { fonts });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(perfTool);
+    ext.registerTool(weightTool);
+    ext.registerTool(blockingTool);
+    ext.registerTool(fontTool);
+}

package/dist/extensions/seo/tools/preload.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_preload_audit tool — Speculation Rules / bfcache / preload audit.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerPreloadTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=preload.d.ts.map

package/dist/extensions/seo/tools/preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/preload.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAK9C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAoD/E"}

package/dist/extensions/seo/tools/preload.js

@@ -0,0 +1,52 @@
+import { auditPreload } from "../analyzers/preload.js";
+import { fetchPage } from "../utils/fetcher.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerPreloadTools(ext, config) {
+    const preloadTool = {
+        name: "seo_preload_audit",
+        label: "SEO Preload Audit",
+        description: "Audit a page's HTML and response headers for preload mechanisms Google rewards in 2025-2026: " +
+            "Speculation Rules API (inline blocks + Speculation-Rules header), <link rel=preload> hints, " +
+            "deprecated <link rel=prerender>, bfcache signals (Cache-Control: no-store, unload/beforeunload listeners), " +
+            "and LCP fetchpriority hints. Returns a 0-100 score and actionable recommendations.",
+        promptSnippet: "`seo_preload_audit { url }` — audit speculation rules, preload, bfcache, LCP hints",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to audit for preload/bfcache signals." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const result = await fetchPage(url, config);
+                if (result.error) {
+                    return errorResult(`Fetch failed: ${result.error}`);
+                }
+                const audit = auditPreload(result);
+                const summary = `✓ Preload Audit: ${result.finalUrl}\n` +
+                    `Score: ${audit.score}/100\n\n` +
+                    `Speculation Rules:\n` +
+                    `  Inline blocks: ${audit.speculationRules.inlineBlocks}\n` +
+                    `  Header present: ${audit.speculationRules.headerPresent ? "✓" : "✗"}\n` +
+                    `  Actions: ${audit.speculationRules.actions.join(", ") || "(none)"}\n\n` +
+                    `Preload hints: ${audit.preloadHints}\n` +
+                    `Deprecated prerender links: ${audit.prerenderLinks}\n\n` +
+                    `bfcache Signals:\n` +
+                    `  Cache-Control: no-store: ${audit.bfcacheSignals.cacheControlNoStore ? "⚠️" : "✓"}\n` +
+                    `  unload listener: ${audit.bfcacheSignals.unloadListener ? "⚠️" : "✓"}\n` +
+                    `  beforeunload listener: ${audit.bfcacheSignals.beforeunloadListener ? "⚠️" : "✓"}\n\n` +
+                    `LCP Hints:\n` +
+                    `  fetchpriority="high" on LCP candidate: ${audit.lcpResourceHints.preloadLcpCandidate ? "✓" : "✗"}\n` +
+                    `  fetchpriority="high" count: ${audit.lcpResourceHints.fetchpriorityHigh}\n\n` +
+                    `Recommendations:\n${audit.recommendations.map((r) => `  • ${r}`).join("\n") || "  (none)"}`;
+                return textResult(summary, { audit });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(preloadTool);
+}

package/dist/extensions/seo/tools/report.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerReportTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=report.d.ts.map