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

package/dist/perf/budget.js

@@ -0,0 +1,122 @@
+/**
+ * Performance Budget Enforcement
+ *
+ * Defines performance budgets based on web.dev recommendations
+ * and checks measured metrics against those budgets. Violations
+ * are reported with severity levels.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+// ============================================================
+// DEFAULT BUDGET
+// ============================================================
+/**
+ * Default performance budgets based on web.dev "good" thresholds.
+ */
+export const DEFAULT_BUDGET = {
+    lcp: 2500,
+    fid: 100,
+    cls: 0.1,
+    fcp: 1800,
+    ttfb: 800,
+    maxRenderTime: 100,
+};
+// ============================================================
+// BUDGET CHECKER
+// ============================================================
+/**
+ * Multiplier above the budget threshold that escalates a
+ * violation from "warning" to "error". A value 20% over
+ * budget is a warning; more than 20% over is an error.
+ */
+const ERROR_MULTIPLIER = 1.2;
+/** Mapping from budget keys to the metric keys used in check() */
+const BUDGET_METRIC_MAP = new Map([
+    ['lcp', 'lcp'],
+    ['fid', 'fid'],
+    ['cls', 'cls'],
+    ['fcp', 'fcp'],
+    ['ttfb', 'ttfb'],
+    ['maxBundleSize', 'maxBundleSize'],
+    ['maxRenderTime', 'maxRenderTime'],
+]);
+/**
+ * Checks measured performance metrics against a budget.
+ *
+ * Uses default web.dev "good" thresholds unless overridden.
+ * Violations are classified as "warning" (within 20% over)
+ * or "error" (more than 20% over).
+ */
+export class BudgetChecker {
+    budget;
+    /**
+     * @param budget - Custom budget thresholds (merged with defaults)
+     */
+    constructor(budget) {
+        this.budget = budget ? { ...DEFAULT_BUDGET, ...budget } : { ...DEFAULT_BUDGET };
+    }
+    /**
+     * Check a set of metrics against the current budget.
+     *
+     * @param metrics - Map of metric name to measured value
+     * @returns Check result with pass/fail and any violations
+     */
+    check(metrics) {
+        const violations = [];
+        for (const [budgetKey, metricKey] of BUDGET_METRIC_MAP) {
+            const threshold = this.budget[budgetKey];
+            if (threshold === undefined) {
+                continue;
+            }
+            const actual = metrics[metricKey];
+            if (actual === undefined) {
+                continue;
+            }
+            if (actual > threshold) {
+                const severity = actual > threshold * ERROR_MULTIPLIER ? 'error' : 'warning';
+                violations.push({
+                    metric: metricKey,
+                    budget: threshold,
+                    actual,
+                    severity,
+                });
+            }
+        }
+        return {
+            passed: violations.length === 0,
+            violations,
+            checkedAt: Date.now(),
+        };
+    }
+    /**
+     * Update the performance budget.
+     *
+     * Merges the provided values with the existing budget.
+     *
+     * @param budget - Partial budget to merge
+     */
+    setBudget(budget) {
+        this.budget = { ...this.budget, ...budget };
+    }
+    /**
+     * Get the current performance budget.
+     *
+     * @returns Readonly copy of the budget
+     */
+    getBudget() {
+        return { ...this.budget };
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new BudgetChecker instance.
+ *
+ * @param budget - Optional custom budget thresholds
+ * @returns A new BudgetChecker
+ */
+export function createBudgetChecker(budget) {
+    return new BudgetChecker(budget);
+}
+//# sourceMappingURL=budget.js.map

package/dist/perf/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/perf/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8CH,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,GAAG;IACR,GAAG,EAAE,GAAG;IACR,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,GAAG;IACT,aAAa,EAAE,GAAG;CACV,CAAA;AAEV,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAE5B,kEAAkE;AAClE,MAAM,iBAAiB,GAAiD,IAAI,GAAG,CAG7E;IACA,CAAC,KAAK,EAAE,KAAK,CAAC;IACd,CAAC,KAAK,EAAE,KAAK,CAAC;IACd,CAAC,KAAK,EAAE,KAAK,CAAC;IACd,CAAC,KAAK,EAAE,KAAK,CAAC;IACd,CAAC,MAAM,EAAE,MAAM,CAAC;IAChB,CAAC,eAAe,EAAE,eAAe,CAAC;IAClC,CAAC,eAAe,EAAE,eAAe,CAAC;CACnC,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAmB;IAEjC;;OAEG;IACH,YAAY,MAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,cAAc,EAAE,CAAA;IACjF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAwC;QAC5C,MAAM,UAAU,GAAsB,EAAE,CAAA;QAExC,KAAK,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,iBAAiB,EAAE,CAAC;YACvD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;YACxC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,SAAQ;YACV,CAAC;YAED,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;YACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,SAAQ;YACV,CAAC;YAED,IAAI,MAAM,GAAG,SAAS,EAAE,CAAC;gBACvB,MAAM,QAAQ,GACZ,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;gBAE7D,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,SAAS;oBACjB,MAAM,EAAE,SAAS;oBACjB,MAAM;oBACN,QAAQ;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;YAC/B,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,MAAkC;QAC1C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;IAC7C,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAC3B,CAAC;CACF;AAED,+DAA+D;AAC/D,UAAU;AACV,+DAA+D;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC","sourcesContent":["/**\n * Performance Budget Enforcement\n *\n * Defines performance budgets based on web.dev recommendations\n * and checks measured metrics against those budgets. Violations\n * are reported with severity levels.\n *\n * @module @pwfabric/runtime/perf\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Performance budget thresholds */\nexport interface PerformanceBudget {\n  /** Max Largest Contentful Paint in ms */\n  readonly lcp?: number\n  /** Max First Input Delay in ms */\n  readonly fid?: number\n  /** Max Cumulative Layout Shift score */\n  readonly cls?: number\n  /** Max First Contentful Paint in ms */\n  readonly fcp?: number\n  /** Max Time to First Byte in ms */\n  readonly ttfb?: number\n  /** Max bundle size in bytes */\n  readonly maxBundleSize?: number\n  /** Max render time in ms */\n  readonly maxRenderTime?: number\n}\n\n/** A single budget violation */\nexport interface BudgetViolation {\n  /** Metric that violated the budget */\n  readonly metric: string\n  /** Budget threshold */\n  readonly budget: number\n  /** Actual measured value */\n  readonly actual: number\n  /** Severity: warning if within 20% over, error if more */\n  readonly severity: 'warning' | 'error'\n}\n\n/** Result of checking metrics against a budget */\nexport interface BudgetCheckResult {\n  /** Whether all metrics passed the budget */\n  readonly passed: boolean\n  /** List of violations (empty if passed) */\n  readonly violations: readonly BudgetViolation[]\n  /** Timestamp when the check was performed */\n  readonly checkedAt: number\n}\n\n// ============================================================\n// DEFAULT BUDGET\n// ============================================================\n\n/**\n * Default performance budgets based on web.dev \"good\" thresholds.\n */\nexport const DEFAULT_BUDGET: Readonly<PerformanceBudget> = {\n  lcp: 2500,\n  fid: 100,\n  cls: 0.1,\n  fcp: 1800,\n  ttfb: 800,\n  maxRenderTime: 100,\n} as const\n\n// ============================================================\n// BUDGET CHECKER\n// ============================================================\n\n/**\n * Multiplier above the budget threshold that escalates a\n * violation from \"warning\" to \"error\". A value 20% over\n * budget is a warning; more than 20% over is an error.\n */\nconst ERROR_MULTIPLIER = 1.2\n\n/** Mapping from budget keys to the metric keys used in check() */\nconst BUDGET_METRIC_MAP: ReadonlyMap<keyof PerformanceBudget, string> = new Map<\n  keyof PerformanceBudget,\n  string\n>([\n  ['lcp', 'lcp'],\n  ['fid', 'fid'],\n  ['cls', 'cls'],\n  ['fcp', 'fcp'],\n  ['ttfb', 'ttfb'],\n  ['maxBundleSize', 'maxBundleSize'],\n  ['maxRenderTime', 'maxRenderTime'],\n])\n\n/**\n * Checks measured performance metrics against a budget.\n *\n * Uses default web.dev \"good\" thresholds unless overridden.\n * Violations are classified as \"warning\" (within 20% over)\n * or \"error\" (more than 20% over).\n */\nexport class BudgetChecker {\n  private budget: PerformanceBudget\n\n  /**\n   * @param budget - Custom budget thresholds (merged with defaults)\n   */\n  constructor(budget?: PerformanceBudget) {\n    this.budget = budget ? { ...DEFAULT_BUDGET, ...budget } : { ...DEFAULT_BUDGET }\n  }\n\n  /**\n   * Check a set of metrics against the current budget.\n   *\n   * @param metrics - Map of metric name to measured value\n   * @returns Check result with pass/fail and any violations\n   */\n  check(metrics: Partial<Record<string, number>>): BudgetCheckResult {\n    const violations: BudgetViolation[] = []\n\n    for (const [budgetKey, metricKey] of BUDGET_METRIC_MAP) {\n      const threshold = this.budget[budgetKey]\n      if (threshold === undefined) {\n        continue\n      }\n\n      const actual = metrics[metricKey]\n      if (actual === undefined) {\n        continue\n      }\n\n      if (actual > threshold) {\n        const severity: 'warning' | 'error' =\n          actual > threshold * ERROR_MULTIPLIER ? 'error' : 'warning'\n\n        violations.push({\n          metric: metricKey,\n          budget: threshold,\n          actual,\n          severity,\n        })\n      }\n    }\n\n    return {\n      passed: violations.length === 0,\n      violations,\n      checkedAt: Date.now(),\n    }\n  }\n\n  /**\n   * Update the performance budget.\n   *\n   * Merges the provided values with the existing budget.\n   *\n   * @param budget - Partial budget to merge\n   */\n  setBudget(budget: Partial<PerformanceBudget>): void {\n    this.budget = { ...this.budget, ...budget }\n  }\n\n  /**\n   * Get the current performance budget.\n   *\n   * @returns Readonly copy of the budget\n   */\n  getBudget(): Readonly<PerformanceBudget> {\n    return { ...this.budget }\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a new BudgetChecker instance.\n *\n * @param budget - Optional custom budget thresholds\n * @returns A new BudgetChecker\n */\nexport function createBudgetChecker(budget?: PerformanceBudget): BudgetChecker {\n  return new BudgetChecker(budget)\n}\n"]}

package/dist/perf/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Performance Monitoring Module
+ *
+ * Provides Core Web Vitals collection, surface render timing,
+ * performance budget enforcement, and unified reporting.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+export type { WebVitalName, WebVitalRating, WebVitalMetric, WebVitalCallback, WebVitalsReport, } from './web-vitals.js';
+export { WebVitalsCollector, createWebVitalsCollector, rateMetric } from './web-vitals.js';
+export type { RenderMetrics, RenderTimerConfig } from './render-timer.js';
+export { RenderTimer, createRenderTimer } from './render-timer.js';
+export type { PerformanceBudget, BudgetViolation, BudgetCheckResult } from './budget.js';
+export { DEFAULT_BUDGET, BudgetChecker, createBudgetChecker } from './budget.js';
+export type { ReportDestination, ReporterConfig, PerformanceReport } from './reporter.js';
+export { PerformanceReporter, createPerformanceReporter } from './reporter.js';

package/dist/perf/index.js

@@ -0,0 +1,13 @@
+/**
+ * Performance Monitoring Module
+ *
+ * Provides Core Web Vitals collection, surface render timing,
+ * performance budget enforcement, and unified reporting.
+ *
+ * @module @pwfabric/runtime/perf
+ */
+export { WebVitalsCollector, createWebVitalsCollector, rateMetric } from './web-vitals.js';
+export { RenderTimer, createRenderTimer } from './render-timer.js';
+export { DEFAULT_BUDGET, BudgetChecker, createBudgetChecker } from './budget.js';
+export { PerformanceReporter, createPerformanceReporter } from './reporter.js';
+//# sourceMappingURL=index.js.map

package/dist/perf/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/perf/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI1F,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAIlE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAIhF,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA","sourcesContent":["/**\n * Performance Monitoring Module\n *\n * Provides Core Web Vitals collection, surface render timing,\n * performance budget enforcement, and unified reporting.\n *\n * @module @pwfabric/runtime/perf\n */\n\n// Web Vitals collection\nexport type {\n  WebVitalName,\n  WebVitalRating,\n  WebVitalMetric,\n  WebVitalCallback,\n  WebVitalsReport,\n} from './web-vitals.js'\nexport { WebVitalsCollector, createWebVitalsCollector, rateMetric } from './web-vitals.js'\n\n// Render timing\nexport type { RenderMetrics, RenderTimerConfig } from './render-timer.js'\nexport { RenderTimer, createRenderTimer } from './render-timer.js'\n\n// Performance budget\nexport type { PerformanceBudget, BudgetViolation, BudgetCheckResult } from './budget.js'\nexport { DEFAULT_BUDGET, BudgetChecker, createBudgetChecker } from './budget.js'\n\n// Reporter\nexport type { ReportDestination, ReporterConfig, PerformanceReport } from './reporter.js'\nexport { PerformanceReporter, createPerformanceReporter } from './reporter.js'\n"]}

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

@@ -0,0 +1,90 @@
+/**
+ * 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;

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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","sourcesContent":["/**\n * Surface / Block Render Timing\n *\n * Tracks render durations for surfaces and blocks using\n * high-resolution timing. Maintains a bounded history of\n * render metrics for performance analysis.\n *\n * Uses `performance.now()` when available, falling back to\n * `Date.now()` for SSR environments.\n *\n * @module @pwfabric/runtime/perf\n */\n\n// ============================================================\n// TIMING UTILITY\n// ============================================================\n\n/**\n * Get the current high-resolution timestamp.\n *\n * Falls back to `Date.now()` when `performance` is not available (SSR).\n */\nfunction now(): number {\n  if (typeof performance !== 'undefined' && typeof performance.now === 'function') {\n    return performance.now()\n  }\n  return Date.now()\n}\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Metrics for a single surface render cycle */\nexport interface RenderMetrics {\n  /** Surface identifier */\n  readonly surfaceId: string\n  /** High-resolution render start time */\n  readonly startTime: number\n  /** High-resolution render end time */\n  readonly endTime: number\n  /** Render duration in milliseconds */\n  readonly duration: number\n  /** Number of blocks rendered */\n  readonly blockCount: number\n}\n\n/** Configuration for the RenderTimer */\nexport interface RenderTimerConfig {\n  /** Maximum number of entries to keep in history (default: 100) */\n  maxEntries?: number\n}\n\n// ============================================================\n// DEFAULTS\n// ============================================================\n\nconst DEFAULT_MAX_ENTRIES = 100\n\n// ============================================================\n// RENDER TIMER\n// ============================================================\n\n/** Active render tracking entry */\ninterface ActiveRender {\n  readonly startTime: number\n  readonly blockCount: number\n}\n\n/**\n * Tracks surface render timing with bounded history.\n *\n * Call `startRender` before a surface renders and `endRender`\n * when rendering completes. The timer records the duration and\n * maintains a history of recent render metrics.\n */\nexport class RenderTimer {\n  private entries = new Map<string, ActiveRender>()\n  private history: RenderMetrics[] = []\n  private readonly maxEntries: number\n\n  /**\n   * @param config - Optional configuration\n   */\n  constructor(config?: RenderTimerConfig) {\n    this.maxEntries = config?.maxEntries ?? DEFAULT_MAX_ENTRIES\n  }\n\n  /**\n   * Mark the start of a surface render.\n   *\n   * @param surfaceId - Unique identifier for the surface\n   * @param blockCount - Number of blocks being rendered (default: 0)\n   */\n  startRender(surfaceId: string, blockCount = 0): void {\n    this.entries.set(surfaceId, {\n      startTime: now(),\n      blockCount,\n    })\n  }\n\n  /**\n   * Mark the end of a surface render and record metrics.\n   *\n   * @param surfaceId - The surface identifier passed to `startRender`\n   * @returns The render metrics, or `undefined` if no matching start was found\n   */\n  endRender(surfaceId: string): RenderMetrics | undefined {\n    const entry = this.entries.get(surfaceId)\n    if (!entry) {\n      return undefined\n    }\n\n    this.entries.delete(surfaceId)\n\n    const endTime = now()\n    const metrics: RenderMetrics = {\n      surfaceId,\n      startTime: entry.startTime,\n      endTime,\n      duration: endTime - entry.startTime,\n      blockCount: entry.blockCount,\n    }\n\n    this.history.push(metrics)\n\n    // Enforce bounded history\n    if (this.history.length > this.maxEntries) {\n      this.history = this.history.slice(-this.maxEntries)\n    }\n\n    return metrics\n  }\n\n  /**\n   * Calculate the average render time across all recorded renders.\n   *\n   * @returns Average duration in milliseconds, or 0 if no renders recorded\n   */\n  getAverageRenderTime(): number {\n    if (this.history.length === 0) {\n      return 0\n    }\n    const total = this.history.reduce((sum, m) => sum + m.duration, 0)\n    return total / this.history.length\n  }\n\n  /**\n   * Get the full render history.\n   *\n   * @returns Readonly array of render metrics\n   */\n  getHistory(): readonly RenderMetrics[] {\n    return this.history\n  }\n\n  /**\n   * Get the slowest renders, sorted by duration descending.\n   *\n   * @param count - Number of entries to return (default: 5)\n   * @returns Array of the slowest render metrics\n   */\n  getSlowest(count = 5): RenderMetrics[] {\n    return [...this.history].sort((a, b) => b.duration - a.duration).slice(0, count)\n  }\n\n  /**\n   * Clear all history and active entries.\n   */\n  clear(): void {\n    this.entries.clear()\n    this.history = []\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a new RenderTimer instance.\n *\n * @param config - Optional configuration\n * @returns A new RenderTimer\n */\nexport function createRenderTimer(config?: RenderTimerConfig): RenderTimer {\n  return new RenderTimer(config)\n}\n"]}

package/dist/perf/reporter.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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;