@vestig/next 0.6.0 → 0.9.0

package/dist/metrics/hooks/use-web-vitals.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Web Vitals Hook
+ *
+ * React hook for capturing Core Web Vitals metrics.
+ * Uses simple useState + useEffect pattern (React Compiler handles memoization).
+ *
+ * @packageDocumentation
+ */
+import type { MetricEntry, MetricSummary, WebVitalName } from '../types';
+/**
+ * Options for useWebVitals hook
+ */
+interface UseWebVitalsOptions {
+    /** Enable Web Vitals collection */
+    enabled?: boolean;
+    /** Sampling rate (0.0 - 1.0) */
+    sampleRate?: number;
+    /** Report endpoint */
+    reportEndpoint?: string;
+    /** Report immediately when rating is poor */
+    reportPoorImmediately?: boolean;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Hook to capture Core Web Vitals
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useWebVitals({
+ *     enabled: process.env.NODE_ENV === 'development',
+ *     sampleRate: 0.1,
+ *     reportPoorImmediately: true,
+ *   })
+ *
+ *   return <div>My App</div>
+ * }
+ * ```
+ */
+export declare function useWebVitals(options?: UseWebVitalsOptions): void;
+/**
+ * Hook to get the current Web Vitals from the store
+ *
+ * Simple useState + useEffect pattern - React Compiler handles memoization.
+ * No useSyncExternalStore = no hydration headaches.
+ *
+ * @returns Latest Web Vitals values
+ *
+ * @example
+ * ```tsx
+ * function MetricsDisplay() {
+ *   const vitals = useWebVitalsData()
+ *
+ *   return (
+ *     <div>
+ *       <p>LCP: {vitals.LCP?.value ?? 'N/A'}</p>
+ *       <p>CLS: {vitals.CLS?.value ?? 'N/A'}</p>
+ *       <p>INP: {vitals.INP?.value ?? 'N/A'}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useWebVitalsData(): Partial<Record<WebVitalName, MetricEntry>>;
+/**
+ * Hook to get Web Vitals summary statistics
+ *
+ * @returns Summary statistics for all Web Vitals
+ */
+export declare function useWebVitalsSummary(): Partial<Record<WebVitalName, MetricSummary>>;
+export {};
+//# sourceMappingURL=use-web-vitals.d.ts.map

package/dist/metrics/hooks/use-web-vitals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-web-vitals.d.ts","sourceRoot":"","sources":["../../../src/metrics/hooks/use-web-vitals.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAkB,YAAY,EAAE,MAAM,UAAU,CAAA;AAExF;;GAEG;AACH,UAAU,mBAAmB;IAC5B,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,iBAAiB;IACjB,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAmBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAqDpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAgB7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAclF"}

package/dist/metrics/hooks/use-web-vitals.js

@@ -0,0 +1,141 @@
+/**
+ * Web Vitals Hook
+ *
+ * React hook for capturing Core Web Vitals metrics.
+ * Uses simple useState + useEffect pattern (React Compiler handles memoization).
+ *
+ * @packageDocumentation
+ */
+'use client';
+import { useEffect, useState } from 'react';
+import { onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals';
+import { MetricsReporter } from '../reporter';
+import { metricsStore } from '../store';
+/**
+ * Convert web-vitals Metric to our MetricEntry format
+ */
+function toMetricEntry(metric) {
+    return {
+        type: 'web-vital',
+        name: metric.name,
+        value: metric.value,
+        rating: metric.rating,
+        metadata: {
+            navigationType: metric.navigationType,
+            delta: metric.delta,
+            pathname: typeof window !== 'undefined' ? window.location.pathname : undefined,
+        },
+    };
+}
+/**
+ * Hook to capture Core Web Vitals
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useWebVitals({
+ *     enabled: process.env.NODE_ENV === 'development',
+ *     sampleRate: 0.1,
+ *     reportPoorImmediately: true,
+ *   })
+ *
+ *   return <div>My App</div>
+ * }
+ * ```
+ */
+export function useWebVitals(options = {}) {
+    const { enabled = true, sampleRate = 1.0, reportEndpoint = '/api/vestig/metrics', reportPoorImmediately = true, debug = false, } = options;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (Math.random() > sampleRate)
+            return;
+        const reporter = new MetricsReporter({
+            endpoint: reportEndpoint,
+            debug,
+        });
+        const handleMetric = (metric) => {
+            const entry = toMetricEntry(metric);
+            metricsStore.addMetric(entry);
+            if (debug) {
+                console.log(`[vestig-metrics] ${metric.name}:`, {
+                    value: metric.value,
+                    rating: metric.rating,
+                    delta: metric.delta,
+                });
+            }
+            const fullEntry = {
+                ...entry,
+                id: `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`,
+                timestamp: new Date().toISOString(),
+            };
+            if (reportPoorImmediately && metric.rating === 'poor') {
+                reporter.reportImmediate(fullEntry);
+            }
+            else {
+                reporter.report(fullEntry);
+            }
+        };
+        onLCP(handleMetric);
+        onCLS(handleMetric);
+        onINP(handleMetric);
+        onTTFB(handleMetric);
+        onFCP(handleMetric);
+        return () => {
+            reporter.destroy();
+        };
+    }, [enabled, sampleRate, reportEndpoint, reportPoorImmediately, debug]);
+}
+/**
+ * Hook to get the current Web Vitals from the store
+ *
+ * Simple useState + useEffect pattern - React Compiler handles memoization.
+ * No useSyncExternalStore = no hydration headaches.
+ *
+ * @returns Latest Web Vitals values
+ *
+ * @example
+ * ```tsx
+ * function MetricsDisplay() {
+ *   const vitals = useWebVitalsData()
+ *
+ *   return (
+ *     <div>
+ *       <p>LCP: {vitals.LCP?.value ?? 'N/A'}</p>
+ *       <p>CLS: {vitals.CLS?.value ?? 'N/A'}</p>
+ *       <p>INP: {vitals.INP?.value ?? 'N/A'}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useWebVitalsData() {
+    const [vitals, setVitals] = useState({});
+    useEffect(() => {
+        // Get initial state
+        setVitals(metricsStore.getLatestVitals());
+        // Subscribe to updates
+        const unsubscribe = metricsStore.subscribe(() => {
+            setVitals(metricsStore.getLatestVitals());
+        });
+        return unsubscribe;
+    }, []);
+    return vitals;
+}
+/**
+ * Hook to get Web Vitals summary statistics
+ *
+ * @returns Summary statistics for all Web Vitals
+ */
+export function useWebVitalsSummary() {
+    const [summary, setSummary] = useState({});
+    useEffect(() => {
+        setSummary(metricsStore.getVitalsSummary());
+        const unsubscribe = metricsStore.subscribe(() => {
+            setSummary(metricsStore.getVitalsSummary());
+        });
+        return unsubscribe;
+    }, []);
+    return summary;
+}
+//# sourceMappingURL=use-web-vitals.js.map

package/dist/metrics/hooks/use-web-vitals.js.map

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

package/dist/metrics/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @vestig/next/metrics - Performance Metrics Module
+ *
+ * This module provides Core Web Vitals and route-level performance
+ * monitoring for Next.js applications.
+ *
+ * @example Quick Start
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @example With Dev Overlay
+ * ```tsx
+ * import { VestigDevOverlay } from '@vestig/next/dev'
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         {process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
+ *         <VestigMetrics />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { VestigMetrics, type VestigMetricsProps } from './web-vitals';
+export { metricsStore } from './store';
+export { useWebVitals, useWebVitalsData, useWebVitalsSummary, } from './hooks/use-web-vitals';
+export { useRouteMetrics, useRouteMetricsData, useRenderTiming, useDataFetchTiming, } from './hooks/use-route-metrics';
+export { THRESHOLDS, RATING_COLORS, getRating, getRatingColors, getMetricDescription, getMetricUnit, formatMetricValue, } from './thresholds';
+export { MetricsReporter } from './reporter';
+export type { WebVitalName, MetricRating, NavigationType, WebVitalMetric, RouteMetric, MetricEntry, MetricSummary, HistogramBucket, MetricsState, MetricsStore, VestigMetricsConfig, MetricsReportPayload, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAGrE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGtC,OAAO,EACN,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACN,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GAClB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EACN,UAAU,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,iBAAiB,GACjB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAG5C,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,cAAc,EACd,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,SAAS,CAAA"}

package/dist/metrics/index.js

@@ -0,0 +1,56 @@
+/**
+ * @vestig/next/metrics - Performance Metrics Module
+ *
+ * This module provides Core Web Vitals and route-level performance
+ * monitoring for Next.js applications.
+ *
+ * @example Quick Start
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @example With Dev Overlay
+ * ```tsx
+ * import { VestigDevOverlay } from '@vestig/next/dev'
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         {process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
+ *         <VestigMetrics />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+'use client';
+// Main component
+export { VestigMetrics } from './web-vitals';
+// Store for programmatic access
+export { metricsStore } from './store';
+// Hooks
+export { useWebVitals, useWebVitalsData, useWebVitalsSummary, } from './hooks/use-web-vitals';
+export { useRouteMetrics, useRouteMetricsData, useRenderTiming, useDataFetchTiming, } from './hooks/use-route-metrics';
+// Thresholds and utilities
+export { THRESHOLDS, RATING_COLORS, getRating, getRatingColors, getMetricDescription, getMetricUnit, formatMetricValue, } from './thresholds';
+// Reporter for custom integrations
+export { MetricsReporter } from './reporter';
+//# sourceMappingURL=index.js.map

package/dist/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,YAAY,CAAA;AAEZ,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAA2B,MAAM,cAAc,CAAA;AAErE,gCAAgC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,QAAQ;AACR,OAAO,EACN,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACN,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GAClB,MAAM,2BAA2B,CAAA;AAElC,2BAA2B;AAC3B,OAAO,EACN,UAAU,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,iBAAiB,GACjB,MAAM,cAAc,CAAA;AAErB,mCAAmC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/metrics/reporter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Metrics Reporter
+ *
+ * Handles batched reporting of metrics to the server.
+ * Uses sendBeacon for reliable delivery on page unload.
+ *
+ * @packageDocumentation
+ */
+import type { MetricEntry } from './types';
+/**
+ * Reporter configuration
+ */
+interface ReporterConfig {
+    /** Endpoint to report metrics to */
+    endpoint: string;
+    /** Batch interval in milliseconds */
+    batchInterval: number;
+    /** Maximum batch size before forced flush */
+    maxBatchSize: number;
+    /** Enable debug logging */
+    debug: boolean;
+}
+/**
+ * Metrics Reporter class
+ *
+ * Collects metrics and sends them in batches to minimize network overhead.
+ * Uses sendBeacon on page unload to ensure metrics are not lost.
+ *
+ * @example
+ * ```ts
+ * const reporter = new MetricsReporter({
+ *   endpoint: '/api/vestig/metrics',
+ *   batchInterval: 5000,
+ *   maxBatchSize: 50,
+ *   debug: false
+ * })
+ *
+ * reporter.report(metric)
+ * reporter.reportImmediate(criticalMetric) // Bypass batch
+ * ```
+ */
+export declare class MetricsReporter {
+    private config;
+    private queue;
+    private flushTimer;
+    private isDestroyed;
+    constructor(config?: Partial<ReporterConfig>);
+    /**
+     * Add a metric to the batch queue
+     */
+    report(metric: MetricEntry): void;
+    /**
+     * Report a metric immediately (bypasses batch)
+     * Use for critical metrics like "poor" ratings
+     */
+    reportImmediate(metric: MetricEntry): void;
+    /**
+     * Flush all queued metrics
+     */
+    flush(): void;
+    /**
+     * Destroy the reporter and clean up
+     */
+    destroy(): void;
+    /**
+     * Start the batch timer
+     */
+    private startBatchTimer;
+    /**
+     * Set up page unload handler to flush metrics
+     */
+    private setupUnloadHandler;
+    /**
+     * Flush metrics using sendBeacon (for page unload)
+     */
+    private flushWithBeacon;
+    /**
+     * Send metrics via fetch
+     */
+    private sendMetrics;
+    /**
+     * Create the report payload
+     */
+    private createPayload;
+}
+export {};
+//# sourceMappingURL=reporter.d.ts.map

package/dist/metrics/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/metrics/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAEhE;;GAEG;AACH,UAAU,cAAc;IACvB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAA;IACpB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,WAAW,CAAQ;gBAEf,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM;IAYhD;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAejC;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAU1C;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,OAAO,IAAI,IAAI;IAYf;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;OAEG;YACW,WAAW;IAwBzB;;OAEG;IACH,OAAO,CAAC,aAAa;CAUrB"}

package/dist/metrics/reporter.js

@@ -0,0 +1,178 @@
+/**
+ * Metrics Reporter
+ *
+ * Handles batched reporting of metrics to the server.
+ * Uses sendBeacon for reliable delivery on page unload.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Metrics Reporter class
+ *
+ * Collects metrics and sends them in batches to minimize network overhead.
+ * Uses sendBeacon on page unload to ensure metrics are not lost.
+ *
+ * @example
+ * ```ts
+ * const reporter = new MetricsReporter({
+ *   endpoint: '/api/vestig/metrics',
+ *   batchInterval: 5000,
+ *   maxBatchSize: 50,
+ *   debug: false
+ * })
+ *
+ * reporter.report(metric)
+ * reporter.reportImmediate(criticalMetric) // Bypass batch
+ * ```
+ */
+export class MetricsReporter {
+    config;
+    queue = [];
+    flushTimer = null;
+    isDestroyed = false;
+    constructor(config = {}) {
+        this.config = {
+            endpoint: config.endpoint ?? '/api/vestig/metrics',
+            batchInterval: config.batchInterval ?? 5000,
+            maxBatchSize: config.maxBatchSize ?? 50,
+            debug: config.debug ?? false,
+        };
+        this.startBatchTimer();
+        this.setupUnloadHandler();
+    }
+    /**
+     * Add a metric to the batch queue
+     */
+    report(metric) {
+        if (this.isDestroyed)
+            return;
+        this.queue.push(metric);
+        if (this.config.debug) {
+            console.log('[vestig-metrics] Queued:', metric.name, metric.value);
+        }
+        // Force flush if queue is full
+        if (this.queue.length >= this.config.maxBatchSize) {
+            this.flush();
+        }
+    }
+    /**
+     * Report a metric immediately (bypasses batch)
+     * Use for critical metrics like "poor" ratings
+     */
+    reportImmediate(metric) {
+        if (this.isDestroyed)
+            return;
+        if (this.config.debug) {
+            console.log('[vestig-metrics] Immediate report:', metric.name, metric.value);
+        }
+        this.sendMetrics([metric]);
+    }
+    /**
+     * Flush all queued metrics
+     */
+    flush() {
+        if (this.queue.length === 0)
+            return;
+        const metrics = [...this.queue];
+        this.queue = [];
+        if (this.config.debug) {
+            console.log('[vestig-metrics] Flushing', metrics.length, 'metrics');
+        }
+        this.sendMetrics(metrics);
+    }
+    /**
+     * Destroy the reporter and clean up
+     */
+    destroy() {
+        this.isDestroyed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Final flush
+        this.flush();
+    }
+    /**
+     * Start the batch timer
+     */
+    startBatchTimer() {
+        this.flushTimer = setInterval(() => {
+            this.flush();
+        }, this.config.batchInterval);
+    }
+    /**
+     * Set up page unload handler to flush metrics
+     */
+    setupUnloadHandler() {
+        if (typeof document === 'undefined')
+            return;
+        const handleVisibilityChange = () => {
+            if (document.visibilityState === 'hidden') {
+                this.flushWithBeacon();
+            }
+        };
+        // visibilitychange is more reliable than beforeunload
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+    }
+    /**
+     * Flush metrics using sendBeacon (for page unload)
+     */
+    flushWithBeacon() {
+        if (this.queue.length === 0)
+            return;
+        const metrics = [...this.queue];
+        this.queue = [];
+        const payload = this.createPayload(metrics);
+        // Use sendBeacon for reliable delivery during page unload
+        if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+            const blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
+            navigator.sendBeacon(this.config.endpoint, blob);
+            if (this.config.debug) {
+                console.log('[vestig-metrics] Beacon sent:', metrics.length, 'metrics');
+            }
+        }
+        else {
+            // Fallback to fetch
+            this.sendMetrics(metrics);
+        }
+    }
+    /**
+     * Send metrics via fetch
+     */
+    async sendMetrics(metrics) {
+        if (metrics.length === 0)
+            return;
+        const payload = this.createPayload(metrics);
+        try {
+            const response = await fetch(this.config.endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                // Use keepalive for reliability during page transitions
+                keepalive: true,
+            });
+            if (!response.ok && this.config.debug) {
+                console.error('[vestig-metrics] Report failed:', response.status);
+            }
+        }
+        catch (error) {
+            if (this.config.debug) {
+                console.error('[vestig-metrics] Report error:', error);
+            }
+        }
+    }
+    /**
+     * Create the report payload
+     */
+    createPayload(metrics) {
+        return {
+            metrics,
+            client: {
+                userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+                pathname: typeof window !== 'undefined' ? window.location.pathname : 'unknown',
+                timestamp: new Date().toISOString(),
+            },
+        };
+    }
+}
+//# sourceMappingURL=reporter.js.map

