@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/event-match-quality.d.ts

@@ -0,0 +1,53 @@
+/**
+ * EventMatchQuality (EMQ) — Évaluateur de qualité de matching des événements publicitaires (Meta CAPI, TikTok Events API).
+ *
+ * Mesure l'efficacité avec laquelle les événements transmis côté serveur peuvent être reliés
+ * aux profils utilisateurs sur les régies publicitaires (Meta, TikTok, Pinterest).
+ * Échelle standardisée de 0 à 10 calquée sur le Meta Events Manager :
+ * - >= 8.0 : Great (Qualité optimale, ciblage et ROAS optimaux)
+ * - >= 6.0 : Good (Bonne attribution, opportunités d'amélioration)
+ * - >= 4.0 : Fair (Attribution partielle, signaux manquants)
+ * - < 4.0  : Poor (Signaux insuffisants, risque de dégradation d'enchère)
+ */
+export interface EmqInput {
+    email?: string | null;
+    phone?: string | null;
+    externalId?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    clientIp?: string | null;
+    clientUserAgent?: string | null;
+    fbp?: string | null;
+    fbc?: string | null;
+    city?: string | null;
+    zip?: string | null;
+    country?: string | null;
+}
+export type EmqRating = "poor" | "fair" | "good" | "great";
+export interface EmqSignalDetail {
+    weight: number;
+    earned: number;
+    present: boolean;
+}
+export interface EmqEvaluation {
+    score: number;
+    rating: EmqRating;
+    signalsPresent: string[];
+    signalsMissing: string[];
+    recommendations: string[];
+    breakdown: Record<string, EmqSignalDetail>;
+}
+export declare class EventMatchQuality {
+    /**
+     * Poids standardisés des signaux d'attribution selon les spécifications Meta & TikTok CAPI.
+     */
+    private static readonly WEIGHTS;
+    /**
+     * Vérifie si une valeur est exploitable (non vide et non factice).
+     */
+    private static isUsable;
+    /**
+     * Évalue le score Event Match Quality (EMQ) pour un événement et ses signaux associés.
+     */
+    static evaluate(input: EmqInput): EmqEvaluation;
+}

package/dist/analytics/event-transformation-runtime.d.ts

