@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/analysis/croAudit.js

@@ -0,0 +1,302 @@
+import { parse as parseHtml } from 'node-html-parser';
+import { calculateVisualSaliency } from './saliency.js';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+
+const GENERIC_CTA_RX = /^(?:submit|click\s*here|continue|next|send|ok|go|learn\s*more|more)$/i;
+const VALUE_CTA_RX = /\b(get|start|try|claim|unlock|explore|join|download|access|calculate|book|schedule|request)\b/i;
+const RISK_REVERSAL_RX = /\b(no\s*credit\s*card\s*required|cancel\s*anytime|money-back\s*guarantee|\d+-day\s*guarantee|risk-free|free\s*(?:\d+-day\s*)?trial|no\s*commitment|guaranteed)\b/i;
+const SOCIAL_PROOF_RX = /\b(trusted\s*by|over\s*\d+[\d,]*\s*(?:users|customers|teams|companies)|customer\s*reviews?|what\s*(?:our\s*)?customers\s*say|case\s*studies|testimonials?)\b/i;
+const OBJECTION_RX = /\b(frequently\s*asked\s*questions|faq|common\s*questions|how\s*much|pricing\s*details|cancel\s*policy|security\s*standards)\b/i;
+
+/**
+ * Perform comprehensive CRO audit on a page model
+ */
+export function auditPageCro(page, ctx = {}) {
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const text = (page.text || root.textContent || '').replace(/\s+/g, ' ').trim();
+  const ctas = page.ctas || [];
+  const forms = page.forms || [];
+  const trustBadges = page.trustBadges || [];
+  const headings = page.headings || [];
+
+  // -------------------------------------------------------------
+  // 1. ABOVE-THE-FOLD (ATF) CLARITY & MESSAGE-MATCH (0-100)
+  // -------------------------------------------------------------
+  let atfScore = 0;
+  const atfSignals = [];
+  const atfGaps = [];
+
+  // Scent match: Title to H1 alignment
+  const titleStem = page.title ? page.title.split(/[|—–-]/)[0].trim().toLowerCase() : '';
+  const h1Text = (headings.find((h) => h.level === 1)?.text || '').trim();
+  const h1Lower = h1Text.toLowerCase();
+
+  let scentMatch = false;
+  if (titleStem && h1Lower) {
+    const titleWords = titleStem.split(/\s+/).filter((w) => w.length > 3);
+    const matchedWords = titleWords.filter((w) => h1Lower.includes(w));
+    if (matchedWords.length >= 1 || titleStem.includes(h1Lower) || h1Lower.includes(titleStem)) {
+      scentMatch = true;
+    }
+  }
+
+  if (scentMatch) {
+    atfScore += 30;
+    atfSignals.push(`Strong information scent: Title and primary H1 corroborate core value proposition ("${h1Text.slice(0, 50)}")`);
+  } else if (h1Text) {
+    atfScore += 15;
+    atfGaps.push(`Scent gap: Primary H1 ("${h1Text.slice(0, 40)}") diverges from title tag ("${titleStem.slice(0, 40)}")`);
+  } else {
+    atfGaps.push('Missing H1 headline above the fold to establish page purpose');
+  }
+
+  // Hero CTA presence & conspicuity
+  const heroCtas = ctas.filter((c) => c.inHero);
+  const primaryHeroCta = heroCtas.find((c) => c.isPrimary) || heroCtas[0];
+
+  const saliency = calculateVisualSaliency({
+    ctas: ctas.map((c) => ({ ...c, isPrimary: c.isPrimary })),
+    headings: headings.map((h) => ({ level: h.level || 1, text: h.text })),
+    forms: forms.map((f) => ({ fieldCount: f.fieldCount })),
+  });
+
+  const pci = saliency.primary_cta_conspicuity_index || 0;
+
+  if (primaryHeroCta && pci >= 0.60) {
+    atfScore += 30;
+    atfSignals.push(`Prominent hero CTA with optimal conspicuity (${Math.round(pci * 100)}% PCI score)`);
+  } else if (primaryHeroCta) {
+    atfScore += 20;
+    atfSignals.push(`Hero CTA present ("${primaryHeroCta.text}") but visual conspicuity is diluted (${Math.round(pci * 100)}% PCI score)`);
+  } else {
+    atfGaps.push('No primary CTA visible above the fold in the hero viewport');
+  }
+
+  // Choice overload penalty
+  if (heroCtas.filter((c) => c.isPrimary).length > 1) {
+    atfScore -= 10;
+    atfGaps.push(`Choice overload: ${heroCtas.filter((c) => c.isPrimary).length} competing primary CTAs in hero zone induce decision paralysis`);
+  }
+
+  // Value proposition lead copy (opening 80 words)
+  const firstP = page.paragraphs?.[0] || '';
+  if (firstP.length >= 40 && firstP.length <= 400) {
+    atfScore += 25;
+    atfSignals.push('Concise value proposition paragraph immediately supports hero headline');
+  } else if (firstP.length > 400) {
+    atfScore += 15;
+    atfGaps.push('Opening hero lead text is too verbose (>400 chars); condense into clear benefit bullets');
+  } else {
+    atfGaps.push('Missing explanatory sub-headline or lead benefit description above the fold');
+  }
+
+  // Supporting micro-signals (risk reversal near hero)
+  const heroText = (h1Text + ' ' + firstP + ' ' + (primaryHeroCta?.text || '')).toLowerCase();
+  if (RISK_REVERSAL_RX.test(heroText)) {
+    atfScore += 15;
+    atfSignals.push('Friction-reducing risk reversal (e.g. "No credit card required") placed directly proximate to hero CTA');
+  } else {
+    atfGaps.push('Add an explicit risk-reversal micro-copy badge under hero CTA (e.g. "Free 14-day trial • No credit card required")');
+  }
+
+  atfScore = Math.min(100, Math.max(0, atfScore));
+
+  // -------------------------------------------------------------
+  // 2. UX FRICTION, COGNITIVE LOAD & ABANDONMENT ANALYSIS
+  // -------------------------------------------------------------
+  const frictionIssues = [];
+  let frictionPoints = 0;
+
+  // Form field count & Keystroke Effort Index (KEI)
+  const totalInputs = forms.reduce((sum, f) => sum + (f.fieldCount || 0), 0);
+  const inputsWithAutocomplete = forms.reduce((sum, f) => sum + f.inputs.filter((inp) => Boolean(inp.autocomplete)).length, 0);
+  const manualKeystrokes = totalInputs * 14;
+  const autofillKeystrokes = totalInputs > 0 && inputsWithAutocomplete > 0
+    ? (totalInputs - inputsWithAutocomplete) * 14 + 1
+    : manualKeystrokes;
+  const keystrokeReductionPct = manualKeystrokes > 0
+    ? Math.round(((manualKeystrokes - autofillKeystrokes) / manualKeystrokes) * 100)
+    : 0;
+
+  for (const f of forms) {
+    if (f.fieldCount > 6) {
+      frictionPoints += 20;
+      frictionIssues.push({
+        severity: 'high',
+        type: 'form_length',
+        issue: `Form contains ${f.fieldCount} fields (recommend <= 4 fields for top-of-funnel lead capture)`,
+        remediation: 'Progressive profiling: reduce initial form fields to work email and name; capture details on subsequent step',
+      });
+    }
+
+    const missingAuto = f.inputs.filter((inp) => !inp.autocomplete && ['email', 'tel', 'text', 'name'].includes(inp.type));
+    if (missingAuto.length > 0) {
+      frictionPoints += 10;
+      frictionIssues.push({
+        severity: 'medium',
+        type: 'autocomplete_missing',
+        issue: `${missingAuto.length} input field(s) lack HTML5 autocomplete attributes, increasing mobile entry friction`,
+        remediation: 'Add standard autocomplete attributes (e.g. autocomplete="email", autocomplete="name", autocomplete="tel")',
+      });
+    }
+
+    if (!f.hasSubmit) {
+      frictionPoints += 30;
+      frictionIssues.push({
+        severity: 'critical',
+        type: 'missing_submit',
+        issue: 'Form has no explicit submit button or trigger mechanism',
+        remediation: 'Add an accessible <button type="submit"> element with clear action microcopy',
+      });
+    }
+  }
+
+  // Navigation distraction on conversion surfaces (leaks)
+  const reg = registryPageFor(ctx, page);
+  const isCheckoutOrCapture = ['checkout', 'pricing', 'signup', 'demo', 'cart'].some((t) => (page.url || '').toLowerCase().includes(t));
+  const navLinks = page.navLinksCount || root.querySelectorAll('header nav a, footer a').length;
+
+  if (isCheckoutOrCapture && navLinks > 15) {
+    frictionPoints += 15;
+    frictionIssues.push({
+      severity: 'medium',
+      type: 'funnel_leak',
+      issue: `High-intent conversion page contains ${navLinks} external/header navigation links (funnel leak)`,
+      remediation: 'Enclose conversion funnel: remove non-essential header navigation and social links during checkout/signup',
+    });
+  }
+
+  // Cognitive load index
+  let cognitiveLoad = 'minimal';
+  if (frictionPoints >= 40) cognitiveLoad = 'critical_friction';
+  else if (frictionPoints >= 25) cognitiveLoad = 'high_cognitive_load';
+  else if (frictionPoints >= 10) cognitiveLoad = 'moderate';
+
+  // -------------------------------------------------------------
+  // 3. TRUST, CREDIBILITY, OBJECTIONS & RISK-REVERSAL (0-100)
+  // -------------------------------------------------------------
+  let trustScore = 0;
+  const trustSignals = [];
+  const trustGaps = [];
+
+  // Social proof
+  const hasSocialProof = SOCIAL_PROOF_RX.test(text) || trustBadges.some((b) => /rating|review|g2|capterra|trustpilot/i.test(b.signal || ''));
+  if (hasSocialProof) {
+    trustScore += 25;
+    trustSignals.push('Customer social proof and review signals detected');
+  } else {
+    trustGaps.push('Add customer social proof (client logos, quantitative adoption stats, or verified review quotes)');
+  }
+
+  // Security credentials & badges
+  const hasSecurityBadge = trustBadges.some((b) => /security|ssl|soc-?2|iso|hipaa|pci|verified/i.test(b.signal || '')) ||
+    Boolean(root.querySelector('[class*="security"], [class*="trust"], [class*="badge"]'));
+  if (hasSecurityBadge) {
+    trustScore += 25;
+    trustSignals.push('Security compliance, SSL, or verification badges present');
+  } else {
+    trustGaps.push('Display enterprise security credentials (SOC-2, ISO, HIPAA, or encryption badges) proximate to conversion action');
+  }
+
+  // Risk reversal
+  const hasRiskReversal = RISK_REVERSAL_RX.test(text);
+  if (hasRiskReversal) {
+    trustScore += 25;
+    trustSignals.push('Explicit risk-reversal guarantees present (money-back guarantee, free trial, or cancel anytime)');
+  } else {
+    trustGaps.push('Eliminate buyer perceived risk with explicit guarantees ("Cancel anytime", "30-day money back guarantee")');
+  }
+
+  // Objection handling (FAQ or comparison)
+  const hasObjectionHandling = OBJECTION_RX.test(text) || root.querySelectorAll('details, .faq, #faq').length > 0;
+  if (hasObjectionHandling) {
+    trustScore += 25;
+    trustSignals.push('Pre-purchase objection handling and structured FAQ content detected');
+  } else {
+    trustGaps.push('Include a pre-purchase FAQ addressing common pricing, onboarding, and contract objections');
+  }
+
+  trustScore = Math.min(100, Math.max(0, trustScore));
+
+  // -------------------------------------------------------------
+  // 4. OFFER ARCHITECTURE & CTA HIERARCHY
+  // -------------------------------------------------------------
+  const offerFindings = [];
+  let primaryCtaCount = 0;
+  let genericCtaCount = 0;
+
+  for (const cta of ctas) {
+    if (cta.isPrimary) primaryCtaCount++;
+    if (GENERIC_CTA_RX.test(cta.text)) {
+      genericCtaCount++;
+      offerFindings.push({
+        cta: cta.text,
+        type: 'generic_microcopy',
+        remediation: `Replace low-intent generic copy "${cta.text}" with high-value benefit action copy (e.g. "Get Started Free", "Claim Your Audit")`,
+      });
+    }
+  }
+
+  const ctaHierarchy = {
+    total_ctas: ctas.length,
+    primary_ctas: primaryCtaCount,
+    secondary_ctas: ctas.length - primaryCtaCount,
+    generic_microcopy_count: genericCtaCount,
+    hierarchy_status: primaryCtaCount === 1 ? 'optimal' : primaryCtaCount > 1 ? 'choice_overload' : 'missing_primary',
+  };
+
+  // Express checkout
+  const walletRx = /apple\s*pay|google\s*pay|paypal|one-click/i;
+  const hasExpressPayment = ctas.some((c) => walletRx.test(c.text || '')) ||
+    trustBadges.some((t) => walletRx.test(t.signal || ''));
+
+  // -------------------------------------------------------------
+  // OVERALL CONVERSION READINESS SCORE (0-100)
+  // -------------------------------------------------------------
+  const conversionReadiness = Math.round(
+    (atfScore * 0.35) +
+    (trustScore * 0.30) +
+    (Math.max(0, 100 - frictionPoints) * 0.25) +
+    (ctaHierarchy.hierarchy_status === 'optimal' ? 10 : 5)
+  );
+
+  return {
+    url: page.url,
+    fact_status: 'modeled_cro_evaluation',
+    conversion_readiness_score: conversionReadiness,
+    atf_clarity: {
+      score: atfScore,
+      scent_match: scentMatch,
+      title_stem: titleStem,
+      h1_headline: h1Text,
+      pci_score_pct: Math.round(pci * 100),
+      signals: atfSignals,
+      gaps: atfGaps,
+    },
+    cognitive_load_and_friction: {
+      load_assessment: cognitiveLoad,
+      friction_points: frictionPoints,
+      keystroke_effort: {
+        total_inputs: totalInputs,
+        inputs_with_autocomplete: inputsWithAutocomplete,
+        keystroke_reduction_pct: keystrokeReductionPct,
+      },
+      issues: frictionIssues,
+    },
+    trust_and_credibility: {
+      score: trustScore,
+      signals: trustSignals,
+      gaps: trustGaps,
+      social_proof_detected: hasSocialProof,
+      security_badges_detected: hasSecurityBadge,
+      risk_reversal_detected: hasRiskReversal,
+      objection_handling_detected: hasObjectionHandling,
+    },
+    offer_architecture: {
+      cta_hierarchy: ctaHierarchy,
+      express_checkout_supported: hasExpressPayment,
+      findings: offerFindings,
+    },
+  };
+}

