@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/measurement-protocol-validator.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MeasurementProtocolValidator — Validateur de Payloads de Tracking Serveur-à-Serveur & CAPI
+ *
+ * Parité : Google Analytics 4 Measurement Protocol Validation Server, Matomo Tracking API, Meta CAPI.
+ *
+ * Valide et assainit rigoureusement les événements de tracking émis depuis le backend
+ * (Server-to-Server, Webhooks, API Gateway) avant leur ingestion dans le pipeline analytics :
+ *
+ * 1. Contrôle de Dérive Temporelle (Timestamp Drift Guard) :
+ *    - Rejette les événements de plus de 72 heures (limite stricte GA4) ou situés dans le futur (>15 min).
+ * 2. Validation d'Identifiants (Client ID / User ID) :
+ *    - Exige au moins un `client_id` conforme ou un `user_id` non vide.
+ * 3. Règles Strictes de Nommage des Événements :
+ *    - Caractères alphanumériques et underscores uniquement, longueur maximale de 40 caractères.
+ *    - Rejette les préfixes réservés (`_ga`, `ga_`, `firebase_`, `google_`).
+ * 4. Limites de Paramètres & Propriétés Utilisateur :
+ *    - Maximum 25 paramètres par événement, valeurs textuelles limitées à 100 caractères.
+ * 5. Garde-Fou PII & Données Confidentielles (Privacy Sentinel) :
+ *    - Détecte et bloque les adresses e-mail en clair, numéros de carte bancaire ou mots de passe passés dans les paramètres.
+ * 6. Clé de Déduplication (Event Deduplication) :
+ *    - Vérifie la présence de `event_id` ou `transaction_id` pour la réconciliation hybride client/serveur.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface MeasurementEvent {
+    name: string;
+    params?: Record<string, string | number | boolean | null>;
+}
+export interface MeasurementPayload {
+    client_id?: string;
+    user_id?: string;
+    timestamp_micros?: number;
+    events: MeasurementEvent[];
+    user_properties?: Record<string, string | number | boolean>;
+    consent?: {
+        ad_storage?: "granted" | "denied";
+        analytics_storage?: "granted" | "denied";
+    };
+}
+export interface ValidationError {
+    field: string;
+    code: "missing_identifier" | "timestamp_too_old" | "timestamp_in_future" | "invalid_event_name" | "reserved_event_prefix" | "too_many_parameters" | "pii_detected" | "missing_dedup_key";
+    message: string;
+}
+export interface MeasurementValidationResult {
+    isValid: boolean;
+    status: "accepted" | "rejected_with_errors" | "accepted_with_warnings";
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    eventsCount: number;
+    sanitizedPayload?: MeasurementPayload;
+    validatedAt: string;
+}
+export declare class MeasurementProtocolValidator {
+    private static readonly RESERVED_PREFIXES;
+    private static readonly MAX_EVENT_PARAMS;
+    private static readonly MAX_EVENT_NAME_LENGTH;
+    private static readonly MAX_PARAM_VALUE_LENGTH;
+    private static readonly SEVENTY_TWO_HOURS_MICROS;
+    private static readonly FIFTEEN_MINUTES_MICROS;
+    validate(payload: MeasurementPayload): MeasurementValidationResult;
+    private containsEmail;
+    private containsCreditCard;
+}

package/dist/analytics/meta-robots-unavailable-after-header-auditor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - MetaRobotsUnavailableAfterHeaderAuditor
+ * Audits Google's 'unavailable_after' robots directive, validating RFC 850/1123/ISO dates,
+ * calculating remaining indexation lifetime, and detecting expired de-indexed content.
+ */
+export interface UnavailableAfterAuditInput {
+    url: string;
+    robotsDirectives: string[];
+    referenceTimestampMs?: number;
+}
+export type UnavailableAfterStatus = "not_configured" | "scheduled_deindexation_active" | "expired_deindexed" | "invalid_date_syntax";
+export interface UnavailableAfterAuditReport {
+    url: string;
+    status: UnavailableAfterStatus;
+    rawDirectiveValue: string | null;
+    parsedExpirationIso: string | null;
+    isDeindexed: boolean;
+    timeRemainingMs: number | null;
+    timeRemainingHours: number | null;
+    strategicAdvice: string;
+}
+export declare class MetaRobotsUnavailableAfterHeaderAuditor {
+    private static readonly UNAVAILABLE_AFTER_REGEX;
+    /**
+     * Audits robots directives for the unavailable_after expiration schedule.
+     */
+    audit(input: UnavailableAfterAuditInput): UnavailableAfterAuditReport;
+}

