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

package/dist/perf/render-timer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Surface / Block Render Timing
+ *
+ * Tracks render durations for surfaces and blocks using
+ * high-resolution timing. Maintains a bounded history of
+ * render metrics for performance analysis.
+ *
+ * Uses `performance.now()` when available, falling back to
+ * `Date.now()` for SSR environments.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+/** Metrics for a single surface render cycle */
+export interface RenderMetrics {
+    /** Surface identifier */
+    readonly surfaceId: string;
+    /** High-resolution render start time */
+    readonly startTime: number;
+    /** High-resolution render end time */
+    readonly endTime: number;
+    /** Render duration in milliseconds */
+    readonly duration: number;
+    /** Number of blocks rendered */
+    readonly blockCount: number;
+}
+/** Configuration for the RenderTimer */
+export interface RenderTimerConfig {
+    /** Maximum number of entries to keep in history (default: 100) */
+    maxEntries?: number;
+}
+/**
+ * Tracks surface render timing with bounded history.
+ *
+ * Call `startRender` before a surface renders and `endRender`
+ * when rendering completes. The timer records the duration and
+ * maintains a history of recent render metrics.
+ */
+export declare class RenderTimer {
+    private entries;
+    private history;
+    private readonly maxEntries;
+    /**
+     * @param config - Optional configuration
+     */
+    constructor(config?: RenderTimerConfig);
+    /**
+     * Mark the start of a surface render.
+     *
+     * @param surfaceId - Unique identifier for the surface
+     * @param blockCount - Number of blocks being rendered (default: 0)
+     */
+    startRender(surfaceId: string, blockCount?: number): void;
+    /**
+     * Mark the end of a surface render and record metrics.
+     *
+     * @param surfaceId - The surface identifier passed to `startRender`
+     * @returns The render metrics, or `undefined` if no matching start was found
+     */
+    endRender(surfaceId: string): RenderMetrics | undefined;
+    /**
+     * Calculate the average render time across all recorded renders.
+     *
+     * @returns Average duration in milliseconds, or 0 if no renders recorded
+     */
+    getAverageRenderTime(): number;
+    /**
+     * Get the full render history.
+     *
+     * @returns Readonly array of render metrics
+     */
+    getHistory(): readonly RenderMetrics[];
+    /**
+     * Get the slowest renders, sorted by duration descending.
+     *
+     * @param count - Number of entries to return (default: 5)
+     * @returns Array of the slowest render metrics
+     */
+    getSlowest(count?: number): RenderMetrics[];
+    /**
+     * Clear all history and active entries.
+     */
+    clear(): void;
+}
+/**
+ * Create a new RenderTimer instance.
+ *
+ * @param config - Optional configuration
+ * @returns A new RenderTimer
+ */
+export declare function createRenderTimer(config?: RenderTimerConfig): RenderTimer;
+//# sourceMappingURL=render-timer.d.ts.map

package/dist/perf/render-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-timer.d.ts","sourceRoot":"","sources":["../../src/perf/render-timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAsBH,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAkBD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IAEnC;;OAEG;gBACS,MAAM,CAAC,EAAE,iBAAiB;IAItC;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,IAAI;IAOpD;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IA2BvD;;;;OAIG;IACH,oBAAoB,IAAI,MAAM;IAQ9B;;;;OAIG;IACH,UAAU,IAAI,SAAS,aAAa,EAAE;IAItC;;;;;OAKG;IACH,UAAU,CAAC,KAAK,SAAI,GAAG,aAAa,EAAE;IAItC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAEzE"}

package/dist/perf/render-timer.js

