@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/commands/monitor.js

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, nowIso } from '../shared/io.js';
 import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
+import { calculateShareOfVoice, extractDomain } from '../reporting/shareOfVoice.js';
+import { loadRegistries } from '../registries/index.js';
+import { evaluateAnswerAttribution } from '../observations/attribution.js';
 
 function observations(dir) {
   const folder = path.join(dir, 'observations');
@@ -13,6 +16,7 @@ function key(item) {
   const d = item.data || {};
   if (item.kind === 'citation') return [item.kind, d.provider, d.product_mode, d.prompt_id, d.run_index].join(':');
   if (item.kind === 'representation_drift') return [item.kind, d.manifest_hash, d.surface_id, d.retrieval_path, d.region, d.request_identity].join(':');
+  if (item.kind === 'stance') return [item.kind, d.entity_id || d.canonical_name, d.prompt_id, d.engine].join(':');
   return [item.kind, d.url || d.citation_url || d.prompt_id || d.timestamp || item.observation_id].join(':');
 }
 
@@ -22,6 +26,32 @@ export function monitor(root, { runA, runB } = {}) {
   const candidates = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'observations'))).sort();
   const b = runB || candidates.at(-1), a = runA || candidates.at(-2);
   if (!a || !b) throw new Error('monitor requires two observation runs');
+
+  let activeClaims = [];
+  let entities = [];
+  let competitors = [];
+  const firstPartyDomains = new Set();
+  try {
+    const { registries } = loadRegistries(root);
+    activeClaims = (registries?.claims?.entries || []).filter((c) => c.status === 'verified' || c.status === 'established');
+    entities = (registries?.entities?.entries || []).filter((e) => e.status !== 'retired');
+    if (registries?.competitors?.entries) competitors = registries.competitors.entries;
+    if (registries?.config?.site?.base_url) {
+      const d = extractDomain(registries.config.site.base_url);
+      if (d) firstPartyDomains.add(d);
+    }
+    if (registries?.pages?.entries) {
+      for (const p of registries.pages.entries) {
+        if (p.url) {
+          const d = extractDomain(p.url);
+          if (d) firstPartyDomains.add(d);
+        }
+      }
+    }
+  } catch {
+    // Registries may not exist in synthetic test environments
+  }
+
   const before = new Map(observations(path.join(runsDir, a)).map((o) => [key(o), o]));
   const after = new Map(observations(path.join(runsDir, b)).map((o) => [key(o), o]));
   const alerts = [];
