@nebulacomponents/citable 1.17.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/schemaRecommendations.js

@@ -0,0 +1,173 @@
+import { parse as parseHtml } from 'node-html-parser';
+
+const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+const HOWTO_TITLE_RX = /^(?:how\s+to|how\s+do\s+i|step-by-step|guide\s+to)\b/i;
+
+/**
+ * Scan audited site pages for FAQPage, Speakable, and HowTo markup opportunities.
+ */
+export function recommendSchemaForPages(pages = []) {
+  const recommendations = {
+    faq: [],
+    speakable: [],
+    howto: [],
+  };
+
+  for (const page of pages) {
+    if (!page || page.status !== 200) continue;
+    const html = page.html || '';
+    const root = parseHtml(html);
+    const existingTypes = new Set(
+      (page.jsonLd || []).flatMap((j) => j.blocks || []).flatMap((b) => [].concat(b['@type'] || []))
+    );
+
+    // -------------------------------------------------------------
+    // 1. FAQPage Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('FAQPage')) {
+      const qas = [];
+
+      // Pattern A: <details><summary>Q</summary><p>A</p></details>
+      for (const details of root.querySelectorAll('details')) {
+        const summary = details.querySelector('summary');
+        if (summary) {
+          const questionText = summary.text.trim();
+          const clone = parseHtml(details.innerHTML);
+          const s = clone.querySelector('summary');
+          if (s) s.remove();
+          const answerText = clone.text.replace(/\s+/g, ' ').trim();
+          if (questionText && answerText) {
+            qas.push({ question: questionText, answer: answerText });
+          }
+        }
+      }
+
+      // Pattern B: Question headings followed by paragraphs
+      if (qas.length < 2) {
+        const headings = root.querySelectorAll('h2, h3');
+        for (const h of headings) {
+          const hText = h.text.trim();
+          if (QUESTION_RX.test(hText)) {
+            // Find next sibling paragraph
+            let next = h.nextElementSibling;
+            let answerText = '';
+            while (next && !['H1', 'H2', 'H3', 'H4'].includes(next.tagName)) {
+              if (['P', 'UL', 'OL', 'DIV'].includes(next.tagName)) {
+                answerText += (answerText ? ' ' : '') + next.text.replace(/\s+/g, ' ').trim();
+                if (answerText.length > 60) break;
+              }
+              next = next.nextElementSibling;
+            }
+            if (hText && answerText) {
+              qas.push({ question: hText, answer: answerText });
+            }
+          }
+        }
+      }
+
+      if (qas.length >= 2) {
+        recommendations.faq.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'FAQPage',
+          rationale: `Detected ${qas.length} visible question-and-answer pairs without FAQPage schema.`,
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'FAQPage',
+            mainEntity: qas.slice(0, 10).map((qa) => ({
+              '@type': 'Question',
+              name: qa.question,
+              acceptedAnswer: {
+                '@type': 'Answer',
+                text: qa.answer,
+              },
+            })),
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 2. Speakable Recommendation (SpeakableSpecification)
+    // -------------------------------------------------------------
+    const hasExistingSpeakable = (page.jsonLd || []).some((j) =>
+      (j.blocks || []).some((b) => b.speakable)
+    );
+
+    if (!hasExistingSpeakable) {
+      const speakableSelectors = [];
+      if (root.querySelector('h1')) speakableSelectors.push('h1');
+      if (root.querySelector('#summary, .executive-summary, .summary, .key-takeaways')) {
+        speakableSelectors.push(root.querySelector('#summary') ? '#summary' : '.executive-summary');
+      } else if (root.querySelector('article > p:first-of-type, main > p:first-of-type, p:first-of-type')) {
+        speakableSelectors.push('article > p:first-of-type');
+      }
+
+      if (speakableSelectors.length >= 2) {
+        recommendations.speakable.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'SpeakableSpecification',
+          rationale: 'Page has clear title and executive lead passage suitable for smart speaker / assistant audio playback.',
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'WebPage',
+            '@id': `${page.url}#webpage`,
+            url: page.url,
+            name: page.title || 'Page',
+            speakable: {
+              '@type': 'SpeakableSpecification',
+              cssSelector: speakableSelectors,
+            },
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 3. HowTo Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('HowTo')) {
+      const pageTitle = page.title || '';
+      const h1s = (page.headings || []).filter((h) => h.level === 1).map((h) => h.text);
+      const isHowToPage = HOWTO_TITLE_RX.test(pageTitle) || h1s.some((h) => HOWTO_TITLE_RX.test(h));
+
+      if (isHowToPage) {
+        const steps = [];
+        // Look for ordered list items or step subheadings
+        const olItems = root.querySelectorAll('ol > li');
+        if (olItems.length >= 2) {
+          olItems.forEach((li, idx) => {
+            const stepText = li.text.replace(/\s+/g, ' ').trim();
+            if (stepText) {
+              steps.push({
+                '@type': 'HowToStep',
+                position: idx + 1,
+                name: `Step ${idx + 1}`,
+                text: stepText,
+              });
+            }
+          });
+        }
+
+        if (steps.length >= 2) {
+          recommendations.howto.push({
+            target_url: page.url,
+            source_file: page.sourceFile || null,
+            schema_type: 'HowTo',
+            rationale: `Procedural instructional guide detected with ${steps.length} ordered steps.`,
+            jsonld: {
+              '@context': 'https://schema.org',
+              '@type': 'HowTo',
+              name: h1s[0] || pageTitle,
+              description: page.paragraphs?.[0] || 'Procedural guide and instructions.',
+              step: steps,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return recommendations;
+}