@@ -0,0 +1,76 @@
+/**
+ * EventTransformationRuntime — Moteur de transformation & enrichissement d'événements (RudderStack & Segment Transformations Parity)
+ *
+ * Permet d'appliquer des règles de transformation déclaratives et déterministes sur
+ * les flux d'événements analytiques avant leur persistance ou leur dispatching vers les destinations :
+ * - Filtrage conditionnel (drop des événements indésirables, bot, staging)
+ * - Renommage d'événements et normalisation
+ * - Masquage et suppression de propriétés PII sensibles
+ * - Enrichissement de propriétés (traits calculés, tags, devise, segments)
+ * - Mutateurs de typage et sanitisation de valeurs.
+ */
+export type TransformFilterOperator = "equals" | "not_equals" | "contains" | "regex" | "exists" | "not_exists" | "in";
+export interface FilterCondition {
+    field: string;
+    operator: TransformFilterOperator;
+    value?: unknown;
+}
+export interface TransformRule {
+    id: string;
+    name: string;
+    enabled: boolean;
+    order: number;
+    conditions?: FilterCondition[];
+    action: "drop" | "rename_event" | "redact_fields" | "enrich_properties" | "rename_fields";
+    newEventName?: string;
+    fieldsToRedact?: string[];
+    fieldsToRename?: Record<string, string>;
+    propertiesToEnrich?: Record<string, unknown>;
+}
+export interface AnalyticsEvent {
+    id?: string;
+    name: string;
+    userId?: string;
+    anonymousId?: string;
+    timestamp?: number;
+    properties?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+export interface TransformationReport {
+    totalProcessed: number;
+    keptCount: number;
+    droppedCount: number;
+    modifiedCount: number;
+    appliedRulesCount: Record<string, number>;
+    events: AnalyticsEvent[];
+}
+export declare class EventTransformationRuntime {
+    /**
+     * Résout une valeur imbriquée par son chemin pointé ("properties.price")
+     */
+    private static getNestedValue;
+    /**
+     * Définit une valeur imbriquée par son chemin pointé
+     */
+    private static setNestedValue;
+    /**
+     * Supprime une clé imbriquée par son chemin pointé
+     */
+    private static deleteNestedValue;
+    /**
+     * Évalue si un événement remplit une liste de conditions de filtrage
+     */
+    static matchesConditions(event: AnalyticsEvent, conditions?: FilterCondition[]): boolean;
+    /**
+     * Exécute un ensemble de règles sur un événement individuel
+     */
+    static transformEvent(event: AnalyticsEvent, rules: TransformRule[]): {
+        transformed: AnalyticsEvent | null;
+        rulesApplied: string[];
+        modified: boolean;
+    };
+    /**
+     * Traite un lot d'événements et génère un rapport complet
+     */
+    static processBatch(events: AnalyticsEvent[], rules: TransformRule[]): TransformationReport;
+}

package/dist/analytics/events.d.ts

@@ -0,0 +1,24 @@
+import type { EventInput } from './types';
+export declare function normalizeEvent(input: EventInput): {
+    ipHash: string | undefined;
+    device: "other" | "mobile" | "desktop" | "tablet" | undefined;
+    consent: boolean;
+    ts: string;
+    siteId: string;
+    sessionId?: string;
+    visitorId?: string;
+    type: "pageview" | "click" | "form_submit" | "custom";
+    name?: string;
+    url: string;
+    referrer?: string;
+    userAgent?: string;
+    ip?: string;
+    country?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmTerm?: string;
+    utmContent?: string;
+    props?: Record<string, unknown>;
+};
+export declare function isBot(ua?: string): boolean;

package/dist/analytics/excessive-dom-depth-node-count-auditor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - ExcessiveDomDepthNodeCountAuditor
+ * Analyzes DOM tree size, nesting depth, and maximum parent-child fan-out
+ * against Google Lighthouse Core Web Vitals thresholds (800 / 1400 nodes, 32 depth, 60 children).
+ */
+export interface DomTreeMetricsInput {
+    url: string;
+    totalElements?: number;
+    maxDepth?: number;
+    maxChildElements?: number;
+    deepestNodeSelector?: string;
+    parentWithMaxChildrenSelector?: string;
+    htmlString?: string;
+}
+export type DomIssueType = "excessive_total_elements" | "heavy_total_elements" | "excessive_tree_depth" | "excessive_parent_children_fanout";
+export interface DomAuditFinding {
+    issue: DomIssueType;
+    severity: "critical" | "warning";
+    currentValue: number;
+    threshold: number;
+    description: string;
+    recommendation: string;
+}
+export interface DomSizeAuditReport {
+    url: string;
+    classification: "optimal" | "heavy" | "excessive_dom_size";
+    score: number;
+    totalElements: number;
+    maxDepth: number;
+    maxChildElements: number;
+    deepestNodeSelector?: string;
+    parentWithMaxChildrenSelector?: string;
+    findings: DomAuditFinding[];
+    recommendations: string[];
+}
+export declare class ExcessiveDomDepthNodeCountAuditor {
+    private static readonly MAX_ELEMENTS_WARN;
+    private static readonly MAX_ELEMENTS_CRITICAL;
+    private static readonly MAX_DEPTH_CRITICAL;
+    private static readonly MAX_CHILDREN_CRITICAL;
+    /**
+     * Audits DOM tree metrics or extracts them directly from an HTML document string.
+     */
+    audit(input: DomTreeMetricsInput): DomSizeAuditReport;
+    private parseHtmlDomMetrics;
+}

package/dist/analytics/experiment-running-time-calculator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Experiment Sample Size & Running-Time Calculator
+ * Clean-room implementation of statistical sizing and experiment duration estimation.
+ * Supports Funnel (Binomial), Count/Mean, Revenue/Sum, and Ratio/Retention metrics with Delta-method variance.
+ * Parity: PostHog Experiment Running Time Calculator & Optimizely Stats Engine.
+ */
+export type ExperimentMetricType = "funnel" | "mean_count" | "mean_sum_or_avg" | "ratio" | "retention";
+export interface BaselineStatistics {
+    numberOfSamples: number;
+    sum: number;
+    sumSquares?: number;
+    denominatorSum?: number;
+    denominatorSumSquares?: number;
+    numeratorDenominatorSumProduct?: number;
+    stepCounts?: number[];
+}
+export interface RunningTimeCalculationInput {
+    metricType: ExperimentMetricType;
+    baselineValue?: number;
+    baselineStats?: BaselineStatistics;
+    /** Minimum Detectable Effect as a percentage (e.g. 5 for 5% relative lift) */
+    mdePercent: number;
+    /** Number of variants including control (e.g. 2 for A/B, 3 for A/B/C) */
+    numberOfVariants?: number;
+    /** Daily expected exposure rate (e.g. 500 visitors/day) */
+    dailyExposures?: number;
+}
+export interface RunningTimeCalculationResult {
+    metricType: ExperimentMetricType;
+    baselineValue: number;
+    derivedVariance?: number;
+    recommendedSampleSize: number;
+    estimatedRunningTimeDays?: number;
+    isFeasible: boolean;
+    notes?: string[];
+}
+export declare class ExperimentRunningTimeCalculator {
+    private static readonly SAMPLE_SIZE_Z_FACTOR;
+    private static readonly VARIANCE_SCALING_FACTOR_COUNT;
+    private static readonly VARIANCE_SCALING_FACTOR_SUM;
+    /**
+     * Derives baseline value from raw sample statistics.
+     */
+    static calculateBaselineValue(metricType: ExperimentMetricType, stats: BaselineStatistics): number | null;
+    /**
+     * Calculates variance for the metric, using the Delta method for ratios if needed.
+     */
+    static calculateVariance(metricType: ExperimentMetricType, baselineValue: number, stats?: BaselineStatistics): number | null;
+    /**
+     * Computes sample size and estimated duration.
+     */
+    static estimate(input: RunningTimeCalculationInput): RunningTimeCalculationResult;
+}

package/dist/analytics/experiment-sample-size-sequential-testing-engine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Sequential Testing & Early Stopping Engine (Batch 19 - Gap 3)
+ *
+ * Wald Sequential Probability Ratio Test (SPRT) & Sample Size Calculator
+ * inspired by Optimizely Stats Engine, Eppo Sequential Testing & Statsig mSPRT.
+ *
+ * Solves the continuous peeking problem in A/B testing by computing always-valid
+ * decision boundaries, enabling safe early stopping without inflating false positive
+ * (Type I error) rates. Includes Sample Ratio Mismatch (SRM) checks.
+ */
+export interface ExperimentVariantData {
+    name: string;
+    visitors: number;
+    conversions: number;
+}
+export interface SequentialTestConfig {
+    alpha?: number;
+    beta?: number;
+    expectedBaselineRate?: number;
+    minimumDetectableEffect?: number;
+}
+export type SequentialVerdict = "continue_test" | "stop_declare_winner" | "stop_declare_loser" | "sample_ratio_mismatch_detected";
+export interface SequentialTestReport {
+    controlName: string;
+    variantName: string;
+    controlConversionRate: number;
+    variantConversionRate: number;
+    relativeLift: number;
+    logLikelihoodRatio: number;
+    upperThresholdA: number;
+    lowerThresholdB: number;
+    srmPValue: number;
+    srmDetected: boolean;
+    verdict: SequentialVerdict;
+    recommendedFixedSampleSize: number;
+    currentTotalVisitors: number;
+    canStopEarlySafely: boolean;
+    actionableSummary: string;
+}
+export declare class ExperimentSampleSizeSequentialTestingEngine {
+    /**
+     * Evaluates sequential test boundaries and provides early stopping recommendation.
+     */
+    static evaluateSequentialTest(control: ExperimentVariantData, variant: ExperimentVariantData, config?: SequentialTestConfig): SequentialTestReport;
+}

package/dist/analytics/exports.d.ts

@@ -0,0 +1,2 @@
+export declare function toCsv(rows: any[], headers?: string[]): string;
+export declare function toJson(rows: any[]): string;

package/dist/analytics/facet-url-combinatorial-trap-auditor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - FacetUrlCombinatorialTrapAuditor
+ * Detects faceted navigation spider traps, parameter permutations, infinite crawls,
+ * and session-ID leakage in e-commerce and catalog architectures.
+ */
+export type FacetTrapSeverity = "critical" | "high" | "medium" | "low";
+export interface FacetParameterAnalysis {
+    paramName: string;
+    uniqueValuesFound: string[];
+    isTrackingParam: boolean;
+    isSortingParam: boolean;
+    isPaginationParam: boolean;
+    isFilterParam: boolean;
+    isSessionParam: boolean;
+}
+export interface DetectedSpiderTrap {
+    type: "parameter_order_permutation" | "combinatorial_explosion" | "tracking_param_internal_link" | "session_id_in_url" | "sorting_duplicate_risk" | "deep_pagination_trap";
+    severity: FacetTrapSeverity;
+    description: string;
+    affectedUrlSample: string[];
+    estimatedWastedPages?: number;
+    remediationRule: string;
+}
+export interface FacetAuditReport {
+    totalUrlsAudited: number;
+    uniqueBasePaths: number;
+    totalParametersDiscovered: number;
+    maxParametersOnSingleUrl: number;
+    spiderTrapRisk: "safe" | "moderate" | "severe" | "critical";
+    parameters: FacetParameterAnalysis[];
+    traps: DetectedSpiderTrap[];
+    recommendedRobotsDisallow: string[];
+    canonicalizationAdvice: string[];
+}
+export declare class FacetUrlCombinatorialTrapAuditor {
+    private static readonly TRACKING_PREFIXES;
+    private static readonly SESSION_NAMES;
+    private static readonly SORT_NAMES;
+    private static readonly PAGINATION_NAMES;
+    /**
+     * Audits a batch of URLs discovered during crawling or log analysis.
+     */
+    audit(urls: string[]): FacetAuditReport;
+}

package/dist/analytics/feature-flag-dormancy-auditor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 🚩 Feature Flag Dormancy & Zombie Flag Auditor
+ * Clean-room implementation inspired by LaunchDarkly Flag Health & PostHog Stale Flags.
+ *
+ * Audits feature flags across environments, identifies technical debt (zombies at 100%, abandoned flags,
+ * stale 50/50 experiments), and generates actionable code cleanup and removal directives.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface FlagEnvironmentState {
+    environment: string;
+    enabled: boolean;
+    rolloutPercentage: number;
+    evaluationsLast30Days: number;
+    lastEvaluatedTimestamp?: number;
+}
+export interface FeatureFlagMetadata {
+    key: string;
+    name: string;
+    createdAtTimestamp: number;
+    isPermanent?: boolean;
+    environments: FlagEnvironmentState[];
+    tags?: string[];
+    owner?: string;
+}
+export type DormancyClassification = "healthy_active" | "permanent_zombie" | "dead_abandoned" | "stale_experiment" | "unreleased_dormant";
+export interface FlagDormancyIssue {
+    flagKey: string;
+    flagName: string;
+    classification: DormancyClassification;
+    severity: "critical" | "warning" | "info";
+    ageDays: number;
+    daysAtFullRollout?: number;
+    totalEvaluations30d: number;
+    cleanupDifficulty: "trivial" | "moderate" | "complex";
+    actionPlan: string;
+}
+export interface FlagDormancyAuditReport {
+    totalFlagsAudited: number;
+    healthyFlagsCount: number;
+    zombieFlagsCount: number;
+    deadFlagsCount: number;
+    staleExperimentsCount: number;
+    flagHygieneScore: number;
+    issues: FlagDormancyIssue[];
+    safeRemovalCandidates: string[];
+    summary: {
+        status: "clean" | "minor_debt" | "severe_debt";
+        recommendedNextStep: string;
+    };
+}
+export declare class FeatureFlagDormancyAuditor {
+    private static readonly ONE_DAY_MS;
+    /**
+     * Audits a list of feature flags for dormancy and code debt.
+     */
+    static audit(flags: FeatureFlagMetadata[], currentTimestamp?: number): FlagDormancyAuditReport;
+    private static emptyReport;
+}

package/dist/analytics/feature-flag-evaluator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FeatureFlagEvaluator — clean-room feature flag evaluation & targeting engine.
+ * Inspired by PostHog / Swetrix feature flags.
+ * Supports: percentage rollouts, user ID hashing, property-based filters, variant overrides.
+ * AGPL-3.0-or-later
+ */
+export interface FlagFilter {
+    property: string;
+    operator: "exact" | "contains" | "regex" | "gt" | "lt" | "in";
+    value: string | number | boolean | Array<string | number>;
+}
+export interface FlagVariant {
+    key: string;
+    rolloutPercentage: number;
+}
+export interface FeatureFlagDefinition {
+    key: string;
+    name: string;
+    enabled: boolean;
+    /** Rollout percentage 0 - 100 for gradual release */
+    rolloutPercentage: number;
+    filters?: FlagFilter[];
+    variants?: FlagVariant[];
+    description?: string;
+}
+export interface EvaluationContext {
+    distinctId: string;
+    properties?: Record<string, string | number | boolean>;
+}
+export interface EvaluationResult {
+    key: string;
+    enabled: boolean;
+    variant?: string;
+    reason: "flag_disabled" | "filter_mismatch" | "rollout_excluded" | "matched";
+}
+/** Deterministic hash for string into 0..99 integer (clean-room FNV-1a variant). */
+export declare function hashDistinctId(key: string, distinctId: string): number;
+export declare class FeatureFlagEvaluator {
+    private flags;
+    upsertFlag(projectId: string, flag: FeatureFlagDefinition): void;
+    getFlag(projectId: string, key: string): FeatureFlagDefinition | null;
+    listFlags(projectId: string): FeatureFlagDefinition[];
+    deleteFlag(projectId: string, key: string): boolean;
+    evaluate(projectId: string, key: string, context: EvaluationContext): EvaluationResult;
+    evaluateAll(projectId: string, context: EvaluationContext): Record<string, {
+        enabled: boolean;
+        variant?: string;
+    }>;
+}

package/dist/analytics/flag-blast-radius-simulator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * FlagBlastRadiusSimulator — Simulateur de Rayon d'Impact & Évaluation de Risque de Déploiement de Feature Flag
+ *
+ * Parité : PostHog (Early Access & Flag Impact) & LaunchDarkly (Blast Radius & Error Budget Safeguard).
+ *
+ * Évalue l'impact potentiel d'un déploiement de Feature Flag AVANT sa mise en production :
+ * 1. Calcul du Rayon d'Impact (Blast Radius) :
+ *    - Nombre absolu et pourcentage d'utilisateurs exposés (DAU / MAU).
+ *    - Exposition des comptes VIP, Enterprise et à fort revenu (MRR / ARR).
+ * 2. Simulation de Consommation du Budget d'Erreur (Error Budget Burn Rate) :
+ *    - Estimation du temps avant rupture du SLO (99.9% / 99.99%) selon différents scénarios de panne (0.5%, 2%, 5% d'erreurs).
+ * 3. Matrice de Risque et Score de Sécurité de Déploiement (0 à 100).
+ * 4. Génération automatique d'un Plan de Déploiement Progressif en 4 phases (Canary Staged Schedule)
+ *    avec critères stricts de passage de palier et déclencheurs d'annulation automatique (Auto-Rollback Triggers).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface FlagUserPopulation {
+    totalUsers: number;
+    dailyActiveUsers: number;
+    enterpriseUsersCount: number;
+    monthlyRecurringRevenueTotal: number;
+    enterpriseMrrShare: number;
+}
+export interface SimulationParams {
+    flagKey: string;
+    targetRolloutPercentage: number;
+    targetSegments?: string[];
+    population: FlagUserPopulation;
+    sloTarget?: number;
+}
+export type BlastRadiusRisk = "minimal" | "moderate" | "high" | "critical";
+export interface StagedRolloutPhase {
+    phase: number;
+    name: string;
+    percentage: number;
+    observationPeriodHours: number;
+    maxToleratedErrorRate: number;
+    rollbackTriggerCondition: string;
+}
+export interface FlagBlastRadiusReport {
+    flagKey: string;
+    targetRolloutPercentage: number;
+    exposedUsersCount: number;
+    exposedDauCount: number;
+    exposedEnterpriseUsers: number;
+    exposedMrrAtRisk: number;
+    blastRadiusRisk: BlastRadiusRisk;
+    safetyScore: number;
+    errorBudgetProjection: {
+        slo: number;
+        minutesToExhaustSloAt1PercentFailure: number;
+        minutesToExhaustSloAt5PercentFailure: number;
+    };
+    recommendedStagedPlan: StagedRolloutPhase[];
+    guardrails: string[];
+    generatedAt: string;
+}
+export declare class FlagBlastRadiusSimulator {
+    simulate(params: SimulationParams): FlagBlastRadiusReport;
+}

package/dist/analytics/font-display-cls-layout-shift-auditor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - FontDisplayClsLayoutShiftAuditor
+ * Audits CSS @font-face declarations for font-display strategy (FOIT/FOUT),
+ * Cumulative Layout Shift (CLS) font metric overrides (size-adjust, ascent-override),
+ * and WOFF2 modern font compression.
+ */
+export interface FontFaceRuleInput {
+    fontFamily: string;
+    fontDisplay?: "auto" | "block" | "swap" | "fallback" | "optional" | string;
+    src?: string;
+    sizeAdjust?: string;
+    ascentOverride?: string;
+    descentOverride?: string;
+    lineGapOverride?: string;
+    unicodeRange?: string;
+    isPreloaded?: boolean;
+}
+export type FontIssueType = "missing_font_display" | "foit_render_blocking_block" | "fout_cls_swap_without_overrides" | "legacy_font_format" | "missing_unicode_range_subsetting" | "unoptimized_font_preload";
+export interface FontAuditFinding {
+    fontFamily: string;
+    issue: FontIssueType;
+    severity: "critical" | "warning" | "info";
+    description: string;
+    recommendation: string;
+}
+export interface FallbackFontMetricOverrides {
+    fallbackFont: "Arial" | "Roboto" | "Georgia" | "Times New Roman" | "system-ui";
+    sizeAdjust: string;
+    ascentOverride: string;
+    descentOverride: string;
+    lineGapOverride: string;
+    cssSnippet: string;
+}
+export interface FontAuditReport {
+    totalFontsAudited: number;
+    score: number;
+    hasFoitRisk: boolean;
+    hasClsRisk: boolean;
+    findings: FontAuditFinding[];
+    metricOverrides: FallbackFontMetricOverrides[];
+    optimizedCss: string;
+}
+export declare class FontDisplayClsLayoutShiftAuditor {
+    /**
+     * Audits CSS text or an array of parsed @font-face rule inputs.
+     */
+    audit(input: string | FontFaceRuleInput[]): FontAuditReport;
+    private parseFontFaceCss;
+    private calculateFallbackOverrides;
+}

package/dist/analytics/font-loading-observer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Font Loading Observer & Web Font Performance Tracker
+ * Clean-room implementation inspired by OpenReplay font module & Web Vitals font metrics.
+ * Measures font load latencies, detects Flash of Invisible/Unstyled Text (FOIT/FOUT),
+ * and computes font layout shift risk indices.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface FontLoadEventInput {
+    family: string;
+    source?: string;
+    weight?: string;
+    style?: string;
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    loadTimeMs: number;
+    status: 'loaded' | 'error' | 'timeout';
+}
+export interface FontMetricAnalysis {
+    family: string;
+    loadTimeMs: number;
+    status: 'loaded' | 'error' | 'timeout';
+    hasFoitRisk: boolean;
+    hasFoutRisk: boolean;
+    layoutShiftRiskScore: number;
+    recommendation?: string;
+}
+export interface FontLoadingReport {
+    totalFontsObserved: number;
+    failedFontsCount: number;
+    avgLoadTimeMs: number;
+    maxLoadTimeMs: number;
+    fonts: FontMetricAnalysis[];
+    overallPerformanceGrade: 'good' | 'needs-improvement' | 'poor';
+}
+export declare class FontLoadingObserver {
+    static analyzeFonts(events: FontLoadEventInput[]): FontLoadingReport;
+}

package/dist/analytics/font-preload-unused-bandwidth-waste-auditor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - FontPreloadUnusedBandwidthWasteAuditor
+ * Audits font preloading tags (<link rel="preload" as="font">), detecting double-fetching
+ * due to missing crossorigin attribute and unused font preload bandwidth waste.
+ */
+export interface PreloadedFontInput {
+    href: string;
+    hasCrossOrigin: boolean;
+    crossOriginValue?: string;
+    transferSizeBytes?: number;
+}
+export interface FontUsageContextInput {
+    preloads: PreloadedFontInput[];
+    usedFontUrlsInDom: string[];
+}
+export type FontPreloadIssueType = "missing_crossorigin_double_fetch" | "unused_preload_bandwidth_waste" | "optimal";
+export interface FontPreloadFinding {
+    href: string;
+    issueType: FontPreloadIssueType;
+    wastedBytesEst: number;
+    explanation: string;
+    remediatedHtmlTag: string;
+}
+export interface FontPreloadAuditReport {
+    totalPreloadedFonts: number;
+    unusedPreloadsCount: number;
+    doubleFetchPreloadsCount: number;
+    totalWastedBandwidthBytes: number;
+    fontPreloadEfficiencyScore: number;
+    findings: FontPreloadFinding[];
+    strategicAdvice: string[];
+}
+export declare class FontPreloadUnusedBandwidthWasteAuditor {
+    private static readonly DEFAULT_FONT_SIZE_BYTES;
+    /**
+     * Audits preloaded fonts for double-fetching and unused bandwidth waste.
+     */
+    audit(context: FontUsageContextInput): FontPreloadAuditReport;
+}