meno-core 1.0.19 → 1.0.21

package/lib/client/core/builders/{cmsListBuilder.ts → listBuilder.ts}

@@ -1,25 +1,28 @@
 /**
- * CMS List Node Builder
- * Handles rendering of CMS list nodes with collection items
+ * Unified List Node Builder
+ * Handles rendering of list nodes with item iteration from either:
+ * - Component props (sourceType: 'prop')
+ * - CMS collections (sourceType: 'collection')
  */
 
 import { createElement as h } from "react";
 import type { ReactElement } from "react";
-import type { CMSListNode, CMSItem, CMSFilterCondition, CMSSortConfig, CMSFilterOperator } from "../../../shared/types/cms";
+import type { ListNode } from "../../../shared/registry/nodeTypes/ListNodeType";
+import type { CMSItem, CMSFilterCondition, CMSSortConfig, CMSFilterOperator } from "../../../shared/types/cms";
 import type { InteractiveStyles, StyleObject, ResponsiveStyleObject } from "../../../shared/types";
 import { singularize } from "../../../shared/types/cms";
 import { buildTemplateContext, resolveItemsTemplate, getNestedValue } from "../../../shared/itemTemplateUtils";
 import type { TemplateContext } from "../../../shared/types/cms";
-import { extractAttributesFromNode } from "../../../shared/attributeNodeUtils";
+import { pathToString, getChildPath } from "../../../shared/pathArrayUtils";
 import { responsiveStylesToClasses } from "../../../shared/utilityClassMapper";
-import { pathToString } from "../../../shared/pathArrayUtils";
+import { extractAttributesFromNode } from "../../../shared/attributeNodeUtils";
 import { generateElementClassName, type ElementClassContext } from "../../../shared/elementClassName";
 import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
 import { hasInteractiveStyleMappings, extractInteractiveStyleMappings, resolveExtractedMappings } from "../../../shared/interactiveStyleMappings";
 import type { ElementRegistry } from "../../elementRegistry";
 import type { BuilderContext, BuildResult, BuildChildrenContext } from "./types";
 