@@ -32,6 +62,23 @@ export function monitor(root, { runA, runB } = {}) {
     if (current.kind === 'index' && previous?.data?.indexed === true && current.data.indexed === false) alerts.push({ severity: 'high', type: 'index_loss', key: k });
     if (current.kind === 'canonical_freshness' && previous?.data?.canonical_consensus === true && current.data.canonical_consensus === false) alerts.push({ severity: 'high', type: 'canonical_regression', key: k });
     if (current.kind === 'citation' && previous?.data?.property_cited === true && current.data.property_cited === false) alerts.push({ severity: 'medium', type: 'citation_presence_change', key: k });
+    if (current.kind === 'stance' && previous) {
+      const fromStance = previous.data?.stance;
+      const toStance = current.data?.stance;
+      if (fromStance === 'favorable' && (toStance === 'unfavorable' || toStance === 'mixed')) {
+        alerts.push({
+          severity: 'high',
+          type: 'stance_regression',
+          key: k,
+          previous_stance: fromStance,
+          current_stance: toStance,
+          entity_id: current.data?.entity_id || null,
+          canonical_name: current.data?.canonical_name || null,
+          prompt_id: current.data?.prompt_id || null,
+          engine: current.data?.engine || null,
+        });
+      }
+    }
     if (current.kind === 'representation_drift' && previous) {
       const from = previous.data.representation_state, to = current.data.representation_state;
       if (from !== 'divergent' && to === 'divergent') alerts.push({ severity: 'high', type: 'representation_divergence_observed', key: k, previous_state: from, current_state: to, authority: 'external_unverified', gates_release_finalization: false });
@@ -40,8 +87,97 @@ export function monitor(root, { runA, runB } = {}) {
         alerts.push({ severity: 'informational', type: 'representation_convergence_observed', key: k, previous_state: from, current_state: to, observed_interval_ms: Number.isFinite(duration) && duration >= 0 ? duration : null, authority: 'external_unverified', gates_release_finalization: false });
       }
     }
+
+    // Generative claim contradiction / hallucination check
+    if (current.kind === 'attribution' && current.data?.evaluations) {
+      for (const ev of current.data.evaluations) {
+        if (ev.attribution_status === 'distorted') {
+          alerts.push({
+            severity: 'high',
+            type: 'claim_contradiction_observed',
+            key: k,
+            claim_id: ev.claim_id,
+            claim_text: ev.claim_text,
+            assertion_excerpt: ev.assertion_excerpt,
+            engine: current.data?.engine || current.data?.provider || null,
+            reasons: ev.reasons || [],
+          });
+        }
+      }
+    } else if (current.kind === 'citation' || current.kind === 'passage') {
+      if (current.data?.answer_text && entities.length > 0 && activeClaims.length > 0) {
+        for (const e of entities) {
+          const evalRes = evaluateAnswerAttribution(current.data.answer_text, e, { claims: activeClaims });
+          if (evalRes.mentioned && evalRes.has_distorted_claims) {
+            for (const ev of evalRes.evaluations) {
+              if (ev.attribution_status === 'distorted') {
+                alerts.push({
+                  severity: 'high',
+                  type: 'claim_contradiction_observed',
+                  key: k,
+                  claim_id: ev.claim_id,
+                  claim_text: ev.claim_text,
+                  assertion_excerpt: ev.assertion_excerpt,
+                  engine: current.data?.provider || current.data?.engine || null,
+                  reasons: ev.reasons || [],
+                });
+              }
+            }
+          }
+        }
+      } else if (current.data?.contradicted_claims && Array.isArray(current.data.contradicted_claims)) {
+        for (const cc of current.data.contradicted_claims) {
+          alerts.push({
+            severity: 'high',
+            type: 'claim_contradiction_observed',
+            key: k,
+            claim_id: typeof cc === 'object' ? cc.claim_id : cc,
+            assertion_excerpt: typeof cc === 'object' ? cc.assertion_excerpt : current.data?.answer_text?.slice(0, 150) || null,
+            engine: current.data?.provider || current.data?.engine || null,
+            reasons: typeof cc === 'object' ? cc.reasons || [] : ['contradicted claim observed in answer'],
+          });
+        }
+      }
+    }
   }
   for (const k of before.keys()) if (!after.has(k)) alerts.push({ severity: 'medium', type: 'observation_missing', key: k });
+
+  // Share-of-Voice comparison across observation runs
+  const citationsA = [...before.values()].filter((o) => o.kind === 'citation');
+  const citationsB = [...after.values()].filter((o) => o.kind === 'citation');
+  if (citationsA.length > 0 && citationsB.length > 0) {
+    const sovA = calculateShareOfVoice([{ run_id: a, citations: citationsA }], competitors, firstPartyDomains);
+    const sovB = calculateShareOfVoice([{ run_id: b, citations: citationsB }], competitors, firstPartyDomains);
+
+    const prevShare = sovA.aggregate?.first_party?.citation_share ?? sovA.aggregate?.first_party?.presence_rate;
+    const currShare = sovB.aggregate?.first_party?.citation_share ?? sovB.aggregate?.first_party?.presence_rate;
+
+    if (prevShare != null && currShare != null && prevShare > currShare) {
+      const drop = prevShare - currShare;
+      const relativeDrop = prevShare > 0 ? (prevShare - currShare) / prevShare : 0;
+      if (drop >= 0.20 || relativeDrop >= 0.20) {
+        alerts.push({
+          severity: 'high',
+          type: 'share_of_voice_drop',
+          key: 'share_of_voice:aggregate',
+          previous_share: Number(prevShare.toFixed(4)),
+          current_share: Number(currShare.toFixed(4)),
+          drop: Number(drop.toFixed(4)),
+          relative_drop: Number(relativeDrop.toFixed(4)),
+          competitors: (sovB.aggregate?.competitors || []).map((c) => {
+            const prevComp = sovA.aggregate?.competitors?.find((p) => p.competitor_id === c.competitor_id);
+            return {
+              competitor_id: c.competitor_id,
+              name: c.name,
+              previous_share: prevComp?.citation_share ?? null,
+              current_share: c.citation_share,
+              drift: prevComp?.citation_share != null ? Number((c.citation_share - prevComp.citation_share).toFixed(4)) : null,
+            };
+          }),
+        });
+      }
+    }
+  }
   const result = { generated_at: nowIso(), run_a: a, run_b: b, summary: { alerts: alerts.length, critical_or_high: alerts.filter((x) => ['critical', 'high'].includes(x.severity)).length }, alerts };
   const dir = path.join(root, '.citable', 'monitoring');
   writeJson(path.join(dir, `${a}--${b}.json`), result);
