cbrowser 18.13.4 → 18.14.0

package/dist/remediation/structured-data.js

@@ -0,0 +1,352 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Structured Data Suggester
+ *
+ * Recommends Schema.org JSON-LD structured data based on detected page content.
+ * Helps sites become more machine-readable for AI agents.
+ *
+ * @since 17.0.0
+ */
+import { chromium } from "playwright";
+/**
+ * Extract signals from a page for type detection
+ */
+async function extractPageSignals(page, url) {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
+    const signals = await page.evaluate(() => {
+        const title = document.querySelector("title")?.textContent?.trim() || "";
+        // Check for article indicators
+        const hasArticleTag = !!document.querySelector("article");
+        const hasPublishDate = !!(document.querySelector('time[datetime], [class*="publish"], [class*="date"], meta[property="article:published_time"]'));
+        const hasAuthor = !!(document.querySelector('[rel="author"], [class*="author"], [class*="byline"], meta[name="author"]'));
+        // Check for product indicators
+        const hasPrice = !!(document.querySelector('[class*="price"], [itemprop="price"], .price'));
+        const hasAddToCart = !!(document.querySelector('[class*="add-to-cart"], [class*="addtocart"], button:has-text("Add to Cart"), button:has-text("Buy")'));
+        const hasProductSchema = !!(document.querySelector('script[type="application/ld+json"]')?.textContent?.includes('"@type":"Product"') ||
+            document.querySelector('[itemtype*="Product"]'));
+        // Check for FAQ indicators
+        const hasFaqSection = !!(document.querySelector('[class*="faq"], details, [itemtype*="FAQPage"]') ||
+            document.querySelector("h2, h3")?.textContent?.toLowerCase().includes("faq"));
+        // Check for how-to/steps
+        const hasStepsList = !!(document.querySelector('[class*="step"], ol li, [itemtype*="HowTo"]'));
+        // Check for event indicators
+        const hasEventDate = !!(document.querySelector('[class*="event-date"], [itemtype*="Event"], time[datetime]')?.closest('[class*="event"]'));
+        // Check for local business indicators
+        const hasAddress = !!(document.querySelector('[class*="address"], address, [itemprop="address"]'));
+        const hasPhone = !!(document.querySelector('a[href^="tel:"], [itemprop="telephone"]'));
+        // Get og:type
+        const ogType = document.querySelector('meta[property="og:type"]')?.getAttribute("content") || undefined;
+        // Check for existing schema
+        const schemaScripts = document.querySelectorAll('script[type="application/ld+json"]');
+        const existingSchema = [];
+        schemaScripts.forEach((script) => {
+            try {
+                const json = JSON.parse(script.textContent || "{}");
+                if (json["@type"]) {
+                    existingSchema.push(json["@type"]);
+                }
+                else if (Array.isArray(json)) {
+                    json.forEach((item) => {
+                        if (item["@type"])
+                            existingSchema.push(item["@type"]);
+                    });
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        });
+        // Check if homepage
+        const isHomepage = window.location.pathname === "/" || window.location.pathname === "";
+        return {
+            title,
+            hasArticleTag,
+            hasProductSchema,
+            hasPrice,
+            hasAddToCart,
+            hasPublishDate,
+            hasAuthor,
+            hasFaqSection,
+            hasStepsList,
+            hasEventDate,
+            hasAddress,
+            hasPhone,
+            isHomepage,
+            ogType,
+            existingSchema,
+        };
+    });
+    return { ...signals, url };
+}
+/**
+ * Detect page type from signals
+ */
+export function detectPageType(signals) {
+    // Score each type based on signals
+    const scores = {
+        homepage: 0,
+        article: 0,
+        product: 0,
+        organization: 0,
+        person: 0,
+        event: 0,
+        faq: 0,
+        howto: 0,
+        recipe: 0,
+        "local-business": 0,
+        unknown: 0.1, // Base score for unknown
+    };
+    // Homepage detection
+    if (signals.isHomepage) {
+        scores.homepage += 0.6;
+        scores.organization += 0.3;
+    }
+    // Article detection
+    if (signals.hasArticleTag)
+        scores.article += 0.4;
+    if (signals.hasPublishDate)
+        scores.article += 0.3;
+    if (signals.hasAuthor)
+        scores.article += 0.2;
+    if (signals.ogType === "article")
+        scores.article += 0.3;
+    // Product detection
+    if (signals.hasProductSchema)
+        scores.product += 0.5;
+    if (signals.hasPrice)
+        scores.product += 0.3;
+    if (signals.hasAddToCart)
+        scores.product += 0.4;
+    // FAQ detection
+    if (signals.hasFaqSection)
+        scores.faq += 0.7;
+    // HowTo detection
+    if (signals.hasStepsList && !signals.hasFaqSection)
+        scores.howto += 0.5;
+    // Event detection
+    if (signals.hasEventDate)
+        scores.event += 0.6;
+    // Local business detection
+    if (signals.hasAddress && signals.hasPhone)
+        scores["local-business"] += 0.6;
+    if (signals.hasAddress && !signals.hasPhone)
+        scores["local-business"] += 0.3;
+    // Find highest scoring type
+    let maxScore = 0;
+    let detectedType = "unknown";
+    for (const [type, score] of Object.entries(scores)) {
+        if (score > maxScore) {
+            maxScore = score;
+            detectedType = type;
+        }
+    }
+    // Normalize confidence
+    const confidence = Math.min(1, maxScore);
+    return { type: detectedType, confidence };
+}
+/**
+ * Generate Organization schema
+ */
+function generateOrganizationSchema(signals) {
+    const url = new URL(signals.url);
+    return {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        name: signals.title.split("|")[0].split("-")[0].trim(),
+        url: `${url.protocol}//${url.hostname}`,
+        description: "", // To be filled
+        logo: "", // To be filled
+        sameAs: [], // Social links to be added
+    };
+}
+/**
+ * Generate Article schema
+ */
+function generateArticleSchema(signals) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "Article",
+        headline: signals.title,
+        description: "", // To be filled
+        author: {
+            "@type": "Person",
+            name: "", // To be filled
+        },
+        datePublished: "", // To be filled from time[datetime]
+        dateModified: "", // To be filled
+        publisher: {
+            "@type": "Organization",
+            name: "", // To be filled
+            logo: {
+                "@type": "ImageObject",
+                url: "", // To be filled
+            },
+        },
+        image: "", // To be filled
+    };
+}
+/**
+ * Generate Product schema
+ */
+function generateProductSchema(signals) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: signals.title,
+        description: "", // To be filled
+        image: "", // To be filled
+        brand: {
+            "@type": "Brand",
+            name: "", // To be filled
+        },
+        offers: {
+            "@type": "Offer",
+            price: "", // To be filled
+            priceCurrency: "USD",
+            availability: "https://schema.org/InStock",
+            url: signals.url,
+        },
+    };
+}
+/**
+ * Generate FAQ schema
+ */
+function generateFaqSchema(_signals) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        mainEntity: [
+            {
+                "@type": "Question",
+                name: "Question 1?", // To be filled from FAQ content
+                acceptedAnswer: {
+                    "@type": "Answer",
+                    text: "Answer 1", // To be filled
+                },
+            },
+            // Add more Q&A pairs
+        ],
+    };
+}
+/**
+ * Generate LocalBusiness schema
+ */
+function generateLocalBusinessSchema(signals) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "LocalBusiness",
+        name: signals.title.split("|")[0].split("-")[0].trim(),
+        url: signals.url,
+        address: {
+            "@type": "PostalAddress",
+            streetAddress: "", // To be filled
+            addressLocality: "", // To be filled
+            addressRegion: "", // To be filled
+            postalCode: "", // To be filled
+            addressCountry: "", // To be filled
+        },
+        telephone: "", // To be filled
+        openingHours: "", // To be filled
+    };
+}
+/**
+ * Generate structured data based on detected page type
+ */
+export function generateStructuredData(signals, pageType) {
+    switch (pageType) {
+        case "homepage":
+        case "organization":
+            return generateOrganizationSchema(signals);
+        case "article":
+            return generateArticleSchema(signals);
+        case "product":
+            return generateProductSchema(signals);
+        case "faq":
+            return generateFaqSchema(signals);
+        case "local-business":
+            return generateLocalBusinessSchema(signals);
+        default:
+            // Default to WebPage
+            return {
+                "@context": "https://schema.org",
+                "@type": "WebPage",
+                name: signals.title,
+                url: signals.url,
+                description: "", // To be filled
+            };
+    }
+}
+/**
+ * Get reasoning for the suggested schema
+ */
+function getReasoningForType(pageType, signals, confidence) {
+    const reasons = [];
+    switch (pageType) {
+        case "homepage":
+            reasons.push("Page is the site root (/)");
+            break;
+        case "article":
+            if (signals.hasArticleTag)
+                reasons.push("Has <article> tag");
+            if (signals.hasPublishDate)
+                reasons.push("Has publish date");
+            if (signals.hasAuthor)
+                reasons.push("Has author attribution");
+            break;
+        case "product":
+            if (signals.hasPrice)
+                reasons.push("Has price display");
+            if (signals.hasAddToCart)
+                reasons.push("Has add-to-cart button");
+            break;
+        case "faq":
+            reasons.push("Has FAQ section or Q&A structure");
+            break;
+        case "local-business":
+            if (signals.hasAddress)
+                reasons.push("Has physical address");
+            if (signals.hasPhone)
+                reasons.push("Has phone number");
+            break;
+        default:
+            reasons.push("No specific page type detected");
+    }
+    const confidenceText = confidence > 0.7 ? "High" : confidence > 0.4 ? "Medium" : "Low";
+    return `${confidenceText} confidence. ${reasons.join(". ")}.`;
+}
+/**
+ * Suggest structured data for a URL
+ */
+export async function suggestStructuredData(options) {
+    const { url, headless = true } = options;
+    let browser = null;
+    try {
+        browser = await chromium.launch({ headless });
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const signals = await extractPageSignals(page, url);
+        await browser.close();
+        browser = null;
+        const { type, confidence } = detectPageType(signals);
+        const suggestedSchema = generateStructuredData(signals, type);
+        const reasoning = getReasoningForType(type, signals, confidence);
+        return {
+            pageType: type,
+            confidence,
+            existingSchema: signals.existingSchema,
+            suggestedSchema,
+            suggestedSchemaString: JSON.stringify(suggestedSchema, null, 2),
+            reasoning,
+        };
+    }
+    finally {
+        if (browser) {
+            await browser.close();
+        }
+    }
+}
+//# sourceMappingURL=structured-data.js.map

