@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/analysis/offpage.js

@@ -0,0 +1,228 @@
+import { URL } from 'node:url';
+
+const SPAM_TLDS = new Set([
+  'top', 'work', 'gdn', 'click', 'monster', 'buzz', 'cfd', 'sbs',
+  'rest', 'cam', 'fit', 'surf', 'stream', 'tk', 'ml', 'ga', 'cf',
+]);
+
+const COMMERCIAL_SPAM_KEYWORDS = /\b(casino|viagra|cialis|payday\s*loans?|replica|cheap\s*essay|free\s*download|warez|crack|hack|gambling|betting|slots|crypto\s*airdrop)\b/i;
+
+function extractHostname(urlString) {
+  try {
+    return new URL(urlString).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function extractRootDomain(hostname) {
+  if (!hostname) return null;
+  const parts = hostname.split('.');
+  if (parts.length <= 2) return hostname;
+  return parts.slice(-2).join('.');
+}
+
+function extractTld(hostname) {
+  if (!hostname) return null;
+  const parts = hostname.split('.');
+  return parts.at(-1) || null;
+}
+
+/**
+ * Audit an inbound backlink profile for authority distribution and toxic domain risks.
+ */
+export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
+  const links = Array.isArray(backlinks) ? backlinks : (backlinks?.backlinks || []);
+  const normalizedTarget = targetDomain ? targetDomain.toLowerCase().replace(/^www\./, '') : null;
+
+  const referringDomains = new Map();
+  const cClassClusters = new Map();
+  let dofollowCount = 0;
+  let nofollowCount = 0;
+  let ugcCount = 0;
+  let sponsoredCount = 0;
+  let homepageLinksCount = 0;
+  let deepLinksCount = 0;
+
+  const anchorTypes = {
+    branded: 0,
+    naked_url: 0,
+    generic: 0,
+    exact_match_commercial: 0,
+    other: 0,
+  };
+
+  const toxicDomains = [];
+  const GENERIC_ANCHORS = /^(?:click here|here|website|link|read more|learn more|source|this site|visit|more info)$/i;
+
+  // 1. Process each backlink
+  for (const link of links) {
+    const srcHost = extractHostname(link.source_url);
+    if (!srcHost) continue;
+    const rootDomain = extractRootDomain(srcHost) || srcHost;
+    const tld = extractTld(srcHost);
+    const anchor = (link.anchor_text || '').trim();
+    const rel = (link.rel || '').toLowerCase();
+    const isNofollow = rel.includes('nofollow');
+    const isUgc = rel.includes('ugc');
+    const isSponsored = rel.includes('sponsored');
+
+    if (isNofollow) nofollowCount++;
+    else if (isUgc) ugcCount++;
+    else if (isSponsored) sponsoredCount++;
+    else dofollowCount++;
+
+    // Deep link vs homepage
+    const targetPath = link.target_url ? (() => { try { return new URL(link.target_url).pathname; } catch { return '/'; } })() : '/';
+    if (targetPath === '/' || targetPath === '') homepageLinksCount++;
+    else deepLinksCount++;
+
+    // Anchor categorization
+    if (normalizedTarget && (anchor.toLowerCase().includes(normalizedTarget) || normalizedTarget.includes(anchor.toLowerCase()))) {
+      anchorTypes.branded++;
+    } else if (/^https?:\/\//i.test(anchor) || anchor.includes('www.') || anchor.includes('.com') || anchor.includes('.org')) {
+      anchorTypes.naked_url++;
+    } else if (GENERIC_ANCHORS.test(anchor)) {
+      anchorTypes.generic++;
+    } else if (COMMERCIAL_SPAM_KEYWORDS.test(anchor) || /\b(buy|best|cheap|discount|order)\b/i.test(anchor)) {
+      anchorTypes.exact_match_commercial++;
+    } else {
+      anchorTypes.other++;
+    }
+
+    // C-class IP clustering
+    if (link.source_ip) {
+      const parts = link.source_ip.split('.');
+      if (parts.length === 4) {
+        const cClass = parts.slice(0, 3).join('.');
+        const cluster = cClassClusters.get(cClass) || new Set();
+        cluster.add(rootDomain);
+        cClassClusters.set(cClass, cluster);
+      }
+    }
+
+    // Domain tracking
+    const domainData = referringDomains.get(rootDomain) || {
+      domain: rootDomain,
+      sample_source_url: link.source_url,
+      total_links: 0,
+      anchors: [],
+      tld,
+      ip: link.source_ip || null,
+      dofollow: false,
+    };
+    domainData.total_links++;
+    if (!isNofollow && !isSponsored) domainData.dofollow = true;
+    if (anchor && !domainData.anchors.includes(anchor)) domainData.anchors.push(anchor);
+    referringDomains.set(rootDomain, domainData);
+  }
+
+  // 2. Toxic domain risk analysis per domain
+  for (const [domain, data] of referringDomains.entries()) {
+    const reasons = [];
+    let riskTier = 'clean';
+
+    // Spam TLD rule
+    if (data.tld && SPAM_TLDS.has(data.tld)) {
+      reasons.push(`Known high-abuse spam TLD (.${data.tld})`);
+      riskTier = 'high';
+    }
+
+    // Spam anchor rule
+    const hasSpamAnchor = data.anchors.some((a) => COMMERCIAL_SPAM_KEYWORDS.test(a));
+    if (hasSpamAnchor) {
+      reasons.push('Anchor text matches known high-risk commercial spam patterns');
+      riskTier = 'critical';
+    }
+
+    // PBN IP clustering rule (3+ distinct domains on the exact same /24 C-block)
+    if (data.ip) {
+      const parts = data.ip.split('.');
+      if (parts.length === 4) {
+        const cClass = parts.slice(0, 3).join('.');
+        const cluster = cClassClusters.get(cClass);
+        if (cluster && cluster.size >= 3) {
+          reasons.push(`Part of hosting cluster on ${cClass}.0/24 with ${cluster.size} domains (PBN footprint)`);
+          riskTier = 'critical';
+        }
+      }
+    }
+
+    // Excessive sitewide link density without nofollow
+    if (data.total_links > 50 && data.dofollow && (data.tld && SPAM_TLDS.has(data.tld))) {
+      reasons.push(`Sitewide link farm pattern (${data.total_links} links without rel="nofollow")`);
+      riskTier = 'critical';
+    }
+
+    if (riskTier !== 'clean') {
+      toxicDomains.push({
+        domain,
+        risk_tier: riskTier,
+        reasons,
+        sample_url: data.sample_source_url,
+        anchors: data.anchors.slice(0, 5),
+        total_links: data.total_links,
+      });
+    }
+  }
+
+  // Sort toxic domains by severity (critical first)
+  toxicDomains.sort((a, b) => (a.risk_tier === 'critical' ? -1 : 1));
+
+  const totalLinks = links.length;
+  const totalDomains = referringDomains.size;
+  const commercialAnchorPct = totalLinks > 0 ? Math.round((anchorTypes.exact_match_commercial / totalLinks) * 100) : 0;
+  const brandedAnchorPct = totalLinks > 0 ? Math.round((anchorTypes.branded / totalLinks) * 100) : 0;
+  const deepLinkPct = totalLinks > 0 ? Math.round((deepLinksCount / totalLinks) * 100) : 0;
+
+  // Authority health assessment
+  let profileHealth = 'natural';
+  if (toxicDomains.some((d) => d.risk_tier === 'critical') || commercialAnchorPct > 30) {
+    profileHealth = 'high_risk_footprint';
+  } else if (toxicDomains.length > 0 || commercialAnchorPct > 15) {
+    profileHealth = 'moderate_risk';
+  }
+
+  // Generate GSC-compatible disavow lines
+  const disavowLines = [
+    `# Citable Google Disavow Candidate Export`,
+    `# Generated at: ${new Date().toISOString()}`,
+    `# Flagged domains: ${toxicDomains.length} (critical: ${toxicDomains.filter((d) => d.risk_tier === 'critical').length})`,
+    ``,
+  ];
+  for (const td of toxicDomains) {
+    disavowLines.push(`# Risk: ${td.risk_tier.toUpperCase()} — ${td.reasons.join('; ')}`);
+    disavowLines.push(`domain:${td.domain}`);
+  }
+
+  return {
+    fact_status: 'observable_risk_indicators',
+    target_domain: targetDomain,
+    profile_health: profileHealth,
+    summary: {
+      total_backlinks: totalLinks,
+      total_referring_domains: totalDomains,
+      toxic_domains_count: toxicDomains.length,
+      critical_risk_domains: toxicDomains.filter((d) => d.risk_tier === 'critical').length,
+      high_risk_domains: toxicDomains.filter((d) => d.risk_tier === 'high').length,
+      dofollow_count: dofollowCount,
+      nofollow_count: nofollowCount,
+      ugc_count: ugcCount,
+      sponsored_count: sponsoredCount,
+      deep_link_ratio_pct: deepLinkPct,
+    },
+    anchor_profile: {
+      branded_pct: brandedAnchorPct,
+      commercial_exact_match_pct: commercialAnchorPct,
+      naked_url_count: anchorTypes.naked_url,
+      generic_count: anchorTypes.generic,
+      over_optimization_risk: commercialAnchorPct > 25 ? 'elevated' : 'normal',
+    },
+    toxic_domains: toxicDomains,
+    disavow_export: disavowLines.join('\n'),
+    limitations: [
+      'Search engines do not disclose algorithmic penalty thresholds; toxic classifications reflect observable risk patterns.',
+      'Manual verification is required before submitting disavow files to Google Search Console.',
+    ],
+  };
+}

package/src/analysis/readiness.js

@@ -0,0 +1,253 @@
+import { parse as parseHtml } from 'node-html-parser';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+
+const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+const COPULA_RX = /\b(?:is|are|refers\s+to|denotes|represents|means|provides|enables)\b/i;
+
+/**
+ * Evaluates a page's extraction, retrieval, and citation readiness across
+ * Perplexity, Bing Copilot, and ChatGPT / SearchGPT.
+ */
+export function evaluateAnswerEngineReadiness(page, ctx = {}) {
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const text = (page.text || root.textContent || '').replace(/\s+/g, ' ').trim();
+  const headings = page.headings || [];
+  const paragraphs = page.paragraphs || root.querySelectorAll('p').map((p) => p.text.trim()).filter(Boolean);
+  const jsonLd = page.jsonLd || [];
+  const tablesCount = (page.tables ?? root.querySelectorAll('table').length);
+  const listsCount = (page.orderedLists ?? root.querySelectorAll('ol').length) + root.querySelectorAll('ul').length;
+  const wordCount = page.rawVisibleWordCount || page.wordCount || text.split(/\s+/).filter(Boolean).length;
+
+  // Crawler directives check (from robots Directives or headers)
+  const robotsDirectives = Array.from(page.robotsDirectives || []);
+  const isNoindex = robotsDirectives.some((d) => d.includes('noindex'));
+
+  // -----------------------------------------------------------------
+  // 1. PERPLEXITY READINESS
+  // -----------------------------------------------------------------
+  const perplexityChecks = [];
+  let perplexityScore = 0;
+
+  // Check 1: Crawler policy (PerplexityBot)
+  const perplexityBotBlocked = robotsDirectives.some((d) => d.includes('perplexitybot: noindex') || d.includes('perplexitybot: none'));
+  if (!perplexityBotBlocked && !isNoindex) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Crawler Policy', passed: true, note: 'PerplexityBot allowed' });
+  } else {
+    perplexityChecks.push({ name: 'Crawler Policy', passed: false, note: 'Blocked by robots directive' });
+  }
+
+  // Check 2: Direct Definitional Lead (Copula in first paragraph)
+  const firstParagraph = paragraphs[0] || '';
+  const hasCopularLead = COPULA_RX.test(firstParagraph.slice(0, 160));
+  if (hasCopularLead) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Definitional Lead', passed: true, note: 'Concise copular definition in opening passage' });
+  } else {
+    perplexityChecks.push({ name: 'Definitional Lead', passed: false, note: 'Opening passage lacks concise definitional copula ("X is Y")' });
+  }
+
+  // Check 3: Structured question headings
+  const questionHeadings = headings.filter((h) => QUESTION_RX.test(h.text.trim()));
+  if (questionHeadings.length >= 2) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Question Density', passed: true, note: `${questionHeadings.length} interrogative headings found` });
+  } else if (questionHeadings.length === 1) {
+    perplexityScore += 15;
+    perplexityChecks.push({ name: 'Question Density', passed: true, note: '1 interrogative heading found' });
+  } else {
+    perplexityChecks.push({ name: 'Question Density', passed: false, note: 'No interrogative headings found (Q&A format optimizes extraction)' });
+  }
+
+  // Check 4: Structured data & tables for citation synthesis
+  if (tablesCount >= 1 || listsCount >= 2) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Tabular / List Data', passed: true, note: `${tablesCount} table(s), ${listsCount} list(s) for direct citation` });
+  } else {
+    perplexityScore += 10;
+    perplexityChecks.push({ name: 'Tabular / List Data', passed: false, note: 'Limited tables or structured lists for bulleted answers' });
+  }
+
+  // -----------------------------------------------------------------
+  // 2. BING COPILOT READINESS
+  // -----------------------------------------------------------------
+  const bingChecks = [];
+  let bingScore = 0;
+
+  // Check 1: Bingbot allowed
+  const bingbotBlocked = robotsDirectives.some((d) => d.includes('bingbot: noindex'));
+  if (!bingbotBlocked && !isNoindex) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Crawler Policy', passed: true, note: 'Bingbot allowed' });
+  } else {
+    bingChecks.push({ name: 'Crawler Policy', passed: false, note: 'Bingbot blocked' });
+  }
+
+  // Check 2: IndexNow protocol support / fast-indexing
+  const hasIndexNow = Boolean(
+    ctx.registries?.connections?.entries?.some((c) => c.provider === 'indexnow') ||
+    root.querySelector('link[rel="indexnow"]') ||
+    ctx.config?.indexnow
+  );
+  if (hasIndexNow) {
+    bingScore += 25;
+    bingChecks.push({ name: 'IndexNow Protocol', passed: true, note: 'IndexNow instant discovery integration detected' });
+  } else {
+    bingScore += 10;
+    bingChecks.push({ name: 'IndexNow Protocol', passed: false, note: 'IndexNow not configured; submission relies on standard crawl schedule' });
+  }
+
+  // Check 3: Schema.org JSON-LD completeness
+  const validSchemaBlocks = jsonLd.flatMap((j) => j.blocks || []).filter((b) => b['@type']);
+  const schemaTypes = validSchemaBlocks.map((b) => [].concat(b['@type']).join(',')).join('; ');
+  if (validSchemaBlocks.length >= 2) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Structured Data', passed: true, note: `Rich schema graphs (${schemaTypes})` });
+  } else if (validSchemaBlocks.length === 1) {
+    bingScore += 15;
+    bingChecks.push({ name: 'Structured Data', passed: true, note: `Basic schema present (${schemaTypes})` });
+  } else {
+    bingChecks.push({ name: 'Structured Data', passed: false, note: 'No valid JSON-LD schema detected; Bing Copilot cards hindered' });
+  }
+
+  // Check 4: Deep page internal linking and canonical clarity
+  const canonicals = page.canonicals || [];
+  if (canonicals.length === 1) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Canonical Authority', passed: true, note: `Canonical unambiguously specified (${canonicals[0]})` });
+  } else {
+    bingChecks.push({ name: 'Canonical Authority', passed: false, note: canonicals.length === 0 ? 'Missing canonical URL' : 'Multiple contradictory canonical tags' });
+  }
+
+  // -----------------------------------------------------------------
+  // 3. CHATGPT / SEARCHGPT READINESS
+  // -----------------------------------------------------------------
+  const chatGptChecks = [];
+  let chatGptScore = 0;
+
+  // Check 1: OAI-SearchBot / ChatGPT-User allowed
+  const oaiBlocked = robotsDirectives.some((d) => d.includes('oai-searchbot: noindex') || d.includes('chatgpt-user: noindex'));
+  if (!oaiBlocked && !isNoindex) {
+    chatGptScore += 25;
+    chatGptScore = Math.min(100, chatGptScore);
+    chatGptChecks.push({ name: 'SearchBot Policy', passed: true, note: 'OAI-SearchBot and ChatGPT-User allowed for search retrieval' });
+  } else {
+    chatGptChecks.push({ name: 'SearchBot Policy', passed: false, note: 'OAI-SearchBot / ChatGPT-User blocked by robots directives' });
+  }
+
+  // Check 2: RAG Chunkability (H2/H3 headers under 350 words per chunk)
+  const estimatedChunks = Math.max(1, Math.ceil(wordCount / 300));
+  const wordsPerHeading = headings.length > 0 ? Math.round(wordCount / headings.length) : wordCount;
+  if (headings.length >= 2 && wordsPerHeading >= 80 && wordsPerHeading <= 400) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: true, note: `Optimal chunk sizes (${wordsPerHeading} words/heading across ${headings.length} headings)` });
+  } else if (headings.length >= 1) {
+    chatGptScore += 15;
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: true, note: `Sub-optimal chunking (${wordsPerHeading} words/heading)` });
+  } else {
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: false, note: 'Monolithic content without H2/H3 hierarchy risks retrieval severance' });
+  }
+
+  // Check 3: Direct answer lead in first 100 words of section
+  const SUMMARY_RX = /\b(?:executive\s+summary|key\s+takeaways?|summary|overview|quick\s+facts|highlights?)\b/i;
+  const hasSummary = headings.some((h) => SUMMARY_RX.test(h.text));
+  if (hasSummary || hasCopularLead) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'Direct Answer Synthesis', passed: true, note: hasSummary ? 'Executive summary / key takeaways section present' : 'Immediate answer thesis in opening paragraph' });
+  } else {
+    chatGptChecks.push({ name: 'Direct Answer Synthesis', passed: false, note: 'Missing executive summary or lead key takeaways section' });
+  }
+
+  // Check 4: Quantitative claim grounding
+  const hasQuantitativeData = /(?:\b\d+(?:\.\d+)?%|\b\d+\s*ms\b|\b\d+\s*s\b|\$\d+(?:,\d{3})*)/.test(text);
+  if (hasQuantitativeData && wordCount >= 300) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'Claim Grounding', passed: true, note: 'Specific numerical metrics and quantitative facts present' });
+  } else if (wordCount >= 300) {
+    chatGptScore += 15;
+    chatGptChecks.push({ name: 'Claim Grounding', passed: false, note: 'Qualitative assertions without empirical statistics' });
+  } else {
+    chatGptChecks.push({ name: 'Claim Grounding', passed: false, note: 'Thin content lacks verifiable data' });
+  }
+
+  // Posture per engine
+  const posture = (s) => (s >= 80 ? 'optimal' : s >= 50 ? 'needs_optimization' : 'obstructed');
+  const perplexityStatus = posture(perplexityScore);
+  const bingStatus = posture(bingScore);
+  const chatGptStatus = posture(chatGptScore);
+
+  const compositeScore = Math.round((perplexityScore + bingScore + chatGptScore) / 3);
+
+  // Cross-engine prioritized recommendations
+  const recommendations = [];
+  if (!hasCopularLead) {
+    recommendations.push({
+      priority: 'high',
+      engine: 'all',
+      action: 'Add a concise definitional sentence ("X is Y") within the first 140 characters of the page',
+    });
+  }
+  if (!hasSummary) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'chatgpt',
+      action: 'Include a "Key Takeaways" or "Executive Summary" section at the top of long-form content',
+    });
+  }
+  if (questionHeadings.length < 2) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'perplexity',
+      action: 'Rephrase section headings as explicit user questions (e.g. "How does X work?", "What are the benefits of Y?")',
+    });
+  }
+  if (validSchemaBlocks.length < 2) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'bing_copilot',
+      action: 'Deploy structured JSON-LD schema (FAQPage, Article, or Product) to power Copilot card extraction',
+    });
+  }
+  if (!hasIndexNow) {
+    recommendations.push({
+      priority: 'low',
+      engine: 'bing_copilot',
+      action: 'Configure IndexNow protocol to notify Bing immediately of content updates',
+    });
+  }
+
+  return {
+    url: page.url,
+    fact_status: 'deterministic_engine_readiness_audit',
+    composite_readiness_score: compositeScore,
+    engines: {
+      perplexity: {
+        score: perplexityScore,
+        status: perplexityStatus,
+        primary_bot: 'PerplexityBot',
+        checks: perplexityChecks,
+      },
+      bing_copilot: {
+        score: bingScore,
+        status: bingStatus,
+        primary_bot: 'Bingbot',
+        checks: bingChecks,
+      },
+      chatgpt: {
+        score: chatGptScore,
+        status: chatGptStatus,
+        primary_bot: 'OAI-SearchBot',
+        checks: chatGptChecks,
+      },
+    },
+    comparison_matrix: [
+      { capability: 'Direct Definitional Lead', perplexity: hasCopularLead ? 'SUPPORTED' : 'MISSING', bing_copilot: hasCopularLead ? 'SUPPORTED' : 'OPTIONAL', chatgpt: hasCopularLead ? 'SUPPORTED' : 'MISSING' },
+      { capability: 'Q&A Heading Structure', perplexity: questionHeadings.length >= 2 ? 'HIGH' : 'LOW', bing_copilot: questionHeadings.length >= 2 ? 'SUPPORTED' : 'OPTIONAL', chatgpt: questionHeadings.length >= 2 ? 'OPTIMAL' : 'MODERATE' },
+      { capability: 'Structured Data (JSON-LD)', perplexity: validSchemaBlocks.length ? 'PARSED' : 'FALLBACK', bing_copilot: validSchemaBlocks.length ? 'REQUIRED_CARD' : 'OBSTRUCTED', chatgpt: validSchemaBlocks.length ? 'GROUNDED' : 'PLAIN_TEXT' },
+      { capability: 'RAG Section Chunkability', perplexity: wordsPerHeading <= 400 ? 'OPTIMAL' : 'LONG', bing_copilot: 'STANDARD', chatgpt: wordsPerHeading <= 400 ? 'OPTIMAL' : 'SEVERED' },
+      { capability: 'Crawler Directives', perplexity: perplexityBotBlocked ? 'BLOCKED' : 'ALLOWED', bing_copilot: bingbotBlocked ? 'BLOCKED' : 'ALLOWED', chatgpt: oaiBlocked ? 'BLOCKED' : 'ALLOWED' },
+    ],
+    recommendations,
+  };
+}

