@vestig/next 0.6.0 → 0.8.0

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,34 @@
+/**
+ * Metrics Store
+ *
+ * Global store for capturing and managing performance metrics.
+ * Follows the same pub/sub pattern as the log store for consistency.
+ *
+ * @packageDocumentation
+ */
+import type { MetricsStore } from './types';
+/**
+ * Global metrics store singleton
+ *
+ * @example
+ * ```ts
+ * import { metricsStore } from '@vestig/next/metrics'
+ *
+ * // Subscribe to changes
+ * const unsubscribe = metricsStore.subscribe(() => {
+ *   const summary = metricsStore.getVitalsSummary()
+ *   console.log('LCP p75:', summary.LCP?.p75)
+ * })
+ *
+ * // Add a metric
+ * metricsStore.addMetric({
+ *   type: 'web-vital',
+ *   name: 'LCP',
+ *   value: 2500,
+ *   rating: 'needs-improvement',
+ *   metadata: { pathname: '/dashboard' }
+ * })
+ * ```
+ */
+export declare const metricsStore: MetricsStore;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/metrics/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAMX,YAAY,EAEZ,MAAM,SAAS,CAAA;AAsKhB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,cAAuB,CAAA"}

package/dist/metrics/store.js

@@ -0,0 +1,172 @@
+/**
+ * Metrics Store
+ *
+ * Global store for capturing and managing performance metrics.
+ * Follows the same pub/sub pattern as the log store for consistency.
+ *
+ * @packageDocumentation
+ */
+import { getRating, THRESHOLDS } from './thresholds';
+/**
+ * Create a unique ID for metrics
+ */
+function createMetricId() {
+    return `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+/**
+ * Calculate percentile from sorted array
+ */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    const clampedIndex = Math.max(0, Math.min(index, sorted.length - 1));
+    return sorted[clampedIndex] ?? 0;
+}
+/**
+ * Create the metrics store singleton
+ */
+function createMetricsStore() {
+    const state = {
+        metrics: [],
+        maxMetrics: 500,
+        latestVitals: {},
+    };
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error('[vestig-metrics] Listener error:', error);
+            }
+        }
+    }
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot() {
+            return state;
+        },
+        addMetric(entry) {
+            const metric = {
+                ...entry,
+                id: createMetricId(),
+                timestamp: new Date().toISOString(),
+            };
+            state.metrics.push(metric);
+            // Update latest vitals cache
+            if (entry.type === 'web-vital') {
+                state.latestVitals[entry.name] = metric;
+            }
+            // Trim if over limit
+            if (state.metrics.length > state.maxMetrics) {
+                state.metrics = state.metrics.slice(-state.maxMetrics);
+            }
+            notify();
+        },
+        getHistogram(name, bucketCount = 10) {
+            const values = state.metrics.filter((m) => m.name === name).map((m) => m.value);
+            if (values.length === 0)
+                return [];
+            const min = Math.min(...values);
+            const max = Math.max(...values);
+            const range = max - min || 1;
+            const bucketSize = range / bucketCount;
+            const buckets = Array.from({ length: bucketCount }, (_, i) => ({
+                min: min + i * bucketSize,
+                max: min + (i + 1) * bucketSize,
+                count: 0,
+                percentage: 0,
+            }));
+            for (const value of values) {
+                const bucketIndex = Math.min(Math.floor((value - min) / bucketSize), bucketCount - 1);
+                const bucket = buckets[bucketIndex];
+                if (bucket)
+                    bucket.count++;
+            }
+            // Calculate percentages
+            for (const bucket of buckets) {
+                bucket.percentage = (bucket.count / values.length) * 100;
+            }
+            return buckets;
+        },
+        getSummary(name) {
+            const values = state.metrics.filter((m) => m.name === name).map((m) => m.value);
+            if (values.length === 0)
+                return null;
+            const sorted = [...values].sort((a, b) => a - b);
+            const sum = values.reduce((acc, v) => acc + v, 0);
+            const avg = sum / values.length;
+            const p75 = percentile(sorted, 75);
+            // Determine rating based on p75 for web vitals
+            let rating = 'needs-improvement';
+            if (name in THRESHOLDS) {
+                rating = getRating(name, p75);
+            }
+            return {
+                name,
+                count: values.length,
+                avg,
+                min: sorted[0] ?? 0,
+                max: sorted[sorted.length - 1] ?? 0,
+                p50: percentile(sorted, 50),
+                p75,
+                p95: percentile(sorted, 95),
+                p99: percentile(sorted, 99),
+                rating,
+            };
+        },
+        getVitalsSummary() {
+            const result = {};
+            const vitals = ['LCP', 'CLS', 'INP', 'TTFB', 'FCP'];
+            for (const name of vitals) {
+                const summary = this.getSummary(name);
+                if (summary) {
+                    result[name] = summary;
+                }
+            }
+            return result;
+        },
+        getLatest(name) {
+            if (name in state.latestVitals) {
+                return state.latestVitals[name] ?? null;
+            }
+            const metrics = state.metrics.filter((m) => m.name === name);
+            return metrics[metrics.length - 1] ?? null;
+        },
+        clear() {
+            state.metrics = [];
+            state.latestVitals = {};
+            notify();
+        },
+    };
+}
+/**
+ * Global metrics store singleton
+ *
+ * @example
+ * ```ts
+ * import { metricsStore } from '@vestig/next/metrics'
+ *
+ * // Subscribe to changes
+ * const unsubscribe = metricsStore.subscribe(() => {
+ *   const summary = metricsStore.getVitalsSummary()
+ *   console.log('LCP p75:', summary.LCP?.p75)
+ * })
+ *
+ * // Add a metric
+ * metricsStore.addMetric({
+ *   type: 'web-vital',
+ *   name: 'LCP',
+ *   value: 2500,
+ *   rating: 'needs-improvement',
+ *   metadata: { pathname: '/dashboard' }
+ * })
+ * ```
+ */
+export const metricsStore = createMetricsStore();
+//# sourceMappingURL=store.js.map

package/dist/metrics/store.js.map

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

package/dist/metrics/thresholds.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Core Web Vitals Thresholds
+ *
+ * Official thresholds from Google's Core Web Vitals program.
+ * These determine whether a metric is rated as "good", "needs-improvement", or "poor".
+ *
+ * @see https://web.dev/articles/vitals
+ * @packageDocumentation
+ */
+import type { MetricRating, WebVitalName } from './types';
+/**
+ * Threshold definition for a metric
+ */
+interface MetricThreshold {
+    /** Upper bound for "good" rating (exclusive) */
+    good: number;
+    /** Upper bound for "needs-improvement" rating (exclusive) */
+    poor: number;
+    /** Unit of measurement */
+    unit: 'ms' | 'score';
+    /** Human-readable description */
+    description: string;
+}
+/**
+ * Official Core Web Vitals thresholds
+ *
+ * Values represent the upper bounds:
+ * - good: value < threshold.good
+ * - needs-improvement: threshold.good <= value < threshold.poor
+ * - poor: value >= threshold.poor
+ */
+export declare const THRESHOLDS: Record<WebVitalName, MetricThreshold>;
+/**
+ * Calculate rating for a metric value
+ *
+ * @param name - Web Vital metric name
+ * @param value - Metric value
+ * @returns Rating based on thresholds
+ *
+ * @example
+ * ```ts
+ * getRating('LCP', 2000) // 'good'
+ * getRating('LCP', 3000) // 'needs-improvement'
+ * getRating('LCP', 5000) // 'poor'
+ * ```
+ */
+export declare function getRating(name: WebVitalName, value: number): MetricRating;
+/**
+ * Get human-readable description for a metric
+ */
+export declare function getMetricDescription(name: WebVitalName): string;
+/**
+ * Get unit for a metric
+ */
+export declare function getMetricUnit(name: WebVitalName): 'ms' | 'score';
+/**
+ * Format a metric value for display
+ *
+ * @param name - Metric name
+ * @param value - Metric value
+ * @returns Formatted string
+ *
+ * @example
+ * ```ts
+ * formatMetricValue('LCP', 2500) // '2.50s'
+ * formatMetricValue('CLS', 0.15) // '0.15'
+ * formatMetricValue('INP', 150)  // '150ms'
+ * ```
+ */
+export declare function formatMetricValue(name: WebVitalName, value: number): string;
+/**
+ * Rating colors for UI display
+ */
+export declare const RATING_COLORS: Record<MetricRating, {
+    bg: string;
+    text: string;
+    border: string;
+}>;
+/**
+ * Get color scheme for a rating
+ */
+export declare function getRatingColors(rating: MetricRating): (typeof RATING_COLORS)[MetricRating];
+export {};
+//# sourceMappingURL=thresholds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.d.ts","sourceRoot":"","sources":["../../src/metrics/thresholds.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEzD;;GAEG;AACH,UAAU,eAAe;IACxB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,IAAI,EAAE,IAAI,GAAG,OAAO,CAAA;IACpB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,YAAY,EAAE,eAAe,CAuD5D,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAOzE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE/D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAe3E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAI5F,CAAA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,YAAY,CAAC,CAE1F"}