package/dist/metrics/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../../src/metrics/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,eAAe;IACnB,MAAM,CAAgB;IACtB,KAAK,GAAkB,EAAE,CAAA;IACzB,UAAU,GAA0C,IAAI,CAAA;IACxD,WAAW,GAAG,KAAK,CAAA;IAE3B,YAAY,SAAkC,EAAE;QAC/C,IAAI,CAAC,MAAM,GAAG;YACb,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,qBAAqB;YAClD,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;YAC3C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE;YACvC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;SAC5B,CAAA;QAED,IAAI,CAAC,eAAe,EAAE,CAAA;QACtB,IAAI,CAAC,kBAAkB,EAAE,CAAA;IAC1B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAmB;QACzB,IAAI,IAAI,CAAC,WAAW;YAAE,OAAM;QAE5B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAEvB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;QACnE,CAAC;QAED,+BAA+B;QAC/B,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YACnD,IAAI,CAAC,KAAK,EAAE,CAAA;QACb,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,MAAmB;QAClC,IAAI,IAAI,CAAC,WAAW;YAAE,OAAM;QAE5B,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,oCAAoC,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;QAC7E,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAEnC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAA;QAEf,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;QACpE,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IAED;;OAEG;IACH,OAAO;QACN,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QAEvB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;QACvB,CAAC;QAED,cAAc;QACd,IAAI,CAAC,KAAK,EAAE,CAAA;IACb,CAAC;IAED;;OAEG;IACK,eAAe;QACtB,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YAClC,IAAI,CAAC,KAAK,EAAE,CAAA;QACb,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;IAC9B,CAAC;IAED;;OAEG;IACK,kBAAkB;QACzB,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE,OAAM;QAE3C,MAAM,sBAAsB,GAAG,GAAS,EAAE;YACzC,IAAI,QAAQ,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC;gBAC3C,IAAI,CAAC,eAAe,EAAE,CAAA;YACvB,CAAC;QACF,CAAC,CAAA;QAED,sDAAsD;QACtD,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAA;IACtE,CAAC;IAED;;OAEG;IACK,eAAe;QACtB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAEnC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAA;QAEf,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;QAE3C,0DAA0D;QAC1D,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAA;YAC9E,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAEhD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,+BAA+B,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;YACxE,CAAC;QACF,CAAC;aAAM,CAAC;YACP,oBAAoB;YACpB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;IACF,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,WAAW,CAAC,OAAsB;QAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAEhC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;QAE3C,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAClD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,wDAAwD;gBACxD,SAAS,EAAE,IAAI;aACf,CAAC,CAAA;YAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACvC,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;YAClE,CAAC;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC,CAAA;YACvD,CAAC;QACF,CAAC;IACF,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,OAAsB;QAC3C,OAAO;YACN,OAAO;YACP,MAAM,EAAE;gBACP,SAAS,EAAE,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;gBAC7E,QAAQ,EAAE,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;gBAC9E,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACnC;SACD,CAAA;IACF,CAAC;CACD"}