package/dist/remediation/structured-data.js.map

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

package/dist/types.d.ts

@@ -378,6 +378,119 @@ export interface CognitiveTraits {
      */
     mentalModelRigidity?: number;
 }
+/**
+ * Selector strategy used by AI agents to find elements.
+ * Different agents prefer different selection approaches.
+ * @since 17.0.0
+ */
+export type AgentSelectorStrategy = "css" | "xpath" | "aria" | "text" | "visual";
+/**
+ * Domain knowledge level for AI agents.
+ * @since 17.0.0
+ */
+export type AgentDomainKnowledge = "general" | "specialized" | "none";
+/**
+ * Traits that define how an AI agent interacts with web pages.
+ * Fundamentally different from human CognitiveTraits - agents don't have emotions.
+ * @since 17.0.0
+ */
+export interface AgentTraits {
+    /**
+     * Primary strategy for selecting elements.
+     * - css: Fast, fragile to changes (crawlers)
+     * - xpath: Flexible path-based selection
+     * - aria: Accessibility-focused, robust (task agents)
+     * - text: Content-based selection (retrieval agents)
+     * - visual: Screenshot-based selection (multimodal agents)
+     */
+    selectorStrategy: AgentSelectorStrategy;
+    /**
+     * Context window size in tokens (affects how much page context agent considers).
+     * Lower values = faster but may miss context. Higher = thorough but slower.
+     * Typical range: 4096 - 128000
+     */
+    contextWindow: number;
+    /**
+     * Maximum retry attempts before abandoning a selector/action.
+     * Unlike human patience (emotional), this is a hard limit.
+     * Typical range: 1 - 10
+     */
+    retryBudget: number;
+    /**
+     * Willingness to backtrack and try alternative paths (0-1).
+     * 0 = commits to first path, never backtracks
+     * 1 = freely explores alternatives, high backtrack tolerance
+     */
+    backtrackWillingness: number;
+    /**
+     * Exploration strategy preference (0-1).
+     * 0 = depth-first (follows links deeply before trying siblings)
+     * 1 = breadth-first (explores all options at current level first)
+     */
+    explorationVsBreadth: number;
+    /**
+     * Tolerance for ambiguous or unclear element matches (0-1).
+     * 0 = only acts on exact matches, very strict
+     * 1 = acts on partial/fuzzy matches, lenient
+     */
+    ambiguityTolerance: number;
+    /**
+     * Ability to recover from errors and continue (0-1).
+     * 0 = fails fast on any error
+     * 1 = robust error handling, continues despite issues
+     */
+    errorRecovery: number;
+    /**
+     * Level of domain-specific knowledge.
+     * - none: Generic web navigation only
+     * - general: Understands common patterns (forms, auth, e-commerce)
+     * - specialized: Deep knowledge of specific domain (e.g., healthcare, finance)
+     */
+    domainKnowledge: AgentDomainKnowledge;
+    /**
+     * Whether agent can process visual content (screenshots, images).
+     * Multimodal agents can "see" the page, not just parse DOM.
+     */
+    multiModalCapability: boolean;
+}
+/**
+ * State tracking for agent journeys (different from human emotional state).
+ * @since 17.0.0
+ */
+export interface AgentJourneyState {
+    /** Total actions taken in this journey */
+    actionCount: number;
+    /** Remaining retries before abandonment */
+    retriesRemaining: number;
+    /** Number of selector failures encountered */
+    selectorFailures: number;
+    /** Number of times agent backtracked */
+    backtrackCount: number;
+    /** Number of ambiguous situations encountered */
+    ambiguityEncountered: number;
+    /** URLs/elements already visited (for loop detection) */
+    visitedPaths: Set<string>;
+    /** Whether agent is stuck in a loop */
+    loopDetected: boolean;
+    /** Current exploration depth */
+    depth: number;
+}
+/**
+ * Agent persona definition combining traits with metadata.
+ * @since 17.0.0
+ */
+export interface AgentPersona {
+    /** Unique identifier for the agent persona */
+    name: string;
+    /** Human-readable description of agent's purpose */
+    description: string;
+    /** Agent behavioral traits */
+    agentTraits: AgentTraits;
+    /** Primary use case for this agent type */
+    useCase: "retrieval" | "task-completion" | "crawling" | "conversation";
+    /** Optional: specific domains this agent excels at */
+    domains?: string[];
+}
 /**
  * Attention patterns that define how a persona visually scans pages.
  */