package/dist/analytics/metric-driver-analyzer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LynxSEO Engine - Metric Delta & Driver Decomposition Engine
+ *
+ * Automatically decomposes the variance of any SEO/product metric between two periods
+ * across categorical dimensions (e.g. device, referrer, country, landing page)
+ * to explain exactly what caused the increase or drop.
+ *
+ * (Parity: Metabase X-Rays & Amplitude Metric Drivers).
+ */
+export interface DimensionSliceEntry {
+    dimension: string;
+    value: string;
+    baselineMetric: number;
+    currentMetric: number;
+}
+export interface DriverImpactItem {
+    dimension: string;
+    value: string;
+    baseline: number;
+    current: number;
+    delta: number;
+    percentChange: number;
+    contributionSharePercent: number;
+    direction: "positive" | "negative" | "neutral";
+}
+export interface MetricDriverReport {
+    metricName: string;
+    totalBaseline: number;
+    totalCurrent: number;
+    totalDelta: number;
+    totalPercentChange: number;
+    topPositiveDrivers: DriverImpactItem[];
+    topNegativeDrivers: DriverImpactItem[];
+    allDrivers: DriverImpactItem[];
+}
+export declare class MetricDriverAnalyzer {
+    /**
+     * Decomposes total metric variance into dimensional driver contributions.
+     */
+    analyzeDrivers(metricName: string, slices: DimensionSliceEntry[]): MetricDriverReport;
+}

package/dist/analytics/metric-formula-engine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MetricFormulaEngine — Moteur d'évaluation de formules de métriques analytiques personnalisées (Parité Metabase / PostHog).
+ *
+ * Évalue en toute sécurité (sans eval/Function) des expressions mathématiques et logiques :
+ * - Arithmétique : +, -, *, /, %, ^
+ * - Logique : ==, !=, >, <, >=, <=, &&, ||
+ * - Fonctions d'agrégation conditionnelle : SumIf(val, cond), CountIf(cond), AvgIf(val, cond)
+ * - Fonctions métier : ShareOf(part, total), GrowthRate(actuel, précédent), Round(val, precision)
+ * - Fenêtrage : CumulativeSum(serie), MovingAverage(serie, fenetre)
+ */
+export interface FormulaRowContext {
+    [key: string]: unknown;
+}
+export interface MetricSeriesRow {
+    date?: string;
+    [key: string]: unknown;
+}
+export interface EvaluatedFormulaResult {
+    formula: string;
+    success: boolean;
+    scalarResult?: number | boolean | string | null;
+    seriesResult?: Array<{
+        date?: string;
+        value: number | null;
+    }>;
+    error?: string;
+}
+export declare class MetricFormulaEngine {
+    /**
+     * Évalue une formule sur un contexte scalaire (ex: métriques globales d'un site).
+     */
+    static evaluateScalar(formula: string, context: FormulaRowContext): EvaluatedFormulaResult;
+    /**
+     * Évalue une formule sur un ensemble de lignes tabulaires avec support de SumIf, CountIf, etc.
+     */
+    static evaluateTabular(formula: string, rows: FormulaRowContext[]): EvaluatedFormulaResult;
+    /**
+     * Évalue une formule de série temporelle (ex: MovingAverage(revenue, 7) ou CumulativeSum(conversions)).
+     */
+    static evaluateSeries(formula: string, series: MetricSeriesRow[], metricKey: string): EvaluatedFormulaResult;
+    private static tokenize;
+    private static parse;
+    private static evalNode;
+    private static evalTabularNode;
+    private static evalBinary;
+    private static evalCall;
+}

