mastercontroller 1.2.11 → 1.2.13

package/ssr/PerformanceMonitor.js

@@ -0,0 +1,233 @@
+/**
+ * PerformanceMonitor - Track and report SSR performance metrics
+ * Version: 1.0.0
+ */
+
+const { MasterControllerError } = require('../MasterErrorHandler');
+
+const isDevelopment = process.env.NODE_ENV !== 'production' && process.env.master === 'development';
+
+// Performance thresholds (milliseconds)
+const THRESHOLDS = {
+  SLOW_RENDER: 100,      // Warn if component takes >100ms to render
+  VERY_SLOW_RENDER: 500, // Error if component takes >500ms
+  TOTAL_SSR: 3000        // Warn if total SSR time exceeds 3s
+};
+
+class PerformanceMonitor {
+  constructor() {
+    this.metrics = {
+      totalStartTime: null,
+      totalEndTime: null,
+      components: new Map(),
+      slowComponents: [],
+      totalRenderTime: 0,
+      componentCount: 0
+    };
+
+    this.enabled = isDevelopment || process.env.MC_PERF_MONITOR === 'true';
+  }
+
+  /**
+   * Start monitoring SSR session
+   */
+  startSession() {
+    if (!this.enabled) return;
+    this.metrics.totalStartTime = Date.now();
+    this.metrics.components.clear();
+    this.metrics.slowComponents = [];
+    this.metrics.totalRenderTime = 0;
+    this.metrics.componentCount = 0;
+  }
+
+  /**
+   * Record component render time
+   */
+  recordComponent(componentName, renderTime, filePath = null) {
+    if (!this.enabled) return;
+
+    this.metrics.componentCount++;
+    this.metrics.totalRenderTime += renderTime;
+
+    // Store component metrics
+    if (!this.metrics.components.has(componentName)) {
+      this.metrics.components.set(componentName, {
+        name: componentName,
+        renderTime,
+        renderCount: 1,
+        filePath
+      });
+    } else {
+      const existing = this.metrics.components.get(componentName);
+      existing.renderTime += renderTime;
+      existing.renderCount++;
+    }
+
+    // Track slow components
+    if (renderTime > THRESHOLDS.SLOW_RENDER) {
+      this.metrics.slowComponents.push({
+        name: componentName,
+        renderTime,
+        filePath,
+        severity: renderTime > THRESHOLDS.VERY_SLOW_RENDER ? 'error' : 'warning'
+      });
+
+      // Warn immediately about slow renders in development
+      if (isDevelopment) {
+        const severity = renderTime > THRESHOLDS.VERY_SLOW_RENDER ? 'error' : 'warning';
+        const message = renderTime > THRESHOLDS.VERY_SLOW_RENDER
+          ? `Component rendering VERY slowly (${renderTime}ms > ${THRESHOLDS.VERY_SLOW_RENDER}ms threshold)`
+          : `Component rendering slowly (${renderTime}ms > ${THRESHOLDS.SLOW_RENDER}ms threshold)`;
+
+        const error = new MasterControllerError({
+          code: 'MC_ERR_SLOW_RENDER',
+          message,
+          component: componentName,
+          file: filePath,
+          details: this._getSuggestions(componentName, renderTime)
+        });
+
+        if (severity === 'error') {
+          console.error(error.format());
+        } else {
+          console.warn(error.format());
+        }
+      }
+    }
+  }
+
+  /**
+   * End monitoring session and generate report
+   */
+  endSession() {
+    if (!this.enabled) return null;
+
+    this.metrics.totalEndTime = Date.now();
+    const totalTime = this.metrics.totalEndTime - this.metrics.totalStartTime;
+
+    // Warn about slow total SSR time
+    if (totalTime > THRESHOLDS.TOTAL_SSR && isDevelopment) {
+      console.warn(
+        new MasterControllerError({
+          code: 'MC_ERR_SLOW_RENDER',
+          message: `Total SSR time exceeded threshold (${totalTime}ms > ${THRESHOLDS.TOTAL_SSR}ms)`,
+          details: `Rendered ${this.metrics.componentCount} components. Consider optimizing slow components or using lazy loading.`
+        }).format()
+      );
+    }
+
+    const report = this._generateReport(totalTime);
+
+    // Print report in development
+    if (isDevelopment) {
+      this._printReport(report);
+    }
+
+    return report;
+  }
+
+  /**
+   * Generate performance report
+   */
+  _generateReport(totalTime) {
+    // Sort components by render time
+    const sortedComponents = Array.from(this.metrics.components.values())
+      .sort((a, b) => b.renderTime - a.renderTime);
+
+    return {
+      totalTime,
+      componentCount: this.metrics.componentCount,
+      averageRenderTime: this.metrics.componentCount > 0
+        ? Math.round(this.metrics.totalRenderTime / this.metrics.componentCount)
+        : 0,
+      slowComponents: this.metrics.slowComponents,
+      topComponents: sortedComponents.slice(0, 10),
+      summary: {
+        fast: sortedComponents.filter(c => c.renderTime <= THRESHOLDS.SLOW_RENDER).length,
+        slow: sortedComponents.filter(c => c.renderTime > THRESHOLDS.SLOW_RENDER && c.renderTime <= THRESHOLDS.VERY_SLOW_RENDER).length,
+        verySlow: sortedComponents.filter(c => c.renderTime > THRESHOLDS.VERY_SLOW_RENDER).length
+      }
+    };
+  }
+
+  /**
+   * Print formatted performance report
+   */
+  _printReport(report) {
+    console.log('\n' + '═'.repeat(80));
+    console.log('🚀 MasterController SSR Performance Report');
+    console.log('═'.repeat(80));
+    console.log(`Total SSR Time: ${report.totalTime}ms`);
+    console.log(`Components Rendered: ${report.componentCount}`);
+    console.log(`Average Render Time: ${report.averageRenderTime}ms`);
+    console.log(`\nPerformance Summary:`);
+    console.log(`  ✅ Fast (<${THRESHOLDS.SLOW_RENDER}ms): ${report.summary.fast}`);
+    console.log(`  ⚠️  Slow (${THRESHOLDS.SLOW_RENDER}-${THRESHOLDS.VERY_SLOW_RENDER}ms): ${report.summary.slow}`);
+    console.log(`  ❌ Very Slow (>${THRESHOLDS.VERY_SLOW_RENDER}ms): ${report.summary.verySlow}`);
+
+    if (report.topComponents.length > 0) {
+      console.log(`\nTop ${Math.min(10, report.topComponents.length)} Slowest Components:`);
+      report.topComponents.forEach((comp, index) => {
+        const icon = comp.renderTime > THRESHOLDS.VERY_SLOW_RENDER ? '❌' :
+                     comp.renderTime > THRESHOLDS.SLOW_RENDER ? '⚠️' : '✅';
+        console.log(`  ${icon} ${index + 1}. ${comp.name}: ${comp.renderTime}ms (${comp.renderCount} render${comp.renderCount > 1 ? 's' : ''})`);
+      });
+    }
+
+    console.log('═'.repeat(80) + '\n');
+  }
+
+  /**
+   * Get optimization suggestions for slow components
+   */
+  _getSuggestions(componentName, renderTime) {
+    const suggestions = [
+      'Reduce the amount of data rendered initially',
+      'Use pagination or virtual scrolling for large lists',
+      'Move expensive calculations to data fetching layer',
+      'Consider lazy loading or code splitting',
+      'Cache computed values',
+      'Optimize database queries if data-fetching is involved'
+    ];
+
+    let details = `\nOptimization Suggestions:\n`;
+    suggestions.forEach((suggestion, index) => {
+      details += `${index + 1}. ${suggestion}\n`;
+    });
+
+    return details;
+  }
+
+  /**
+   * Get current metrics snapshot
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      currentTime: Date.now() - (this.metrics.totalStartTime || Date.now())
+    };
+  }
+
+  /**
+   * Reset metrics
+   */
+  reset() {
+    this.metrics = {
+      totalStartTime: null,
+      totalEndTime: null,
+      components: new Map(),
+      slowComponents: [],
+      totalRenderTime: 0,
+      componentCount: 0
+    };
+  }
+}
+
+// Singleton instance
+const monitor = new PerformanceMonitor();
+
+module.exports = {
+  PerformanceMonitor,
+  monitor,
+  THRESHOLDS
+};

