kanmi-perf-revenue 1.0.0 → 1.2.0

package/dist/empirical/forecasting.js

@@ -0,0 +1,287 @@
+/**
+ * Prediction & Forecasting
+ *
+ * Project future revenue based on planned performance improvements.
+ * Uses empirical data and improvement scenarios.
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+// =============================================================================
+// CORE FORECASTING
+// =============================================================================
+const MONTH_NAMES = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+];
+/**
+ * Calculate baseline metrics from sessions.
+ */
+function calculateBaseline(sessions) {
+    const conversions = sessions.filter(s => s.has_purchase);
+    const cvr = sessions.length > 0 ? conversions.length / sessions.length : 0;
+    const totalRevenue = conversions.reduce((sum, s) => sum + s.purchase_value, 0);
+    const aov = conversions.length > 0 ? totalRevenue / conversions.length : 100;
+    // Assume data is ~2 weeks, project to monthly
+    const multiplier = 2;
+    return {
+        monthlyRevenue: totalRevenue * multiplier,
+        monthlySessions: sessions.length * multiplier,
+        cvr,
+        aov,
+    };
+}
+/**
+ * Estimate CVR lift from improvement scenario.
+ */
+function estimateLift(scenario, sessions, curve) {
+    // Use curve data if available
+    if (curve && curve.buckets.length > 0) {
+        // Find sessions that would be improved
+        const getValue = (s) => {
+            switch (scenario.metric) {
+                case 'lcp': return s.lcp_ms;
+                case 'inp': return s.inp_ms;
+                case 'cls': return s.cls;
+                case 'fcp': return s.fcp_ms;
+                case 'ttfb': return s.ttfb_ms;
+                default: return null;
+            }
+        };
+        const sessionsAboveTarget = sessions.filter(s => {
+            const value = getValue(s);
+            return value !== null && value > scenario.targetP75;
+        });
+        const sessionsAtTarget = sessions.filter(s => {
+            const value = getValue(s);
+            return value !== null && value <= scenario.targetP75;
+        });
+        if (sessionsAboveTarget.length >= 50 && sessionsAtTarget.length >= 50) {
+            const currentCvr = sessionsAboveTarget.filter(s => s.has_purchase).length / sessionsAboveTarget.length;
+            const targetCvr = sessionsAtTarget.filter(s => s.has_purchase).length / sessionsAtTarget.length;
+            // Only sessions above target will improve
+            const proportionAffected = sessionsAboveTarget.length / sessions.length;
+            const lift = (targetCvr - currentCvr) * proportionAffected;
+            return lift * scenario.confidence;
+        }
+    }
+    // Fallback to benchmark estimates
+    return estimateLiftFromBenchmarks(scenario);
+}
+/**
+ * Benchmark-based lift estimation.
+ */
+function estimateLiftFromBenchmarks(scenario) {
+    // Rough estimates based on industry data
+    const benchmarks = {
+        lcp: 0.003, // ~0.3% per 100ms improvement
+        inp: 0.002, // ~0.2% per 50ms improvement
+        cls: 0.005, // ~0.5% per 0.1 improvement
+        fcp: 0.002,
+        ttfb: 0.0015,
+    };
+    const baseRate = benchmarks[scenario.metric] || 0.002;
+    // Assume moving from poor (4000ms LCP) to target
+    const estimatedDelta = {
+        lcp: Math.max(0, 4000 - scenario.targetP75),
+        inp: Math.max(0, 500 - scenario.targetP75),
+        cls: Math.max(0, 0.25 - scenario.targetP75),
+        fcp: Math.max(0, 3000 - scenario.targetP75),
+        ttfb: Math.max(0, 1800 - scenario.targetP75),
+    };
+    const delta = estimatedDelta[scenario.metric] || 0;
+    const lift = (delta / 100) * baseRate;
+    return lift * scenario.confidence * 0.5; // Conservative estimate
+}
+/**
+ * Generate revenue forecast for a single improvement scenario.
+ */
+export function forecastRevenue(scenario, sessions, curve, config = {}) {
+    const forecastMonths = config.forecastMonths || 12;
+    const growthRate = config.growthRate || 0; // Monthly baseline growth
+    const seasonality = config.seasonalityFactors || Array(12).fill(1);
+    const baseline = calculateBaseline(sessions);
+    const cvrLift = estimateLift(scenario, sessions, curve);
+    const periods = [];
+    let cumulativeAdditional = 0;
+    const startMonth = new Date().getMonth();
+    for (let i = 0; i < forecastMonths; i++) {
+        const monthIndex = (startMonth + i) % 12;
+        const seasonFactor = seasonality[monthIndex] || 1;
+        // Baseline grows over time
+        const growthFactor = Math.pow(1 + growthRate, i);
+        const baselineRevenue = baseline.monthlyRevenue * growthFactor * seasonFactor;
+        // Additional revenue from CVR improvement
+        const additionalConversions = baseline.monthlySessions * growthFactor * cvrLift;
+        const additionalRevenue = additionalConversions * baseline.aov * seasonFactor;
+        cumulativeAdditional += additionalRevenue;
+        periods.push({
+            month: i + 1,
+            monthName: MONTH_NAMES[monthIndex],
+            baselineRevenue,
+            forecastedRevenue: baselineRevenue + additionalRevenue,
+            additionalRevenue,
+            cumulativeAdditional,
+        });
+    }
+    const totalAdditionalRevenue = cumulativeAdditional;
+    const avgMonthlyLift = totalAdditionalRevenue / forecastMonths;
+    const baselineAnnual = periods.reduce((sum, p) => sum + p.baselineRevenue, 0);
+    const revenueGrowthPercent = baselineAnnual > 0
+        ? (totalAdditionalRevenue / baselineAnnual) * 100
+        : 0;
+    const assumptions = [
+        `Base CVR: ${(baseline.cvr * 100).toFixed(2)}%`,
+        `Expected CVR lift: ${(cvrLift * 100).toFixed(3)}%`,
+        `Average Order Value: $${baseline.aov.toFixed(2)}`,
+        `Confidence: ${(scenario.confidence * 100).toFixed(0)}%`,
+        `Monthly sessions: ${baseline.monthlySessions.toLocaleString()}`,
+    ];
+    return {
+        scenario,
+        periods,
+        summary: {
+            totalAdditionalRevenue,
+            avgMonthlyLift,
+            revenueGrowthPercent,
+        },
+        assumptions,
+    };
+}
+/**
+ * Generate combined forecast for multiple improvements.
+ */
+export function forecastMultipleImprovements(scenarios, sessions, curves, config = {}) {
+    const forecastMonths = config.forecastMonths || 12;
+    const synergisticBonus = config.synergisticBonus || 1.1; // 10% bonus for multiple improvements
+    const forecasts = [];
+    for (const scenario of scenarios) {
+        const curve = curves[scenario.metric] || null;
+        const forecast = forecastRevenue(scenario, sessions, curve, { forecastMonths });
+        forecasts.push(forecast);
+    }
+    // Combined forecast (with synergy bonus if multiple improvements)
+    const combinedPeriods = [];
+    let combinedCumulative = 0;
+    const synergyMultiplier = scenarios.length > 1 ? synergisticBonus : 1;
+    for (let i = 0; i < forecastMonths; i++) {
+        const baselineRevenue = forecasts[0]?.periods[i]?.baselineRevenue || 0;
+        // Sum additional revenue from all improvements
+        let totalAdditional = 0;
+        for (const forecast of forecasts) {
+            totalAdditional += forecast.periods[i]?.additionalRevenue || 0;
+        }
+        // Apply synergy bonus
+        totalAdditional *= synergyMultiplier;
+        combinedCumulative += totalAdditional;
+        combinedPeriods.push({
+            month: i + 1,
+            monthName: forecasts[0]?.periods[i]?.monthName || '',
+            baselineRevenue,
+            forecastedRevenue: baselineRevenue + totalAdditional,
+            additionalRevenue: totalAdditional,
+            cumulativeAdditional: combinedCumulative,
+        });
+    }
+    const recommendations = [];
+    // Find highest impact scenario
+    const sorted = [...forecasts].sort((a, b) => b.summary.totalAdditionalRevenue - a.summary.totalAdditionalRevenue);
+    if (sorted.length > 0) {
+        const top = sorted[0];
+        recommendations.push(`Prioritize ${top.scenario.name}: $${top.summary.totalAdditionalRevenue.toLocaleString()} potential annual impact`);
+    }
+    if (scenarios.length > 1) {
+        recommendations.push(`Combined improvements yield ${((synergyMultiplier - 1) * 100).toFixed(0)}% synergy bonus`);
+    }
+    return {
+        forecasts,
+        combined: {
+            periods: combinedPeriods,
+            totalAdditionalRevenue: combinedCumulative,
+            netImpact: combinedCumulative,
+        },
+        recommendations,
+    };
+}
+// =============================================================================
+// REPORT GENERATION
+// =============================================================================
+/**
+ * Generate markdown report for forecast.
+ */
+export function generateForecastMarkdown(forecast) {
+    const lines = [];
+    lines.push('## Revenue Forecast');
+    lines.push('');
+    lines.push(`### ${forecast.scenario.name}`);
+    lines.push('');
+    lines.push(`**Target**: ${forecast.scenario.metric.toUpperCase()} p75 ≤ ${forecast.scenario.targetP75}`);
+    lines.push('');
+    // Summary
+    lines.push('### Summary');
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| 12-Month Additional Revenue | $${forecast.summary.totalAdditionalRevenue.toLocaleString()} |`);
+    lines.push(`| Average Monthly Lift | $${forecast.summary.avgMonthlyLift.toLocaleString()} |`);
+    lines.push(`| Revenue Growth | ${forecast.summary.revenueGrowthPercent.toFixed(2)}% |`);
+    lines.push('');
+    // Assumptions
+    lines.push('### Assumptions');
+    lines.push('');
+    for (const assumption of forecast.assumptions) {
+        lines.push(`- ${assumption}`);
+    }
+    lines.push('');
+    // Monthly breakdown
+    lines.push('### Monthly Breakdown');
+    lines.push('');
+    lines.push('| Month | Baseline | Forecasted | Additional | Cumulative |');
+    lines.push('|-------|----------|------------|------------|------------|');
+    for (const period of forecast.periods) {
+        lines.push(`| ${period.monthName} | $${period.baselineRevenue.toLocaleString()} | $${period.forecastedRevenue.toLocaleString()} | $${period.additionalRevenue.toLocaleString()} | $${period.cumulativeAdditional.toLocaleString()} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Generate multi-scenario comparison markdown.
+ */
+export function generateMultiForecastMarkdown(multiForecast) {
+    const lines = [];
+    lines.push('## Multi-Scenario Revenue Forecast');
+    lines.push('');
+    // Scenario comparison
+    lines.push('### Scenario Comparison');
+    lines.push('');
+    lines.push('| Scenario | 12-Month Impact | Avg Monthly | Growth % |');
+    lines.push('|----------|-----------------|-------------|----------|');
+    for (const forecast of multiForecast.forecasts) {
+        lines.push(`| ${forecast.scenario.name} | $${forecast.summary.totalAdditionalRevenue.toLocaleString()} | $${forecast.summary.avgMonthlyLift.toLocaleString()} | ${forecast.summary.revenueGrowthPercent.toFixed(2)}% |`);
+    }
+    lines.push('');
+    // Combined impact
+    lines.push('### Combined Impact');
+    lines.push('');
+    lines.push(`**Total 12-Month Additional Revenue**: $${multiForecast.combined.totalAdditionalRevenue.toLocaleString()}`);
+    lines.push('');
+    // Recommendations
+    if (multiForecast.recommendations.length > 0) {
+        lines.push('### Recommendations');
+        lines.push('');
+        for (const rec of multiForecast.recommendations) {
+            lines.push(`- ${rec}`);
+        }
+        lines.push('');
+    }
+    // Combined monthly breakdown
+    lines.push('### Combined Monthly Breakdown');
+    lines.push('');
+    lines.push('| Month | Baseline | Combined Forecast | Combined Additional |');
+    lines.push('|-------|----------|-------------------|---------------------|');
+    for (const period of multiForecast.combined.periods) {
+        lines.push(`| ${period.monthName} | $${period.baselineRevenue.toLocaleString()} | $${period.forecastedRevenue.toLocaleString()} | $${period.additionalRevenue.toLocaleString()} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=forecasting.js.map

package/dist/empirical/forecasting.js.map

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

package/dist/empirical/funnel.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Funnel Analysis
+ *
+ * Analyzes where in the user journey performance matters most.
+ * Tracks progression through funnel stages and identifies
+ * performance-related drop-offs.
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+import type { SessionData } from './datadog-session-query.js';
+export type FunnelStage = 'landing' | 'browse' | 'product' | 'cart' | 'checkout' | 'purchase';
+export interface FunnelStageStats {
+    stage: FunnelStage;
+    sessions: number;
+    conversions: number;
+    dropoffRate: number;
+    avgLcp: number | null;
+    avgInp: number | null;
+    /** CVR difference between good vs poor performance at this stage */
+    performanceImpact: number | null;
+}
+export interface FunnelStep {
+    from: FunnelStage;
+    to: FunnelStage;
+    sessions: number;
+    progressions: number;
+    progressionRate: number;
+    avgLcp: number | null;
+    /** Performance-based progression rates */
+    goodPerfProgressionRate: number | null;
+    poorPerfProgressionRate: number | null;
+    performanceGap: number | null;
+}
+export interface FunnelReport {
+    stages: FunnelStageStats[];
+    steps: FunnelStep[];
+    overallConversionRate: number;
+    biggestDropoff: {
+        step: string;
+        dropoffRate: number;
+        performanceGap: number | null;
+    } | null;
+    performanceHotspots: Array<{
+        stage: FunnelStage;
+        impact: number;
+        message: string;
+    }>;
+    recommendations: string[];
+}
+/**
+ * Infer funnel stage from session data.
+ */
+export declare function inferFunnelStage(session: SessionData): FunnelStage;
+/**
+ * Infer deepest stage reached from conversion events.
+ */
+export declare function inferDeepestStage(session: SessionData): FunnelStage;
+/**
+ * Analyze funnel progression and performance impact.
+ */
+export declare function analyzeFunnel(sessions: SessionData[]): FunnelReport;
+/**
+ * Generate markdown report for funnel analysis.
+ */
+export declare function generateFunnelMarkdown(report: FunnelReport): string;
+//# sourceMappingURL=funnel.d.ts.map

package/dist/empirical/funnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel.d.ts","sourceRoot":"","sources":["../../src/empirical/funnel.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAM9D,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9F,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0CAA0C;IAC1C,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,IAAI,CAAC;IACT,mBAAmB,EAAE,KAAK,CAAC;QACzB,KAAK,EAAE,WAAW,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAsClE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAmBnE;AAQD;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,YAAY,CAiMnE;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAwEnE"}

package/dist/empirical/funnel.js

@@ -0,0 +1,293 @@
+/**
+ * Funnel Analysis
+ *
+ * Analyzes where in the user journey performance matters most.
+ * Tracks progression through funnel stages and identifies
+ * performance-related drop-offs.
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+// =============================================================================
+// STAGE DETECTION
+// =============================================================================
+/**
+ * Infer funnel stage from session data.
+ */
+export function inferFunnelStage(session) {
+    // Use page_type if available
+    const pageType = session.page_type?.toLowerCase() || '';
+    if (pageType.includes('checkout') || pageType.includes('payment')) {
+        return 'checkout';
+    }
+    if (pageType.includes('cart') || pageType.includes('basket')) {
+        return 'cart';
+    }
+    if (pageType.includes('product') || pageType.includes('pdp') || pageType.includes('item')) {
+        return 'product';
+    }
+    if (pageType.includes('category') ||
+        pageType.includes('listing') ||
+        pageType.includes('search') ||
+        pageType.includes('browse') ||
+        pageType.includes('plp')) {
+        return 'browse';
+    }
+    if (pageType.includes('home') || pageType.includes('landing') || pageType === '/') {
+        return 'landing';
+    }
+    // Infer from page views
+    const pageViews = session.page_views || 1;
+    if (session.has_purchase) {
+        return 'purchase';
+    }
+    if (pageViews === 1) {
+        return 'landing';
+    }
+    if (pageViews <= 3) {
+        return 'browse';
+    }
+    return 'product';
+}
+/**
+ * Infer deepest stage reached from conversion events.
+ */
+export function inferDeepestStage(session) {
+    if (session.has_purchase) {
+        return 'purchase';
+    }
+    const events = session.conversions || [];
+    const eventNames = events.map((e) => e.name.toLowerCase());
+    if (eventNames.some((n) => n.includes('checkout') || n.includes('payment'))) {
+        return 'checkout';
+    }
+    if (eventNames.some((n) => n.includes('cart') || n.includes('add_to_cart'))) {
+        return 'cart';
+    }
+    if (eventNames.some((n) => n.includes('product_view') || n.includes('view_item'))) {
+        return 'product';
+    }
+    return inferFunnelStage(session);
+}
+// =============================================================================
+// FUNNEL ANALYSIS
+// =============================================================================
+const STAGE_ORDER = ['landing', 'browse', 'product', 'cart', 'checkout', 'purchase'];
+/**
+ * Analyze funnel progression and performance impact.
+ */
+export function analyzeFunnel(sessions) {
+    // Group sessions by deepest stage reached
+    const stageData = new Map();
+    for (const stage of STAGE_ORDER) {
+        stageData.set(stage, []);
+    }
+    for (const session of sessions) {
+        const deepestStage = inferDeepestStage(session);
+        stageData.get(deepestStage).push(session);
+    }
+    // Calculate cumulative counts (users who reached at least this stage)
+    const cumulativeCounts = new Map();
+    let cumulative = sessions.length;
+    for (let i = 0; i < STAGE_ORDER.length; i++) {
+        cumulativeCounts.set(STAGE_ORDER[i], cumulative);
+        // Subtract those who dropped off at this stage
+        if (i < STAGE_ORDER.length - 1) {
+            cumulative -= stageData.get(STAGE_ORDER[i]).length;
+        }
+    }
+    // Calculate stage statistics
+    const stages = [];
+    for (let i = 0; i < STAGE_ORDER.length; i++) {
+        const stage = STAGE_ORDER[i];
+        const sessionsAtStage = sessions.filter((s) => {
+            const deepest = inferDeepestStage(s);
+            return STAGE_ORDER.indexOf(deepest) >= i;
+        });
+        const sessionsCount = sessionsAtStage.length;
+        const conversions = sessionsAtStage.filter((s) => s.has_purchase).length;
+        const dropoffCount = stageData.get(stage).length;
+        const dropoffRate = sessionsCount > 0 ? dropoffCount / sessionsCount : 0;
+        // Calculate performance metrics
+        const lcpValues = sessionsAtStage.map((s) => s.lcp_ms).filter((v) => v !== null);
+        const inpValues = sessionsAtStage.map((s) => s.inp_ms).filter((v) => v !== null);
+        // Performance impact: compare CVR for good vs poor LCP
+        let performanceImpact = null;
+        const goodPerf = sessionsAtStage.filter((s) => s.lcp_ms !== null && s.lcp_ms <= 2500);
+        const poorPerf = sessionsAtStage.filter((s) => s.lcp_ms !== null && s.lcp_ms >= 4000);
+        if (goodPerf.length >= 10 && poorPerf.length >= 10) {
+            const goodCvr = goodPerf.filter((s) => s.has_purchase).length / goodPerf.length;
+            const poorCvr = poorPerf.filter((s) => s.has_purchase).length / poorPerf.length;
+            performanceImpact = goodCvr - poorCvr;
+        }
+        stages.push({
+            stage,
+            sessions: sessionsCount,
+            conversions,
+            dropoffRate,
+            avgLcp: lcpValues.length > 0 ? lcpValues.reduce((a, b) => a + b, 0) / lcpValues.length : null,
+            avgInp: inpValues.length > 0 ? inpValues.reduce((a, b) => a + b, 0) / inpValues.length : null,
+            performanceImpact,
+        });
+    }
+    // Calculate step progressions
+    const steps = [];
+    for (let i = 0; i < STAGE_ORDER.length - 1; i++) {
+        const fromStage = STAGE_ORDER[i];
+        const toStage = STAGE_ORDER[i + 1];
+        const fromSessions = sessions.filter((s) => {
+            const deepest = inferDeepestStage(s);
+            return STAGE_ORDER.indexOf(deepest) >= i;
+        });
+        const toSessions = sessions.filter((s) => {
+            const deepest = inferDeepestStage(s);
+            return STAGE_ORDER.indexOf(deepest) >= i + 1;
+        });
+        const progressionRate = fromSessions.length > 0 ? toSessions.length / fromSessions.length : 0;
+        // Performance-based progression
+        const goodPerfFrom = fromSessions.filter((s) => s.lcp_ms !== null && s.lcp_ms <= 2500);
+        const poorPerfFrom = fromSessions.filter((s) => s.lcp_ms !== null && s.lcp_ms >= 4000);
+        let goodPerfProgressionRate = null;
+        let poorPerfProgressionRate = null;
+        if (goodPerfFrom.length >= 10) {
+            const goodPerfTo = goodPerfFrom.filter((s) => {
+                const deepest = inferDeepestStage(s);
+                return STAGE_ORDER.indexOf(deepest) >= i + 1;
+            });
+            goodPerfProgressionRate = goodPerfTo.length / goodPerfFrom.length;
+        }
+        if (poorPerfFrom.length >= 10) {
+            const poorPerfTo = poorPerfFrom.filter((s) => {
+                const deepest = inferDeepestStage(s);
+                return STAGE_ORDER.indexOf(deepest) >= i + 1;
+            });
+            poorPerfProgressionRate = poorPerfTo.length / poorPerfFrom.length;
+        }
+        const performanceGap = goodPerfProgressionRate !== null && poorPerfProgressionRate !== null
+            ? goodPerfProgressionRate - poorPerfProgressionRate
+            : null;
+        const lcpValues = fromSessions.map((s) => s.lcp_ms).filter((v) => v !== null);
+        steps.push({
+            from: fromStage,
+            to: toStage,
+            sessions: fromSessions.length,
+            progressions: toSessions.length,
+            progressionRate,
+            avgLcp: lcpValues.length > 0 ? lcpValues.reduce((a, b) => a + b, 0) / lcpValues.length : null,
+            goodPerfProgressionRate,
+            poorPerfProgressionRate,
+            performanceGap,
+        });
+    }
+    // Find biggest dropoff
+    const significantSteps = steps.filter((s) => s.sessions >= 100);
+    let biggestDropoff = null;
+    if (significantSteps.length > 0) {
+        const sorted = [...significantSteps].sort((a, b) => 1 - a.progressionRate - (1 - b.progressionRate));
+        const worst = sorted[0];
+        biggestDropoff = {
+            step: `${worst.from} → ${worst.to}`,
+            dropoffRate: 1 - worst.progressionRate,
+            performanceGap: worst.performanceGap,
+        };
+    }
+    // Find performance hotspots
+    const performanceHotspots = [];
+    for (const step of steps) {
+        if (step.performanceGap !== null && step.performanceGap > 0.05) {
+            performanceHotspots.push({
+                stage: step.from,
+                impact: step.performanceGap,
+                message: `${(step.performanceGap * 100).toFixed(1)}% higher progression with good performance at ${step.from}`,
+            });
+        }
+    }
+    // Generate recommendations
+    const recommendations = [];
+    if (biggestDropoff && biggestDropoff.dropoffRate > 0.5) {
+        recommendations.push(`Focus on ${biggestDropoff.step} - ${(biggestDropoff.dropoffRate * 100).toFixed(0)}% drop-off rate`);
+    }
+    if (performanceHotspots.length > 0) {
+        const topHotspot = performanceHotspots.sort((a, b) => b.impact - a.impact)[0];
+        recommendations.push(`Prioritize performance on ${topHotspot.stage} pages - ${topHotspot.message}`);
+    }
+    // Check for checkout performance
+    const checkoutStep = steps.find((s) => s.from === 'cart' && s.to === 'checkout');
+    if (checkoutStep && checkoutStep.performanceGap && checkoutStep.performanceGap > 0.1) {
+        recommendations.push(`Critical: Checkout performance impacts ${(checkoutStep.performanceGap * 100).toFixed(0)}% of cart abandonment`);
+    }
+    const overallConversionRate = sessions.length > 0 ? sessions.filter((s) => s.has_purchase).length / sessions.length : 0;
+    return {
+        stages,
+        steps,
+        overallConversionRate,
+        biggestDropoff,
+        performanceHotspots,
+        recommendations,
+    };
+}
+// =============================================================================
+// REPORT GENERATION
+// =============================================================================
+/**
+ * Generate markdown report for funnel analysis.
+ */
+export function generateFunnelMarkdown(report) {
+    const lines = [];
+    lines.push('## Funnel Analysis');
+    lines.push('');
+    lines.push(`Overall Conversion Rate: **${(report.overallConversionRate * 100).toFixed(2)}%**`);
+    lines.push('');
+    // Recommendations
+    if (report.recommendations.length > 0) {
+        lines.push('### Recommendations');
+        lines.push('');
+        for (const rec of report.recommendations) {
+            lines.push(`- ${rec}`);
+        }
+        lines.push('');
+    }
+    // Funnel visualization
+    lines.push('### Funnel Progression');
+    lines.push('');
+    lines.push('| Stage | Sessions | CVR | Drop-off | Perf Impact |');
+    lines.push('|-------|----------|-----|----------|-------------|');
+    for (const stage of report.stages) {
+        const perfImpact = stage.performanceImpact
+            ? `${stage.performanceImpact > 0 ? '+' : ''}${(stage.performanceImpact * 100).toFixed(2)}%`
+            : 'N/A';
+        const cvr = stage.sessions > 0 ? (stage.conversions / stage.sessions * 100).toFixed(2) : '0.00';
+        lines.push(`| ${stage.stage} | ${stage.sessions.toLocaleString()} | ${cvr}% | ${(stage.dropoffRate * 100).toFixed(1)}% | ${perfImpact} |`);
+    }
+    lines.push('');
+    // Step-by-step analysis
+    lines.push('### Step Analysis');
+    lines.push('');
+    lines.push('| Step | Progression | Good Perf | Poor Perf | Gap |');
+    lines.push('|------|-------------|-----------|-----------|-----|');
+    for (const step of report.steps) {
+        const goodPerf = step.goodPerfProgressionRate
+            ? `${(step.goodPerfProgressionRate * 100).toFixed(1)}%`
+            : 'N/A';
+        const poorPerf = step.poorPerfProgressionRate
+            ? `${(step.poorPerfProgressionRate * 100).toFixed(1)}%`
+            : 'N/A';
+        const gap = step.performanceGap
+            ? `${step.performanceGap > 0 ? '+' : ''}${(step.performanceGap * 100).toFixed(1)}%`
+            : 'N/A';
+        lines.push(`| ${step.from} → ${step.to} | ${(step.progressionRate * 100).toFixed(1)}% | ${goodPerf} | ${poorPerf} | ${gap} |`);
+    }
+    lines.push('');
+    // Performance Hotspots
+    if (report.performanceHotspots.length > 0) {
+        lines.push('### Performance Hotspots');
+        lines.push('');
+        lines.push('Stages where performance has the highest impact on progression:');
+        lines.push('');
+        for (const hotspot of report.performanceHotspots) {
+            lines.push(`- **${hotspot.stage}**: ${hotspot.message}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=funnel.js.map