package/src/analysis/croRoadmap.js

@@ -0,0 +1,121 @@
+import { nowIso } from '../shared/io.js';
+import { generateExperimentBacklog } from '../commands/croBacklog.js';
+
+/**
+ * Generate a 30 / 90 / 180-Day CRO Roadmap tied to measurable conversion outcomes.
+ */
+export function buildCroRoadmap({ findings = [], targetDomain = 'example.com', dailyVisitors = 500, baselineRate = 0.02 } = {}) {
+  const backlog = generateExperimentBacklog(findings, { dailyVisitors, baselineRate });
+
+  const horizon30 = {
+    horizon: '30_days',
+    label: 'Days 1 - 30: Immediate Mechanical Friction Removal (Quick Wins)',
+    objective: 'Eradicate mechanical conversion leaks, keystroke friction, and title-to-H1 scent divergence.',
+    focus_areas: [
+      'Funnel Continuity: Fix broken conversion progression links and attribution parameter loss (CRO-017, CRO-018)',
+      'Keystroke Friction: Inject HTML5 autocomplete attributes on all form fields (CRO-007) to reduce manual typing by up to 70%',
+      'Information Scent: Align above-the-fold H1 headlines directly with title and ad intent to close scent gaps (CRO-005)',
+      'Mobile Tap Sizing: Expand diminutive mobile CTA touch targets to >= 48px standard (CRO-015)',
+    ],
+    target_outcomes: [
+      '100% conversion funnel continuity intact across all declared paths',
+      'Keystroke Effort Index: Form completion friction reduced by >= 40%',
+      'Above-the-fold information scent match verified across all primary landing pages',
+      'Zero mobile touch target defects under 48px',
+    ],
+    measurable_conversion_kpi: 'Form Completion Rate (+8% to +15% expected relative lift)',
+    experiments: backlog.experiments.filter((e) => ['CRO-007', 'CRO-005', 'CRO-015', 'CRO-017', 'CRO-018'].includes(e.detector_id) || e.ice_prioritization.effort <= 3),
+  };
+
+  const horizon90 = {
+    horizon: '90_days',
+    label: 'Days 31 - 90: Offer Architecture, Credibility & Governed A/B Testing',
+    objective: 'Overhaul value proposition hierarchy, deploy proximate social proof and risk-reversals, and run governed A/B experiments.',
+    focus_areas: [
+      'Choice Overload: Consolidate competing hero buttons into exactly ONE dominant primary action and one secondary link (CRO-010)',
+      'Microcopy Elevation: Replace generic "Submit" / "Click Here" with high-intent benefit microcopy (CRO-012)',
+      'Credibility & Proof: Position enterprise client logos and security badges immediately adjacent to conversion buttons (CRO-006)',
+      'Objection Reversal: Deploy pre-purchase FAQ accordions directly addressing pricing, security, and contract terms',
+      'Governed Experimentation: Launch first wave of A/B tests with statistical power and SRM sample-ratio mismatch guardrails',
+    ],
+    target_outcomes: [
+      'Primary CTA Conspicuity Index (PCI) >= 70% with zero choice overload',
+      'Trust & Credibility score >= 75/100 across commercial surfaces',
+      'Statistically validated A/B experiment win with zero SRM violations (p >= 0.001)',
+      'At least 2 high-confidence Nebula Component remediations verified in production',
+    ],
+    measurable_conversion_kpi: 'Lead Capture / Trial Signup Rate (+12% to +20% expected relative lift)',
+    experiments: backlog.experiments.filter((e) => ['CRO-001', 'CRO-006', 'CRO-010', 'CRO-012', 'CRO-002'].includes(e.detector_id)),
+  };
+
+  const horizon180 = {
+    horizon: '180_days',
+    label: 'Days 91 - 180: Payment Acceleration, Funnel Enclosure & Continuous Optimization',
+    objective: 'Accelerate checkout velocity with express payment wallets, enclose high-intent funnels, and automate regression monitoring.',
+    focus_areas: [
+      'Express Checkout: Integrate 1-click Apple Pay, Google Pay, and PayPal express wallet buttons on purchase steps (CRO-021)',
+      'Distraction-Free Funnels: Enclose checkout steps by stripping non-essential navigation and external outbound links (CRO-013)',
+      'AI-Scent Landing Personalization: Ground landing pages cited by AI answer engines with immediate claim corroboration (CRO-019)',
+      'Automated Governance: Schedule weekly continuous CRO audits with automated webhook regression alerts',
+    ],
+    target_outcomes: [
+      'Checkout completion rate lift of +15% to +25%',
+      'Zero distraction leaks on checkout and demo request steps',
+      'AI answer engine referral conversion parity with organic search',
+      'Fully automated, version-pinned continuous conversion governance active',
+    ],
+    measurable_conversion_kpi: 'Checkout / Revenue Conversion Rate (+15% to +25% expected relative lift)',
+    experiments: backlog.experiments.filter((e) => ['CRO-021', 'CRO-013', 'CRO-019', 'CRO-014', 'CRO-020'].includes(e.detector_id)),
+  };
+
+  return {
+    fact_status: 'cro_roadmap_projection',
+    target_domain: targetDomain,
+    generated_at: nowIso(),
+    total_planned_experiments: backlog.total_experiments,
+    methodology: 'Horizon Phasing: 30-Day (Mechanical Friction) -> 90-Day (Offer & Trust) -> 180-Day (Payment & Scale)',
+    horizons: [horizon30, horizon90, horizon180],
+  };
+}
+
+/**
+ * Format CRO Roadmap as GitHub-flavored Markdown
+ */
+export function formatCroRoadmapMarkdown(roadmap) {
+  const lines = [
+    `# 30 / 90 / 180-Day Conversion Rate Optimization (CRO) Roadmap`,
+    `=============================================================`,
+    `- Target: \`${roadmap.target_domain}\``,
+    `- Generated: ${roadmap.generated_at}`,
+    `- Planned Experiments: ${roadmap.total_planned_experiments}`,
+    `- Strategic Framework: ${roadmap.methodology}`,
+    ``,
+    `> **Operating Premise Reminder**: This roadmap sequences verified conversion design remediations and A/B experiments. It eliminates friction and elevates decision clarity, but never guarantees conversion or revenue outcomes without empirical testing.`,
+    ``,
+  ];
+
+  for (const h of roadmap.horizons) {
+    lines.push(`## ${h.label}`);
+    lines.push(``);
+    lines.push(`**Core Objective**: ${h.objective}`);
+    lines.push(`**Measurable Target KPI**: **${h.measurable_conversion_kpi}**`);
+    lines.push(``);
+    lines.push(`### Strategic Focus Areas:`);
+    for (const f of h.focus_areas) lines.push(`- ${f}`);
+    lines.push(``);
+    lines.push(`### Target Outcomes & Success Milestones:`);
+    for (const o of h.target_outcomes) lines.push(`- [ ] ${o}`);
+    lines.push(``);
+    if (h.experiments.length) {
+      lines.push(`### Sequenced A/B Experiments (${h.experiments.length}):`);
+      lines.push(`| Experiment ID | Title | Expected Lift | Sample Size | Est. Days | ICE Score |`);
+      lines.push(`| :--- | :--- | :--- | :--- | :--- | :--- |`);
+      for (const e of h.experiments) {
+        lines.push(`| **${e.experiment_id}** | ${e.title.slice(0, 35)} | +${e.statistical_setup.expected_mde_pct}% | ${e.statistical_setup.sample_size_per_variant.toLocaleString()}/var | ~${e.statistical_setup.estimated_duration_days}d | **${e.ice_prioritization.ice_score}** |`);
+      }
+      lines.push(``);
+    }
+  }
+
+  return lines.join('\n');
+}