@coherent.js/performance 1.0.0-beta.3 → 1.0.0-beta.6

package/README.md

@@ -0,0 +1,505 @@
+# @coherent.js/performance
+
+Performance monitoring and optimization utilities for Coherent.js applications.
+
+## Installation
+
+```bash
+npm install @coherent.js/performance
+# or
+pnpm add @coherent.js/performance
+# or
+yarn add @coherent.js/performance
+```
+
+## Overview
+
+The `@coherent.js/performance` package provides comprehensive performance monitoring and optimization tools for Coherent.js applications, including:
+
+- Real-time performance monitoring
+- Rendering performance metrics
+- Memory usage tracking
+- Bundle size analysis
+- Performance bottlenecks detection
+- Optimization recommendations
+
+## Quick Start
+
+```javascript
+import { createPerformanceMonitor } from '@coherent.js/performance';
+
+// Create performance monitor
+const monitor = createPerformanceMonitor({
+  // Optional configuration
+  logLevel: 'info',
+  sampleRate: 1.0, // Monitor all renders
+  thresholds: {
+    render: 50, // Warn if render takes >50ms
+    memory: 100 // Warn if memory usage >100MB
+  }
+});
+
+// Start monitoring
+monitor.start();
+
+// Your Coherent.js application
+function App() {
+  return {
+    div: {
+      children: [
+        { h1: { text: 'Performance Monitored App' } },
+        { p: { text: 'Performance data is being collected...' } }
+      ]
+    }
+  };
+}
+
+// Stop monitoring when needed
+// monitor.stop();
+```
+
+## Features
+
+### Real-time Monitoring
+
+Monitor application performance in real-time:
+
+```javascript
+import { createPerformanceMonitor } from '@coherent.js/performance';
+
+const monitor = createPerformanceMonitor({
+  onMetrics: (metrics) => {
+    // Handle metrics in real-time
+    console.log('Render time:', metrics.renderTime, 'ms');
+    console.log('Memory usage:', metrics.memoryUsage, 'MB');
+    
+    // Send to analytics
+    sendToAnalytics('performance', metrics);
+  }
+});
+
+monitor.start();
+```
+
+### Rendering Performance
+
+Track component rendering performance:
+
+```javascript
+import { withPerformance } from '@coherent.js/performance';
+
+const OptimizedComponent = withPerformance({
+  name: 'UserProfile',
+  threshold: 30 // Warn if rendering takes >30ms
+})(function UserProfile({ user }) {
+  return {
+    div: {
+      className: 'user-profile',
+      children: [
+        { img: { src: user.avatar, alt: user.name } },
+        { h2: { text: user.name } },
+        { p: { text: user.bio } }
+      ]
+    }
+  };
+});
+```
+
+### Memory Tracking
+
+Monitor memory usage patterns:
+
+```javascript
+import { createMemoryTracker } from '@coherent.js/performance';
+
+const memoryTracker = createMemoryTracker({
+  interval: 5000, // Check every 5 seconds
+  onWarning: (usage) => {
+    console.warn('High memory usage detected:', usage);
+  }
+});
+
+memoryTracker.start();
+```
+
+## Performance Metrics
+
+### Core Metrics
+
+Track essential performance metrics:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  metrics: {
+    renderTime: true,      // Component render time
+    totalTime: true,       // Total render time
+    memoryUsage: true,     // Memory consumption
+    gcEvents: true,        // Garbage collection events
+    eventLoopDelay: true,  // Event loop delay
+    bundleSize: true       // Bundle size analysis
+  }
+});
+```
+
+### Custom Metrics
+
+Define custom performance metrics:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  customMetrics: {
+    databaseQueries: () => getQueryCount(),
+    apiCalls: () => getApiCallCount(),
+    cacheHits: () => getCacheHitRate()
+  }
+});
+```
+
+## Configuration Options
+
+### Thresholds
+
+Set performance thresholds for alerts:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  thresholds: {
+    renderTime: 50,        // ms
+    totalTime: 200,        // ms
+    memoryUsage: 150,      // MB
+    eventLoopDelay: 20,    // ms
+    bundleSize: 500        // KB
+  }
+});
+```
+
+### Sampling
+
+Control monitoring sampling rate:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  sampleRate: 0.1, // Only monitor 10% of renders
+  sampleStrategy: 'random' // or 'first' or 'last'
+});
+```
+
+### Logging
+
+Configure logging behavior:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  logLevel: 'warn', // 'debug', 'info', 'warn', 'error'
+  logFormat: 'json', // or 'text'
+  logDestination: 'console' // or 'file' or custom function
+});
+```
+
+## Performance Optimization
+
+### Bundle Analysis
+
+Analyze and optimize bundle size:
+
+```javascript
+import { analyzeBundle } from '@coherent.js/performance';
+
+// Analyze your application bundle
+const bundleAnalysis = await analyzeBundle({
+  entryPoints: ['./src/index.js'],
+  outputDir: './dist'
+});
+
+console.log('Bundle size:', bundleAnalysis.totalSize);
+console.log('Largest modules:', bundleAnalysis.largestModules);
+```
+
+### Code Splitting Recommendations
+
+Get code splitting recommendations:
+
+```javascript
+import { getCodeSplittingRecommendations } from '@coherent.js/performance';
+
+const recommendations = getCodeSplittingRecommendations({
+  componentUsage: getComponentUsageData(),
+  routePatterns: getRoutePatterns()
+});
+
+recommendations.forEach(rec => {
+  console.log(`Split ${rec.component} into separate bundle`);
+});
+```
+
+## Advanced Features
+
+### Profiling
+
+Detailed performance profiling:
+
+```javascript
+import { createProfiler } from '@coherent.js/performance';
+
+const profiler = createProfiler({
+  detailLevel: 'high', // 'low', 'medium', 'high'
+  outputFormat: 'json' // or 'html'
+});
+
+// Profile a specific operation
+profiler.profile('render-dashboard', () => {
+  return renderDashboard(data);
+});
+```
+
+### Comparison Reports
+
+Generate performance comparison reports:
+
+```javascript
+import { createComparisonReport } from '@coherent.js/performance';
+
+const beforeMetrics = getMetricsBeforeOptimization();
+const afterMetrics = getMetricsAfterOptimization();
+
+const report = createComparisonReport({
+  before: beforeMetrics,
+  after: afterMetrics,
+  improvementsOnly: true
+});
+
+console.log(report.summary);
+```
+
+### Integration with Monitoring Services
+
+Integrate with external monitoring services:
+
+```javascript
+const monitor = createPerformanceMonitor({
+  integrations: {
+    newRelic: {
+      apiKey: process.env.NEW_RELIC_API_KEY,
+      accountId: process.env.NEW_RELIC_ACCOUNT_ID
+    },
+    datadog: {
+      apiKey: process.env.DATADOG_API_KEY,
+      site: 'datadoghq.com'
+    }
+  }
+});
+```
+
+## API Reference
+
+### createPerformanceMonitor(options)
+
+Create a new performance monitor instance.
+
+**Parameters:**
+- `options.logLevel` - Logging level ('debug', 'info', 'warn', 'error')
+- `options.sampleRate` - Sampling rate (0.0 to 1.0)
+- `options.thresholds` - Performance thresholds for alerts
+- `options.metrics` - Which metrics to collect
+- `options.onMetrics` - Callback for real-time metrics
+
+**Returns:** Performance monitor instance
+
+### withPerformance(options)
+
+Higher-order component for performance monitoring.
+
+**Parameters:**
+- `options.name` - Component name for tracking
+- `options.threshold` - Performance threshold in ms
+- `options.onRender` - Callback after each render
+
+**Returns:** Wrapped component function
+
+### createMemoryTracker(options)
+
+Create a memory usage tracker.
+
+**Parameters:**
+- `options.interval` - Check interval in ms
+- `options.onWarning` - Callback for memory warnings
+
+### Methods
+
+- `monitor.start()` - Start performance monitoring
+- `monitor.stop()` - Stop performance monitoring
+- `monitor.getMetrics()` - Get current metrics
+- `monitor.reset()` - Reset collected metrics
+
+## Examples
+
+### Full Application Monitoring
+
+```javascript
+import { createPerformanceMonitor, withPerformance } from '@coherent.js/performance';
+import { render } from '@coherent.js/core';
+
+// Create monitor
+const monitor = createPerformanceMonitor({
+  logLevel: 'info',
+  thresholds: {
+    renderTime: 30,
+    memoryUsage: 100
+  },
+  onMetrics: (metrics) => {
+    // Send to analytics service
+    analytics.track('performance_metrics', metrics);
+    
+    // Alert on issues
+    if (metrics.renderTime > 100) {
+      alertService.warn('High render time detected');
+    }
+  }
+});
+
+// Monitor specific components
+const MonitoredDashboard = withPerformance({
+  name: 'Dashboard',
+  threshold: 25
+})(function Dashboard({ data }) {
+  return {
+    div: {
+      className: 'dashboard',
+      children: data.widgets.map(widget => ({
+        div: {
+          className: 'widget',
+          children: [
+            { h3: { text: widget.title } },
+            { p: { text: widget.content } }
+          ]
+        }
+      }))
+    }
+  };
+});
+
+// Start monitoring
+monitor.start();
+
+// Render application
+render(MonitoredDashboard, { data: getDashboardData() });
+```
+
+### Production Performance Dashboard
+
+```javascript
+import { createPerformanceMonitor } from '@coherent.js/performance';
+
+class PerformanceDashboard {
+  constructor() {
+    this.monitor = createPerformanceMonitor({
+      sampleRate: 0.05, // Only 5% in production
+      logLevel: 'warn',
+      thresholds: {
+        renderTime: 100,
+        memoryUsage: 200,
+        eventLoopDelay: 50
+      }
+    });
+    
+    this.metricsHistory = [];
+  }
+  
+  start() {
+    this.monitor.start();
+    
+    // Collect metrics periodically
+    setInterval(() => {
+      const metrics = this.monitor.getMetrics();
+      this.metricsHistory.push({
+        timestamp: Date.now(),
+        ...metrics
+      });
+      
+      // Keep only last 100 entries
+      if (this.metricsHistory.length > 100) {
+        this.metricsHistory.shift();
+      }
+    }, 60000); // Every minute
+  }
+  
+  getReport() {
+    return {
+      avgRenderTime: this.getAverage('renderTime'),
+      peakMemory: this.getPeak('memoryUsage'),
+      metricsHistory: this.metricsHistory
+    };
+  }
+  
+  getAverage(metric) {
+    const values = this.metricsHistory.map(m => m[metric]).filter(Boolean);
+    return values.reduce((sum, val) => sum + val, 0) / values.length;
+  }
+  
+  getPeak(metric) {
+    return Math.max(...this.metricsHistory.map(m => m[metric]).filter(Boolean));
+  }
+}
+
+// Usage
+const dashboard = new PerformanceDashboard();
+dashboard.start();
+
+// Expose report endpoint
+app.get('/performance-report', (req, res) => {
+  res.json(dashboard.getReport());
+});
+```
+
+## Best Practices
+
+### 1. Environment-Specific Configuration
+
+```javascript
+const config = process.env.NODE_ENV === 'production' 
+  ? {
+      sampleRate: 0.1,
+      logLevel: 'warn'
+    }
+  : {
+      sampleRate: 1.0,
+      logLevel: 'debug'
+    };
+
+const monitor = createPerformanceMonitor(config);
+```
+
+### 2. Selective Monitoring
+
+```javascript
+// Only monitor in production or staging
+if (['production', 'staging'].includes(process.env.NODE_ENV)) {
+  monitor.start();
+}
+```
+
+### 3. Resource-Efficient Monitoring
+
+```javascript
+const monitor = createPerformanceMonitor({
+  sampleRate: 0.1,           // Only sample 10%
+  metrics: {                 // Only collect essential metrics
+    renderTime: true,
+    memoryUsage: true
+  },
+  thresholds: {              // Conservative thresholds
+    renderTime: 100,
+    memoryUsage: 500
+  }
+});
+```
+
+## Related Packages
+
+- [@coherent.js/core](../core/README.md) - Core framework
+- [@coherent.js/profiler](../profiler/README.md) - Detailed profiling tools
+- [@coherent.js/devtools](../devtools/README.md) - Development tools
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/performance",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.6",
   "description": "Performance optimization utilities for Coherent.js",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "author": "Coherent.js Team",
   "license": "MIT",
   "peerDependencies": {
-    "@coherent.js/core": "1.0.0-beta.3"
+    "@coherent.js/core": "1.0.0-beta.6"
   },
   "repository": {
     "type": "git",
@@ -35,6 +35,7 @@
     "README.md",
     "types/"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "node build.mjs",
     "clean": "rm -rf dist"

package/types/index.d.ts

@@ -3,164 +3,561 @@
  * @module @coherent.js/performance
  */
 
-// ===== Code Splitting Types =====
+import type { CoherentNode, CoherentComponent, ComponentProps } from '@coherent.js/core';
 
+// ============================================================================
+// Performance Metrics
+// ============================================================================
+
+/**
+ * Comprehensive performance metrics
+ */
+export interface PerformanceMetrics {
+  /** Total render time (ms) */
+  renderTime: number;
+  /** Number of components rendered */
+  componentCount: number;
+  /** Total number of renders */
+  totalRenders: number;
+  /** Average render time */
+  avgRenderTime: number;
+  /** Slowest render information */
+  slowestRender: {
+    component: string;
+    time: number;
+  };
+  /** Memory usage (if available) */
+  memoryUsage?: number;
+  /** Cache hit rate */
+  cacheHitRate?: number;
+  /** Bundle size information */
+  bundleSize?: {
+    total: number;
+    gzipped: number;
+  };
+}
+
+/**
+ * Performance configuration
+ */
+export interface PerformanceConfig {
+  /** Enable performance tracking */
+  enabled?: boolean;
+  /** Sample rate (0-1) for measurement */
+  sampleRate?: number;
+  /** Threshold for slow render warning (ms) */
+  slowThreshold?: number;
+  /** Callback for slow renders */
+  onSlowRender?: (component: string, time: number) => void;
+  /** Enable detailed tracing */
+  tracing?: boolean;
+}
+
+/**
+ * Profiler result for a single render
+ */
+export interface ProfilerResult {
+  /** Component name */
+  componentName: string;
+  /** Total duration (ms) */
+  duration: number;
+  /** Render phase */
+  phase: 'mount' | 'update';
+  /** Actual render duration */
+  actualDuration: number;
+  /** Base duration (without memoization) */
+  baseDuration: number;
+  /** Start time (relative to page load) */
+  startTime: number;
+  /** Commit time */
+  commitTime: number;
+}
+
+/**
+ * Create a performance profiler
+ */
+export function createProfiler(config?: PerformanceConfig): {
+  /** Start a measurement */
+  start(label: string): void;
+  /** End a measurement and return duration */
+  end(label: string): number;
+  /** Measure a synchronous function */
+  measure<T>(label: string, fn: () => T): T;
+  /** Measure an async function */
+  measureAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /** Get current metrics */
+  getMetrics(): PerformanceMetrics;
+  /** Reset all measurements */
+  reset(): void;
+  /** Subscribe to render events */
+  onRender(callback: (result: ProfilerResult) => void): () => void;
+};
+
+/**
+ * HOC to add profiling to a component
+ */
+export function withProfiling<P extends ComponentProps>(
+  component: CoherentComponent<P>,
+  name?: string
+): CoherentComponent<P>;
+
+/**
+ * Memoize with metrics tracking
+ */
+export function memoWithMetrics<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  options?: {
+    name?: string;
+    maxSize?: number;
+  }
+): T & {
+  hits: number;
+  misses: number;
+  hitRate: () => number;
+};
+
+// ============================================================================
+// Code Splitting
+// ============================================================================
+
+/**
+ * Split options for lazy loading
+ */
 export interface SplitOptions {
-  loading?: any;
-  error?: any;
+  /** Loading component */
+  loading?: CoherentNode;
+  /** Error component */
+  error?: CoherentNode;
+  /** Delay before showing loading (ms) */
   delay?: number;
+  /** Timeout for loading (ms) */
   timeout?: number;
 }
 
-export type LazyComponent = () => Promise<any>;
+/**
+ * Lazy component loader type
+ */
+export type LazyComponent = () => Promise<{ default: CoherentComponent }>;
 
+/**
+ * Code splitter class
+ */
 export class CodeSplitter {
   constructor();
-  lazy(loader: LazyComponent, options?: SplitOptions): LazyComponent;
-  split(component: any, chunkName?: string): LazyComponent;
-  preload(loader: LazyComponent): Promise<any>;
+
+  /** Create a lazy-loaded component */
+  lazy(loader: LazyComponent, options?: SplitOptions): CoherentComponent;
+
+  /** Split a component into a separate chunk */
+  split(component: CoherentComponent, chunkName?: string): LazyComponent;
+
+  /** Preload a lazy component */
+  preload(loader: LazyComponent): Promise<CoherentComponent>;
+
+  /** Prefetch a lazy component (lower priority) */
   prefetch(loader: LazyComponent): void;
 }
 
+/**
+ * Create a code splitter instance
+ */
 export function createCodeSplitter(): CodeSplitter;
-export function lazy(loader: LazyComponent, options?: SplitOptions): LazyComponent;
-export function splitComponent(component: any, chunkName?: string): LazyComponent;
 
+/**
+ * Create a lazy-loaded component
+ */
+export function lazy(loader: LazyComponent, options?: SplitOptions): CoherentComponent;
+
+/**
+ * Split a component into a separate chunk
+ */
+export function splitComponent(component: CoherentComponent, chunkName?: string): LazyComponent;
+
+/**
+ * Route-based code splitting configuration
+ */
 export interface RouteConfig {
+  /** Route path */
   path: string;
+  /** Lazy component loader */
   component: LazyComponent;
+  /** Preload on route definition */
   preload?: boolean;
+  /** Prefetch on idle */
   prefetch?: boolean;
 }
 
+/**
+ * Create a route-based code splitter
+ */
 export function createRouteSplitter(routes: RouteConfig[]): {
+  /** Get route configuration */
   getRoute(path: string): RouteConfig | undefined;
+  /** Preload a route's component */
   preloadRoute(path: string): Promise<void>;
+  /** Prefetch a route's component */
   prefetchRoute(path: string): void;
 };
 
-// ===== Cache Types =====
+// ============================================================================
+// Caching
+// ============================================================================
 
-export interface CacheEntry<T = any> {
+/**
+ * Cache entry structure
+ */
+export interface CacheEntry<T = unknown> {
+  /** Cached value */
   value: T;
+  /** Creation timestamp */
   timestamp: number;
+  /** Hit count */
   hits: number;
+  /** Size in bytes (estimated) */
   size?: number;
 }
 
+/**
+ * Cache options
+ */
 export interface CacheOptions {
+  /** Maximum cache size */
   maxSize?: number;
+  /** Maximum age in ms */
   maxAge?: number;
-  onEvict?: (key: string, value: any) => void;
+  /** Callback when entry is evicted */
+  onEvict?: (key: string, value: unknown) => void;
 }
 
-export class LRUCache<K = string, V = any> {
+/**
+ * LRU Cache class
+ */
+export class LRUCache<K = string, V = unknown> {
   constructor(options?: CacheOptions);
+
+  /** Get a cached value */
   get(key: K): V | undefined;
+
+  /** Set a cached value */
   set(key: K, value: V): void;
+
+  /** Check if key exists */
   has(key: K): boolean;
+
+  /** Delete a key */
   delete(key: K): boolean;
+
+  /** Clear all entries */
   clear(): void;
+
+  /** Get cache size */
   size(): number;
+
+  /** Get all keys */
   keys(): K[];
+
+  /** Get all values */
   values(): V[];
+
+  /** Get all entries */
   entries(): Array<[K, V]>;
 }
 
-export class MemoryCache<K = string, V = any> {
+/**
+ * Memory cache with TTL support
+ */
+export class MemoryCache<K = string, V = unknown> {
   constructor(options?: CacheOptions);
+
+  /** Get a cached value */
   get(key: K): V | undefined;
+
+  /** Set a cached value with optional TTL */
   set(key: K, value: V, ttl?: number): void;
+
+  /** Check if key exists */
   has(key: K): boolean;
+
+  /** Delete a key */
   delete(key: K): boolean;
+
+  /** Clear all entries */
   clear(): void;
+
+  /** Get cache size */
   size(): number;
+
+  /** Clean up expired entries */
   cleanup(): void;
 }
 
+/**
+ * Memoization options
+ */
 export interface MemoOptions {
+  /** Maximum cache size */
   maxSize?: number;
-  keyGenerator?: (...args: any[]) => string;
+  /** Custom key generator */
+  keyGenerator?: (...args: unknown[]) => string;
+  /** TTL in ms */
   ttl?: number;
 }
 
+/**
+ * Memoization cache class
+ */
 export class MemoCache {
   constructor(options?: MemoOptions);
-  memoize<T extends (...args: any[]) => any>(fn: T): T;
-  clear(fn?: Function): void;
-  has(fn: Function, args: any[]): boolean;
-  delete(fn: Function, args?: any[]): boolean;
+
+  /** Memoize a function */
+  memoize<T extends (...args: unknown[]) => unknown>(fn: T): T;
+
+  /** Clear cache for a function */
+  clear(fn?: (...args: unknown[]) => unknown): void;
+
+  /** Check if result is cached */
+  has(fn: (...args: unknown[]) => unknown, args: unknown[]): boolean;
+
+  /** Delete cached result */
+  delete(fn: (...args: unknown[]) => unknown, args?: unknown[]): boolean;
 }
 
+/**
+ * Render cache options
+ */
 export interface RenderCacheOptions extends CacheOptions {
-  keyGenerator?: (component: any, props: any) => string;
+  /** Custom key generator */
+  keyGenerator?: (component: CoherentComponent, props: unknown) => string;
 }
 
+/**
+ * Render cache for component output
+ */
 export class RenderCache {
   constructor(options?: RenderCacheOptions);
-  get(component: any, props: any): string | undefined;
-  set(component: any, props: any, html: string): void;
-  clear(component?: any): void;
+
+  /** Get cached render */
+  get(component: CoherentComponent, props: unknown): string | undefined;
+
+  /** Set cached render */
+  set(component: CoherentComponent, props: unknown, html: string): void;
+
+  /** Clear cache for a component */
+  clear(component?: CoherentComponent): void;
+
+  /** Get cache size */
   size(): number;
 }
 
-export function createCache<K = string, V = any>(type: 'lru' | 'memory' | 'memo' | 'render', options?: CacheOptions): LRUCache<K, V> | MemoryCache<K, V> | MemoCache | RenderCache;
-export function memoize<T extends (...args: any[]) => any>(fn: T, options?: MemoOptions): T;
+/**
+ * Create a cache of specified type
+ */
+export function createCache<K = string, V = unknown>(
+  type: 'lru' | 'memory' | 'memo' | 'render',
+  options?: CacheOptions
+): LRUCache<K, V> | MemoryCache<K, V> | MemoCache | RenderCache;
+
+/**
+ * Memoize a function
+ */
+export function memoize<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  options?: MemoOptions
+): T;
 
-// ===== Lazy Loading Types =====
+// ============================================================================
+// Lazy Loading
+// ============================================================================
 
+/**
+ * Lazy load options
+ */
 export interface LazyLoadOptions {
+  /** Intersection threshold (0-1) */
   threshold?: number;
+  /** Root margin for intersection */
   rootMargin?: string;
+  /** Root element for intersection */
   root?: Element | null;
+  /** Callback when loaded */
   onLoad?: () => void;
+  /** Callback on error */
   onError?: (error: Error) => void;
 }
 
+/**
+ * Lazy loader class
+ */
 export class LazyLoader {
   constructor(options?: LazyLoadOptions);
-  observe(element: Element, loader: () => Promise<any>): void;
+
+  /** Start observing an element */
+  observe(element: Element, loader: () => Promise<unknown>): void;
+
+  /** Stop observing an element */
   unobserve(element: Element): void;
+
+  /** Disconnect all observers */
   disconnect(): void;
+
+  /** Load all observed elements */
   loadAll(): Promise<void[]>;
 }
 
+/**
+ * Image lazy load options
+ */
 export interface ImageLazyLoadOptions extends LazyLoadOptions {
+  /** Placeholder image URL */
   placeholder?: string;
+  /** Blur data URL for preview */
   blurDataURL?: string;
+  /** Enable fade-in animation */
   fadeIn?: boolean;
+  /** Fade-in duration (ms) */
   fadeInDuration?: number;
 }
 
+/**
+ * Image lazy loader class
+ */
 export class ImageLazyLoader extends LazyLoader {
   constructor(options?: ImageLazyLoadOptions);
+
+  /** Lazy load an image */
   lazyImage(element: HTMLImageElement, src: string, options?: ImageLazyLoadOptions): void;
 }
 
+/**
+ * Preload options
+ */
 export interface PreloadOptions {
+  /** Resource type */
   as?: 'script' | 'style' | 'image' | 'font' | 'fetch';
+  /** Cross-origin setting */
   crossOrigin?: 'anonymous' | 'use-credentials';
+  /** MIME type */
   type?: string;
+  /** Media query */
   media?: string;
 }
 
+/**
+ * Resource preloader class
+ */
 export class ResourcePreloader {
   constructor();
+
+  /** Preload a resource (high priority) */
   preload(url: string, options?: PreloadOptions): void;
+
+  /** Prefetch a resource (low priority) */
   prefetch(url: string): void;
+
+  /** Preconnect to a domain */
   preconnect(url: string, crossOrigin?: boolean): void;
+
+  /** DNS prefetch for a domain */
   dnsPrefetch(url: string): void;
+
+  /** Check if resource is preloaded */
   hasPreloaded(url: string): boolean;
 }
 
+/**
+ * Create a lazy loader
+ */
 export function createLazyLoader(options?: LazyLoadOptions): LazyLoader;
-export function lazyImage(element: HTMLImageElement | string, src: string, options?: ImageLazyLoadOptions): void;
 
+/**
+ * Lazy load an image
+ */
+export function lazyImage(
+  element: HTMLImageElement | string,
+  src: string,
+  options?: ImageLazyLoadOptions
+): void;
+
+/**
+ * Progressive image loading options
+ */
 export interface ProgressiveImageOptions {
+  /** Low quality image source */
   lowQualitySrc: string;
+  /** High quality image source */
   highQualitySrc: string;
+  /** Placeholder while loading */
   placeholder?: string;
+  /** Fade-in duration (ms) */
   fadeInDuration?: number;
 }
 
-export function progressiveImage(element: HTMLImageElement | string, options: ProgressiveImageOptions): Promise<void>;
+/**
+ * Load an image progressively (low quality first)
+ */
+export function progressiveImage(
+  element: HTMLImageElement | string,
+  options: ProgressiveImageOptions
+): Promise<void>;
+
+// ============================================================================
+// Bundle Optimization
+// ============================================================================
+
+/**
+ * Bundle analysis result
+ */
+export interface BundleAnalysis {
+  /** Total size in bytes */
+  totalSize: number;
+  /** Gzipped size */
+  gzippedSize: number;
+  /** Modules in bundle */
+  modules: Array<{
+    name: string;
+    size: number;
+    gzippedSize: number;
+  }>;
+  /** Duplicate modules */
+  duplicates: Array<{
+    name: string;
+    count: number;
+    totalSize: number;
+  }>;
+}
+
+/**
+ * Tree shaking result
+ */
+export interface TreeShakeResult {
+  /** Original size */
+  originalSize: number;
+  /** Size after tree shaking */
+  shakenSize: number;
+  /** Removed exports */
+  removed: string[];
+  /** Kept exports */
+  kept: string[];
+}
+
+/**
+ * Bundle optimizer class
+ */
+export class BundleOptimizer {
+  /** Analyze a bundle */
+  analyze(bundle: unknown): BundleAnalysis;
+
+  /** Optimize a bundle */
+  optimize(bundle: unknown): unknown;
+
+  /** Split bundle into chunks */
+  splitChunks(bundle: unknown): unknown[];
+
+  /** Tree shake a bundle */
+  treeshake(bundle: unknown): TreeShakeResult;
+}
+
+/**
+ * Global bundle optimizer instance
+ */
+export const bundleOptimizer: BundleOptimizer;