@@ -0,0 +1,136 @@
+/**
+ * Surface / Block Render Timing
+ *
+ * Tracks render durations for surfaces and blocks using
+ * high-resolution timing. Maintains a bounded history of
+ * render metrics for performance analysis.
+ *
+ * Uses `performance.now()` when available, falling back to
+ * `Date.now()` for SSR environments.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+// ============================================================
+// TIMING UTILITY
+// ============================================================
+/**
+ * Get the current high-resolution timestamp.
+ *
+ * Falls back to `Date.now()` when `performance` is not available (SSR).
+ */
+function now() {
+    if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+        return performance.now();
+    }
+    return Date.now();
+}
+// ============================================================
+// DEFAULTS
+// ============================================================
+const DEFAULT_MAX_ENTRIES = 100;
+/**
+ * Tracks surface render timing with bounded history.
+ *
+ * Call `startRender` before a surface renders and `endRender`
+ * when rendering completes. The timer records the duration and
+ * maintains a history of recent render metrics.
+ */
+export class RenderTimer {
+    entries = new Map();
+    history = [];
+    maxEntries;
+    /**
+     * @param config - Optional configuration
+     */
+    constructor(config) {
+        this.maxEntries = config?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Mark the start of a surface render.
+     *
+     * @param surfaceId - Unique identifier for the surface
+     * @param blockCount - Number of blocks being rendered (default: 0)
+     */
+    startRender(surfaceId, blockCount = 0) {
+        this.entries.set(surfaceId, {
+            startTime: now(),
+            blockCount,
+        });
+    }
+    /**
+     * Mark the end of a surface render and record metrics.
+     *
+     * @param surfaceId - The surface identifier passed to `startRender`
+     * @returns The render metrics, or `undefined` if no matching start was found
+     */
+    endRender(surfaceId) {
+        const entry = this.entries.get(surfaceId);
+        if (!entry) {
+            return undefined;
+        }
+        this.entries.delete(surfaceId);
+        const endTime = now();
+        const metrics = {
+            surfaceId,
+            startTime: entry.startTime,
+            endTime,
+            duration: endTime - entry.startTime,
+            blockCount: entry.blockCount,
+        };
+        this.history.push(metrics);
+        // Enforce bounded history
+        if (this.history.length > this.maxEntries) {
+            this.history = this.history.slice(-this.maxEntries);
+        }
+        return metrics;
+    }
+    /**
+     * Calculate the average render time across all recorded renders.
+     *
+     * @returns Average duration in milliseconds, or 0 if no renders recorded
+     */
+    getAverageRenderTime() {
+        if (this.history.length === 0) {
+            return 0;
+        }
+        const total = this.history.reduce((sum, m) => sum + m.duration, 0);
+        return total / this.history.length;
+    }
+    /**
+     * Get the full render history.
+     *
+     * @returns Readonly array of render metrics
+     */
+    getHistory() {
+        return this.history;
+    }
+    /**
+     * Get the slowest renders, sorted by duration descending.
+     *
+     * @param count - Number of entries to return (default: 5)
+     * @returns Array of the slowest render metrics
+     */
+    getSlowest(count = 5) {
+        return [...this.history].sort((a, b) => b.duration - a.duration).slice(0, count);
+    }
+    /**
+     * Clear all history and active entries.
+     */
+    clear() {
+        this.entries.clear();
+        this.history = [];
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new RenderTimer instance.
+ *
+ * @param config - Optional configuration
+ * @returns A new RenderTimer
+ */
+export function createRenderTimer(config) {
+    return new RenderTimer(config);
+}
+//# sourceMappingURL=render-timer.js.map

package/dist/perf/render-timer.js.map

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

package/dist/perf/reporter.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 type { WebVitalsReport } from './web-vitals.js';
+import type { RenderMetrics } from './render-timer.js';
+import type { PerformanceBudget, BudgetCheckResult } from './budget.js';
+import { WebVitalsCollector } from './web-vitals.js';
+import { RenderTimer } from './render-timer.js';
+/** Where to send performance reports */
+export type ReportDestination = 'console' | 'custom';
+/** Reporter configuration */
+export interface ReporterConfig {
+    /** Report destination */
+    readonly destination: ReportDestination;
+    /** Custom report handler (required when destination is 'custom') */
+    readonly onReport?: (report: PerformanceReport) => void | Promise<void>;
+    /** Reporting interval in ms (0 = manual only, default: 0) */
+    readonly interval?: number;
+    /** Whether to include render metrics (default: true) */
+    readonly includeRenderMetrics?: boolean;
+    /** Whether to include Web Vitals (default: true) */
+    readonly includeWebVitals?: boolean;
+    /** Performance budget to check against */
+    readonly budget?: PerformanceBudget;
+}
+/** A complete performance report */
+export interface PerformanceReport {
+    /** Timestamp when the report was generated */
+    readonly timestamp: number;
+    /** Web Vitals snapshot */
+    readonly webVitals?: WebVitalsReport | undefined;
+    /** Render timing summary */
+    readonly renderMetrics?: {
+        readonly averageRenderTime: number;
+        readonly totalRenders: number;
+        readonly slowestRenders: readonly RenderMetrics[];
+    } | undefined;
+    /** Budget check result */
+    readonly budgetCheck?: BudgetCheckResult | undefined;
+}
+/**
+ * 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 declare class PerformanceReporter {
+    private readonly destination;
+    private readonly onReportCallback?;
+    private readonly interval;
+    private readonly includeRenderMetrics;
+    private readonly includeWebVitals;
+    private webVitals?;
+    private renderTimer?;
+    private budgetChecker?;
+    private intervalId?;
+    /**
+     * @param config - Reporter configuration
+     */
+    constructor(config: ReporterConfig);
+    /**
+     * 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(): void;
+    /**
+     * 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
+     */
+    report(): Promise<PerformanceReport>;
+    /**
+     * Stop periodic reporting.
+     *
+     * Does not stop Web Vitals collection or clear history.
+     * Use `dispose()` for full cleanup.
+     */
+    stop(): void;
+    /**
+     * Get the internal WebVitalsCollector.
+     *
+     * Useful for registering custom metric callbacks.
+     *
+     * @returns The collector, or undefined if Web Vitals are disabled
+     */
+    getWebVitals(): WebVitalsCollector | undefined;
+    /**
+     * Get the internal RenderTimer.
+     *
+     * Useful for tracking surface render timing externally.
+     *
+     * @returns The timer, or undefined if render metrics are disabled
+     */
+    getRenderTimer(): RenderTimer | undefined;
+    /**
+     * Stop reporting and release all resources.
+     */
+    dispose(): void;
+    private buildWebVitalsSection;
+    private buildRenderMetricsSection;
+    private buildBudgetCheckSection;
+    private deliverReport;
+    private logToConsole;
+}
+/**
+ * Create a new PerformanceReporter instance.
+ *
+ * @param config - Reporter configuration
+ * @returns A new PerformanceReporter
+ */
+export declare function createPerformanceReporter(config: ReporterConfig): PerformanceReporter;
+//# sourceMappingURL=reporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/perf/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAO/C,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEpD,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;IACvC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvE,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;IACvC,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;CACpC;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IAChD,4BAA4B;IAC5B,QAAQ,CAAC,aAAa,CAAC,EACnB;QACE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;QAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAA;KAClD,GACD,SAAS,CAAA;IACb,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CACrD;AAYD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAErB;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,SAAS,CAAC,CAAgC;IAClD,OAAO,CAAC,WAAW,CAAC,CAAyB;IAC7C,OAAO,CAAC,aAAa,CAAC,CAA2B;IACjD,OAAO,CAAC,UAAU,CAAC,CAA4C;IAE/D;;OAEG;gBACS,MAAM,EAAE,cAAc;IAqBlC;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAYb;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAa1C;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAOZ;;;;;;OAMG;IACH,YAAY,IAAI,kBAAkB,GAAG,SAAS;IAI9C;;;;;;OAMG;IACH,cAAc,IAAI,WAAW,GAAG,SAAS;IAIzC;;OAEG;IACH,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,yBAAyB;IAajC,OAAO,CAAC,uBAAuB;YAiCjB,aAAa;IAc3B,OAAO,CAAC,YAAY;CAgCrB;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,mBAAmB,CAErF"}

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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"}