@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/perf/reporter.js

@@ -0,0 +1,241 @@
+/**
+ * Performance Metric Reporter
+ *
+ * Orchestrates Web Vitals collection, render timing, and budget
+ * checking into a unified reporting pipeline. Supports periodic
+ * automatic reporting or manual on-demand reports.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+import { WebVitalsCollector } from './web-vitals.js';
+import { RenderTimer } from './render-timer.js';
+import { BudgetChecker } from './budget.js';
+// ============================================================
+// DEFAULTS
+// ============================================================
+const DEFAULT_SLOWEST_COUNT = 5;
+// ============================================================
+// REPORTER
+// ============================================================
+/**
+ * Orchestrates performance monitoring components and generates
+ * unified performance reports.
+ *
+ * Manages a WebVitalsCollector, RenderTimer, and BudgetChecker
+ * internally. Supports automatic periodic reporting or manual
+ * on-demand report generation.
+ */
+export class PerformanceReporter {
+    destination;
+    onReportCallback;
+    interval;
+    includeRenderMetrics;
+    includeWebVitals;
+    webVitals;
+    renderTimer;
+    budgetChecker;
+    intervalId;
+    /**
+     * @param config - Reporter configuration
+     */
+    constructor(config) {
+        this.destination = config.destination;
+        this.onReportCallback = config.onReport;
+        this.interval = config.interval ?? 0;
+        this.includeRenderMetrics = config.includeRenderMetrics ?? true;
+        this.includeWebVitals = config.includeWebVitals ?? true;
+        // Initialize sub-components
+        if (this.includeWebVitals) {
+            this.webVitals = new WebVitalsCollector();
+        }
+        if (this.includeRenderMetrics) {
+            this.renderTimer = new RenderTimer();
+        }
+        if (config.budget) {
+            this.budgetChecker = new BudgetChecker(config.budget);
+        }
+    }
+    /**
+     * Start periodic reporting and Web Vitals collection.
+     *
+     * If an interval is configured, reports will be generated
+     * automatically at that interval. Web Vitals collection
+     * starts immediately.
+     */
+    start() {
+        // Start web vitals collection
+        this.webVitals?.startCollecting();
+        // Set up periodic reporting
+        if (this.interval > 0) {
+            this.intervalId = setInterval(() => {
+                void this.report();
+            }, this.interval);
+        }
+    }
+    /**
+     * Generate and deliver a performance report.
+     *
+     * Collects metrics from all active sub-components, runs
+     * budget checks if configured, and delivers the report
+     * to the configured destination.
+     *
+     * @returns The generated performance report
+     */
+    async report() {
+        const performanceReport = {
+            timestamp: Date.now(),
+            webVitals: this.buildWebVitalsSection(),
+            renderMetrics: this.buildRenderMetricsSection(),
+            budgetCheck: this.buildBudgetCheckSection(),
+        };
+        await this.deliverReport(performanceReport);
+        return performanceReport;
+    }
+    /**
+     * Stop periodic reporting.
+     *
+     * Does not stop Web Vitals collection or clear history.
+     * Use `dispose()` for full cleanup.
+     */
+    stop() {
+        if (this.intervalId !== undefined) {
+            clearInterval(this.intervalId);
+            this.intervalId = undefined;
+        }
+    }
+    /**
+     * Get the internal WebVitalsCollector.
+     *
+     * Useful for registering custom metric callbacks.
+     *
+     * @returns The collector, or undefined if Web Vitals are disabled
+     */
+    getWebVitals() {
+        return this.webVitals;
+    }
+    /**
+     * Get the internal RenderTimer.
+     *
+     * Useful for tracking surface render timing externally.
+     *
+     * @returns The timer, or undefined if render metrics are disabled
+     */
+    getRenderTimer() {
+        return this.renderTimer;
+    }
+    /**
+     * Stop reporting and release all resources.
+     */
+    dispose() {
+        this.stop();
+        this.webVitals?.dispose();
+        this.renderTimer?.clear();
+        this.webVitals = undefined;
+        this.renderTimer = undefined;
+        this.budgetChecker = undefined;
+    }
+    // ----------------------------------------------------------
+    // Private: report building
+    // ----------------------------------------------------------
+    buildWebVitalsSection() {
+        if (!this.includeWebVitals || !this.webVitals) {
+            return undefined;
+        }
+        return this.webVitals.getReport();
+    }
+    buildRenderMetricsSection() {
+        if (!this.includeRenderMetrics || !this.renderTimer) {
+            return undefined;
+        }
+        const history = this.renderTimer.getHistory();
+        return {
+            averageRenderTime: this.renderTimer.getAverageRenderTime(),
+            totalRenders: history.length,
+            slowestRenders: this.renderTimer.getSlowest(DEFAULT_SLOWEST_COUNT),
+        };
+    }
+    buildBudgetCheckSection() {
+        if (!this.budgetChecker) {
+            return undefined;
+        }
+        // Collect all available numeric metrics for budget checking
+        const metrics = {};
+        // Web Vitals
+        if (this.webVitals) {
+            const vitalsReport = this.webVitals.getReport();
+            if (vitalsReport.lcp)
+                metrics['lcp'] = vitalsReport.lcp.value;
+            if (vitalsReport.fid)
+                metrics['fid'] = vitalsReport.fid.value;
+            if (vitalsReport.cls)
+                metrics['cls'] = vitalsReport.cls.value;
+            if (vitalsReport.fcp)
+                metrics['fcp'] = vitalsReport.fcp.value;
+            if (vitalsReport.ttfb)
+                metrics['ttfb'] = vitalsReport.ttfb.value;
+        }
+        // Render metrics
+        if (this.renderTimer) {
+            const avg = this.renderTimer.getAverageRenderTime();
+            if (avg > 0) {
+                metrics['maxRenderTime'] = avg;
+            }
+        }
+        return this.budgetChecker.check(metrics);
+    }
+    // ----------------------------------------------------------
+    // Private: report delivery
+    // ----------------------------------------------------------
+    async deliverReport(performanceReport) {
+        switch (this.destination) {
+            case 'console':
+                this.logToConsole(performanceReport);
+                break;
+            case 'custom':
+                if (this.onReportCallback) {
+                    await this.onReportCallback(performanceReport);
+                }
+                break;
+        }
+    }
+    logToConsole(performanceReport) {
+        if (typeof globalThis.console === 'undefined') {
+            return;
+        }
+        const log = globalThis.console;
+        const group = typeof log.group === 'function' ? log.group.bind(log) : undefined;
+        const groupEnd = typeof log.groupEnd === 'function' ? log.groupEnd.bind(log) : undefined;
+        if (group) {
+            group('[PWFabric Perf Report]');
+        }
+        else {
+            log.warn('[PWFabric Perf Report]');
+        }
+        if (performanceReport.webVitals) {
+            log.warn('Web Vitals:', performanceReport.webVitals);
+        }
+        if (performanceReport.renderMetrics) {
+            log.warn('Render Metrics:', performanceReport.renderMetrics);
+        }
+        if (performanceReport.budgetCheck) {
+            const status = performanceReport.budgetCheck.passed ? 'PASS' : 'FAIL';
+            log.warn(`Budget Check: ${status}`, performanceReport.budgetCheck.violations);
+        }
+        if (groupEnd) {
+            groupEnd();
+        }
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new PerformanceReporter instance.
+ *
+ * @param config - Reporter configuration
+ * @returns A new PerformanceReporter
+ */
+export function createPerformanceReporter(config) {
+    return new PerformanceReporter(config);
+}
+//# sourceMappingURL=reporter.js.map

package/dist/perf/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../../src/perf/reporter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Performance Metric Reporter\n *\n * Orchestrates Web Vitals collection, render timing, and budget\n * checking into a unified reporting pipeline. Supports periodic\n * automatic reporting or manual on-demand reports.\n *\n * @module @pwfabric/runtime/perf\n */\n\nimport type { WebVitalsReport } from './web-vitals.js'\nimport type { RenderMetrics } from './render-timer.js'\nimport type { PerformanceBudget, BudgetCheckResult } from './budget.js'\nimport { WebVitalsCollector } from './web-vitals.js'\nimport { RenderTimer } from './render-timer.js'\nimport { BudgetChecker } from './budget.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Where to send performance reports */\nexport type ReportDestination = 'console' | 'custom'\n\n/** Reporter configuration */\nexport interface ReporterConfig {\n  /** Report destination */\n  readonly destination: ReportDestination\n  /** Custom report handler (required when destination is 'custom') */\n  readonly onReport?: (report: PerformanceReport) => void | Promise<void>\n  /** Reporting interval in ms (0 = manual only, default: 0) */\n  readonly interval?: number\n  /** Whether to include render metrics (default: true) */\n  readonly includeRenderMetrics?: boolean\n  /** Whether to include Web Vitals (default: true) */\n  readonly includeWebVitals?: boolean\n  /** Performance budget to check against */\n  readonly budget?: PerformanceBudget\n}\n\n/** A complete performance report */\nexport interface PerformanceReport {\n  /** Timestamp when the report was generated */\n  readonly timestamp: number\n  /** Web Vitals snapshot */\n  readonly webVitals?: WebVitalsReport | undefined\n  /** Render timing summary */\n  readonly renderMetrics?:\n    | {\n        readonly averageRenderTime: number\n        readonly totalRenders: number\n        readonly slowestRenders: readonly RenderMetrics[]\n      }\n    | undefined\n  /** Budget check result */\n  readonly budgetCheck?: BudgetCheckResult | undefined\n}\n\n// ============================================================\n// DEFAULTS\n// ============================================================\n\nconst DEFAULT_SLOWEST_COUNT = 5\n\n// ============================================================\n// REPORTER\n// ============================================================\n\n/**\n * Orchestrates performance monitoring components and generates\n * unified performance reports.\n *\n * Manages a WebVitalsCollector, RenderTimer, and BudgetChecker\n * internally. Supports automatic periodic reporting or manual\n * on-demand report generation.\n */\nexport class PerformanceReporter {\n  private readonly destination: ReportDestination\n  private readonly onReportCallback?:\n    | ((report: PerformanceReport) => void | Promise<void>)\n    | undefined\n  private readonly interval: number\n  private readonly includeRenderMetrics: boolean\n  private readonly includeWebVitals: boolean\n\n  private webVitals?: WebVitalsCollector | undefined\n  private renderTimer?: RenderTimer | undefined\n  private budgetChecker?: BudgetChecker | undefined\n  private intervalId?: ReturnType<typeof setInterval> | undefined\n\n  /**\n   * @param config - Reporter configuration\n   */\n  constructor(config: ReporterConfig) {\n    this.destination = config.destination\n    this.onReportCallback = config.onReport\n    this.interval = config.interval ?? 0\n    this.includeRenderMetrics = config.includeRenderMetrics ?? true\n    this.includeWebVitals = config.includeWebVitals ?? true\n\n    // Initialize sub-components\n    if (this.includeWebVitals) {\n      this.webVitals = new WebVitalsCollector()\n    }\n\n    if (this.includeRenderMetrics) {\n      this.renderTimer = new RenderTimer()\n    }\n\n    if (config.budget) {\n      this.budgetChecker = new BudgetChecker(config.budget)\n    }\n  }\n\n  /**\n   * Start periodic reporting and Web Vitals collection.\n   *\n   * If an interval is configured, reports will be generated\n   * automatically at that interval. Web Vitals collection\n   * starts immediately.\n   */\n  start(): void {\n    // Start web vitals collection\n    this.webVitals?.startCollecting()\n\n    // Set up periodic reporting\n    if (this.interval > 0) {\n      this.intervalId = setInterval(() => {\n        void this.report()\n      }, this.interval)\n    }\n  }\n\n  /**\n   * Generate and deliver a performance report.\n   *\n   * Collects metrics from all active sub-components, runs\n   * budget checks if configured, and delivers the report\n   * to the configured destination.\n   *\n   * @returns The generated performance report\n   */\n  async report(): Promise<PerformanceReport> {\n    const performanceReport: PerformanceReport = {\n      timestamp: Date.now(),\n      webVitals: this.buildWebVitalsSection(),\n      renderMetrics: this.buildRenderMetricsSection(),\n      budgetCheck: this.buildBudgetCheckSection(),\n    }\n\n    await this.deliverReport(performanceReport)\n\n    return performanceReport\n  }\n\n  /**\n   * Stop periodic reporting.\n   *\n   * Does not stop Web Vitals collection or clear history.\n   * Use `dispose()` for full cleanup.\n   */\n  stop(): void {\n    if (this.intervalId !== undefined) {\n      clearInterval(this.intervalId)\n      this.intervalId = undefined\n    }\n  }\n\n  /**\n   * Get the internal WebVitalsCollector.\n   *\n   * Useful for registering custom metric callbacks.\n   *\n   * @returns The collector, or undefined if Web Vitals are disabled\n   */\n  getWebVitals(): WebVitalsCollector | undefined {\n    return this.webVitals\n  }\n\n  /**\n   * Get the internal RenderTimer.\n   *\n   * Useful for tracking surface render timing externally.\n   *\n   * @returns The timer, or undefined if render metrics are disabled\n   */\n  getRenderTimer(): RenderTimer | undefined {\n    return this.renderTimer\n  }\n\n  /**\n   * Stop reporting and release all resources.\n   */\n  dispose(): void {\n    this.stop()\n    this.webVitals?.dispose()\n    this.renderTimer?.clear()\n    this.webVitals = undefined\n    this.renderTimer = undefined\n    this.budgetChecker = undefined\n  }\n\n  // ----------------------------------------------------------\n  // Private: report building\n  // ----------------------------------------------------------\n\n  private buildWebVitalsSection(): WebVitalsReport | undefined {\n    if (!this.includeWebVitals || !this.webVitals) {\n      return undefined\n    }\n    return this.webVitals.getReport()\n  }\n\n  private buildRenderMetricsSection(): PerformanceReport['renderMetrics'] | undefined {\n    if (!this.includeRenderMetrics || !this.renderTimer) {\n      return undefined\n    }\n\n    const history = this.renderTimer.getHistory()\n    return {\n      averageRenderTime: this.renderTimer.getAverageRenderTime(),\n      totalRenders: history.length,\n      slowestRenders: this.renderTimer.getSlowest(DEFAULT_SLOWEST_COUNT),\n    }\n  }\n\n  private buildBudgetCheckSection(): BudgetCheckResult | undefined {\n    if (!this.budgetChecker) {\n      return undefined\n    }\n\n    // Collect all available numeric metrics for budget checking\n    const metrics: Record<string, number> = {}\n\n    // Web Vitals\n    if (this.webVitals) {\n      const vitalsReport = this.webVitals.getReport()\n      if (vitalsReport.lcp) metrics['lcp'] = vitalsReport.lcp.value\n      if (vitalsReport.fid) metrics['fid'] = vitalsReport.fid.value\n      if (vitalsReport.cls) metrics['cls'] = vitalsReport.cls.value\n      if (vitalsReport.fcp) metrics['fcp'] = vitalsReport.fcp.value\n      if (vitalsReport.ttfb) metrics['ttfb'] = vitalsReport.ttfb.value\n    }\n\n    // Render metrics\n    if (this.renderTimer) {\n      const avg = this.renderTimer.getAverageRenderTime()\n      if (avg > 0) {\n        metrics['maxRenderTime'] = avg\n      }\n    }\n\n    return this.budgetChecker.check(metrics)\n  }\n\n  // ----------------------------------------------------------\n  // Private: report delivery\n  // ----------------------------------------------------------\n\n  private async deliverReport(performanceReport: PerformanceReport): Promise<void> {\n    switch (this.destination) {\n      case 'console':\n        this.logToConsole(performanceReport)\n        break\n\n      case 'custom':\n        if (this.onReportCallback) {\n          await this.onReportCallback(performanceReport)\n        }\n        break\n    }\n  }\n\n  private logToConsole(performanceReport: PerformanceReport): void {\n    if (typeof globalThis.console === 'undefined') {\n      return\n    }\n\n    const log = globalThis.console\n    const group = typeof log.group === 'function' ? log.group.bind(log) : undefined\n    const groupEnd = typeof log.groupEnd === 'function' ? log.groupEnd.bind(log) : undefined\n\n    if (group) {\n      group('[PWFabric Perf Report]')\n    } else {\n      log.warn('[PWFabric Perf Report]')\n    }\n\n    if (performanceReport.webVitals) {\n      log.warn('Web Vitals:', performanceReport.webVitals)\n    }\n\n    if (performanceReport.renderMetrics) {\n      log.warn('Render Metrics:', performanceReport.renderMetrics)\n    }\n\n    if (performanceReport.budgetCheck) {\n      const status = performanceReport.budgetCheck.passed ? 'PASS' : 'FAIL'\n      log.warn(`Budget Check: ${status}`, performanceReport.budgetCheck.violations)\n    }\n\n    if (groupEnd) {\n      groupEnd()\n    }\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a new PerformanceReporter instance.\n *\n * @param config - Reporter configuration\n * @returns A new PerformanceReporter\n */\nexport function createPerformanceReporter(config: ReporterConfig): PerformanceReporter {\n  return new PerformanceReporter(config)\n}\n"]}

package/dist/perf/web-vitals.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Core Web Vitals Collection
+ *
+ * Collects Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP) using
+ * PerformanceObserver. Provides real-time metric collection with
+ * rating classification based on web.dev thresholds.
+ *
+ * All browser APIs are guarded for SSR safety.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+/** Web Vital metric names */
+export type WebVitalName = 'LCP' | 'FID' | 'CLS' | 'FCP' | 'TTFB' | 'INP';
+/** Rating classification for a metric */
+export type WebVitalRating = 'good' | 'needs-improvement' | 'poor';
+/** A single Web Vital measurement */
+export interface WebVitalMetric {
+    /** Metric name */
+    readonly name: WebVitalName;
+    /** Metric value (ms for timing metrics, unitless for CLS) */
+    readonly value: number;
+    /** Rating based on web.dev thresholds */
+    readonly rating: WebVitalRating;
+    /** Timestamp when the metric was collected */
+    readonly timestamp: number;
+}
+/** Callback invoked when a metric is collected */
+export type WebVitalCallback = (metric: WebVitalMetric) => void;
+/** Aggregated report of all collected Web Vitals */
+export interface WebVitalsReport {
+    /** Largest Contentful Paint */
+    readonly lcp?: WebVitalMetric | undefined;
+    /** First Input Delay */
+    readonly fid?: WebVitalMetric | undefined;
+    /** Cumulative Layout Shift */
+    readonly cls?: WebVitalMetric | undefined;
+    /** First Contentful Paint */
+    readonly fcp?: WebVitalMetric | undefined;
+    /** Time to First Byte */
+    readonly ttfb?: WebVitalMetric | undefined;
+    /** Interaction to Next Paint */
+    readonly inp?: WebVitalMetric | undefined;
+    /** Timestamp when the report was generated */
+    readonly collectedAt: number;
+}
+/**
+ * Rate a metric value against web.dev thresholds.
+ *
+ * @param name - The metric name
+ * @param value - The measured value
+ * @returns The rating classification
+ */
+export declare function rateMetric(name: WebVitalName, value: number): WebVitalRating;
+/**
+ * Collects Core Web Vitals using PerformanceObserver.
+ *
+ * Supports LCP, FID, CLS, FCP, TTFB, and INP metrics.
+ * All observers are cleaned up on dispose.
+ */
+export declare class WebVitalsCollector {
+    private metrics;
+    private observers;
+    private callbacks;
+    private clsValue;
+    private clsSessionEntries;
+    private clsSessionValue;
+    /**
+     * Start collecting all Web Vitals.
+     *
+     * Creates PerformanceObservers for each metric type.
+     * Safe to call in SSR environments (no-ops silently).
+     */
+    startCollecting(): void;
+    /**
+     * Register a callback for a specific metric.
+     *
+     * The callback fires each time the metric is updated.
+     *
+     * @param name - The metric name to observe
+     * @param callback - Function to call with the metric
+     */
+    onMetric(name: WebVitalName, callback: WebVitalCallback): void;
+    /**
+     * Get the current Web Vitals report.
+     *
+     * @returns A snapshot of all collected metrics
+     */
+    getReport(): WebVitalsReport;
+    /**
+     * Stop collecting metrics and disconnect all observers.
+     */
+    stopCollecting(): void;
+    /**
+     * Stop collecting and clear all state.
+     */
+    dispose(): void;
+    private recordMetric;
+    private tryObserve;
+    private observeLCP;
+    private observeFID;
+    private observeCLS;
+    private observeFCP;
+    private observeTTFB;
+    private observeINP;
+}
+/**
+ * Create a new WebVitalsCollector instance.
+ *
+ * @returns A new collector (not yet started)
+ */
+export declare function createWebVitalsCollector(): WebVitalsCollector;

package/dist/perf/web-vitals.js

@@ -0,0 +1,268 @@
+/**
+ * Core Web Vitals Collection
+ *
+ * Collects Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP) using
+ * PerformanceObserver. Provides real-time metric collection with
+ * rating classification based on web.dev thresholds.
+ *
+ * All browser APIs are guarded for SSR safety.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+// ============================================================
+// THRESHOLDS (from web.dev)
+// ============================================================
+/** Rating thresholds: [goodThreshold, poorThreshold] */
+const THRESHOLDS = {
+    LCP: [2500, 4000],
+    FID: [100, 300],
+    CLS: [0.1, 0.25],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+    INP: [200, 500],
+};
+// ============================================================
+// UTILITY
+// ============================================================
+/**
+ * Rate a metric value against web.dev thresholds.
+ *
+ * @param name - The metric name
+ * @param value - The measured value
+ * @returns The rating classification
+ */
+export function rateMetric(name, value) {
+    const threshold = THRESHOLDS[name];
+    if (!threshold) {
+        return 'good';
+    }
+    if (value <= threshold[0]) {
+        return 'good';
+    }
+    if (value > threshold[1]) {
+        return 'poor';
+    }
+    return 'needs-improvement';
+}
+// ============================================================
+// COLLECTOR
+// ============================================================
+/**
+ * Collects Core Web Vitals using PerformanceObserver.
+ *
+ * Supports LCP, FID, CLS, FCP, TTFB, and INP metrics.
+ * All observers are cleaned up on dispose.
+ */
+export class WebVitalsCollector {
+    metrics = new Map();
+    observers = [];
+    callbacks = new Map();
+    clsValue = 0;
+    clsSessionEntries = [];
+    clsSessionValue = 0;
+    /**
+     * Start collecting all Web Vitals.
+     *
+     * Creates PerformanceObservers for each metric type.
+     * Safe to call in SSR environments (no-ops silently).
+     */
+    startCollecting() {
+        if (typeof PerformanceObserver === 'undefined') {
+            return;
+        }
+        this.observeLCP();
+        this.observeFID();
+        this.observeCLS();
+        this.observeFCP();
+        this.observeTTFB();
+        this.observeINP();
+    }
+    /**
+     * Register a callback for a specific metric.
+     *
+     * The callback fires each time the metric is updated.
+     *
+     * @param name - The metric name to observe
+     * @param callback - Function to call with the metric
+     */
+    onMetric(name, callback) {
+        const existing = this.callbacks.get(name) ?? [];
+        existing.push(callback);
+        this.callbacks.set(name, existing);
+    }
+    /**
+     * Get the current Web Vitals report.
+     *
+     * @returns A snapshot of all collected metrics
+     */
+    getReport() {
+        return {
+            lcp: this.metrics.get('LCP'),
+            fid: this.metrics.get('FID'),
+            cls: this.metrics.get('CLS'),
+            fcp: this.metrics.get('FCP'),
+            ttfb: this.metrics.get('TTFB'),
+            inp: this.metrics.get('INP'),
+            collectedAt: Date.now(),
+        };
+    }
+    /**
+     * Stop collecting metrics and disconnect all observers.
+     */
+    stopCollecting() {
+        for (const observer of this.observers) {
+            observer.disconnect();
+        }
+        this.observers = [];
+    }
+    /**
+     * Stop collecting and clear all state.
+     */
+    dispose() {
+        this.stopCollecting();
+        this.metrics.clear();
+        this.callbacks.clear();
+        this.clsValue = 0;
+        this.clsSessionEntries = [];
+        this.clsSessionValue = 0;
+    }
+    // ----------------------------------------------------------
+    // Private: metric recording
+    // ----------------------------------------------------------
+    recordMetric(name, value) {
+        const metric = {
+            name,
+            value,
+            rating: rateMetric(name, value),
+            timestamp: Date.now(),
+        };
+        this.metrics.set(name, metric);
+        const cbs = this.callbacks.get(name);
+        if (cbs) {
+            for (const cb of cbs) {
+                cb(metric);
+            }
+        }
+    }
+    // ----------------------------------------------------------
+    // Private: observer helpers
+    // ----------------------------------------------------------
+    tryObserve(entryType, handler, options) {
+        try {
+            const observer = new PerformanceObserver((list) => {
+                handler(list.getEntries());
+            });
+            const observeOptions = {
+                type: options?.type ?? entryType,
+                buffered: options?.buffered ?? true,
+            };
+            observer.observe(observeOptions);
+            this.observers.push(observer);
+        }
+        catch {
+            // Entry type not supported in this browser — silently skip
+        }
+    }
+    observeLCP() {
+        this.tryObserve('largest-contentful-paint', (entries) => {
+            const last = entries[entries.length - 1];
+            if (last) {
+                this.recordMetric('LCP', last.startTime);
+            }
+        });
+    }
+    observeFID() {
+        this.tryObserve('first-input', (entries) => {
+            const first = entries[0];
+            if (first) {
+                const fidEntry = first;
+                this.recordMetric('FID', fidEntry.processingStart - fidEntry.startTime);
+            }
+        });
+    }
+    observeCLS() {
+        this.tryObserve('layout-shift', (entries) => {
+            for (const entry of entries) {
+                const lsEntry = entry;
+                // Only count shifts without recent user input
+                if (!lsEntry.hadRecentInput) {
+                    // Session window algorithm
+                    if (this.clsSessionEntries.length > 0 &&
+                        entry.startTime -
+                            (this.clsSessionEntries[this.clsSessionEntries.length - 1]?.startTime ?? 0) >
+                            1000) {
+                        // Gap > 1s → start new session window
+                        if (this.clsSessionValue > this.clsValue) {
+                            this.clsValue = this.clsSessionValue;
+                        }
+                        this.clsSessionEntries = [];
+                        this.clsSessionValue = 0;
+                    }
+                    // Add to current session
+                    if (this.clsSessionEntries.length === 0 ||
+                        entry.startTime - (this.clsSessionEntries[0]?.startTime ?? 0) <= 5000) {
+                        this.clsSessionEntries.push(entry);
+                        this.clsSessionValue += lsEntry.value;
+                    }
+                    else {
+                        // Session exceeded 5s → start new session
+                        if (this.clsSessionValue > this.clsValue) {
+                            this.clsValue = this.clsSessionValue;
+                        }
+                        this.clsSessionEntries = [entry];
+                        this.clsSessionValue = lsEntry.value;
+                    }
+                    // Report the max of current session and previous max
+                    const currentCls = Math.max(this.clsValue, this.clsSessionValue);
+                    this.recordMetric('CLS', currentCls);
+                }
+            }
+        });
+    }
+    observeFCP() {
+        this.tryObserve('paint', (entries) => {
+            const fcp = entries.find((e) => e.name === 'first-contentful-paint');
+            if (fcp) {
+                this.recordMetric('FCP', fcp.startTime);
+            }
+        });
+    }
+    observeTTFB() {
+        this.tryObserve('navigation', (entries) => {
+            const nav = entries[0];
+            if (nav) {
+                this.recordMetric('TTFB', nav.responseStart);
+            }
+        });
+    }
+    observeINP() {
+        this.tryObserve('event', (entries) => {
+            let maxDuration = 0;
+            for (const entry of entries) {
+                const eventEntry = entry;
+                if (eventEntry.duration > maxDuration) {
+                    maxDuration = eventEntry.duration;
+                }
+            }
+            if (maxDuration > 0) {
+                const existing = this.metrics.get('INP');
+                // INP tracks the worst interaction
+                if (!existing || maxDuration > existing.value) {
+                    this.recordMetric('INP', maxDuration);
+                }
+            }
+        }, { type: 'event', buffered: true });
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new WebVitalsCollector instance.
+ *
+ * @returns A new collector (not yet started)
+ */
+export function createWebVitalsCollector() {
+    return new WebVitalsCollector();
+}
+//# sourceMappingURL=web-vitals.js.map