package/src/analysis/saliency.js

@@ -0,0 +1,119 @@
+/**
+ * Privacy-First Algorithmic Attention & Visual Saliency Modeling
+ *
+ * Computes visual conspicuity and predicted eye-tracking gaze paths
+ * directly from DOM geometry, typography, and contrast metrics without
+ * requiring intrusive third-party client-side tracking scripts.
+ */
+
+export function calculateVisualSaliency(pageData = {}) {
+  const elements = [];
+  const ctas = pageData.ctas || [];
+  const headings = pageData.headings || [];
+  const forms = pageData.forms || [];
+
+  // Headings
+  for (const h of headings) {
+    const level = h.level || 1;
+    const isHero = level === 1;
+    const salience = isHero ? 0.85 : Math.max(0.3, 0.7 - level * 0.1);
+    elements.push({
+      type: 'heading',
+      text: (h.text || '').slice(0, 50),
+      salience,
+      isHero,
+    });
+  }
+
+  // CTAs
+  let primaryCtaSalience = 0;
+  let totalCtaSalience = 0;
+
+  for (let i = 0; i < ctas.length; i++) {
+    const c = ctas[i];
+    const isPrimary = c.isPrimary || i === 0;
+    const inHero = c.inHero || false;
+    let base = isPrimary ? 0.9 : 0.5;
+    if (inHero) base += 0.08;
+    // Penalize diminutive size or generic text
+    if (c.text && /^(submit|click here|learn more)$/i.test(c.text)) base -= 0.15;
+
+    const salience = Math.min(1.0, Math.max(0.1, base));
+    if (isPrimary && primaryCtaSalience === 0) primaryCtaSalience = salience;
+    totalCtaSalience += salience;
+
+    elements.push({
+      type: 'cta',
+      text: c.text || 'Action Button',
+      salience,
+      isPrimary,
+      inHero,
+    });
+  }
+
+  // Forms
+  for (const f of forms) {
+    const fieldCount = f.fieldCount || 3;
+    const salience = Math.min(0.8, 0.4 + fieldCount * 0.05);
+    elements.push({
+      type: 'form',
+      text: `Form (${fieldCount} fields)`,
+      salience,
+      fieldCount,
+    });
+  }
+
+  // Sort by salience descending
+  elements.sort((a, b) => b.salience - a.salience);
+
+  // Top 3 fixations (Gaze path)
+  const gazePath = elements.slice(0, 3).map((el, idx) => ({
+    order: idx + 1,
+    type: el.type,
+    label: el.text,
+    salience_score: Number(el.salience.toFixed(2)),
+  }));
+
+  // Primary CTA Conspicuity Index (PCI)
+  const pci = totalCtaSalience > 0 ? Number((primaryCtaSalience / totalCtaSalience).toFixed(2)) : 0;
+
+  // Clutter score: count of high-salience items (>0.7) competing in hero
+  const highSalienceHeroItems = elements.filter((el) => el.salience >= 0.75);
+  const visualClutterScore = highSalienceHeroItems.length > 2 ? 'high' : highSalienceHeroItems.length === 2 ? 'moderate' : 'clean';
+
+  // SVG Heatmap representation
+  const svgHeatmap = generateHeatmapSvg(elements);
+
+  return {
+    model: 'heuristic DOM-geometry index',
+    fact_status: 'modeled_index_not_observed_behavior',
+    interpretation_note: 'PCI, clutter, and gaze-path outputs are modeled heuristic indices computed from element salience labels. They are not observed user attention, eye-tracking data, or behavior measurements.',
+    primary_cta_conspicuity_index: pci,
+    pci_assessment: pci >= 0.6 ? 'optimal' : pci >= 0.4 ? 'adequate' : 'diluted',
+    visual_clutter: visualClutterScore,
+    competing_hero_elements_count: highSalienceHeroItems.length,
+    predicted_gaze_path: gazePath,
+    gaze_path_note: 'order of modeled salience, not measured fixations',
+    elements_evaluated: elements.length,
+    svg_heatmap: svgHeatmap,
+  };
+}
+
+function generateHeatmapSvg(elements) {
+  const top = elements.slice(0, 5);
+  const bars = top.map((el, i) => {
+    const y = 30 + i * 40;
+    const width = Math.round(el.salience * 300);
+    const color = el.salience >= 0.8 ? '#ef4444' : el.salience >= 0.6 ? '#f59e0b' : '#3b82f6';
+    return `<g transform="translate(10, ${y})">
+      <text x="0" y="-8" fill="#94a3b8" font-size="12" font-family="sans-serif">${el.type.toUpperCase()}: ${el.text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</text>
+      <rect x="0" y="0" width="${width}" height="18" rx="4" fill="${color}" opacity="0.85" />
+      <text x="${width + 10}" y="14" fill="#f8fafc" font-size="11" font-weight="bold" font-family="sans-serif">${Math.round(el.salience * 100)}%</text>
+    </g>`;
+  }).join('\n');
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 450 250" width="100%" height="250" style="background:#0f172a; border-radius:8px;">
+    <text x="10" y="20" fill="#38bdf8" font-size="13" font-weight="bold" font-family="sans-serif">Visual Attention Saliency Distribution</text>
+    ${bars}
+  </svg>`;
+}