@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/font-subsetting-unicode-range-optimizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - FontSubsettingUnicodeRangeOptimizer
+ * Audits webfont usage and @font-face declarations, detecting bloated multi-megabyte font files,
+ * missing woff2 modern compression, and absent unicode-range subsetting.
+ */
+export type FontFileFormat = "woff2" | "woff" | "ttf" | "otf" | "eot" | "svg";
+export interface FontFaceDeclarationInput {
+    fontFamily: string;
+    fontUrl: string;
+    format: FontFileFormat;
+    fileSizeBytes: number;
+    unicodeRangeDeclared?: string;
+    fontDisplay?: "swap" | "optional" | "block" | "fallback" | "auto";
+}
+export interface FontOptimizationOpportunity {
+    fontFamily: string;
+    fontUrl: string;
+    currentSizeBytes: number;
+    format: FontFileFormat;
+    isModernWoff2: boolean;
+    hasUnicodeRangeSubsetting: boolean;
+    estimatedOptimizedSizeBytes: number;
+    potentialByteSavings: number;
+    urgency: "critical" | "high" | "medium" | "low";
+    actionRecommendation: string;
+}
+export interface FontSubsettingAuditReport {
+    totalFontsAudited: number;
+    totalFontWeightBytes: number;
+    potentialTotalSavingsBytes: number;
+    overallFontEfficiencyScore: number;
+    opportunities: FontOptimizationOpportunity[];
+    remediationAdvice: string[];
+}
+export declare class FontSubsettingUnicodeRangeOptimizer {
+    /**
+     * Evaluates webfont declarations for compression, subsetting, and payload efficiency.
+     */
+    audit(fonts: FontFaceDeclarationInput[]): FontSubsettingAuditReport;
+}

package/dist/analytics/form-input-friction-tracker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Form Input Friction Tracker & Drop-Off Analyzer
+ * Clean-room implementation inspired by OpenReplay input module & Form Analytics.
+ * Tracks field interaction durations, correction frequencies, abandonment points, and friction scores.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface FormFieldInteraction {
+    fieldName: string;
+    fieldType: string;
+    focusTimeMs: number;
+    blurTimeMs?: number;
+    keystrokeCount: number;
+    correctionCount: number;
+    pastedContent: boolean;
+    validationErrorOccurred?: boolean;
+}
+export interface FieldFrictionMetrics {
+    fieldName: string;
+    fieldType: string;
+    totalTimeSpentMs: number;
+    hesitationScore: number;
+    correctionRatio: number;
+    hadValidationError: boolean;
+    frictionLevel: 'low' | 'moderate' | 'high';
+}
+export interface FormFrictionReport {
+    totalFieldsInteracted: number;
+    abandonedAtField?: string;
+    formCompletionTimeMs: number;
+    overallFrictionScore: number;
+    fieldMetrics: FieldFrictionMetrics[];
+    recommendations: string[];
+}
+export declare class FormInputFrictionTracker {
+    private static readonly SENSITIVE_TYPES;
+    static analyzeFormInteractions(interactions: FormFieldInteraction[], abandonedField?: string): FormFrictionReport;
+}