@@ -3053,6 +3166,12 @@ export interface DismissOverlayResult {
 export type AgentReadyIssueCategory = "findability" | "stability" | "accessibility" | "semantics";
 /** Severity level for agent-ready issues */
 export type AgentReadyIssueSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * AI-specific audit subcategories for granular reporting.
+ * These provide more detail within the main categories without affecting scoring.
+ * @since 17.0.0
+ */
+export type AIAuditSubcategory = "machine-metadata" | "navigation-patterns" | "actionable-elements" | "content-chrome" | "api-exposure" | "llms-txt" | "state-persistence" | "dynamic-content";
 /** Effort level for fixing issues */
 export type AgentReadyEffort = "trivial" | "easy" | "medium" | "hard";
 /** Impact level for fixing issues */
@@ -3063,6 +3182,8 @@ export interface AgentReadyIssue {
     category: AgentReadyIssueCategory;
     /** Severity level */
     severity: AgentReadyIssueSeverity;
+    /** AI-specific subcategory for granular reporting @since 17.0.0 */
+    subcategory?: AIAuditSubcategory;
     /** Element selector or description */
     element: string;
     /** Description of the issue */
@@ -3120,6 +3241,16 @@ export interface AgentReadySummary {
     customDropdowns: number;
     /** Elements without visible text */
     elementsWithoutText: number;
+    /** Machine-readable metadata found (JSON-LD, OG, Twitter) */
+    machineMetadataCount?: number;
+    /** Navigation aids found (breadcrumbs, skip links) */
+    navigationAidsCount?: number;
+    /** Whether /llms.txt was found */
+    hasLlmsTxt?: boolean;
+    /** API endpoints detected in page */
+    apiEndpointsCount?: number;
+    /** Dynamic content patterns detected */
+    dynamicContentCount?: number;
 }
 /** Letter grade for agent-ready audit */
 export type AgentReadyGrade = "A" | "B" | "C" | "D" | "F";
@@ -3261,6 +3392,88 @@ export interface CompetitiveBenchmarkOptions {
     /** Generate HTML report */
     html?: boolean;
 }
+/** Result for a single site in AI benchmark */
+export interface AIBenchmarkSiteResult {
+    /** URL tested */
+    url: string;
+    /** Site name (extracted from hostname) */
+    siteName: string;
+    /** AI readiness grade (A-F) */
+    grade: AgentReadyGrade;
+    /** AI readiness score (0-100) */
+    score: number;
+    /** Score breakdown by category */
+    scoreBreakdown: AgentReadyScore;
+    /** Top issues found */
+    topIssues: string[];
+    /** Strengths for AI agents */
+    strengths: string[];
+    /** Weaknesses for AI agents */
+    weaknesses: string[];
+    /** Duration of audit in ms */
+    duration: number;
+    /** Error message if audit failed */
+    error?: string;
+}
+/** Comparison data between sites */
+export interface AIBenchmarkComparison {
+    /** Best overall site for AI agents */
+    bestOverall: string;
+    /** Best site for findability */
+    bestFindability: string;
+    /** Best site for stability */
+    bestStability: string;
+    /** Best site for accessibility */
+    bestAccessibility: string;
+    /** Best site for semantics */
+    bestSemantics: string;
+    /** Common issues across all sites */
+    commonIssues: string[];
+    /** What each site does better */
+    siteAdvantages: Record<string, string[]>;
+}
+/** Recommendation for improving AI readiness */
+export interface AIBenchmarkRecommendation {
+    /** Site this applies to */
+    site: string;
+    /** Priority (1=highest) */
+    priority: number;
+    /** What to improve */
+    improvement: string;
+    /** Which competitor does it better */
+    competitorReference?: string;
+}
+/** Result of AI readiness benchmark */
+export interface AIBenchmarkResult {
+    /** When benchmark was run */
+    timestamp: string;
+    /** Duration of entire benchmark in ms */
+    duration: number;
+    /** Results per site */
+    sites: AIBenchmarkSiteResult[];
+    /** Sites ranked by AI readiness */
+    ranking: Array<{
+        rank: number;
+        site: string;
+        grade: AgentReadyGrade;
+        score: number;
+    }>;
+    /** Comparative analysis */
+    comparison: AIBenchmarkComparison;
+    /** Prioritized recommendations */
+    recommendations: AIBenchmarkRecommendation[];
+}
+/** Options for AI readiness benchmark */
+export interface AIBenchmarkOptions {
+    /** URLs to benchmark */
+    urls: string[];
+    /** Optional goal for agent journey simulation */
+    goal?: string;
+    /** Run headless */
+    headless?: boolean;
+    /** Max concurrent audits */
+    maxConcurrency?: number;
+}
 /** Accessibility traits for personas */
 export interface AccessibilityTraits {
     /** Motor control level 0-1 (0=severe impairment, 1=full control) */