meno-core 1.0.0

package/lib/server/ssrRenderer.ts

@@ -0,0 +1,878 @@
+/**
+ * Server-Side Rendering (SSR) Module
+ * Converts JSON component structures to HTML strings for SEO-friendly initial page loads
+ */
+
+import type { ComponentNode, ComponentDefinition, JSONPage } from '../shared/types';
+import type { ResponsiveStyleObject, StyleObject } from '../shared/types';
+import type { BreakpointConfig } from '../shared/breakpoints';
+import { evaluateTemplate, processStructure, isResponsiveStyle } from '../client/templateEngine';
+import { resolvePropsFromDefinition } from '../shared/propResolver';
+import { generateColorVariablesCSS, generateThemeColorVariablesCSS } from './cssGenerator';
+import { loadBreakpointConfig, loadResponsiveScalesConfig, loadI18nConfig, loadIconsConfig } from './jsonLoader';
+import type { I18nConfig } from '../shared/types/components';
+import { extractLocaleFromPath, DEFAULT_I18N_CONFIG, resolveI18nValue, buildLocalizedPath } from '../shared/i18n';
+import { NODE_TYPE } from '../shared/constants';
+import { isComponentNode, isHtmlNode, isObjectLinkNode, isEmbedNode, isLocaleListNode } from '../shared/nodeUtils';
+import { extractAttributesFromNode } from '../shared/attributeNodeUtils';
+import { SSRRegistry } from '../shared/registry/SSRRegistry';
+import { generateFontCSS } from '../shared/fontLoader';
+import { colorService } from './services/ColorService';
+import { mergeResponsiveStyles } from '../shared/responsiveStyleUtils';
+import DOMPurify from 'isomorphic-dompurify';
+import { generateUtilityCSS, extractUtilityClassesFromHTML } from '../shared/cssGeneration';
+import { responsiveStylesToClasses } from '../shared/utilityClassMapper';
+import { validateStyleCoverage, printMissingStyleWarnings } from './validateStyleCoverage';
+import type { SlugMap } from '../shared/slugTranslator';
+import { buildSlugIndex, getLocaleLinks, translatePath } from '../shared/slugTranslator';
+import { formHandlerScript, needsFormHandler } from '../client/scripts/formHandler';
+
+/**
+ * CMS context for template interpolation
+ */
+export interface CMSContext {
+  cms?: Record<string, unknown>;
+}
+
+/**
+ * SSR rendering context - passed through the render chain
+ */
+interface SSRContext {
+  locale?: string;
+  i18nConfig?: I18nConfig;
+  slugMappings?: SlugMap[];
+  pagePath?: string;
+  breakpoints?: BreakpointConfig;
+  viewportWidth?: number;
+  cmsContext?: CMSContext;
+}
+
+/**
+ * Component registry for SSR (shared between requests)
+ * Uses the shared SSRRegistry for consistency
+ */
+const ssrComponentRegistry = new SSRRegistry();
+
+/**
+ * Escape HTML special characters to prevent XSS
+ */
+function escapeHtml(unsafe: string): string {
+  return unsafe
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Process CMS template strings like {{cms.title}} or {{cms.author}}
+ * Replaces template expressions with values from CMS item
+ */
+function processCMSTemplate(template: string, cmsItem: Record<string, unknown>): string {
+  return template.replace(/\{\{cms\.([^}]+)\}\}/g, (match, fieldPath) => {
+    // Support nested paths like cms.author.name
+    const parts = fieldPath.trim().split('.');
+    let value: unknown = cmsItem;
+
+    for (const part of parts) {
+      if (value && typeof value === 'object' && part in value) {
+        value = (value as Record<string, unknown>)[part];
+      } else {
+        // Field not found, return empty string
+        return '';
+      }
+    }
+
+    // Return string representation
+    if (value === null || value === undefined) {
+      return '';
+    }
+    return String(value);
+  });
+}
+
+/**
+ * Process CMS templates in props object
+ * Recursively processes all string values in props
+ */
+function processCMSPropsTemplate(
+  props: Record<string, unknown>,
+  cmsItem: Record<string, unknown>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value === 'string' && value.includes('{{cms.')) {
+      result[key] = processCMSTemplate(value, cmsItem);
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively process nested objects (but not arrays or null)
+      result[key] = processCMSPropsTemplate(value as Record<string, unknown>, cmsItem);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build HTML string from component node (server-side)
+ */
+async function buildComponentHTML(
+  node: ComponentNode | ComponentNode[] | string | number | null | undefined,
+  globalComponents: Record<string, ComponentDefinition> = {},
+  pageComponents: Record<string, ComponentDefinition> = {},
+  locale?: string,
+  i18nConfig?: I18nConfig,
+  slugMappings?: SlugMap[],
+  pagePath?: string,
+  cmsContext?: CMSContext
+): Promise<{ html: string }> {
+  if (!node) return { html: '' };
+
+  // Register components for this render
+  ssrComponentRegistry.merge(globalComponents);
+  ssrComponentRegistry.merge(pageComponents);
+
+  // Load breakpoint config for responsive style resolution
+  const breakpoints = await loadBreakpointConfig();
+
+  // Render using desktop viewport (1920px) - same as editor system
+  const SSR_VIEWPORT_WIDTH = 1920;
+
+  // Build SSR context
+  const ctx: SSRContext = {
+    locale,
+    i18nConfig,
+    slugMappings,
+    pagePath,
+    breakpoints,
+    viewportWidth: SSR_VIEWPORT_WIDTH,
+    cmsContext,
+  };
+
+  const html = renderNode(node, ctx);
+
+  return { html };
+}
+
+function renderNode(
+  node: ComponentNode | ComponentNode[] | string | number | null | undefined,
+  ctx: SSRContext
+): string {
+  const { breakpoints, viewportWidth, locale, i18nConfig, slugMappings, pagePath } = ctx;
+
+  if (node === null || node === undefined) return '';
+
+  if (typeof node === 'string' || typeof node === 'number') {
+    let text = String(node);
+    // Process CMS template strings like {{cms.title}}
+    if (ctx.cmsContext?.cms && text.includes('{{cms.')) {
+      text = processCMSTemplate(text, ctx.cmsContext.cms);
+    }
+    return escapeHtml(text);
+  }
+
+  if (Array.isArray(node)) {
+    return node.map(child => renderNode(child, ctx)).join('');
+  }
+
+  if (typeof node !== 'object') return '';
+
+  const nodeType = 'type' in node ? node.type : undefined;
+  const nodeStyle = ('style' in node) ? node.style : undefined;
+  const children = ('children' in node) ? (node.children || []) : [];
+
+  // Handle embed nodes - render custom HTML content
+  if (isEmbedNode(node)) {
+    // Sanitize HTML with allowlist for SVG and common elements (same as client)
+    const sanitizedHtml = DOMPurify.sanitize(node.html, {
+      ALLOWED_TAGS: ['svg', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'g', 'text', 'tspan', 'image', 'defs', 'use', 'linearGradient', 'radialGradient', 'stop', 'clipPath', 'mask', 'pattern', 'marker', 'symbol', 'a', 'div', 'span', 'p', 'br', 'button', 'img', 'iframe', 'video', 'audio', 'source', 'canvas'],
+      ALLOWED_ATTR: ['class', 'id', 'style', 'width', 'height', 'viewBox', 'xmlns', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray', 'stroke-dashoffset', 'd', 'cx', 'cy', 'r', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'points', 'href', 'src', 'alt', 'target', 'rel', 'data-*', 'aria-*', 'transform', 'opacity', 'fill-opacity', 'stroke-opacity', 'font-size', 'font-family', 'text-anchor', 'dominant-baseline', 'offset', 'stop-color', 'stop-opacity'],
+      KEEP_CONTENT: true
+    });
+
+    // Extract attributes from node
+    const nodeAttributes = extractAttributesFromNode(node);
+    const attrs = buildAttributes(nodeAttributes);
+
+    // Convert styles to utility classes
+    let classAttr = '';
+    if (nodeStyle) {
+      const utilityClasses = responsiveStylesToClasses(nodeStyle);
+      if (utilityClasses.length > 0) {
+        classAttr = ` class="${escapeHtml(utilityClasses.join(' '))}"`;
+      }
+    }
+
+    // Wrap sanitized content in a div with utility classes and attributes
+    return `<div${classAttr}${attrs}>${sanitizedHtml}</div>`;
+  }
+
+  // Handle object link nodes (render as <a> tag in SSR)
+  if (isObjectLinkNode(node)) {
+    let href = node.href || '#';
+
+    // Localize internal page links to current locale
+    if (href.startsWith('/') && !href.startsWith('//') && locale && i18nConfig) {
+      if (slugMappings) {
+        const slugIndex = buildSlugIndex(slugMappings);
+        href = translatePath(href, locale, i18nConfig.defaultLocale, i18nConfig.defaultLocale, slugIndex);
+      } else if (locale !== i18nConfig.defaultLocale) {
+        href = buildLocalizedPath(href, locale);
+      }
+    }
+
+    // Extract attributes from node
+    const nodeAttributes = extractAttributesFromNode(node);
+    const attrs = buildAttributes(nodeAttributes, ['href']);
+
+    // Convert styles to utility classes and add olink base class
+    const utilityClasses = nodeStyle ? responsiveStylesToClasses(nodeStyle) : [];
+    const allClasses = ['olink', ...utilityClasses];
+    const classAttr = ` class="${escapeHtml(allClasses.join(' '))}"`;
+
+    const childrenHTML = Array.isArray(children)
+      ? children.map((child) => renderNode(child, ctx)).join('')
+      : renderNode(children, ctx);
+
+    return `<a href="${escapeHtml(String(href))}"${classAttr}${attrs}>${childrenHTML}</a>`;
+  }
+
+  // Handle locale-list node type (render locale switcher links)
+  if (isLocaleListNode(node)) {
+    if (slugMappings && pagePath && i18nConfig && locale) {
+      const slugIndex = buildSlugIndex(slugMappings);
+      const localeLinks = getLocaleLinks(pagePath, locale, i18nConfig, slugIndex);
+      const showCurrent = node.showCurrent !== false;
+      const showSeparator = node.showSeparator !== false;
+      const showFlag = node.showFlag !== false;
+
+      // Build a map of locale code to icon for quick lookup
+      const localeIconMap = new Map<string, string>();
+      for (const localeConfig of i18nConfig.locales) {
+        if (localeConfig.icon) {
+          localeIconMap.set(localeConfig.code, localeConfig.icon);
+        }
+      }
+
+      // Convert container styles to utility classes
+      let containerClasses: string[] = [];
+      if (nodeStyle) {
+        containerClasses = responsiveStylesToClasses(nodeStyle);
+      }
+      const containerClassAttr = containerClasses.length > 0
+        ? ` class="${escapeHtml(containerClasses.join(' '))}"`
+        : '';
+
+      // Convert item styles to utility classes
+      let itemClasses: string[] = [];
+      if (node.itemStyle) {
+        itemClasses = responsiveStylesToClasses(node.itemStyle);
+      }
+      const itemClassAttr = itemClasses.length > 0
+        ? ` class="${escapeHtml(itemClasses.join(' '))}"`
+        : '';
+
+      // Convert active item styles to utility classes
+      let activeItemClasses: string[] = [];
+      if (node.activeItemStyle) {
+        activeItemClasses = responsiveStylesToClasses(node.activeItemStyle);
+      }
+
+      // Convert separator styles to utility classes
+      let separatorClasses: string[] = [];
+      if (node.separatorStyle) {
+        separatorClasses = responsiveStylesToClasses(node.separatorStyle);
+      }
+      const separatorClassAttr = separatorClasses.length > 0
+        ? ` class="${escapeHtml(separatorClasses.join(' '))}"`
+        : '';
+
+      // Convert flag styles to utility classes
+      let flagClasses: string[] = [];
+      if (node.flagStyle) {
+        flagClasses = responsiveStylesToClasses(node.flagStyle);
+      }
+      const flagClassAttr = flagClasses.length > 0
+        ? ` class="${escapeHtml(flagClasses.join(' '))}"`
+        : '';
+
+      // Current item gets both itemStyle + activeItemStyle (additive/override)
+      const currentItemClasses = [...itemClasses, ...activeItemClasses];
+      const currentItemClassAttr = currentItemClasses.length > 0
+        ? ` class="${escapeHtml(currentItemClasses.join(' '))}"`
+        : '';
+
+      // Build links HTML
+      const links: string[] = [];
+      for (const link of localeLinks) {
+        if (!showCurrent && link.isCurrent) continue;
+        const currentAttr = link.isCurrent ? ' data-current="true"' : ' data-current="false"';
+        const classAttr = link.isCurrent ? currentItemClassAttr : itemClassAttr;
+        const hreflangAttr = ` hreflang="${escapeHtml(link.langTag)}"`;
+
+        // Build link content with optional flag icon + text in div
+        let linkContent = '';
+        const localeIcon = localeIconMap.get(link.locale);
+        if (showFlag && localeIcon) {
+          linkContent += `<img src="${escapeHtml(localeIcon)}" alt="${escapeHtml(link.nativeName)} flag"${flagClassAttr}>`;
+        }
+        linkContent += `<div>${escapeHtml(link.nativeName)}</div>`;
+
+        links.push(`<a href="${escapeHtml(link.path)}"${hreflangAttr}${currentAttr} data-locale="${escapeHtml(link.locale)}"${classAttr}>${linkContent}</a>`);
+      }
+
+      // Join links with separator (empty span styled via separatorStyle) or concatenate directly
+      const linksHTML = showSeparator
+        ? links.join(`<span${separatorClassAttr}></span>`)
+        : links.join('');
+
+      // Extract attributes from node
+      const nodeAttributes = extractAttributesFromNode(node);
+      const attrs = buildAttributes(nodeAttributes);
+
+      return `<div data-locale-list="true"${containerClassAttr}${attrs}>${linksHTML}</div>`;
+    }
+    // If context is missing, return empty div
+    return '<div data-locale-list="true"></div>';
+  }
+
+  // Extract tag or component name based on node type
+  let tag = isHtmlNode(node) ? node.tag : undefined;
+  const componentName = isComponentNode(node) ? node.component : undefined;
+  let nodeProps = isComponentNode(node) ? (node.props || {}) : {};
+
+  // Process CMS templates in props
+  if (ctx.cmsContext?.cms && Object.keys(nodeProps).length > 0) {
+    nodeProps = processCMSPropsTemplate(nodeProps, ctx.cmsContext.cms);
+  }
+
+  // Extract attributes from node
+  const nodeAttributes = extractAttributesFromNode(node);
+
+  if (!tag && !componentName) return '';
+
+  // Convert styles to utility classes instead of inline styles
+  let utilityClasses: string[] = [];
+  let resolvedStyle: StyleObject = {};
+
+  if (nodeStyle) {
+    // Validate that all styles can generate utility classes (build-time warnings)
+    validateStyleCoverage(nodeStyle, `Node: ${nodeType || 'unknown'}`);
+
+    // Convert style object to utility class names
+    utilityClasses = responsiveStylesToClasses(nodeStyle);
+
+    // Only keep inline styles from nodeProps, not from the style object
+    // (style objects are converted to classes instead)
+    // For backward compatibility with components that set styles via props
+  } else if (nodeProps.style) {
+    // If no node.style but props have style, keep it for backward compatibility
+    if (isResponsiveStyle(nodeProps.style) && breakpoints && viewportWidth) {
+      resolvedStyle = mergeResponsiveStyles(nodeProps.style as ResponsiveStyleObject, 'viewport', viewportWidth, breakpoints);
+    } else {
+      resolvedStyle = nodeProps.style as StyleObject;
+    }
+  }
+
+  // Merge resolved style into props.style, and merge attributes
+  const propsWithStyleAndAttrs = {
+    ...nodeProps,
+    ...nodeAttributes,
+    ...(utilityClasses.length > 0 ? { className: utilityClasses.join(' ') } : {}),
+    ...(Object.keys(resolvedStyle).length > 0 ? { style: resolvedStyle } : {})
+  };
+
+  // Check if this is a custom component
+  if (nodeType === NODE_TYPE.COMPONENT && componentName && ssrComponentRegistry.has(componentName)) {
+    const componentDef = ssrComponentRegistry.get(componentName);
+    if (!componentDef) return '';
+
+    try {
+      const structuredComponentDef = componentDef.component;
+      if (!structuredComponentDef) return '';
+
+      // Resolve props with defaults from interface definition (with i18n support)
+      const resolvedProps = resolvePropsFromDefinition(
+        structuredComponentDef,
+        propsWithStyleAndAttrs,
+        children,
+        locale,
+        i18nConfig
+      );
+
+      // Process the structure with resolved props
+      // Pass instance children to replace { type: "children" } markers
+      // Use preserveResponsiveStyles: true to keep responsive styles intact for SSR rendering
+      const processedStructure = processStructure(
+        structuredComponentDef.structure,
+        { props: resolvedProps, componentDef: structuredComponentDef },
+        undefined,
+        children,
+        true
+      );
+
+      if (!processedStructure) return '';
+
+      // Type guard: ensure processedStructure is a ComponentNode
+      if (typeof processedStructure === 'string' || typeof processedStructure === 'number' || Array.isArray(processedStructure)) {
+        return renderNode(processedStructure, ctx);
+      }
+
+      // Merge instance style overrides, className, and attributes
+      // processedStructure should be a ComponentInstanceNode at this point
+      if (isComponentNode(processedStructure)) {
+        if (!processedStructure.props) {
+          processedStructure.props = {};
+        }
+
+        if (processedStructure.props.style && typeof processedStructure.props.style === 'object') {
+          processedStructure.props.style = {
+            ...(processedStructure.props.style as Record<string, unknown>),
+            ...(propsWithStyleAndAttrs.style as Record<string, unknown> || {})
+          };
+        } else if (propsWithStyleAndAttrs.style) {
+          processedStructure.props.style = propsWithStyleAndAttrs.style;
+        }
+
+        // Merge className from component instance (includes responsive utility classes)
+        if (propsWithStyleAndAttrs.className) {
+          const existingClassName = processedStructure.props.className || '';
+          processedStructure.props.className = existingClassName
+            ? `${existingClassName} ${propsWithStyleAndAttrs.className}`
+            : propsWithStyleAndAttrs.className;
+        }
+
+        // Merge attributes into props
+        Object.assign(processedStructure.props, nodeAttributes);
+      }
+
+      // Render the processed component structure
+      return renderNode(processedStructure, ctx);
+
+    } catch (error) {
+      console.error(`❌ SSR Error rendering component ${componentName}:`, error);
+      return '';
+    }
+  }
+
+  // Handle Link component for navigation (only for HTML nodes)
+  if (tag === 'Link') {
+    const to = 'to' in propsWithStyleAndAttrs ? propsWithStyleAndAttrs.to : undefined;
+    const restProps: Record<string, unknown> = { ...propsWithStyleAndAttrs };
+    delete restProps.to;
+    const href = (typeof to === 'string' ? to : undefined) || '#';
+
+    // Build class attribute from utility classes
+    const linkClassAttr = restProps.className
+      ? ` class="${escapeHtml(String(restProps.className))}"`
+      : '';
+
+    const attrs = buildAttributes(restProps, ['style', 'className', 'to']);
+    const childrenHTML = Array.isArray(children)
+      ? children.map((child) => renderNode(child, ctx)).join('')
+      : renderNode(children, ctx);
+
+    return `<a href="${escapeHtml(String(href))}"${linkClassAttr}${attrs}>${childrenHTML}</a>`;
+  }
+
+  // Regular HTML element (must have tag)
+  if (!tag) {
+    console.error('Missing tag for HTML element in SSR');
+    return '';
+  }
+
+  // Build class attribute from utility classes
+  const classAttr = propsWithStyleAndAttrs.className
+    ? ` class="${escapeHtml(String(propsWithStyleAndAttrs.className))}"`
+    : '';
+
+  const attrs = buildAttributes(propsWithStyleAndAttrs, ['style', 'className']);
+  const childrenHTML = Array.isArray(children)
+    ? children.map((child) => renderNode(child, ctx)).join('')
+    : renderNode(children, ctx);
+
+  // Self-closing tags
+  const voidElements = ['img', 'input', 'br', 'hr', 'meta', 'link', 'area', 'base', 'col', 'embed', 'source', 'track', 'wbr'];
+  if (voidElements.includes(tag.toLowerCase())) {
+    return `<${tag}${classAttr}${attrs} />`;
+  }
+
+  return `<${tag}${classAttr}${attrs}>${childrenHTML}</${tag}>`;
+}
+
+/**
+ * Build HTML attributes string from props (excluding style and other special props)
+ */
+function buildAttributes(props: Record<string, unknown>, exclude: string[] = []): string {
+  const attrs: string[] = [];
+  // Internal props that should never be rendered as HTML attributes
+  const internalProps = ['type', 'tag', 'component', 'props', 'children', 'src', 'alt', 'loading', 'width', 'height'];
+  const defaultExclude = [...internalProps, ...exclude];
+
+  // Regex to detect unresolved template strings like {{link.target}}
+  const unresolvedTemplatePattern = /^\{\{.+\}\}$/;
+
+  for (const [key, value] of Object.entries(props)) {
+    if (defaultExclude.includes(key)) continue;
+    if (value === null || value === undefined) continue;
+    if (typeof value === 'function') continue; // Skip event handlers in SSR
+    if (typeof value === 'object') continue; // Skip objects (prevents [object Object] in attributes)
+    // Skip unresolved template strings (e.g., {{link.target}} when link.target is undefined)
+    if (typeof value === 'string' && unresolvedTemplatePattern.test(value)) continue;
+    
+    // Convert camelCase to kebab-case for HTML attributes
+    const attrName = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+    const attrValue = typeof value === 'boolean' 
+      ? (value ? '' : undefined)
+      : escapeHtml(String(value));
+    
+    if (attrValue !== undefined) {
+      if (typeof value === 'boolean' && value) {
+        attrs.push(attrName);
+      } else {
+        attrs.push(`${attrName}="${attrValue}"`);
+      }
+    }
+  }
+  
+  return attrs.length > 0 ? ' ' + attrs.join(' ') : '';
+}
+
+/**
+ * Extract meta information from page JSON for SEO
+ */
+export interface PageMeta {
+  title?: string;
+  description?: string;
+  keywords?: string;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+  ogType?: string;
+}
+
+export function extractPageMeta(pageData: JSONPage): PageMeta {
+  const meta: PageMeta = {};
+  
+  if (pageData?.meta) {
+    meta.title = pageData.meta.title;
+    meta.description = pageData.meta.description;
+    meta.keywords = pageData.meta.keywords;
+    meta.ogTitle = pageData.meta.ogTitle || pageData.meta.title;
+    meta.ogDescription = pageData.meta.ogDescription || pageData.meta.description;
+    meta.ogImage = pageData.meta.ogImage;
+    meta.ogType = pageData.meta.ogType || 'website';
+  }
+  
+  return meta;
+}
+
+/**
+ * Generate HTML meta tags string
+ * Resolves i18n values using the provided locale and config
+ */
+export function generateMetaTags(
+  meta: PageMeta,
+  url: string = '',
+  locale: string = 'en',
+  config: I18nConfig = DEFAULT_I18N_CONFIG
+): string {
+  const tags: string[] = [];
+
+  // Helper to resolve i18n values and ensure string type
+  const resolve = (value: unknown): string => {
+    const resolved = resolveI18nValue(value, locale, config);
+    return typeof resolved === 'string' ? resolved : '';
+  };
+
+  const title = resolve(meta.title);
+  const description = resolve(meta.description);
+  const keywords = resolve(meta.keywords);
+  const ogTitle = resolve(meta.ogTitle) || title;
+  const ogDescription = resolve(meta.ogDescription) || description;
+  const ogImage = resolve(meta.ogImage);
+  const ogType = resolve(meta.ogType);
+
+  if (title) {
+    tags.push(`<title>${escapeHtml(title)}</title>`);
+  }
+
+  if (description) {
+    tags.push(`<meta name="description" content="${escapeHtml(description)}" />`);
+  }
+
+  if (keywords) {
+    tags.push(`<meta name="keywords" content="${escapeHtml(keywords)}" />`);
+  }
+
+  // Open Graph tags
+  if (ogTitle) {
+    tags.push(`<meta property="og:title" content="${escapeHtml(ogTitle)}" />`);
+  }
+
+  if (ogDescription) {
+    tags.push(`<meta property="og:description" content="${escapeHtml(ogDescription)}" />`);
+  }
+
+  if (ogImage) {
+    tags.push(`<meta property="og:image" content="${escapeHtml(ogImage)}" />`);
+  }
+
+  if (ogType) {
+    tags.push(`<meta property="og:type" content="${escapeHtml(ogType)}" />`);
+  }
+
+  if (url) {
+    tags.push(`<meta property="og:url" content="${escapeHtml(url)}" />`);
+  }
+
+  // Canonical URL
+  if (url) {
+    tags.push(`<link rel="canonical" href="${escapeHtml(url)}" />`);
+  }
+
+  return tags.join('\n  ');
+}
+
+/**
+ * Collect JavaScript code from all components (global and page-specific)
+ */
+function collectComponentJavaScript(
+  globalComponents: Record<string, ComponentDefinition> = {},
+  pageComponents: Record<string, ComponentDefinition> = {}
+): string {
+  const jsCodeBlocks: string[] = [];
+  
+  // Collect JS from global components
+  for (const [name, component] of Object.entries(globalComponents)) {
+    if (component?.component?.javascript) {
+      jsCodeBlocks.push(`// Component: ${name}\n${component.component.javascript}`);
+    }
+  }
+  
+  // Collect JS from page-specific components
+  for (const [name, component] of Object.entries(pageComponents)) {
+    // Skip if already collected from global components
+    if (!globalComponents[name] && component?.component?.javascript) {
+      jsCodeBlocks.push(`// Component: ${name}\n${component.component.javascript}`);
+    }
+  }
+  
+  return jsCodeBlocks.join('\n\n');
+}
+
+/**
+ * Collect CSS code from all components (global and page-specific)
+ */
+function collectComponentCSS(
+  globalComponents: Record<string, ComponentDefinition> = {},
+  pageComponents: Record<string, ComponentDefinition> = {}
+): string {
+  const cssBlocks: string[] = [];
+  
+  // Collect CSS from global components
+  for (const [name, component] of Object.entries(globalComponents)) {
+    if (component?.component?.css) {
+      cssBlocks.push(`/* Component: ${name} */\n${component.component.css}`);
+    }
+  }
+  
+  // Collect CSS from page-specific components
+  for (const [name, component] of Object.entries(pageComponents)) {
+    // Skip if already collected from global components
+    if (!globalComponents[name] && component?.component?.css) {
+      cssBlocks.push(`/* Component: ${name} */\n${component.component.css}`);
+    }
+  }
+  
+  return cssBlocks.join('\n\n');
+}
+
+/**
+ * Main SSR render function - generates complete HTML with pre-rendered content
+ */
+export async function renderPageSSR(
+  pageData: JSONPage,
+  globalComponents: Record<string, ComponentDefinition> = {},
+  pagePath: string = '/',
+  baseUrl: string = '',
+  locale?: string,
+  i18nConfig?: I18nConfig,
+  slugMappings?: SlugMap[],
+  cmsContext?: CMSContext
+): Promise<{ html: string; meta: string; title: string; javascript: string; componentCSS?: string; locale: string }> {
+  // Extract page content
+  const rootNode = pageData?.root || undefined;
+  if (!rootNode) {
+    throw new Error('Page data must have a root node');
+  }
+
+  // Load i18n config if not provided
+  const config = i18nConfig || await loadI18nConfig();
+
+  // Extract locale from path if not explicitly provided
+  const { locale: pathLocale, pathWithoutLocale } = extractLocaleFromPath(pagePath, config);
+  const effectiveLocale = locale || pathLocale || config.defaultLocale;
+
+  // Extract meta information and process CMS templates in meta
+  let meta = extractPageMeta(pageData);
+  if (cmsContext?.cms) {
+    // Process CMS templates in meta fields
+    if (typeof meta.title === 'string') {
+      meta = { ...meta, title: processCMSTemplate(meta.title, cmsContext.cms) };
+    }
+    if (typeof meta.description === 'string') {
+      meta = { ...meta, description: processCMSTemplate(meta.description, cmsContext.cms) };
+    }
+    if (typeof meta.ogTitle === 'string') {
+      meta = { ...meta, ogTitle: processCMSTemplate(meta.ogTitle, cmsContext.cms) };
+    }
+    if (typeof meta.ogDescription === 'string') {
+      meta = { ...meta, ogDescription: processCMSTemplate(meta.ogDescription, cmsContext.cms) };
+    }
+  }
+
+  const pageComponents = pageData?.components || {};
+
+  // Render the component tree to HTML with i18n and CMS support
+  const { html: contentHTML } = rootNode
+    ? await buildComponentHTML(rootNode, globalComponents, pageComponents, effectiveLocale, config, slugMappings, pagePath, cmsContext)
+    : { html: '' };
+
+  // Collect JavaScript and CSS from all components
+  const javascript = collectComponentJavaScript(globalComponents, pageComponents);
+  const componentCSS = collectComponentCSS(globalComponents, pageComponents);
+
+  // Build full URL for meta tags
+  const fullUrl = baseUrl ? `${baseUrl}${pagePath}` : pagePath;
+
+  // Generate meta tags with i18n resolution
+  const metaTags = generateMetaTags(meta, fullUrl, effectiveLocale, config);
+
+  // Resolve title for use in HTML template
+  const resolvedTitle = resolveI18nValue(meta.title, effectiveLocale, config);
+
+  // Return pre-rendered HTML (will be injected into template)
+  return {
+    html: contentHTML,
+    meta: metaTags,
+    title: typeof resolvedTitle === 'string' ? resolvedTitle : 'UPLO',
+    javascript,
+    // Component CSS is still included in the final HTML document
+    componentCSS,
+    locale: effectiveLocale
+  };
+}
+
+/**
+ * Generate complete HTML document with SSR content
+ */
+export async function generateSSRHTML(
+  pageData: JSONPage,
+  globalComponents: Record<string, ComponentDefinition> = {},
+  pagePath: string = '/',
+  baseUrl: string = '',
+  useBuiltBundle: boolean = false,
+  locale?: string,
+  slugMappings?: SlugMap[],
+  cmsContext?: CMSContext
+): Promise<string> {
+  const rendered = await renderPageSSR(pageData, globalComponents, pagePath, baseUrl, locale, undefined, slugMappings, cmsContext);
+
+  // Use built bundle in production, dev server in development
+  const clientScript = useBuiltBundle
+    ? '' // No client router in static build (true static HTML)
+    : '<script type="module" src="/client-router.tsx"></script>'; // Dev server (development)
+
+  // Render component JavaScript if any
+  // Escape </script> sequences to prevent premature script tag closure
+  const escapedJavaScript = rendered.javascript
+    ? rendered.javascript.replace(/<\/script>/gi, '<\\/script>')
+    : '';
+  const componentScript = escapedJavaScript
+    ? `\n  <script>\n${escapedJavaScript}\n  </script>`
+    : '';
+
+  // Add form handler script if page contains fetch-handled forms
+  const formScript = needsFormHandler(rendered.html)
+    ? `\n  <script>\n${formHandlerScript}\n  </script>`
+    : '';
+
+  // Generate font CSS from project config
+  const fontCSS = generateFontCSS();
+
+  // Load icons config for favicon and apple touch icon
+  const iconsConfig = await loadIconsConfig();
+
+  // Load and generate theme color variables CSS
+  const themeConfig = await colorService.loadThemeConfig();
+  const themeColorVariablesCSS = generateThemeColorVariablesCSS(themeConfig);
+
+  // Include component CSS (no longer generating inline style classes)
+  const allCSS = rendered.componentCSS || '';
+
+  // Extract and generate utility CSS from rendered HTML
+  const usedUtilityClasses = extractUtilityClassesFromHTML(rendered.html);
+  const breakpointConfig = await loadBreakpointConfig();
+  const responsiveScalesConfig = await loadResponsiveScalesConfig();
+  const utilityCSS = generateUtilityCSS(usedUtilityClasses, breakpointConfig, responsiveScalesConfig);
+
+  // Print warnings for any unmapped styles found during build
+  printMissingStyleWarnings(false);
+
+  // Generate favicon and apple touch icon link tags
+  const faviconTag = iconsConfig.favicon
+    ? `<link rel="icon" href="${escapeHtml(iconsConfig.favicon)}" />`
+    : '';
+  const appleTouchIconTag = iconsConfig.appleTouchIcon
+    ? `<link rel="apple-touch-icon" href="${escapeHtml(iconsConfig.appleTouchIcon)}" />`
+    : '';
+  const iconTags = [faviconTag, appleTouchIconTag].filter(Boolean).join('\n  ');
+
+  return `<!DOCTYPE html>
+<html lang="${rendered.locale}" theme="${themeConfig.default}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  ${iconTags ? iconTags + '\n  ' : ''}${rendered.meta}
+  <style>
+    ${fontCSS ? fontCSS + '\n    ' : ''}${themeColorVariablesCSS ? themeColorVariablesCSS + '\n    ' : ''}* {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
+    }
+    button {
+      background: none;
+      border: none;
+      padding: 0;
+      font: inherit;
+      cursor: pointer;
+      outline: inherit;
+    }
+
+    img {
+      width: 100%;
+      height: 100%;
+    }
+
+    .olink {
+      text-decoration: none;
+    }
+
+    ${allCSS}
+
+    ${utilityCSS}
+  </style>
+</head>
+<body>
+  <div id="root">${rendered.html}</div>
+  ${clientScript}${componentScript}${formScript}
+</body>
+</html>`;
+}