package/dist/analytics/frustration-analyzer.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Frustration & UX Friction Analyzer
+ *
+ * Analyse avancée des signaux d'irritation utilisateur et de friction UX
+ * inspirée des moteurs de session replay et product analytics (PostHog, OpenReplay).
+ *
+ * Détecte :
+ * 1. Rage Clicks : clics répétés rapides sur le même élément (>= 3 clics en < 1000ms).
+ * 2. Dead Clicks : clics sur des éléments apparemment interactifs n'ayant déclenché
+ *    aucune action (pas de navigation, pas de requête réseau, pas de mutation).
+ * 3. Error Clicks : clics immédiatement suivis d'une erreur JavaScript (< 1500ms).
+ * 4. Mouse Shake : mouvements erratiques rapides de la souris (hésitation/agacement).
+ * 5. Frustration Score (0 à 100) par session et agrégé par page/sélecteur CSS.
+ */
+export interface RawInteractionEvent {
+    id?: string;
+    type: "click" | "rage_click" | "dead_click" | "error_click" | "mouse_shake" | "js_error" | "network_error" | "pageview" | "input" | "scroll";
+    timestamp: number;
+    url: string;
+    selector?: string;
+    tagName?: string;
+    x?: number;
+    y?: number;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DetectedRageClick {
+    url: string;
+    selector: string;
+    clickCount: number;
+    durationMs: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+    coordinates: {
+        x: number;
+        y: number;
+    };
+}
+export interface DetectedDeadClick {
+    url: string;
+    selector: string;
+    timestamp: number;
+    tagName?: string;
+}
+export interface DetectedErrorClick {
+    url: string;
+    selector: string;
+    clickTimestamp: number;
+    errorTimestamp: number;
+    deltaMs: number;
+    errorMessage: string;
+}
+export interface SessionFrustrationResult {
+    sessionId?: string;
+    frustrationScore: number;
+    isFrustratedSession: boolean;
+    metrics: {
+        rageClickCount: number;
+        deadClickCount: number;
+        errorClickCount: number;
+        mouseShakeCount: number;
+        totalClicks: number;
+        rageClickRatePct: number;
+    };
+    rageClicks: DetectedRageClick[];
+    deadClicks: DetectedDeadClick[];
+    errorClicks: DetectedErrorClick[];
+}
+export interface PageFrictionReport {
+    url: string;
+    totalSessions: number;
+    frustratedSessions: number;
+    frustrationRatePct: number;
+    averageFrustrationScore: number;
+    topOffendingSelectors: Array<{
+        selector: string;
+        rageClicks: number;
+        deadClicks: number;
+        errorClicks: number;
+        totalFrictionEvents: number;
+    }>;
+    summaryRecommendation: string;
+}
+export interface FrustrationDetectionOptions {
+    rageClickThreshold?: number;
+    rageClickWindowMs?: number;
+    errorClickWindowMs?: number;
+    deadClickWindowMs?: number;
+}
+export declare class FrustrationAnalyzer {
+    /**
+     * Détecte les Rage Clicks dans un flux ordonné d'interactions.
+     */
+    static detectRageClicks(events: RawInteractionEvent[], options?: FrustrationDetectionOptions): DetectedRageClick[];
+    private static formatRageCluster;
+    /**
+     * Détecte les Dead Clicks : clics sur des éléments interactifs sans réaction.
+     */
+    static detectDeadClicks(events: RawInteractionEvent[], options?: FrustrationDetectionOptions): DetectedDeadClick[];
+    /**
+     * Détecte les Error Clicks : clics immédiatement suivis d'une erreur JS ou réseau.
+     * Attribue chaque erreur au clic le plus proche survenu dans la fenêtre temporelle.
+     */
+    static detectErrorClicks(events: RawInteractionEvent[], options?: FrustrationDetectionOptions): DetectedErrorClick[];
+    /**
+     * Calcule le score global de frustration d'une session (0 à 100).
+     */
+    static analyzeSession(events: RawInteractionEvent[], sessionId?: string, options?: FrustrationDetectionOptions): SessionFrustrationResult;
+    /**
+     * Agrège les signaux de frustration par URL pour identifier les pages à friction critique.
+     */
+    static aggregateFrictionByPage(sessions: Array<{
+        sessionId: string;
+        events: RawInteractionEvent[];
+    }>, options?: FrustrationDetectionOptions): PageFrictionReport[];
+    private static bumpSelector;
+}

package/dist/analytics/frustration-signals-engine.d.ts

@@ -0,0 +1,88 @@
+/**
+ * FrustrationSignalsEngine — Détection des Signaux de Frustration UX
+ *
+ * Parité : FullStory (Frustration Index), PostHog (Rage Clicks & Dead Clicks), Hotjar.
+ *
+ * Analyse les flux d'interactions utilisateur (clics, mouvements de souris, erreurs JS, mutations DOM)
+ * pour identifier automatiquement les points de friction et blocages d'expérience :
+ *
+ * 1. Rage Clicks : Clics frénétiques répétés (>= 3 clics dans un rayon de 25px en moins de 600ms).
+ * 2. Dead Clicks : Clics sur des éléments statiques / non interactifs sans aucun effet
+ *    (aucune navigation, aucune mutation DOM, aucune requête réseau dans les 1000ms suivantes).
+ * 3. Error Clicks : Clics immédiatement suivis (dans les 1000ms) d'une erreur JavaScript ou requête réseau en échec.
+ * 4. Mouse Thrashing (Agitation du curseur) : Mouvements erratiques rapides avec changements d'angle brusques
+ *    (indicateur de confusion, attente ou lenteur de chargement).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface InteractionClick {
+    id: string;
+    timestamp: number;
+    x: number;
+    y: number;
+    targetTag: string;
+    targetSelector: string;
+    targetText?: string;
+    hasNavigationFollowup?: boolean;
+    hasDomMutationFollowup?: boolean;
+    hasNetworkCallFollowup?: boolean;
+}
+export interface InteractionError {
+    timestamp: number;
+    message: string;
+    sourceUrl?: string;
+}
+export interface MouseTrajectoryPoint {
+    timestamp: number;
+    x: number;
+    y: number;
+}
+export interface SessionInteractionStream {
+    sessionId: string;
+    pageUrl: string;
+    clicks: InteractionClick[];
+    errors: InteractionError[];
+    mouseMovements?: MouseTrajectoryPoint[];
+}
+export type FrustrationType = "rage_click" | "dead_click" | "error_click" | "mouse_thrashing";
+export interface DetectedFrustrationEvent {
+    id: string;
+    type: FrustrationType;
+    timestamp: number;
+    targetSelector?: string;
+    targetText?: string;
+    scoreContribution: number;
+    details: string;
+}
+export interface ElementFrustrationHotspot {
+    targetSelector: string;
+    totalFrustrations: number;
+    rageClicksCount: number;
+    deadClicksCount: number;
+    errorClicksCount: number;
+    frustrationScore: number;
+}
+export interface FrustrationAuditReport {
+    sessionId: string;
+    pageUrl: string;
+    overallFrustrationScore: number;
+    frustrationLevel: "none" | "low" | "medium" | "high" | "severe";
+    summary: {
+        totalClicks: number;
+        rageClicksCount: number;
+        deadClicksCount: number;
+        errorClicksCount: number;
+        mouseThrashingCount: number;
+    };
+    events: DetectedFrustrationEvent[];
+    topHotspots: ElementFrustrationHotspot[];
+    recommendations: string[];
+    generatedAt: string;
+}
+export declare class FrustrationSignalsEngine {
+    private readonly rageClickRadius;
+    private readonly rageClickWindowMs;
+    private readonly errorClickWindowMs;
+    analyze(stream: SessionInteractionStream): FrustrationAuditReport;
+    private detectMouseThrashing;
+}

package/dist/analytics/funnel-velocity-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * FunnelVelocityEngine — Analyse de vélocité d'entonnoir et distribution du temps de conversion
+ *
+ * Calcule :
+ * 1. Le temps écoulé entre chaque étape consécutive d'un entonnoir (Step N -> Step N+1).
+ * 2. Les percentiles de latence de conversion (P25, Médiane/P50, P75, P90, Moyenne).
+ * 3. L'histogramme de distribution temporelle pour distinguer la conversion immédiate
+ *    de l'indécision ou de l'abandon par friction.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface FunnelVelocityEvent {
+    distinctId: string;
+    stepName: string;
+    timestamp: string | Date;
+}
+export interface FunnelVelocityOptions {
+    steps: string[];
+    conversionWindowMs?: number;
+}
+export interface TimeDurationBucket {
+    label: string;
+    minSeconds: number;
+    maxSeconds: number | null;
+    count: number;
+    percentage: number;
+}
+export interface StepVelocityMetrics {
+    fromStep: string;
+    toStep: string;
+    convertedUsersCount: number;
+    droppedUsersCount: number;
+    conversionRatePct: number;
+    meanSeconds: number;
+    medianSeconds: number;
+    p25Seconds: number;
+    p75Seconds: number;
+    p90Seconds: number;
+    minSeconds: number;
+    maxSeconds: number;
+    distribution: TimeDurationBucket[];
+}
+export interface FunnelVelocityReport {
+    steps: string[];
+    totalEntered: number;
+    totalCompleted: number;
+    overallConversionRatePct: number;
+    overallMedianDurationSeconds: number;
+    stepVelocities: StepVelocityMetrics[];
+    generatedAt: string;
+}
+export declare class FunnelVelocityEngine {
+    calculate(events: FunnelVelocityEvent[], options: FunnelVelocityOptions): FunnelVelocityReport;
+    private getPercentile;
+}

package/dist/analytics/funnels.d.ts

@@ -0,0 +1,22 @@
+export interface FunnelStep {
+    id: string;
+    match: {
+        type: 'pageview' | 'event';
+        urlPattern?: string;
+        eventName?: string;
+    };
+}
+export interface FunnelDef {
+    id: string;
+    siteId: string;
+    name: string;
+    steps: FunnelStep[];
+    windowHours?: number;
+}
+export interface FunnelResultStep {
+    stepId: string;
+    users: number;
+    conversionFromPrev: number;
+    conversionFromStart: number;
+}
+export declare function computeFunnel(steps: FunnelResultStep[]): FunnelResultStep[];

package/dist/analytics/ga4-data-transpiler.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Ga4DataTranspiler — Swetrix & Matomo GA4 Importer / BigQuery Export Parity
+ *
+ * Transpile et normalise les exports d'événements Google Analytics 4 (BigQuery, JSON, CSV)
+ * vers le schéma d'événements canonique LynxSEO.
+ *
+ * Mappe les événements standard (page_view, purchase, scroll, user_engagement),
+ * extrait et aplatit les paramètres d'événements typés (string_value, int_value, float_value)
+ * et préserve les dimensions personnalisées ainsi que les propriétés e-commerce.
+ */
+export interface Ga4RawParamValue {
+    string_value?: string;
+    int_value?: string | number;
+    float_value?: number;
+    double_value?: number;
+}
+export interface Ga4RawParam {
+    key: string;
+    value: Ga4RawParamValue | string | number | boolean;
+}
+export interface Ga4RawItem {
+    item_id?: string;
+    item_name?: string;
+    item_category?: string;
+    price?: number;
+    quantity?: number;
+}
+export interface Ga4RawEventRecord {
+    event_date?: string;
+    event_timestamp?: string | number;
+    event_name: string;
+    event_params?: Ga4RawParam[] | Record<string, unknown>;
+    user_id?: string;
+    user_pseudo_id?: string;
+    geo?: {
+        country?: string;
+        region?: string;
+        city?: string;
+    };
+    device?: {
+        category?: string;
+        operating_system?: string;
+        web_info?: {
+            browser?: string;
+        };
+    };
+    traffic_source?: {
+        name?: string;
+        medium?: string;
+        source?: string;
+    };
+    items?: Ga4RawItem[];
+}
+export interface CanonicalLynxEvent {
+    eventId: string;
+    eventName: string;
+    originalGa4Event: string;
+    timestamp: number;
+    userId?: string;
+    anonymousId: string;
+    url: string;
+    path: string;
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    country?: string;
+    deviceType?: string;
+    browser?: string;
+    properties: Record<string, unknown>;
+    ecommerce?: {
+        transactionId?: string;
+        value?: number;
+        currency?: string;
+        items?: Ga4RawItem[];
+    };
+}
+export interface TranspilationSummary {
+    totalInputRecords: number;
+    successfullyTranspiled: number;
+    skippedOrMalformed: number;
+    uniqueUsersCount: number;
+    totalRevenue: number;
+    earliestTimestamp?: number;
+    latestTimestamp?: number;
+    eventsByType: Record<string, number>;
+    events: CanonicalLynxEvent[];
+}
+export declare class Ga4DataTranspiler {
+    /**
+     * Transpile un lot d'enregistrements bruts GA4 en événements LynxSEO.
+     */
+    static transpile(records: Ga4RawEventRecord[]): TranspilationSummary;
+    private static mapEventName;
+    private static flattenParams;
+}

package/dist/analytics/ga4-historical-importer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * GA4 Historical Data Importer & Event Schema Mapper
+ * Clean-room implementation inspired by Swetrix data-import & GA4 BigQuery export format.
+ * Ingests, parses, and normalizes Google Analytics 4 export rows into LynxSEO unified event models.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface Ga4RawEventRow {
+    event_date: string;
+    event_timestamp?: string | number;
+    event_name: string;
+    user_pseudo_id: string;
+    ga_session_id?: string | number;
+    page_location?: string;
+    page_title?: string;
+    traffic_source?: string;
+    traffic_medium?: string;
+    traffic_campaign?: string;
+    purchase_revenue?: number;
+    currency?: string;
+}
+export interface LynxSeoImportedEvent {
+    siteId: string;
+    timestamp: string;
+    eventType: string;
+    visitorId: string;
+    sessionId?: string;
+    path: string;
+    pageTitle?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    revenue?: number;
+    currency?: string;
+}
+export interface Ga4ImportSummary {
+    totalProcessed: number;
+    totalImported: number;
+    totalSkipped: number;
+    eventsByType: Record<string, number>;
+    events: LynxSeoImportedEvent[];
+    errors: string[];
+}
+export declare class Ga4HistoricalImporter {
+    static importGa4Batch(siteId: string, rows: Ga4RawEventRow[]): Ga4ImportSummary;
+    private static mapGa4EventType;
+    private static parseDate;
+}

package/dist/analytics/goal-pacing-tracker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Metric Goal & KPI Pacing Tracker
+ *
+ * Implémentation clean-room conforme aux standards Metabase KPI Pacing & PostHog Goals.
+ * Compare les réalisations actuelles par rapport au calendrier linéaire cible,
+ * projette la valeur finale selon le run-rate actuel et diagnostique les risques de sous-performance.
+ */
+export type GoalPacingStatus = 'ahead' | 'on_track' | 'at_risk' | 'behind';
+export interface GoalPacingInput {
+    goalId: string;
+    goalName: string;
+    metric: string;
+    targetValue: number;
+    currentValue: number;
+    periodStart: string | number;
+    periodEnd: string | number;
+    asOfDate?: string | number;
+}
+export interface GoalPacingAnalysis {
+    goalId: string;
+    goalName: string;
+    metric: string;
+    targetValue: number;
+    currentValue: number;
+    elapsedDays: number;
+    totalDays: number;
+    remainingDays: number;
+    timeElapsedPercentage: number;
+    targetCompletionPercentage: number;
+    expectedValueAtCurrentTime: number;
+    pacingRatio: number;
+    status: GoalPacingStatus;
+    currentDailyRunRate: number;
+    requiredDailyRunRate: number;
+    projectedEndValue: number;
+    projectedDelta: number;
+    recommendation: string;
+}
+export declare class GoalPacingTracker {
+    /**
+     * Analyse le rythme d'avancement d'un objectif KPI.
+     */
+    static calculate(input: GoalPacingInput): GoalPacingAnalysis;
+}

package/dist/analytics/google-update-impact-analyzer.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Google Algorithm Update Impact Analyzer
+ *
+ * Correlates organic search performance (impressions, clicks, rankings, CTR) with Google algorithm updates
+ * (Core Updates, Helpful Content Updates, Spam Updates).
+ * Calculates pre-vs-post roll-out windows, identifies winning vs losing URL clusters, and provides
+ * recovery diagnoses with actionable steps.
+ */
+export interface GoogleUpdateDefinition {
+    id: string;
+    name: string;
+    category: "core" | "helpful_content" | "spam" | "reviews" | "page_experience";
+    rolloutDate: string;
+    completionDate?: string;
+}
+export interface DailySearchMetric {
+    date: string;
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    averagePosition: number;
+    url?: string;
+    directory?: string;
+}
+export interface DirectoryImpact {
+    directory: string;
+    preClicks: number;
+    postClicks: number;
+    clickDelta: number;
+    percentChange: number;
+    status: "hit" | "stable" | "benefited";
+}
+export interface UrlImpact {
+    url: string;
+    preClicks: number;
+    postClicks: number;
+    prePosition: number;
+    postPosition: number;
+    clickDelta: number;
+    percentChange: number;
+}
+export interface AlgorithmImpactReport {
+    update: GoogleUpdateDefinition;
+    analyzedDaysWindow: number;
+    preWindow: {
+        start: string;
+        end: string;
+        totalClicks: number;
+        totalImpressions: number;
+        avgCtr: number;
+        avgPosition: number;
+    };
+    postWindow: {
+        start: string;
+        end: string;
+        totalClicks: number;
+        totalImpressions: number;
+        avgCtr: number;
+        avgPosition: number;
+    };
+    impactDeltas: {
+        clickDelta: number;
+        clickPercentChange: number;
+        impressionDelta: number;
+        impressionPercentChange: number;
+        positionDelta: number;
+    };
+    diagnosis: {
+        severity: "critical_loss" | "moderate_drop" | "neutral" | "positive_gain";
+        headline: string;
+        description: string;
+        probableCause: string;
+        recommendations: string[];
+    };
+    affectedDirectories: DirectoryImpact[];
+    topLosers: UrlImpact[];
+    topWinners: UrlImpact[];
+}
+export declare class GoogleUpdateImpactAnalyzer {
+    /**
+     * Evaluates the impact of a Google Update by comparing the pre-rollout window vs post-rollout window.
+     * Default window is 14 days before and 14 days after rollout.
+     */
+    static analyze(update: GoogleUpdateDefinition, dailyMetrics: DailySearchMetric[], windowDays?: number): AlgorithmImpactReport | null;
+}

package/dist/analytics/heading-hierarchy-outline-validator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HeadingHierarchyOutlineValidator
+ * Validates document heading structure (H1-H6) for SEO topical hierarchy,
+ * WCAG 2.2 1.3.1 accessibility, skipped levels, and outline integrity.
+ */
+export type HeadingIssueSeverity = "critical" | "warning" | "info";
+export interface FlatHeadingEntry {
+    level: number;
+    text: string;
+    orderIndex: number;
+}
+export interface HeadingTreeNode {
+    level: number;
+    text: string;
+    children: HeadingTreeNode[];
+}
+export interface HeadingIssue {
+    type: "missing_h1" | "multiple_h1" | "skipped_heading_level" | "empty_heading" | "excessively_long_heading" | "duplicate_heading_text";
+    severity: HeadingIssueSeverity;
+    description: string;
+    headingText?: string;
+    level?: number;
+    expectedLevel?: number;
+}
+export interface HeadingAuditReport {
+    totalHeadings: number;
+    h1Count: number;
+    h2Count: number;
+    h3Count: number;
+    h4Count: number;
+    h5Count: number;
+    h6Count: number;
+    structureScore: number;
+    isHierarchyValid: boolean;
+    issues: HeadingIssue[];
+    outlineTree: HeadingTreeNode[];
+    recommendations: string[];
+}
+export declare class HeadingHierarchyOutlineValidator {
+    /**
+     * Audits the heading structure of an HTML string.
+     */
+    audit(html: string): HeadingAuditReport;
+    private extractHeadings;
+    private buildOutlineTree;
+}