-export interface CMSListBuilderDeps {
+export interface ListBuilderDeps {
   elementRegistry: ElementRegistry;
   getCachedStyleClasses: (style: object) => string[];
   buildChildren: (
@@ -37,13 +40,13 @@ export interface CMSListBuilderDeps {
 }
 
 /**
- * Build a CMS list node
+ * Build a unified list node - handles both prop and collection source types
  */
-export function buildCMSList(
-  node: CMSListNode,
+export function buildList(
+  node: ListNode,
   children: unknown,
   ctx: BuilderContext,
-  deps: CMSListBuilderDeps
+  deps: ListBuilderDeps
 ): ReactElement {
   const {
     key, elementPath, parentComponentName, viewportWidth, componentContext, componentRootPath,
@@ -51,17 +54,27 @@ export function buildCMSList(
     cmsItemIndexPath, cmsListPaths, templateContext, componentResolvedProps
   } = ctx;
 
+  // Determine source type (default to 'prop', but handle legacy 'cms-list' type)
+  const nodeType = (node as any).type;
+  const isLegacyCMSList = nodeType === 'cms-list';
+  const sourceType = isLegacyCMSList ? 'collection' : (node.sourceType || 'prop');
+  const isCollectionMode = sourceType === 'collection';
+
+  // Get source - handle both new 'source' and legacy 'collection' property
+  // Source can be a string (prop name) or array (pre-resolved by processStructure)
+  const rawSource = node.source || (node as any).collection;
+  const source = typeof rawSource === 'string' ? rawSource : '';
+  const sourceIsResolved = Array.isArray(rawSource);
+
   const effectiveParentComponentName = deps.getEffectiveParentComponentName(componentContext, parentComponentName);
 
   // Extract attributes
   const extractedAttributes = extractAttributesFromNode(node as any);
 
-  // Build CMS list container props
-  const cmsListProps: Record<string, any> = {
+  // Build container props with appropriate data attributes
+  const containerProps: Record<string, any> = {
     key,
     'data-element-path': pathToString(elementPath),
-    'data-cms-list': 'true',
-    'data-collection': node.collection || '',
     ref: (el: HTMLElement | null) => {
       deps.elementRegistry.register(elementPath, el, effectiveParentComponentName, false);
       // Apply CSS variables for interactive styles
@@ -76,16 +89,26 @@ export function buildCMSList(
     }
   };
 
+  // Set data attributes based on source type
+  // All list types need data-cms-list for click handler to find them
+  containerProps['data-cms-list'] = 'true';
+  if (isCollectionMode) {
+    containerProps['data-collection'] = source || '';
+  } else {
+    containerProps['data-list'] = 'true';
+    containerProps['data-source'] = source || (sourceIsResolved ? 'resolved' : '');
+  }
+
   // Start building className
   let classNames: string[] = [];
 
-  // Convert container styles to utility classes (using cache for performance)
+  // Apply styles
   if (node.style) {
     const utilityClasses = deps.getCachedStyleClasses(node.style);
     classNames.push(...utilityClasses);
   }
 
-  // Handle interactive styles (cast to InteractiveStyles since Zod-inferred type is slightly different)
+  // Handle interactive styles
   const nodeInteractiveStyles = node.interactiveStyles as InteractiveStyles | undefined;
   const nodeGenerateElementClass = node.generateElementClass;
   const nodeLabel = node.label;
@@ -148,42 +171,179 @@ export function buildCMSList(
 
   // Set final className
   if (classNames.length > 0) {
-    cmsListProps.className = classNames.filter(Boolean).join(' ');
+    containerProps.className = classNames.filter(Boolean).join(' ');
   }
 
   // Add extracted attributes
   if (Object.keys(extractedAttributes).length > 0) {
-    Object.assign(cmsListProps, extractedAttributes);
+    Object.assign(containerProps, extractedAttributes);
   }
 
   // Add parent component context
   if (effectiveParentComponentName) {
-    cmsListProps['data-parent-component'] = effectiveParentComponentName;
+    containerProps['data-parent-component'] = effectiveParentComponentName;
   }
   if (componentContext) {
-    cmsListProps['data-component-context'] = componentContext;
+    containerProps['data-component-context'] = componentContext;
   }
 
-  // Determine variable name for this list's items (use itemAs or singular of collection)
-  const variableName = node.itemAs || singularize(node.collection);
+  // Get items based on source type
+  let itemsToRender: unknown[];
 
-  // Get items for this collection
-  let itemsToRender: CMSItem[] = [];
+  if (isCollectionMode) {
+    itemsToRender = getCollectionItems(node, source, ctx);
+  } else {
+    // Prop mode: Read from component props or template context
+    // If source was already resolved to an array by processStructure (e.g., from {{features}}),
+    // use it directly instead of looking up by prop name
+    if (sourceIsResolved) {
+      itemsToRender = rawSource as unknown[];
+    } else if (source) {
+      itemsToRender = getPropItems(source, ctx);
+    } else {
+      itemsToRender = [];
+    }
+  }
+
+  // Determine variable name for this list's items
+  let variableName: string;
+  if (node.itemAs) {
+    variableName = node.itemAs;
+  } else if (isCollectionMode) {
+    variableName = singularize(source);
+  } else {
+    variableName = 'item';
+  }
+
+  // Different colors for collection vs prop modes
+  const bgColor = isCollectionMode ? 'rgba(139, 92, 246, 0.05)' : 'rgba(59, 130, 246, 0.05)';
+  const borderColor = isCollectionMode ? 'rgba(139, 92, 246, 0.3)' : 'rgba(59, 130, 246, 0.3)';
+  const textColor = isCollectionMode ? '#8b5cf6' : '#3b82f6';
+  const label = isCollectionMode ? 'CMS List' : 'List';
+
+  // Use configurable tag (defaults to 'div') - declared early for all return paths
+  const tag = node.tag || 'div';
+
+  if (!source && !sourceIsResolved) {
+    // No source - render empty container with placeholder
+    const emptyState = h('div', {
+      key: 'list-empty',
+      style: {
+        padding: '12px',
+        background: bgColor,
+        border: `1px dashed ${borderColor}`,
+        borderRadius: '4px',
+        color: textColor,
+        fontSize: '12px',
+        fontFamily: 'system-ui, sans-serif',
+        textAlign: 'center'
+      }
+    }, `${label}: No source - No items`);
+    return h(tag, containerProps, emptyState);
+  }
+
+  if (itemsToRender.length === 0) {
+    // No items - render empty container with placeholder
+    const emptyState = h('div', {
+      key: 'list-empty',
+      style: {
+        padding: '12px',
+        background: bgColor,
+        border: `1px dashed ${borderColor}`,
+        borderRadius: '4px',
+        color: textColor,
+        fontSize: '12px',
+        fontFamily: 'system-ui, sans-serif',
+        textAlign: 'center'
+      }
+    }, `${label}: ${source || 'resolved'} - No items`);
+    return h(tag, containerProps, emptyState);
+  }
+
+  // Render children for each item
+  const renderedItems: (ReactElement | string | number)[] = [];
+
+  for (let index = 0; index < itemsToRender.length; index++) {
+    const item = itemsToRender[index];
+    // Build template context for this item
+    const itemTemplateContext = buildTemplateContext(
+      variableName,
+      item as CMSItem,
+      index,
+      itemsToRender.length,
+      templateContext || undefined
+    );
+
+    // Build children with item context
+    // Track item index for BOTH collection and prop mode (enables selection of individual list items)
+    const newIndexPath = [...(cmsItemIndexPath || []), index];
+    const newListPaths = [...(cmsListPaths || []), elementPath];
+
+    const itemChildren = deps.buildChildren(children, {
+      elementPath,
+      parentComponentName: effectiveParentComponentName,
+      viewportWidth,
+      componentContext,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext,
+      cmsLocale,
+      collectionItemsMap,
+      itemContext: null,
+      cmsItemIndexPath: newIndexPath,
+      cmsListPaths: newListPaths,
+      templateContext: itemTemplateContext,
+      componentResolvedProps
+    });
+
+    // Add children directly (no wrapper div)
+    if (itemChildren === null) continue;
+    if (Array.isArray(itemChildren)) {
+      // Add unique keys by combining original key with item index
+      for (const child of itemChildren) {
+        if (typeof child === 'object' && child !== null && 'key' in child) {
+          renderedItems.push({ ...child, key: `${child.key}-item-${index}` } as ReactElement);
+        } else {
+          renderedItems.push(child);
+        }
+      }
+    } else if (typeof itemChildren === 'object' && itemChildren !== null && 'key' in itemChildren) {
+      // Single child - ensure unique key
+      renderedItems.push({ ...itemChildren, key: `${(itemChildren as ReactElement).key}-item-${index}` } as ReactElement);
+    } else {
+      renderedItems.push(itemChildren);
+    }
+  }
+
+  return h(tag, containerProps, renderedItems);
+}
+
+// ============================================================================
+// Item Fetching Functions
+// ============================================================================
+
+/**
+ * Get items from CMS collection (for sourceType: 'collection')
+ */
+function getCollectionItems(node: ListNode, source: string, ctx: BuilderContext): CMSItem[] {
+  const { collectionItemsMap = {}, cmsContext, templateContext } = ctx;
+  const collectionItems = source ? (collectionItemsMap[source] || []) : [];
 
   // Helper to lookup items by ID or filename
-  const lookupItemsByIds = (ids: string[], collectionItems: CMSItem[]): CMSItem[] => {
-    const itemMap = new Map(collectionItems.map(item => [item._id, item]));
-    const filenameMap = new Map(collectionItems.map(item => [item._filename, item]));
+  const lookupItemsByIds = (ids: string[], items: CMSItem[]): CMSItem[] => {
+    const itemMap = new Map(items.map(item => [item._id, item]));
+    const filenameMap = new Map(items.map(item => [item._filename, item]));
     return ids
       .filter(Boolean)
       .map(id => itemMap.get(id) || filenameMap.get(id))
       .filter((item): item is CMSItem => item !== undefined);
   };
 
+  let itemsToRender: CMSItem[] = [];
+
   // Check if items are specified directly (for nested reference lists)
   if (node.items) {
-    const collectionItems = node.collection ? (collectionItemsMap[node.collection] || []) : [];
-
     // If items is a template expression, resolve it from current context
     if (typeof node.items === 'string' && node.items.startsWith('{{')) {
       let resolvedIds: string | string[] | undefined;
@@ -204,7 +364,7 @@ export function buildCMSList(
           resolvedIds = Array.isArray(value) ? value.map(v => String(v)) : String(value);
         }
       } else {
-        // Otherwise resolve from template context (for nested cms-lists)
+        // Otherwise resolve from template context (for nested lists)
         const effectiveTemplateContext = templateContext || { _type: 'template' as const };
         resolvedIds = resolveItemsTemplate(node.items, effectiveTemplateContext);
       }
@@ -221,19 +381,18 @@ export function buildCMSList(
 
     // Apply filters and sorting to referenced items
     if (node.filter) {
-      itemsToRender = applyClientFilters(itemsToRender, node.filter, cmsContext ?? undefined, templateContext ?? undefined);
+      itemsToRender = applyClientFilters(itemsToRender, node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown>, cmsContext ?? undefined, templateContext ?? undefined);
     }
     if (node.sort) {
       itemsToRender = applyClientSorting(itemsToRender, node.sort);
     }
   } else {
     // Get items for this collection from the map
-    const collectionItems = node.collection ? (collectionItemsMap[node.collection] || []) : [];
-    itemsToRender = collectionItems;
+    itemsToRender = [...collectionItems];
 
     // Apply filters (BEFORE offset/limit)
     if (node.filter) {
-      itemsToRender = applyClientFilters(itemsToRender, node.filter, cmsContext ?? undefined, templateContext ?? undefined);
+      itemsToRender = applyClientFilters(itemsToRender, node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown>, cmsContext ?? undefined, templateContext ?? undefined);
     }
 
     // Apply sorting (BEFORE offset/limit)
@@ -256,73 +415,46 @@ export function buildCMSList(
     itemsToRender = itemsToRender.filter(item => item._id !== currentId);
   }
 
-  // If no items, show empty state in editor
-  if (itemsToRender.length === 0) {
-    const emptyState = h('div', {
-      key: 'cms-list-empty',
-      style: {
-        padding: '12px',
-        background: 'rgba(139, 92, 246, 0.05)',
-        border: '1px dashed rgba(139, 92, 246, 0.3)',
-        borderRadius: '4px',
-        color: '#8b5cf6',
-        fontSize: '12px',
-        fontFamily: 'system-ui, sans-serif',
-        textAlign: 'center'
+  return itemsToRender;
+}
+
+/**
+ * Get items from component props or template context (for sourceType: 'prop')
+ */
+function getPropItems(source: string, ctx: BuilderContext): unknown[] {
+  const { componentResolvedProps, templateContext, cmsContext } = ctx;
+
+  // Check if source is a template expression
+  if (source.startsWith('{{') && source.endsWith('}}')) {
+    // Template expression - resolve from template context (for nested lists)
+    // e.g., {{category.items}} where category is from parent list
+    if (templateContext) {
+      const path = source.slice(2, -2).trim(); // Extract "category.items"
+      const resolved = getNestedValue(templateContext as Record<string, unknown>, path);
+      if (Array.isArray(resolved)) {
+        return resolved;
       }
-    }, `CMS List: ${node.collection || 'No collection'} - No items`);
-    return h('div', cmsListProps, emptyState);
+    }
+    return [];
   }
 
-  // Render children for each item - no wrapper div, cmsItemIndexPath flows to all descendants
-  const renderedItems: (ReactElement | string | number)[] = [];
-  for (let index = 0; index < itemsToRender.length; index++) {
-    const item = itemsToRender[index];
-    // Build template context with named variable (preserves parent context for nested lists)
-    const newTemplateContext = buildTemplateContext(
-      variableName,
-      item,
-      index,
-      itemsToRender.length,
-      templateContext || undefined
-    );
-
-    // Build children with templateContext (contains both named and legacy context)
-    // Append current index to existing path to support nested CMS lists
-    const newIndexPath = [...(cmsItemIndexPath || []), index];
-    // Also track the CMS list element paths (parallel array to newIndexPath)
-    const newListPaths = [...(cmsListPaths || []), elementPath];
-    const itemChildren = deps.buildChildren(children, {
-      elementPath, parentComponentName: effectiveParentComponentName, viewportWidth, componentContext, componentRootPath,
-      locale, i18nConfig, cmsContext, cmsLocale, collectionItemsMap,
-      itemContext: null,  // itemContext no longer needed - templateContext has all data
-      cmsItemIndexPath: newIndexPath,  // Pass updated path - will be applied to all descendants via ref callback
-      cmsListPaths: newListPaths,  // Pass updated list paths - enables full CMS context on elements
-      templateContext: newTemplateContext,  // Pass named template context for nested lists
-      componentResolvedProps
-    });
+  // Direct prop name - resolve from component props
+  if (componentResolvedProps) {
+    const propValue = componentResolvedProps[source];
+    if (Array.isArray(propValue)) {
+      return propValue;
+    }
+  }
 
-    // Add children directly (no wrapper div)
-    // Each child element will have data-cms-item-index attribute via ref callback
-    if (itemChildren === null) continue;
-    if (Array.isArray(itemChildren)) {
-      // Add unique keys by combining original key with item index
-      for (const child of itemChildren) {
-        if (typeof child === 'object' && child !== null && 'key' in child) {
-          renderedItems.push({ ...child, key: `${child.key}-item-${index}` } as ReactElement);
-        } else {
-          renderedItems.push(child);
-        }
-      }
-    } else if (typeof itemChildren === 'object' && itemChildren !== null && 'key' in itemChildren) {
-      // Single child - ensure unique key
-      renderedItems.push({ ...itemChildren, key: `${(itemChildren as ReactElement).key}-item-${index}` } as ReactElement);
-    } else {
-      renderedItems.push(itemChildren);
+  // Also try CMS context for prop mode (for cms context values)
+  if (cmsContext) {
+    const cmsValue = (cmsContext as Record<string, unknown>)[source];
+    if (Array.isArray(cmsValue)) {
+      return cmsValue;
     }
   }
 
-  return h('div', cmsListProps, renderedItems);
+  return [];
 }
 
 // ============================================================================
@@ -387,7 +519,7 @@ function resolveTemplateValue(
     return result;
   }
 
-  // Handle {{itemAs.field}} - resolve from template context (for nested cms-lists)
+  // Handle {{itemAs.field}} - resolve from template context (for nested lists)
   if (templateContext) {
     const result = getNestedValue(templateContext as Record<string, unknown>, path);
     if (result !== undefined) {

package/lib/client/responsiveStyleResolver.test.ts

@@ -54,8 +54,8 @@ describe("Responsive Style Resolver - getBreakpointName", () => {
     test("should use custom breakpoints when provided", () => {
       const viewportWidth = 800;
       const customBreakpoints = {
-        tablet: 900,
-        mobile: 400
+        tablet: { breakpoint: 900, previewPoint: 768 },
+        mobile: { breakpoint: 400, previewPoint: 375 }
       };
       const result = getBreakpointName(viewportWidth, customBreakpoints);
       expect(result).toBe("tablet");
@@ -64,13 +64,13 @@ describe("Responsive Style Resolver - getBreakpointName", () => {
 
   describe("Edge cases", () => {
     test("should handle exact breakpoint boundaries", () => {
-      const tabletWidth = DEFAULT_BREAKPOINTS.tablet;
-      const mobileWidth = DEFAULT_BREAKPOINTS.mobile;
-      
+      const tabletWidth = DEFAULT_BREAKPOINTS.tablet.breakpoint;
+      const mobileWidth = DEFAULT_BREAKPOINTS.mobile.breakpoint;
+
       expect(getBreakpointName(tabletWidth)).toBe("tablet");
       expect(getBreakpointName(tabletWidth - 1)).toBe("tablet");
       expect(getBreakpointName(tabletWidth + 1)).toBe("base");
-      
+
       expect(getBreakpointName(mobileWidth)).toBe("mobile");
       expect(getBreakpointName(mobileWidth - 1)).toBe("mobile");
       expect(getBreakpointName(mobileWidth + 1)).toBe("tablet");
@@ -301,9 +301,9 @@ describe("Responsive Style Resolver - resolveResponsiveStyleSync", () => {
         base: { fontSize: "16px" },
         tablet: { fontSize: "14px" }
       };
-      
-      const result = resolveResponsiveStyleSync(style, DEFAULT_BREAKPOINTS.tablet);
-      
+
+      const result = resolveResponsiveStyleSync(style, DEFAULT_BREAKPOINTS.tablet.breakpoint);
+
       expect(result.fontSize).toBe("14px");
     });
 
@@ -313,9 +313,9 @@ describe("Responsive Style Resolver - resolveResponsiveStyleSync", () => {
         tablet: { fontSize: "14px" },
         mobile: { fontSize: "12px" }
       };
-      
-      const result = resolveResponsiveStyleSync(style, DEFAULT_BREAKPOINTS.mobile);
-      
+
+      const result = resolveResponsiveStyleSync(style, DEFAULT_BREAKPOINTS.mobile.breakpoint);
+
       expect(result.fontSize).toBe("12px");
     });
 

package/lib/client/responsiveStyleResolver.ts

@@ -4,8 +4,8 @@
  */
 
 import type { ResponsiveStyleObject, StyleObject } from '../shared/types';
-import type { BreakpointConfig } from '../shared/breakpoints';
-import { DEFAULT_BREAKPOINTS } from '../shared/breakpoints';
+import type { BreakpointConfig, BreakpointConfigInput, BreakpointEntry } from '../shared/breakpoints';
+import { DEFAULT_BREAKPOINTS, normalizeBreakpointConfig } from '../shared/breakpoints';
 import type { ResponsiveScales } from '../shared/responsiveScaling';
 import { DEFAULT_RESPONSIVE_SCALES } from '../shared/responsiveScaling';
 import { isResponsiveStyle } from '../shared/styleUtils';
@@ -81,16 +81,28 @@ async function loadConfig(): Promise<void> {
         const response = await fetch('/api/config');
         const config = await response.json();
 
-        // Parse breakpoints
+        // Parse breakpoints - supports both legacy and new format
         if (config.breakpoints && typeof config.breakpoints === 'object') {
-          const breakpoints: BreakpointConfig = {};
+          const validInput: BreakpointConfigInput = {};
           for (const [key, value] of Object.entries(config.breakpoints)) {
             if (typeof value === 'number' && value > 0) {
-              breakpoints[key] = value;
+              // Legacy format: number
+              validInput[key] = value;
+            } else if (typeof value === 'object' && value !== null) {
+              // New format: object with breakpoint and optional previewPoint
+              const entry = value as BreakpointEntry;
+              if (typeof entry.breakpoint === 'number' && entry.breakpoint > 0) {
+                validInput[key] = {
+                  breakpoint: entry.breakpoint,
+                  previewPoint: typeof entry.previewPoint === 'number' && entry.previewPoint > 0
+                    ? entry.previewPoint
+                    : entry.breakpoint,
+                };
+              }
             }
           }
-          breakpointConfig = Object.keys(breakpoints).length > 0
-            ? breakpoints
+          breakpointConfig = Object.keys(validInput).length > 0
+            ? normalizeBreakpointConfig(validInput)
             : { ...DEFAULT_BREAKPOINTS };
         } else {
           breakpointConfig = { ...DEFAULT_BREAKPOINTS };

package/lib/client/routing/Router.tsx

@@ -119,6 +119,8 @@ export function Router(props: RouterProps = {}): ReactElement {
   const [componentTree, setComponentTree] = useState<ComponentNode | ComponentNode[] | null>(null);
   // Keep previous componentTree to show during transitions
   const [previousComponentTree, setPreviousComponentTree] = useState<ComponentNode | ComponentNode[] | null>(null);
+  // Preview component tree (for hover preview from editor - temporarily overrides componentTree)
+  const [previewComponentTree, setPreviewComponentTree] = useState<ComponentNode | ComponentNode[] | null>(null);
   // Ref to track current componentTree for closure access (needed for capturing current value in async functions)
   const componentTreeRef = useRef<ComponentNode | ComponentNode[] | null>(null);
   const [loading, setLoading] = useState(getInitialLoadingState(hasSSRContent));
@@ -270,6 +272,28 @@ export function Router(props: RouterProps = {}): ReactElement {
     return () => window.removeEventListener('message', handleMessage);
   }, []);
 
+  // Listen for page data preview updates from parent window (editor)
+  // Used for component hover preview in the components tab
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleMessage = (event: MessageEvent) => {
+      if (event.data?.type === IFRAME_MESSAGE_TYPES.PAGE_DATA_PREVIEW) {
+        // Set preview tree from pageData.root
+        const pageData = event.data.pageData;
+        if (pageData?.root) {
+          setPreviewComponentTree(pageData.root);
+        }
+      } else if (event.data?.type === IFRAME_MESSAGE_TYPES.PAGE_DATA_PREVIEW_REVERT) {
+        // Clear preview tree to revert to normal componentTree
+        setPreviewComponentTree(null);
+      }
+    };
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, []);
+
   // Request CMS context from parent when iframe is ready
   // Don't block rendering - just request context and re-render when it arrives
   useEffect(() => {
@@ -282,8 +306,10 @@ export function Router(props: RouterProps = {}): ReactElement {
   }, []);
 
   // Inject CSS and execute JavaScript after component tree is rendered
+  // Include previewComponentTree to ensure styles are injected for hover previews
   useEffect(() => {
-    if (componentTree) {
+    const treeToRender = previewComponentTree || componentTree;
+    if (treeToRender) {
       // Inject CSS immediately
       services.styleInjector.inject();
 
@@ -313,7 +339,7 @@ export function Router(props: RouterProps = {}): ReactElement {
       // Clear registry when tree is cleared (no elements to register)
       elementRegistry.clear();
     }
-  }, [componentTree, services, disableScripts]);
+  }, [previewComponentTree, componentTree, services, disableScripts]);
 
   // Prefetch all internal links when using 'load' strategy
   useEffect(() => {
@@ -415,13 +441,15 @@ export function Router(props: RouterProps = {}): ReactElement {
     };
   }, [services]);
 
-  // Render logic: prioritize current tree, then previous tree during loading, then loading/not found states
+  // Render logic: prioritize preview tree, then current tree, then previous tree during loading, then loading/not found states
+  // Use preview tree if set (from component hover preview), otherwise use current tree
+  const treeToRender = previewComponentTree || componentTree;
   let pageContent: ReactElement | null = null;
 
-  if (componentTree && !awaitingCmsContext) {
-    // Show current tree when we have it and CMS context is ready (or not needed)
+  if (treeToRender && !awaitingCmsContext) {
+    // Show current/preview tree when we have it and CMS context is ready (or not needed)
     pageContent = renderPage({
-      tree: componentTree,
+      tree: treeToRender,
       currentPath,
       viewportWidth,
       componentBuilder: services.componentBuilder,
@@ -432,7 +460,7 @@ export function Router(props: RouterProps = {}): ReactElement {
       collectionItemsMap,
       templateContext: null
     });
-  } else if (componentTree && awaitingCmsContext && previousComponentTree) {
+  } else if (treeToRender && awaitingCmsContext && previousComponentTree) {
     // While waiting for CMS context, show previous tree to avoid blink
     pageContent = renderPage({
       tree: previousComponentTree,