package/ssr/SSRErrorHandler.js

@@ -0,0 +1,273 @@
+/**
+ * SSRErrorHandler - Server-side rendering error handling
+ * Handles component render failures with graceful fallbacks
+ * Version: 1.0.0
+ */
+
+const { MasterControllerError } = require('../MasterErrorHandler');
+
+const isDevelopment = process.env.NODE_ENV !== 'production' && process.env.master === 'development';
+
+/**
+ * Render error component for development mode
+ */
+function renderErrorComponent(options = {}) {
+  const {
+    component,
+    error,
+    stack,
+    file,
+    line,
+    details
+  } = options;
+
+  const errorObj = new MasterControllerError({
+    code: 'MC_ERR_COMPONENT_RENDER_FAILED',
+    message: error || 'Component failed to render on server',
+    component,
+    file,
+    line,
+    details: details || stack,
+    originalError: options.originalError
+  });
+
+  // Return full HTML error page in development
+  return errorObj.toHTML();
+}
+
+/**
+ * Render fallback component for production mode
+ */
+function renderFallback(componentName, options = {}) {
+  const { showSkeleton = true, customMessage } = options;
+
+  if (showSkeleton) {
+    return `
+      <div class="mc-fallback" data-component="${componentName}" style="
+        padding: 20px;
+        background: #f9fafb;
+        border-radius: 8px;
+        border: 1px dashed #d1d5db;
+        min-height: 100px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: #6b7280;
+      ">
+        <div class="mc-fallback-content">
+          ${customMessage || ''}
+          <div class="skeleton-loader" style="
+            width: 100%;
+            height: 20px;
+            background: linear-gradient(90deg, #e5e7eb 25%, #f3f4f6 50%, #e5e7eb 75%);
+            background-size: 200% 100%;
+            animation: skeleton-loading 1.5s ease-in-out infinite;
+            border-radius: 4px;
+          "></div>
+        </div>
+        <style>
+          @keyframes skeleton-loading {
+            0% { background-position: 200% 0; }
+            100% { background-position: -200% 0; }
+          }
+        </style>
+      </div>
+    `;
+  }
+
+  // Minimal fallback - just an empty div
+  return `<div class="mc-fallback" data-component="${componentName}"></div>`;
+}
+
+/**
+ * Safe component render wrapper
+ * Catches errors and returns either error page (dev) or fallback (prod)
+ */
+function safeRenderComponent(component, componentName, filePath) {
+  try {
+    // Try tempRender first
+    if (typeof component.tempRender === 'function') {
+      const startTime = Date.now();
+      const result = component.tempRender();
+      const renderTime = Date.now() - startTime;
+
+      // Warn about slow renders in development
+      if (isDevelopment && renderTime > 100) {
+        console.warn(
+          new MasterControllerError({
+            code: 'MC_ERR_SLOW_RENDER',
+            message: `Component rendering slowly on server (${renderTime}ms)`,
+            component: componentName,
+            file: filePath,
+            details: `Render time exceeded 100ms threshold. Consider optimizing this component.`
+          }).format()
+        );
+      }
+
+      return { success: true, html: result, renderTime };
+    }
+
+    // Fallback to connectedCallback
+    if (typeof component.connectedCallback === 'function') {
+      const startTime = Date.now();
+      component.connectedCallback();
+      const renderTime = Date.now() - startTime;
+
+      // Get the rendered HTML
+      const html = component.innerHTML || '';
+      return { success: true, html, renderTime };
+    }
+
+    // No render method found
+    throw new Error('No tempRender() or connectedCallback() method found');
+
+  } catch (error) {
+    console.error(
+      new MasterControllerError({
+        code: 'MC_ERR_COMPONENT_RENDER_FAILED',
+        message: `Failed to render component: ${error.message}`,
+        component: componentName,
+        file: filePath,
+        originalError: error
+      }).format()
+    );
+
+    if (isDevelopment) {
+      return {
+        success: false,
+        html: renderErrorComponent({
+          component: componentName,
+          error: error.message,
+          stack: error.stack,
+          file: filePath,
+          originalError: error
+        }),
+        renderTime: 0
+      };
+    } else {
+      // Log error for monitoring
+      logProductionError(error, componentName, filePath);
+
+      return {
+        success: false,
+        html: renderFallback(componentName, { showSkeleton: true }),
+        renderTime: 0
+      };
+    }
+  }
+}
+
+/**
+ * Log production errors for monitoring
+ */
+function logProductionError(error, component, file) {
+  const errorData = {
+    timestamp: new Date().toISOString(),
+    component,
+    file,
+    message: error.message,
+    stack: error.stack,
+    environment: 'production'
+  };
+
+  // Log to console (can be captured by monitoring services)
+  console.error('[MasterController Production Error]', JSON.stringify(errorData, null, 2));
+
+  // Hook for external logging services (Sentry, LogRocket, etc.)
+  if (global.masterControllerErrorHook) {
+    try {
+      global.masterControllerErrorHook(errorData);
+    } catch (hookError) {
+      console.error('[MasterController] Error hook failed:', hookError.message);
+    }
+  }
+}
+
+/**
+ * Wrap connectedCallback with try-catch
+ */
+function wrapConnectedCallback(element, componentName, filePath) {
+  if (!element || typeof element.connectedCallback !== 'function') {
+    return;
+  }
+
+  const originalCallback = element.connectedCallback;
+
+  element.connectedCallback = function(...args) {
+    try {
+      return originalCallback.apply(this, args);
+    } catch (error) {
+      console.error(
+        new MasterControllerError({
+          code: 'MC_ERR_COMPONENT_RENDER_FAILED',
+          message: `connectedCallback failed: ${error.message}`,
+          component: componentName,
+          file: filePath,
+          originalError: error
+        }).format()
+      );
+
+      if (isDevelopment) {
+        this.innerHTML = renderErrorComponent({
+          component: componentName,
+          error: error.message,
+          stack: error.stack,
+          file: filePath,
+          originalError: error
+        });
+      } else {
+        logProductionError(error, componentName, filePath);
+        this.innerHTML = renderFallback(componentName);
+      }
+    }
+  };
+}
+
+/**
+ * Check if component has required SSR methods
+ */
+function validateSSRComponent(componentClass, componentName, filePath) {
+  const warnings = [];
+
+  // Check for tempRender method
+  if (!componentClass.prototype.tempRender && !componentClass.prototype.connectedCallback) {
+    warnings.push(
+      new MasterControllerError({
+        code: 'MC_ERR_TEMPRENDER_MISSING',
+        message: 'Component missing tempRender() method for SSR',
+        component: componentName,
+        file: filePath,
+        details: `Add a tempRender() method to enable server-side rendering:\n\n  tempRender() {\n    return \`<div>Your HTML here</div>\`;\n  }`
+      })
+    );
+  }
+
+  // Warn if only render() exists (client-only)
+  if (componentClass.prototype.render && !componentClass.prototype.tempRender) {
+    warnings.push(
+      new MasterControllerError({
+        code: 'MC_ERR_TEMPRENDER_MISSING',
+        message: 'Component has render() but no tempRender() - will not SSR',
+        component: componentName,
+        file: filePath,
+        details: 'For SSR, rename render() to tempRender() or add a separate tempRender() method'
+      })
+    );
+  }
+
+  if (warnings.length > 0 && isDevelopment) {
+    warnings.forEach(warning => console.warn(warning.format()));
+  }
+
+  return warnings.length === 0;
+}
+
+module.exports = {
+  renderErrorComponent,
+  renderFallback,
+  safeRenderComponent,
+  wrapConnectedCallback,
+  validateSSRComponent,
+  logProductionError,
+  isDevelopment
+};