package/dist/metrics/store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Metrics Store
+ *
+ * Simple pub/sub store for performance metrics.
+ * Designed for reliability over cleverness - no useSyncExternalStore magic.
+ *
+ * @packageDocumentation
+ */
+import type { HistogramBucket, MetricEntry, MetricSummary, MetricsState, WebVitalName } from './types';
+type Listener = () => void;
+/**
+ * Simple metrics store - no React magic, just data + subscriptions
+ */
+declare class SimpleMetricsStore {
+    private state;
+    private listeners;
+    /**
+     * Subscribe to store changes
+     */
+    subscribe(listener: Listener): () => void;
+    /**
+     * Notify all listeners of a change
+     */
+    private notify;
+    /**
+     * Add a new metric to the store
+     */
+    addMetric(entry: Omit<MetricEntry, 'id' | 'timestamp'>): void;
+    /**
+     * Get latest vitals - returns a new object each time (React will handle memoization)
+     */
+    getLatestVitals(): Partial<Record<WebVitalName, MetricEntry>>;
+    /**
+     * Get vitals summary
+     */
+    getVitalsSummary(): Partial<Record<WebVitalName, MetricSummary>>;
+    /**
+     * Get route metrics
+     */
+    getRouteMetrics(): MetricEntry[];
+    /**
+     * Get histogram for a specific metric
+     */
+    getHistogram(name: string, bucketCount?: number): HistogramBucket[];
+    /**
+     * Get summary statistics for a metric
+     */
+    getSummary(name: string): MetricSummary | null;
+    /**
+     * Get the latest metric for a given name
+     */
+    getLatest(name: string): MetricEntry | null;
+    /**
+     * Get current snapshot (for debugging)
+     */
+    getSnapshot(): MetricsState;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+/**
+ * Global metrics store singleton
+ */
+export declare const metricsStore: SimpleMetricsStore;
+export {};
+//# sourceMappingURL=store.d.ts.map