package/dist/analytics/mixed-content-http-resource-passive-active-auditor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - MixedContentHttpResourcePassiveActiveAuditor
+ * Detects insecure HTTP subresources on HTTPS pages, distinguishing between Active Mixed Content
+ * (scripts, styles, iframes blocked outright by Chrome/Safari) and Passive Mixed Content (images, media).
+ */
+export type MixedResourceType = "script" | "stylesheet" | "iframe" | "fetch_xhr" | "webfont" | "image" | "audio_video";
+export type MixedContentThreatLevel = "active_blocked" | "passive_degraded";
+export interface PageSubresourceInput {
+    url: string;
+    type: MixedResourceType;
+    pageUrl: string;
+}
+export interface FlaggedMixedContentResource {
+    resourceUrl: string;
+    type: MixedResourceType;
+    threatLevel: MixedContentThreatLevel;
+    browserBehavior: string;
+    recommendedHttpsUrl: string;
+    remediationAdvice: string;
+}
+export interface MixedContentAuditReport {
+    pageUrl: string;
+    isHttpsPage: boolean;
+    totalSubresourcesAudited: number;
+    mixedContentCount: number;
+    activeMixedContentCount: number;
+    passiveMixedContentCount: number;
+    securityStatus: "secure" | "degraded_passive" | "critical_active_blocked";
+    flaggedResources: FlaggedMixedContentResource[];
+    recommendedCspHeader: string;
+}
+export declare class MixedContentHttpResourcePassiveActiveAuditor {
+    private static readonly ACTIVE_TYPES;
+    /**
+     * Audits page subresources for insecure HTTP mixed content violations.
+     */
+    audit(pageUrl: string, subresources: PageSubresourceInput[]): MixedContentAuditReport;
+}

package/dist/analytics/mobile-replay-sanitizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mobile Replay Wireframe Sanitizer & Web Converter
+ * Clean-room implementation for normalizing native mobile UI wireframes
+ * (iOS UIKit/SwiftUI & Android View/Jetpack Compose) into browser-renderable DOM elements.
+ * Parity: PostHog Mobile Replay Wireframe Transformer & OpenReplay Mobile Parser.
+ */
+export interface MobileWireframe {
+    id: number;
+    type: "view" | "text" | "image" | "button" | "input";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    text?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    fontSize?: number;
+    children?: MobileWireframe[];
+    disabled?: boolean;
+}
+export interface SanitizedWebNode {
+    tagName: "div" | "span" | "button" | "input" | "img";
+    attributes: Record<string, string>;
+    style: Record<string, string>;
+    children?: SanitizedWebNode[];
+    textContent?: string;
+}
+export declare class MobileReplaySanitizer {
+    /**
+     * Transforms a native mobile wireframe tree into standard web DOM elements.
+     */
+    static transformToWeb(wireframe: MobileWireframe): SanitizedWebNode;
+    /**
+     * Strips out system bars (status bar, navigation bar) if present at coordinates (0, 0).
+     */
+    static stripSystemBars(wireframes: MobileWireframe[]): MobileWireframe[];
+}

package/dist/analytics/mobile-symbolizer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MobileSymbolizer — Dé-obfuscation de stacktraces Android (ProGuard/R8) & iOS (dSYM)
+ *
+ * Permet de convertir les traces d'erreurs mobiles obfusquées :
+ * - Android : parsing de `mapping.txt` (ProGuard / R8 / DexGuard)
+ * - iOS : symbolisation des adresses mémoire (dSYM / Symbol Maps)
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface ProGuardMethodMapping {
+    startLine: number;
+    endLine: number;
+    originalMethodName: string;
+    originalReturnType: string;
+    originalArguments: string;
+    obfuscatedMethodName: string;
+}
+export interface ProGuardClassMapping {
+    originalClassName: string;
+    obfuscatedClassName: string;
+    methods: ProGuardMethodMapping[];
+    fields: Map<string, string>;
+}
+export interface AppleSymbolEntry {
+    address: string;
+    symbol: string;
+    file?: string;
+    line?: number;
+}
+export interface SymbolizationResult {
+    platform: "android" | "ios";
+    symbolizedStacktrace: string;
+    framesCount: number;
+    symbolizedFramesCount: number;
+    unresolvedFramesCount: number;
+}
+export declare class MobileSymbolizer {
+    private androidClassMap;
+    private iosSymbolMap;
+    /**
+     * Charge un fichier mapping.txt ProGuard / R8 Android.
+     */
+    loadProGuardMapping(mappingContent: string): number;
+    /**
+     * Charge une table de symboles Apple dSYM (format JSON ou TSV).
+     */
+    loadAppleSymbolMap(entries: AppleSymbolEntry[]): number;
+    /**
+     * Dé-obfusque une stacktrace Android selon le mapping ProGuard chargé.
+     */
+    deobfuscateAndroid(stacktrace: string): SymbolizationResult;
+    /**
+     * Symbolise une stacktrace iOS dSYM selon les tables de symboles chargées.
+     */
+    symbolizeIos(stacktrace: string): SymbolizationResult;
+    private normalizeHexAddress;
+}