package/ssr/hydration-client.js

@@ -0,0 +1,93 @@
+/**
+ * MasterController Client-Side Hydration Runtime
+ * Handles error boundaries and hydration mismatch detection
+ * Version: 2.0.0
+ */
+
+// Import error boundary
+import { ErrorBoundary } from './ErrorBoundary.js';
+
+// Import hydration mismatch detection
+const isDevelopment = window.location.hostname === 'localhost' ||
+                     window.location.hostname === '127.0.0.1';
+
+if (isDevelopment && typeof require !== 'undefined') {
+  try {
+    const { enableHydrationMismatchDetection } = require('./HydrationMismatch.js');
+    enableHydrationMismatchDetection({
+      verbose: localStorage.getItem('mc-hydration-debug') === 'true',
+      delay: 1000
+    });
+  } catch (e) {
+    console.warn('[MasterController] Could not load hydration mismatch detection:', e.message);
+  }
+}
+
+// Auto-wrap app root with error boundary if not already wrapped
+document.addEventListener('DOMContentLoaded', () => {
+  const appRoot = document.querySelector('root-layout') || document.body;
+
+  // Check if already wrapped
+  if (!appRoot.closest('error-boundary')) {
+    // Create error boundary wrapper
+    const boundary = document.createElement('error-boundary');
+
+    // Set development mode
+    if (isDevelopment) {
+      boundary.setAttribute('dev-mode', '');
+    }
+
+    // Configure custom error handler
+    boundary.onError = (errorInfo) => {
+      console.error('[App Error]', errorInfo);
+
+      // Send to monitoring service if configured
+      if (window.masterControllerErrorReporter) {
+        window.masterControllerErrorReporter(errorInfo);
+      }
+    };
+
+    // Wrap content
+    const parent = appRoot.parentNode;
+    parent.insertBefore(boundary, appRoot);
+    boundary.appendChild(appRoot);
+  }
+});
+
+// Global error reporter hook
+window.masterControllerErrorReporter = window.masterControllerErrorReporter || function(errorData) {
+  console.log('[MasterController] Error reported:', errorData);
+
+  // Example: Send to your monitoring service
+  // fetch('/api/errors', {
+  //   method: 'POST',
+  //   headers: { 'Content-Type': 'application/json' },
+  //   body: JSON.stringify(errorData)
+  // });
+
+  // Example: Send to Sentry
+  // if (window.Sentry) {
+  //   Sentry.captureException(new Error(errorData.message), {
+  //     extra: errorData
+  //   });
+  // }
+};
+
+// Log successful hydration
+if (isDevelopment) {
+  window.addEventListener('load', () => {
+    const ssrElements = document.querySelectorAll('[data-ssr]');
+    if (ssrElements.length > 0) {
+      console.log(
+        `%c✓ MasterController Hydration Complete`,
+        'color: #10b981; font-weight: bold; font-size: 14px;'
+      );
+      console.log(`  ${ssrElements.length} server-rendered components hydrated`);
+    }
+  });
+}
+
+// Export for manual use
+export {
+  ErrorBoundary
+};