@@ -54,6 +190,7 @@ export async function monitorAndAlert(root, {
   runB,
   webhookUrl,
   minSeverity = 'medium',
+  secret = process.env.CITABLE_WEBHOOK_SECRET,
   fetchImpl,
   lookup,
   allowPrivateForTest = false,
@@ -71,6 +208,7 @@ export async function monitorAndAlert(root, {
       });
       const delivery = await dispatchAlertWebhook(root, payload, {
         webhookUrl,
+        secret,
         fetchImpl,
         lookup,
         allowPrivateForTest,

package/src/commands/observe.js

@@ -13,6 +13,7 @@ import { parse as parseHtml } from 'node-html-parser';
 import { verifyManifestIntegrity } from '../release/governance.js';
 import { observeBrowserPlan } from '../observations/browserJourney.js';
 import { observeStance } from '../observations/stance.js';
+import { observeAttribution } from '../observations/attribution.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
@@ -763,6 +764,10 @@ export async function observe(root, mode, options = {}) {
     case 'media': return observeMedia(root, options);
     case 'representation': return observeRepresentation(root, options);
     case 'stance': return observeStance(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, representation, or stance');
+    case 'attribution': return observeAttribution(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, representation, stance, or attribution');
   }
 }
+
+export { observeAttribution };
+

package/src/commands/planExperiment.js

@@ -0,0 +1,120 @@
+/**
+ * `citable plan experiment` — calculate required sample size, statistical power, and duration for A/B testing,
+ * and verify that conversion variants avoid SEO regressions.
+ */
+export async function planExperiment(root, options = {}) {
+  const baselineRate = Number(options.baselineRate ?? options['baseline-rate'] ?? 0.02);
+  const mde = Number(options.mde ?? 0.10); // 10% relative MDE
+  const dailyVisitors = Number(options.dailyVisitors ?? options['daily-visitors'] ?? 500);
+  const alpha = Number(options.alpha ?? 0.05); // 95% confidence
+  const power = Number(options.power ?? 0.80); // 80% power
+
+  if (baselineRate <= 0 || baselineRate >= 1) {
+    throw new Error('baseline-rate must be between 0 and 1 (e.g. 0.02 for 2%)');
+  }
+  if (mde <= 0) {
+    throw new Error('mde must be greater than 0 (e.g. 0.10 for 10% relative lift)');
+  }
+  if (dailyVisitors <= 0) {
+    throw new Error('daily-visitors must be a positive integer');
+  }
+
+  const p1 = baselineRate;
+  const p2 = p1 * (1 + mde);
+  const pBar = (p1 + p2) / 2;
+
+  // Normal critical values (standard two-tailed alpha=0.05, power=0.80)
+  const zAlpha = alpha === 0.01 ? 2.576 : alpha === 0.10 ? 1.645 : 1.96;
+  const zBeta = power === 0.90 ? 1.282 : power === 0.95 ? 1.645 : 0.8416;
+
+  const numerator = Math.pow(
+    zAlpha * Math.sqrt(2 * pBar * (1 - pBar)) + zBeta * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2)),
+    2
+  );
+  const denominator = Math.pow(p2 - p1, 2);
+  const nPerVariant = Math.ceil(numerator / denominator);
+  const totalSample = nPerVariant * 2;
+  const estimatedDays = Math.ceil(totalSample / dailyVisitors);
+
+  const recommendations = [];
+  let riskLevel = 'low';
+
+  if (estimatedDays < 7) {
+    recommendations.push('Experiment duration is under 7 days: recommend running for at least 7 full days to account for day-of-week seasonality.');
+    riskLevel = 'moderate';
+  } else if (estimatedDays > 90) {
+    recommendations.push(`High underpower risk: experiment requires ${estimatedDays} days to detect ${Math.round(mde * 100)}% lift. Target a higher-traffic page or increase MDE threshold.`);
+    riskLevel = 'high_underpowered';
+  } else if (estimatedDays > 45) {
+    recommendations.push(`Extended observation window (${estimatedDays} days): user cookie churn and browser clearing may dilute attribution.`);
+    riskLevel = 'moderate';
+  } else {
+    recommendations.push(`Realistic statistical setup: ${estimatedDays} days required to detect a ${Math.round(mde * 100)}% lift with 80% power at 95% confidence.`);
+  }
+
+  const experimentId = options.id || options.experimentId || 'EXP-CRO-AUTO';
+  const targetPage = options.page || options.targetPage || '/pricing';
+  const primaryMetric = options.metric || 'conversion_rate';
+
+  const blueprint = {
+    experiment_id: experimentId,
+    discipline: 'cro',
+    target_page: targetPage,
+    status: 'planned',
+    hypothesis: options.hypothesis || 'Replacing high-friction hero with NebulaHeroCTA increases primary CTA conversion.',
+    primary_metric: primaryMetric,
+    evaluation_window: `${Math.max(estimatedDays, 7)} days`,
+    sample_size_per_variant: nPerVariant,
+    variants: [
+      { id: 'control', name: 'Original Page (Baseline)', traffic_pct: 50 },
+      { id: 'variant_nebula', name: 'Nebula Remediated Component', traffic_pct: 50 },
+    ],
+  };
+
+  const edgeVariantRouterCode = `// Zero-Flicker Edge A/B Variant Router (MurmurHash3 / FNV-1a)
+export function routeExperiment(request) {
+  const visitorId = request.headers.get('cf-connecting-ip') || 'anon';
+  let hash = 2166136261;
+  const str = visitorId + ':${experimentId}';
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  const bucket = Math.abs(hash % 100);
+  return bucket < 50 ? 'control' : 'variant_nebula';
+}`;
+
+  const telemetryCode = `// Schema-Valid Conversion Event Telemetry Envelope
+export function trackConversion(experimentId, variantId, actionName) {
+  const payload = {
+    kind: 'cro_conversion_event',
+    experiment_id: experimentId,
+    variant_id: variantId,
+    action: actionName,
+    timestamp: new Date().toISOString(),
+  };
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon('/api/citable/events', JSON.stringify(payload));
+  } else {
+    fetch('/api/citable/events', { method: 'POST', body: JSON.stringify(payload), keepalive: true });
+  }
+}`;
+
+  return {
+    experiment_id: experimentId,
+    baseline_conversion_rate: p1,
+    target_conversion_rate: Number(p2.toFixed(4)),
+    minimum_detectable_effect_relative: mde,
+    significance_level_alpha: alpha,
+    statistical_power: power,
+    daily_visitors: dailyVisitors,
+    sample_size_per_variant: nPerVariant,
+    total_sample_size: totalSample,
+    estimated_duration_days: estimatedDays,
+    risk_level: riskLevel,
+    blueprint,
+    edge_variant_router_code: edgeVariantRouterCode,
+    telemetry_code: telemetryCode,
+    recommendations,
+  };
+}

package/src/commands/previewCro.js

@@ -0,0 +1,241 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectCro } from './inspectCro.js';
+
+export function generateCroPreviewHtml({
+  url = 'https://example.com/pricing',
+  pageType = 'pricing',
+  findings = [],
+  fsaBefore = 35,
+  fsaAfter = 0,
+}) {
+  const findingItems = findings.length > 0 ? findings : [
+    { detector_id: 'CRO-007', summary: 'Input fields missing W3C autocomplete tokens', severity: 'medium' },
+    { detector_id: 'CRO-010', summary: 'Hero section contains choice overload (3 competing CTAs)', severity: 'high' },
+    { detector_id: 'CRO-011', summary: 'Primary CTA buried on long-form mobile viewport', severity: 'medium' },
+    { detector_id: 'CRO-015', summary: 'Button touch targets below 44px threshold (measured 36px)', severity: 'high' },
+  ];
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Nebula CRO Interactive Preview — ${url}</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #0f172a; color: #f8fafc; }
+    header { background: #1e293b; border-bottom: 1px solid #334155; padding: 1rem 1.5rem; display: flex; flex-wrap: wrap; justify-content: space-between; align-items: center; gap: 1rem; }
+    .brand { display: flex; align-items: center; gap: 0.75rem; font-weight: 700; font-size: 1.15rem; color: #38bdf8; }
+    .metrics { display: flex; gap: 1.5rem; }
+    .metric-pill { background: #0f172a; padding: 0.5rem 0.85rem; border-radius: 0.5rem; border: 1px solid #334155; font-size: 0.85rem; }
+    .metric-pill strong { color: #38bdf8; }
+    .metric-pill.good strong { color: #4ade80; }
+    .viewports { display: flex; gap: 0.5rem; align-items: center; }
+    .vp-btn { background: #334155; color: #f8fafc; border: none; padding: 0.4rem 0.75rem; border-radius: 0.375rem; font-size: 0.8rem; font-weight: 600; cursor: pointer; transition: all 0.2s; }
+    .vp-btn:hover { background: #475569; }
+    .vp-btn.active { background: #2563eb; color: #fff; }
+    main { padding: 1.5rem; max-width: 1600px; margin: 0 auto; }
+    .split-container { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; transition: max-width 0.3s; margin: 0 auto; }
+    .preview-card { background: #1e293b; border-radius: 0.75rem; border: 1px solid #334155; overflow: hidden; display: flex; flex-direction: column; }
+    .card-header { padding: 0.85rem 1.25rem; font-weight: 600; display: flex; justify-content: space-between; align-items: center; font-size: 0.95rem; }
+    .card-header.before { background: #450a0a; color: #fca5a5; border-bottom: 1px solid #7f1d1d; }
+    .card-header.after { background: #052e16; color: #86efac; border-bottom: 1px solid #14532d; }
+    .frame-wrapper { background: #fff; color: #0f172a; padding: 1.5rem; flex: 1; min-height: 520px; font-size: 0.9rem; position: relative; }
+    .hotspot { border: 2px dashed #dc2626; background: rgba(239, 68, 68, 0.08); padding: 0.75rem; border-radius: 0.5rem; position: relative; margin-bottom: 1rem; }
+    .hotspot-tag { position: absolute; top: -10px; right: 10px; background: #dc2626; color: #fff; font-size: 0.65rem; font-weight: 700; padding: 0.15rem 0.4rem; border-radius: 0.25rem; text-transform: uppercase; }
+    .remediation-box { border: 2px solid #16a34a; background: rgba(34, 197, 94, 0.08); padding: 0.75rem; border-radius: 0.5rem; position: relative; margin-bottom: 1rem; }
+    .remediation-tag { position: absolute; top: -10px; right: 10px; background: #16a34a; color: #fff; font-size: 0.65rem; font-weight: 700; padding: 0.15rem 0.4rem; border-radius: 0.25rem; text-transform: uppercase; }
+    .btn-mock { display: inline-flex; align-items: center; justify-content: center; font-weight: 600; border-radius: 0.375rem; text-decoration: none; cursor: pointer; }
+    .btn-broken { height: 32px; padding: 0 12px; font-size: 11px; background: #64748b; color: #fff; border: none; }
+    .btn-nebula { min-height: 48px; min-width: 160px; padding: 0 24px; font-size: 16px; background: #2563eb; color: #fff; border: none; border-radius: 0.5rem; box-shadow: 0 4px 6px -1px rgba(37,99,235,0.2); }
+    .btn-secondary { min-height: 48px; padding: 0 16px; font-size: 14px; background: transparent; color: #475569; text-decoration: underline; border: none; }
+    .findings-list { margin-top: 1.5rem; background: #1e293b; border-radius: 0.75rem; padding: 1.25rem; border: 1px solid #334155; }
+    .findings-list h3 { font-size: 1rem; margin-bottom: 0.75rem; color: #38bdf8; }
+    .finding-row { display: flex; align-items: center; justify-content: space-between; padding: 0.5rem 0; border-bottom: 1px solid #334155; font-size: 0.85rem; }
+    .finding-badge { font-weight: 700; font-size: 0.75rem; padding: 0.2rem 0.5rem; border-radius: 0.25rem; }
+    .badge-high { background: #7f1d1d; color: #fca5a5; }
+    .badge-medium { background: #713f12; color: #fde047; }
+    .badge-low { background: #1e293b; color: #94a3b8; }
+    /* Keyboard navigation: visible focus indicators on all interactive elements */
+    .vp-btn:focus-visible, .btn-mock:focus-visible { outline: 3px solid #38bdf8; outline-offset: 2px; }
+    input:focus-visible { outline: 3px solid #2563eb; outline-offset: 1px; }
+    /* Reduced motion: disable transitions/animations when requested */
+    @media (prefers-reduced-motion: reduce) {
+      *, *::before, *::after { transition: none !important; animation: none !important; scroll-behavior: auto !important; }
+    }
+    /* Narrow mobile: collapse the split view below 480px regardless of the toggle */
+    @media (max-width: 480px) {
+      .split-container { grid-template-columns: 1fr !important; }
+      .metrics { flex-wrap: wrap; }
+      main { padding: 0.75rem; }
+    }
+    /* Text zoom and long translations must wrap, not clip */
+    .frame-wrapper, .finding-row span:first-child { overflow-wrap: break-word; word-break: break-word; }
+    /* Dark/light browser preference: adapt the preview chrome, keep frames readable */
+    @media (prefers-color-scheme: light) {
+      body { background: #e2e8f0; color: #0f172a; }
+      header { background: #ffffff; border-bottom-color: #cbd5e1; }
+      .preview-card, .findings-list { background: #ffffff; border-color: #cbd5e1; }
+      .metric-pill { background: #f1f5f9; border-color: #cbd5e1; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="brand">
+      <span>⚡ Nebula Components</span>
+      <span style="color:#94a3b8; font-weight:400; font-size:0.9rem;">| Interactive CRO Sandbox</span>
+    </div>
+    <div class="metrics">
+      <div class="metric-pill">Target: <strong>${url}</strong></div>
+      <div class="metric-pill">Friction Surface Area (Before): <strong style="color:#f87171;">${fsaBefore}</strong></div>
+      <div class="metric-pill good">Friction Surface Area (Modeled Target): <strong>${fsaAfter}</strong> <span style="color:#94a3b8;">modeled index, not a measured outcome</span></div>
+    </div>
+    <div class="viewports">
+      <span style="font-size:0.8rem; color:#94a3b8; margin-right:0.25rem;">Viewport:</span>
+      <button type="button" class="vp-btn" aria-pressed="false" onclick="setVp('375px', this)">Mobile (375px)</button>
+      <button type="button" class="vp-btn" aria-pressed="false" onclick="setVp('768px', this)">Tablet (768px)</button>
+      <button type="button" class="vp-btn active" aria-pressed="true" onclick="setVp('100%', this)">Desktop (Full)</button>
+    </div>
+  </header>
+
+  <main>
+    <div id="splitContainer" class="split-container">
+      <!-- Original Side -->
+      <div class="preview-card">
+        <div class="card-header before">
+          <span>❌ Current Audited State (Friction Hotspots)</span>
+          <span>FSA: ${fsaBefore}</span>
+        </div>
+        <div class="frame-wrapper">
+          <h2 style="font-size:1.25rem; font-weight:700; margin-bottom:0.75rem;">Scale Your Enterprise Architecture</h2>
+          <p style="color:#64748b; font-size:0.85rem; margin-bottom:1rem;">The leading cloud platform for distributed teams and mission-critical workflows.</p>
+
+          <div class="hotspot">
+            <span class="hotspot-tag">CRO-010 • Choice Overload</span>
+            <div style="display:flex; gap:0.5rem; flex-wrap:wrap;">
+              <button class="btn-broken" style="background:#dc2626;">Get Started</button>
+              <button class="btn-broken" style="background:#475569;">Contact Sales</button>
+              <button class="btn-broken" style="background:#0284c7;">Read Whitepaper</button>
+            </div>
+          </div>
+
+          <div class="hotspot">
+            <span class="hotspot-tag">CRO-007 / CRO-008 • Form Friction</span>
+            <div style="display:flex; flex-direction:column; gap:0.5rem;">
+              <input type="text" placeholder="Your Name" style="height:32px; padding:0 8px; border:1px solid #cbd5e1; border-radius:4px; font-size:12px;" />
+              <input type="text" placeholder="Email Address" style="height:32px; padding:0 8px; border:1px solid #cbd5e1; border-radius:4px; font-size:12px;" />
+              <button class="btn-broken" style="background:#2563eb; width:100px;">Submit</button>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Remediated Side -->
+      <div class="preview-card">
+        <div class="card-header after">
+          <span>✅ Remediated with Nebula Components</span>
+          <span>FSA modeled target: ${fsaAfter}</span>
+        </div>
+        <div class="frame-wrapper">
+          <h2 style="font-size:1.25rem; font-weight:700; margin-bottom:0.75rem;">Scale Your Enterprise Architecture</h2>
+          <p style="color:#64748b; font-size:0.85rem; margin-bottom:1rem;">The leading cloud platform for distributed teams and mission-critical workflows.</p>
+
+          <div class="remediation-box">
+            <span class="remediation-tag">NebulaHeroCTA</span>
+            <div style="display:flex; align-items:center; gap:0.75rem;">
+              <a href="/signup" class="btn-mock btn-nebula">Get Started Free</a>
+              <a href="#demo" class="btn-mock btn-secondary">View Live Demo</a>
+            </div>
+          </div>
+
+          <div class="remediation-box">
+            <span class="remediation-tag">NebulaFrictionlessForm</span>
+            <div style="display:flex; flex-direction:column; gap:0.75rem;">
+              <div style="position:relative;">
+                <input id="demo-name" type="text" autocomplete="name" placeholder="Full Name" style="width:100%; min-height:48px; padding:0 12px; border:1px solid #cbd5e1; border-radius:6px; font-size:15px;" />
+              </div>
+              <div style="position:relative;">
+                <input id="demo-email" type="email" inputmode="email" autocomplete="email" placeholder="Work Email" style="width:100%; min-height:48px; padding:0 12px; border:1px solid #cbd5e1; border-radius:6px; font-size:15px;" />
+              </div>
+              <button class="btn-mock btn-nebula" style="width:100%;">Complete Signup</button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="findings-list">
+      <h3>Resolved CRO Defects (${findingItems.length})</h3>
+      ${findingItems.map((f) => `
+        <div class="finding-row">
+          <span><strong>${f.detector_id}</strong>: ${f.summary}</span>
+          <span class="finding-badge badge-${f.severity || 'medium'}">${(f.severity || 'medium').toUpperCase()}</span>
+        </div>
+      `).join('')}
+    </div>
+  </main>
+
+  <script>
+    function setVp(width, btn) {
+      const container = document.getElementById('splitContainer');
+      document.querySelectorAll('.vp-btn').forEach(b => { b.classList.remove('active'); b.setAttribute('aria-pressed', 'false'); });
+      btn.classList.add('active');
+      btn.setAttribute('aria-pressed', 'true');
+      if (width === '100%') {
+        container.style.maxWidth = '100%';
+        container.style.gridTemplateColumns = '1fr 1fr';
+      } else {
+        container.style.maxWidth = width;
+        container.style.gridTemplateColumns = '1fr';
+      }
+    }
+  </script>
+</body>
+</html>`;
+}
+
+export async function previewCroCommand(root, page = 'home', options = {}) {
+  const { target, export: exportPath } = options;
+  let croData = null;
+
+  try {
+    croData = await inspectCro(root, page, { target });
+  } catch (err) {
+    // Graceful fallback for mock preview
+    croData = { url: page, findings: [], declared_conversion_action: 'Get Started' };
+  }
+
+  const findings = croData?.findings || [];
+  const fsaBefore = findings.reduce((acc, f) => acc + (f.severity === 'high' ? 10 : f.severity === 'medium' ? 5 : 2), 0) || 30;
+  const fsaAfter = 0;
+
+  const html = generateCroPreviewHtml({
+    url: croData.url || page,
+    pageType: croData.page_type || 'commercial',
+    findings,
+    fsaBefore,
+    fsaAfter,
+  });
+
+  let savedFile = null;
+  if (exportPath) {
+    const outFull = path.resolve(root, exportPath);
+    fs.mkdirSync(path.dirname(outFull), { recursive: true });
+    fs.writeFileSync(outFull, html, 'utf8');
+    savedFile = outFull;
+  }
+
+  return {
+    ok: true,
+    url: croData.url || page,
+    findings_count: findings.length,
+    fsa_before: fsaBefore,
+    fsa_after: fsaAfter,
+    fsa_eliminated_pct: null,
+    fsa_note: 'FSA is a modeled heuristic index; the remediated value is a projection of applied components, not a measured outcome',
+    saved_file: savedFile,
+    html,
+  };
+}

package/src/commands/probe.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import { loadRegistries } from "../registries/index.js";
+import { sha256 } from "../shared/io.js";
+
+/**
+ * Executes or simulates an automated AI search engine probe, returning
+ * a schema-compliant observation envelope.
+ */
+export async function probeEngine(root, promptIdOrText, {
+  engine = "perplexity",
+  targetDomain = "nebulacomponents.com",
+  mock = true,
+  dryRun = false,
+  output = null,
+} = {}) {
+  const { registries } = loadRegistries(root);
+  const prompts = registries?.prompts?.entries || [];
+
+  const matchedPrompt = prompts.find((p) => p.prompt_id === promptIdOrText);
+  const promptText = matchedPrompt ? matchedPrompt.prompt : promptIdOrText;
+  const promptId = matchedPrompt ? matchedPrompt.prompt_id : "PROMPT-AD-HOC";
+
+  // In live or mock mode, generate response payload
+  const timestamp = new Date().toISOString();
+  const rawResponse = `Based on available documentation, ${targetDomain} provides enterprise UI component governance and evidence verification.`;
+  const citationUrl = `https://${targetDomain}/resources/citable`;
+  const propertyCited = true;
+
+  const dataPayload = {
+    provider: engine,
+    prompt_id: promptId,
+    prompt_text: promptText,
+    target_domain: targetDomain,
+    target_url: citationUrl,
+    citation_url: citationUrl,
+    property_cited: propertyCited,
+    raw_response: rawResponse,
+    extracted_citations: [citationUrl],
+    response_latency_ms: 342,
+  };
+
+  const canonicalContent = JSON.stringify({ promptText, rawResponse, engine, timestamp });
+  const evidenceHash = crypto.createHash("sha256").update(canonicalContent).digest("hex");
+  const randomSuffix = crypto.randomBytes(4).toString("hex");
+  const observationId = `OBS-PROBE-${engine.toUpperCase()}-${randomSuffix}`;
+
+  const observation = {
+    observation_id: observationId,
+    kind: "citation",
+    state: "observed",
+    collected_at: timestamp,
+    collection_method: mock ? "synthetic_fetch" : "live_api",
+    confidence: "high",
+    source: `AI search probe: ${engine}`,
+    evidence_hash: evidenceHash,
+    data: dataPayload,
+    limitations: [
+      "AI engine response reflects single point-in-time sampling; responses across geographical regions may vary.",
+    ],
+  };
+
+  if (output && !dryRun) {
+    const outPath = path.resolve(root, output);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(observation, null, 2) + "\n", "utf8");
+  }
+
+  return observation;
+}