package/dist/analytics/monitor.d.ts

@@ -0,0 +1,11 @@
+import type { CrawlSnapshotItem } from './types';
+export declare function hashItem(i: Omit<CrawlSnapshotItem, 'hash'>): string;
+export interface CrawlDiffResult {
+    url: string;
+    type: 'added' | 'changed' | 'removed';
+    severity: 'low' | 'medium' | 'high';
+    changes?: string[];
+    old?: CrawlSnapshotItem;
+    new?: CrawlSnapshotItem;
+}
+export declare function diffSnapshots(a: CrawlSnapshotItem[], b: CrawlSnapshotItem[]): CrawlDiffResult[];

package/dist/analytics/movers-and-shakers-detector.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Movers and Shakers Anomaly & Evolution Detector
+ * Clean-room implementation for detecting significant shifts, breakout metrics,
+ * and high-impact movers/shakers across reports and dimensions.
+ * Parity: Matomo Insights (getMoversAndShakers) & Google Analytics Anomalies.
+ */
+export interface MetricEvolutionRow {
+    label: string;
+    currentValue: number;
+    previousValue: number;
+    metadata?: Record<string, unknown>;
+}
+export interface MoverAndShakerResult {
+    label: string;
+    currentValue: number;
+    previousValue: number;
+    absoluteChange: number;
+    relativeChangePercent: number;
+    evolutionImpactPercent: number;
+    category: "new_entrant" | "riser" | "faller" | "disappeared";
+    isSignificant: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface MoversAndShakersReport {
+    metricName: string;
+    totalCurrentValue: number;
+    totalPreviousValue: number;
+    totalAbsoluteChange: number;
+    totalRelativeChangePercent: number;
+    risers: MoverAndShakerResult[];
+    fallers: MoverAndShakerResult[];
+    newEntrants: MoverAndShakerResult[];
+    disappeared: MoverAndShakerResult[];
+    topShaker: MoverAndShakerResult | null;
+}
+export interface MoversAndShakersConfig {
+    metricName?: string;
+    minRelativeChangePercent?: number;
+    minAbsoluteChange?: number;
+    significanceThresholdPercent?: number;
+    limit?: number;
+}
+export declare class MoversAndShakersDetector {
+    /**
+     * Analyzes rows between two periods and extracts movers and shakers.
+     */
+    static analyze(rows: MetricEvolutionRow[], config?: MoversAndShakersConfig): MoversAndShakersReport;
+}

package/dist/analytics/multi-armed-bandit-allocator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * MultiArmedBanditAllocator — Allocation Dynamique de Trafic par Échantillonnage de Thompson (Multi-Armed Bandit)
+ *
+ * Parité : PostHog (MAB Experiments) & Optimizely (Adaptive Multi-Armed Bandit).
+ *
+ * Résout le dilemme classique Exploration vs Exploitation dans les tests A/B :
+ * Plutôt que de gaspiller 50% du trafic pendant 4 semaines sur une variante perdante,
+ * l'algorithme de Thompson Sampling (loi Bêta conjuguée) ajuste dynamiquement la part
+ * de trafic envoyée vers chaque variante en fonction de sa probabilité a posteriori d'être la meilleure :
+ *
+ * 1. Modélisation Bayésienne Bêta-Bernoulli :
+ *    - A priori uniforme Beta(1, 1).
+ *    - A posteriori Beta(1 + conversions, 1 + impressions - conversions).
+ * 2. Simulation de Monte Carlo (10 000 tirages) :
+ *    - Calcule la probabilité exacte que chaque variante soit la gagnante (P(Best)).
+ * 3. Allocation Dynamique de Trafic avec Plancher d'Exploration :
+ *    - Alloue le trafic proportionnellement à P(Best) tout en garantissant un plancher minimal (ex: 5%)
+ *      pour éviter la famine statistique des variantes récentes.
+ * 4. Calcul du Regret Estimé (Cumulative Regret) & Détection de Convergence :
+ *    - Détecte automatiquement quand une variante dépasse 99% de certitude pour auto-promotion.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface BanditArmInput {
+    id: string;
+    name: string;
+    impressions: number;
+    conversions: number;
+}
+export interface BanditArmResult {
+    id: string;
+    name: string;
+    impressions: number;
+    conversions: number;
+    observedConversionRate: number;
+    winProbability: number;
+    recommendedTrafficSharePercentage: number;
+    isWinner: boolean;
+}
+export interface BanditAllocationReport {
+    totalImpressions: number;
+    totalConversions: number;
+    overallConversionRate: number;
+    arms: BanditArmResult[];
+    leadingArmId: string;
+    hasConvergedWinner: boolean;
+    estimatedConversionsSaved: number;
+    recommendations: string[];
+    generatedAt: string;
+}
+export declare class MultiArmedBanditAllocator {
+    private static readonly MONTE_CARLO_ROUNDS;
+    private static readonly MIN_EXPLORATION_FLOOR;
+    allocate(arms: BanditArmInput[]): BanditAllocationReport;
+    private sampleBeta;
+    private sampleGamma;
+    private sampleStandardNormal;
+    private emptyReport;
+}

package/dist/analytics/multi-attribution-engine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Multi-Attribution Models Engine
+ *
+ * Clean-room implementation inspired by Matomo MultiChannelAttribution & PostHog attribution modeling.
+ * Evaluates conversion touchpoints across 5 attribution models:
+ * First Touch, Last Touch, Linear, Position-Based (40/40/20), and Time-Decay (7-day half-life).
+ */
+export interface MultiTouchpointRecord {
+    id: string;
+    channel: string;
+    campaign?: string;
+    source?: string;
+    timestamp: number;
+}
+export interface MultiTouchAttributionResult {
+    channel: string;
+    credit: number;
+    percentage: number;
+}
+export type AttributionModelType = "first_touch" | "last_touch" | "linear" | "position_based" | "time_decay";
+export declare class MultiAttributionEngine {
+    calculateAttribution(touchpoints: MultiTouchpointRecord[], conversionValue?: number, model?: AttributionModelType, conversionTimestamp?: number): MultiTouchAttributionResult[];
+}

package/dist/analytics/multi-domain-hreflang-cluster-graph.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Multi-Domain Hreflang Cluster Graph (Batch 15 - Gap 4)
+ *
+ * International SEO multi-domain hreflang cluster graph validator inspired by
+ * Botify International Hreflang Graph & OnCrawl Hreflang Matrix.
+ *
+ * Validates complex international SEO setups across ccTLDs and subdomains:
+ * - Bidirectional return tag reciprocation (Google requirement)
+ * - Self-referential hreflang tag presence
+ * - x-default parity and consistency across cluster nodes
+ * - RFC 5646 language/region ISO code compliance (flags en-UK -> en-GB, etc.)
+ * - Broken or redirecting hreflang target destinations
+ */
+export interface HreflangDeclaration {
+    lang: string;
+    targetUrl: string;
+}
+export interface PageHreflangNode {
+    url: string;
+    domain: string;
+    httpStatus?: number;
+    declarations: HreflangDeclaration[];
+}
+export type HreflangViolationType = "missing_return_tag" | "missing_self_reference" | "inconsistent_x_default" | "invalid_iso_code" | "target_http_error";
+export interface HreflangViolation {
+    violationType: HreflangViolationType;
+    severity: "critical" | "warning";
+    sourceUrl: string;
+    targetUrl?: string;
+    declaredLang?: string;
+    impactDescription: string;
+    remediationAdvice: string;
+}
+export interface InternationalClusterSummary {
+    clusterId: string;
+    languagesCovered: string[];
+    participatingDomains: string[];
+    clusterNodeCount: number;
+    hasConsistentXDefault: boolean;
+    reciprocatedEdgesCount: number;
+    brokenEdgesCount: number;
+}
+export interface MultiDomainHreflangAuditReport {
+    totalPagesAudited: number;
+    totalUniqueDomains: number;
+    hreflangHealthScore: number;
+    clusters: InternationalClusterSummary[];
+    violations: HreflangViolation[];
+    internationalSeoDirectives: string[];
+}
+export declare class MultiDomainHreflangClusterGraph {
+    /**
+     * Normalizes URL for uniform graph comparison.
+     */
+    private static normalizeUrl;
+    /**
+     * Audits international hreflang declarations across multi-domain nodes.
+     */
+    static auditHreflangClusters(nodes: PageHreflangNode[]): MultiDomainHreflangAuditReport;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Multi-Funnel Flow Engine
+ *
+ * Clean-room implementation inspired by PostHog Funnels & Matomo Funnels.
+ * Computes step-by-step funnel drop-offs, conversion rates, median time-to-convert,
+ * and user breakdown by specific cohorts or device attributes.
+ */
+export interface MultiFunnelStepDefinition {
+    id: string;
+    name: string;
+    event: string;
+    conditions?: Record<string, any>;
+}
+export interface FunnelUserEvent {
+    userId: string;
+    event: string;
+    timestamp: number;
+    properties?: Record<string, any>;
+}
+export interface MultiFunnelStepResult {
+    stepIndex: number;
+    stepName: string;
+    enteredCount: number;
+    convertedCount: number;
+    conversionRate: number;
+    dropoffCount: number;
+    dropoffRate: number;
+    medianTimeToConvertMs?: number;
+}
+export interface FunnelAnalysisSummary {
+    steps: MultiFunnelStepResult[];
+    overallConversionRate: number;
+    totalStarted: number;
+    totalCompleted: number;
+}
+export declare class MultiFunnelEngine {
+    analyzeFunnel(steps: MultiFunnelStepDefinition[], events: FunnelUserEvent[], windowDurationMs?: number): FunnelAnalysisSummary;
+}

package/dist/analytics/multi-site-rollup-engine.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Multi-Site Rollup & Comparative Benchmark Engine
+ * Clean-room implementation for aggregating metrics across multi-domain / multi-tenant networks,
+ * computing network-wide averages, traffic share distribution, and growth benchmarks.
+ * Parity: Matomo MultiSites Reporting & PostHog Cross-Project Insights.
+ */
+export interface NetworkSiteMetrics {
+    siteId: string;
+    siteName: string;
+    domain: string;
+    visits: number;
+    uniqueVisitors: number;
+    pageviews: number;
+    bounces: number;
+    conversions?: number;
+    revenue?: number;
+    previousVisits?: number;
+}
+export interface SiteBenchmarkComparison {
+    siteId: string;
+    siteName: string;
+    domain: string;
+    visits: number;
+    uniqueVisitors: number;
+    pageviews: number;
+    bounceRatePercent: number;
+    trafficSharePercent: number;
+    growthPercent?: number;
+    revenueSharePercent?: number;
+    performanceTier: "leader" | "average" | "lagging";
+}
+export interface MultiSiteRollupReport {
+    totalSites: number;
+    totalVisits: number;
+    totalUniqueVisitors: number;
+    totalPageviews: number;
+    totalRevenue: number;
+    networkBounceRatePercent: number;
+    sites: SiteBenchmarkComparison[];
+    topPerformingSite?: {
+        siteId: string;
+        siteName: string;
+        visits: number;
+        trafficSharePercent: number;
+    };
+    fastestGrowingSite?: {
+        siteId: string;
+        siteName: string;
+        growthPercent: number;
+    };
+    networkHealth: "excellent" | "healthy" | "needs_attention";
+}
+export declare class MultiSiteRollupEngine {
+    /**
+     * Aggregates an array of site metrics into a unified network benchmark report.
+     */
+    static aggregateNetwork(sites: NetworkSiteMetrics[]): MultiSiteRollupReport;
+}

package/dist/analytics/multi-tab-session-sync.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Tab Session Synchronization Engine
+ * Clean-room implementation inspired by OpenReplay multi-tab tracker & PostHog cross-tab session unification.
+ * Tracks events across multiple concurrent browser tabs, synchronizes chronological ordering
+ * using Lamport logical timestamps, and detects tab switches and background throttling.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface TabEventRecord {
+    tabId: string;
+    eventId: string;
+    eventType: string;
+    timestamp: number;
+    lamportClock: number;
+    data?: Record<string, unknown>;
+}
+export interface TabSwitchEvent {
+    fromTabId: string | null;
+    toTabId: string;
+    timestamp: number;
+}
+export interface SynchronizedTabEvent extends TabEventRecord {
+    globalOrder: number;
+}
+export interface MergedMultiTabSession {
+    sessionDurationMs: number;
+    tabsCount: number;
+    tabIds: string[];
+    synchronizedEvents: SynchronizedTabEvent[];
+    tabSwitches: TabSwitchEvent[];
+}
+export declare class MultiTabSessionSync {
+    /**
+     * Merges multi-tab events and sorts by Lamport clock and physical timestamp
+     */
+    static mergeAndOrderEvents(events: TabEventRecord[]): MergedMultiTabSession;
+    /**
+     * Computes the next Lamport clock for an incoming event
+     */
+    static advanceLamportClock(localClock: number, receivedRemoteClock?: number): number;
+}