meno-core 1.0.53 → 1.1.0

package/lib/client/core/ComponentBuilder.ts

@@ -4,36 +4,59 @@
  * responsive styles, event handlers, and element registration.
  */
 
-import { createElement as h, Fragment } from "react";
-import type { ReactElement } from "react";
+import { createElement as h, Fragment } from 'react';
+import type { ReactElement } from 'react';
 
 // Component registry and utilities
-import { ComponentRegistry } from "../componentRegistry";
-import { processStructure } from "../templateEngine";
-import { NODE_TYPE } from "../../shared/constants";
-import { ErrorBoundary } from "../ErrorBoundary";
-import type { ComponentNode, StyleValue, StyleObject, ResponsiveStyleObject } from "../../shared/types";
-import { isComponentNode, extractNodeProperties, isSlotMarker, isEmbedNode, isLinkNode, isLocaleListNode, isListNode, markAsSlotContent, evaluateNodeIf, isBooleanMapping, hasIf, hasChildren, isSlotContent as isSlotContentNode } from "../../shared/nodeUtils";
-import { mergeNodeStyles } from "../../shared/styleNodeUtils";
-import { isCurrentLink } from "../../shared/linkUtils";
-import { extractAttributesFromNode, skipEmptyTemplateAttributes } from "../../shared/attributeNodeUtils";
-import { resolvePropsFromDefinition } from "../../shared/propResolver";
-import { ElementRegistry } from "../elementRegistry";
-import { InteractiveStylesRegistry } from "../InteractiveStylesRegistry";
-import type { Path } from "../../shared/pathArrayUtils";
-import type { I18nConfig } from "../../shared/types/components";
-import type { ItemContext, TemplateContext } from "../../shared/types/cms";
-import { processItemTemplate, processItemPropsTemplate, hasItemTemplates, type ValueResolver } from "../../shared/itemTemplateUtils";
-import { DEFAULT_I18N_CONFIG, isI18nValue, resolveI18nValue } from "../../shared/i18n";
-import { getChildPath, pathToString } from "../../shared/pathArrayUtils";
-import { responsiveStylesToClasses } from "../../shared/utilityClassMapper";
-import { getCachedResponsiveScalesConfig } from "../responsiveStyleResolver";
-import { UtilityClassCollector } from "../styles/UtilityClassCollector";
-import { processCMSTemplate, processCMSPropsTemplate, RAW_HTML_PREFIX } from "./cmsTemplateProcessor";
-import type { PrefetchService } from "../services/PrefetchService";
-import { generateElementClassName, type ElementClassContext } from "../../shared/elementClassName";
-import type { InteractiveStyles } from "../../shared/types/styles";
-import { extractInteractiveStyleMappings, resolveExtractedMappings, hasInteractiveStyleMappings } from "../../shared/interactiveStyleMappings";
+import type { ComponentRegistry } from '../componentRegistry';
+import { processStructure } from '../templateEngine';
+import { NODE_TYPE } from '../../shared/constants';
+import { ErrorBoundary } from '../ErrorBoundary';
+import type { ComponentNode, StyleValue, StyleObject, ResponsiveStyleObject } from '../../shared/types';
+import {
+  isComponentNode,
+  extractNodeProperties,
+  isSlotMarker,
+  isEmbedNode,
+  isLinkNode,
+  isLocaleListNode,
+  isListNode,
+  isIslandNode,
+  isCustomNode,
+  isValidNodeType,
+  markAsSlotContent,
+  isBooleanMapping,
+  hasIf,
+  hasChildren,
+  isSlotContent as isSlotContentNode,
+} from '../../shared/nodeUtils';
+import { mergeNodeStyles } from '../../shared/styleNodeUtils';
+import { isCurrentLink } from '../../shared/linkUtils';
+import { extractAttributesFromNode, skipEmptyTemplateAttributes } from '../../shared/attributeNodeUtils';
+import { resolvePropsFromDefinition } from '../../shared/propResolver';
+import type { ElementRegistry } from '../elementRegistry';
+import { InteractiveStylesRegistry } from '../InteractiveStylesRegistry';
+import type { Path } from '../../shared/pathArrayUtils';
+import {
+  processItemTemplate,
+  processItemPropsTemplate,
+  hasItemTemplates,
+  type ValueResolver,
+} from '../../shared/itemTemplateUtils';
+import { DEFAULT_I18N_CONFIG, isI18nValue, resolveI18nValue } from '../../shared/i18n';
+import { getChildPath, pathToString } from '../../shared/pathArrayUtils';
+import { responsiveStylesToClasses } from '../../shared/utilityClassMapper';
+import { getCachedResponsiveScalesConfig } from '../responsiveStyleResolver';
+import { UtilityClassCollector } from '../styles/UtilityClassCollector';
+import { processCMSTemplate, processCMSPropsTemplate, RAW_HTML_PREFIX } from './cmsTemplateProcessor';
+import type { PrefetchService } from '../services/PrefetchService';
+import { generateElementClassName, type ElementClassContext } from '../../shared/elementClassName';
+import type { InteractiveStyles } from '../../shared/types/styles';
+import {
+  extractInteractiveStyleMappings,
+  resolveExtractedMappings,
+  hasInteractiveStyleMappings,
+} from '../../shared/interactiveStyleMappings';
 
 // Extracted builders
 import {
@@ -46,10 +69,20 @@ import {
   buildLocaleList,
   buildList,
   buildLink,
-} from "./builders";
+} from './builders';
 
 type ComponentProps = Record<string, unknown>;
 
+/**
+ * Narrow processStructure's object result to a renderable node.
+ * processStructure returns a plain Record<string, unknown> when the input was
+ * not a node (e.g. a props object) — real nodes always carry a valid `type`
+ * discriminant. Non-node objects can't be rendered, so callers bail out.
+ */
+function isProcessedComponentNode(value: ComponentNode | Record<string, unknown>): value is ComponentNode {
+  return typeof value.type === 'string' && isValidNodeType(value.type);
+}
+
 // Document-structure tags can't nest inside <div id="root">: the HTML5 parser
 // hoists a nested <body>'s attributes onto the outer <body> and drops the tag,
 // so SSR and client-side (React createElement) end up with divergent DOMs.
@@ -101,12 +134,11 @@ export class ComponentBuilder {
     let cached = this.styleClassCache.get(style);
     if (!cached) {
       const scales = getCachedResponsiveScalesConfig();
-      const fluidActive =
-        scales?.enabled === true && scales?.mode === 'fluid';
-      cached = responsiveStylesToClasses(
-        style as StyleObject | ResponsiveStyleObject,
-        { fluidActive, responsiveScales: scales ?? undefined }
-      );
+      const fluidActive = scales?.enabled === true && scales?.mode === 'fluid';
+      cached = responsiveStylesToClasses(style as StyleObject | ResponsiveStyleObject, {
+        fluidActive,
+        responsiveScales: scales ?? undefined,
+      });
       this.styleClassCache.set(style, cached);
     }
     UtilityClassCollector.collect(cached);
@@ -128,7 +160,7 @@ export class ComponentBuilder {
   private getParentComponentNameForNestedComponent(
     componentContext: string | null,
     parentComponentName: string | null,
-    componentName: string | null
+    componentName: string | null,
   ): string | null {
     return componentContext || parentComponentName || componentName || null;
   }
@@ -138,7 +170,7 @@ export class ComponentBuilder {
    */
   private getEffectiveParentComponentName(
     componentContext: string | null,
-    parentComponentName: string | null
+    parentComponentName: string | null,
   ): string | null {
     return componentContext || parentComponentName;
   }
@@ -235,12 +267,24 @@ export class ComponentBuilder {
    */
   buildChildren(
     children: (string | ComponentNode)[] | string | ComponentNode | undefined,
-    ctx: BuildChildrenContext
+    ctx: BuildChildrenContext,
   ): ReactElement | ReactElement[] | string | number | null {
     const {
-      elementPath, parentComponentName, viewportWidth, componentContext, componentRootPath,
-      locale, i18nConfig, cmsContext, cmsLocale, collectionItemsMap,
-      itemContext, cmsItemIndexPath, cmsListPaths, templateContext, componentResolvedProps
+      elementPath,
+      parentComponentName,
+      viewportWidth,
+      componentContext,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext,
+      cmsLocale,
+      collectionItemsMap,
+      itemContext,
+      cmsItemIndexPath,
+      cmsListPaths,
+      templateContext,
+      componentResolvedProps,
     } = ctx;
 
     if (Array.isArray(children)) {
@@ -264,8 +308,8 @@ export class ComponentBuilder {
             cmsItemIndexPath,
             cmsListPaths,
             templateContext,
-            componentResolvedProps
-          })
+            componentResolvedProps,
+          }),
         )
         .filter((item): item is ReactElement | string | number => item !== null) as ReactElement[];
     }
@@ -287,7 +331,7 @@ export class ComponentBuilder {
       cmsItemIndexPath,
       cmsListPaths,
       templateContext,
-      componentResolvedProps
+      componentResolvedProps,
     });
   }
 
@@ -313,7 +357,7 @@ export class ComponentBuilder {
       templateContext = null,
       cmsItemIndexPath = null,
       cmsListPaths = null,
-      componentResolvedProps = null
+      componentResolvedProps = null,
     } = options;
 
     if (!node) return null;
@@ -340,9 +384,22 @@ export class ComponentBuilder {
 
     // Build context for specialized builders (needed for if condition evaluation)
     const ctx: BuilderContext = {
-      key, elementPath, parentComponentName, viewportWidth, componentContext, componentRootPath,
-      locale, i18nConfig, cmsContext, cmsLocale, collectionItemsMap,
-      itemContext, cmsItemIndexPath, cmsListPaths, templateContext, componentResolvedProps
+      key,
+      elementPath,
+      parentComponentName,
+      viewportWidth,
+      componentContext,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext,
+      cmsLocale,
+      collectionItemsMap,
+      itemContext,
+      cmsItemIndexPath,
+      cmsListPaths,
+      templateContext,
+      componentResolvedProps,
     };
 
     // Dependencies for specialized builders
@@ -380,7 +437,7 @@ export class ComponentBuilder {
 
     // Get node type
     const nodeType = typeof node === 'object' && node !== null && 'type' in node ? node.type : undefined;
-    const children = typeof node === 'object' && node !== null && 'children' in node ? (node.children || []) : [];
+    const children = typeof node === 'object' && node !== null && 'children' in node ? node.children || [] : [];
 
     // Handle specialized node types using extracted builders
     if (nodeType === NODE_TYPE.EMBED && isEmbedNode(node)) {
@@ -395,6 +452,20 @@ export class ComponentBuilder {
       return buildLocaleList(node, ctx, builderDeps);
     }
 
+    // Islands (BYO framework components) and Custom nodes (opaque hand-authored
+    // `.astro` black boxes) can't run in meno-core — real rendering is play/build
+    // only. On the canvas we render their slotted children as normal content (so
+    // such pages read cleanly) and fall back to a quiet inline marker when there
+    // are none. The wrapper carries `data-element-path` so a click selects the
+    // node itself (like any other), plus `data-island`/`data-custom` for
+    // identification — but draws no highlight box.
+    if (nodeType === NODE_TYPE.ISLAND && isIslandNode(node)) {
+      return this.buildBlackBoxNode(node, 'data-island', /\.(tsx|jsx|vue|svelte)$/i, options);
+    }
+    if (nodeType === NODE_TYPE.CUSTOM && isCustomNode(node)) {
+      return this.buildBlackBoxNode(node, 'data-custom', /\.astro$/i, options);
+    }
+
     // Handle List nodes (unified - handles both prop and collection source types)
     // isListNode() also matches legacy 'cms-list' type for migration
     if (isListNode(node)) {
@@ -429,23 +500,27 @@ export class ComponentBuilder {
       if (process.env.NODE_ENV !== 'production') {
         console.warn(
           `[Meno] Component "${componentName}" not found in registry. ` +
-          `Registered: [${this.componentRegistry.getNames().join(', ')}]`
+            `Registered: [${this.componentRegistry.getNames().join(', ')}]`,
         );
       }
-      return h('div', {
-        key,
-        style: {
-          border: '1px dashed #e5a00d',
-          padding: '8px 12px',
-          margin: '4px 0',
-          borderRadius: '4px',
-          color: '#b8860b',
-          fontSize: '13px',
-          fontFamily: 'monospace',
-          background: '#fffbe6',
+      return h(
+        'div',
+        {
+          key,
+          style: {
+            border: '1px dashed #e5a00d',
+            padding: '8px 12px',
+            margin: '4px 0',
+            borderRadius: '4px',
+            color: '#b8860b',
+            fontSize: '13px',
+            fontFamily: 'monospace',
+            background: '#fffbe6',
+          },
+          'data-missing-component': componentName,
         },
-        'data-missing-component': componentName,
-      }, `Component not found: ${componentName}`);
+        `Component not found: ${componentName}`,
+      );
     }
 
     // Handle Link component
@@ -472,20 +547,25 @@ export class ComponentBuilder {
     const markerRegex = /<div\s+data-meno-component="([^"]+)"\s+data-meno-props="([^"]*)"[^>]*><\/div>/g;
     const segments: ReactElement[] = [];
     let lastIndex = 0;
-    let match: RegExpExecArray | null;
+    let match: RegExpExecArray | null = markerRegex.exec(html);
     let segmentIndex = 0;
 
-    while ((match = markerRegex.exec(html)) !== null) {
+    while (match !== null) {
+      const currentMatch = match;
+      match = markerRegex.exec(html);
       // Add HTML before this match
-      if (match.index > lastIndex) {
-        const chunk = html.slice(lastIndex, match.index);
+      if (currentMatch.index > lastIndex) {
+        const chunk = html.slice(lastIndex, currentMatch.index);
         segments.push(h('span', { key: `rt-${segmentIndex++}`, dangerouslySetInnerHTML: { __html: chunk } }));
       }
 
-      const componentName = match[1];
+      const componentName = currentMatch[1];
+      if (componentName === undefined) {
+        continue;
+      }
       let props: Record<string, unknown> = {};
       try {
-        const propsStr = match[2]
+        const propsStr = (currentMatch[2] ?? '')
           .replace(/&quot;/g, '"')
           .replace(/&#039;/g, "'")
           .replace(/&amp;/g, '&');
@@ -527,16 +607,18 @@ export class ComponentBuilder {
         }
       } else {
         // Keep marker as-is for unregistered components
-        segments.push(h('span', { key: `rt-${segmentIndex}`, dangerouslySetInnerHTML: { __html: match[0] } }));
+        segments.push(h('span', { key: `rt-${segmentIndex}`, dangerouslySetInnerHTML: { __html: currentMatch[0] } }));
       }
 
       segmentIndex++;
-      lastIndex = match.index + match[0].length;
+      lastIndex = currentMatch.index + currentMatch[0].length;
     }
 
     // Add remaining HTML
     if (lastIndex < html.length) {
-      segments.push(h('span', { key: `rt-${segmentIndex}`, dangerouslySetInnerHTML: { __html: html.slice(lastIndex) } }));
+      segments.push(
+        h('span', { key: `rt-${segmentIndex}`, dangerouslySetInnerHTML: { __html: html.slice(lastIndex) } }),
+      );
     }
 
     return h(Fragment, null, ...segments);
@@ -580,34 +662,47 @@ export class ComponentBuilder {
    */
   private buildNodeArray(nodes: ComponentNode[], options: BuildComponentOptions): ReactElement[] {
     const {
-      customProps, elementPath = [0], parentComponentName = null, viewportWidth = 1920,
-      componentContext = null, locale, i18nConfig, cmsContext = null, cmsLocale = null,
-      collectionItemsMap = {}, itemContext = null, cmsItemIndexPath = null,
-      cmsListPaths = null, templateContext = null, componentResolvedProps = null
+      customProps,
+      elementPath = [0],
+      parentComponentName = null,
+      viewportWidth = 1920,
+      componentContext = null,
+      locale,
+      i18nConfig,
+      cmsContext = null,
+      cmsLocale = null,
+      collectionItemsMap = {},
+      itemContext = null,
+      cmsItemIndexPath = null,
+      cmsListPaths = null,
+      templateContext = null,
+      componentResolvedProps = null,
     } = options;
 
-    return nodes.map((child, index) => {
-      const childPath = getChildPath(elementPath, index);
-      return this.buildComponent({
-        node: child,
-        key: index,
-        customProps,
-        elementPath: childPath,
-        parentComponentName,
-        viewportWidth,
-        componentContext,
-        locale,
-        i18nConfig,
-        cmsContext,
-        cmsLocale,
-        collectionItemsMap,
-        itemContext,
-        cmsItemIndexPath,
-        cmsListPaths,
-        templateContext,
-        componentResolvedProps
-      });
-    }).filter((item): item is ReactElement => item !== null && typeof item === 'object');
+    return nodes
+      .map((child, index) => {
+        const childPath = getChildPath(elementPath, index);
+        return this.buildComponent({
+          node: child,
+          key: index,
+          customProps,
+          elementPath: childPath,
+          parentComponentName,
+          viewportWidth,
+          componentContext,
+          locale,
+          i18nConfig,
+          cmsContext,
+          cmsLocale,
+          collectionItemsMap,
+          itemContext,
+          cmsItemIndexPath,
+          cmsListPaths,
+          templateContext,
+          componentResolvedProps,
+        });
+      })
+      .filter((item): item is ReactElement => item !== null && typeof item === 'object');
   }
 
   /**
@@ -659,7 +754,11 @@ export class ComponentBuilder {
   /**
    * Apply style classes to props
    */
-  private applyStyleClasses(props: Record<string, unknown>, node: ComponentNode, ctx: BuilderContext): Record<string, unknown> {
+  private applyStyleClasses(
+    props: Record<string, unknown>,
+    node: ComponentNode,
+    ctx: BuilderContext,
+  ): Record<string, unknown> {
     const nodeStyle = node.style || (isComponentNode(node) ? node.props?.style : undefined);
 
     if (nodeStyle && typeof nodeStyle === 'object') {
@@ -678,7 +777,11 @@ export class ComponentBuilder {
       if (utilityClasses.length > 0) {
         const existingClassName = (props.className || '') as string;
         const classArray = existingClassName ? existingClassName.split(/\s+/) : [];
-        return { ...props, className: [...classArray, ...utilityClasses].filter(Boolean).join(' '), style: processedStyle };
+        return {
+          ...props,
+          className: [...classArray, ...utilityClasses].filter(Boolean).join(' '),
+          style: processedStyle,
+        };
       }
     }
 
@@ -688,10 +791,16 @@ export class ComponentBuilder {
   /**
    * Apply interactive styles and generate element class
    */
-  private applyInteractiveStyles(props: Record<string, unknown>, node: ComponentNode, ctx: BuilderContext): Record<string, unknown> {
-    const nodeInteractiveStyles = 'interactiveStyles' in node ? node.interactiveStyles as InteractiveStyles | undefined : undefined;
-    const nodeGenerateElementClass = 'generateElementClass' in node ? node.generateElementClass as boolean | undefined : undefined;
-    const nodeLabel = 'label' in node ? node.label as string | undefined : undefined;
+  private applyInteractiveStyles(
+    props: Record<string, unknown>,
+    node: ComponentNode,
+    ctx: BuilderContext,
+  ): Record<string, unknown> {
+    const nodeInteractiveStyles =
+      'interactiveStyles' in node ? (node.interactiveStyles as InteractiveStyles | undefined) : undefined;
+    const nodeGenerateElementClass =
+      'generateElementClass' in node ? (node.generateElementClass as boolean | undefined) : undefined;
+    const nodeLabel = 'label' in node ? (node.label as string | undefined) : undefined;
 
     if (!((nodeInteractiveStyles && nodeInteractiveStyles.length > 0) || nodeGenerateElementClass)) {
       return props;
@@ -700,11 +809,16 @@ export class ComponentBuilder {
     // Check if slot content
     const isSlotContent = isSlotContentNode(node);
     const useComponentContext = ctx.componentContext && !isSlotContent;
-    const fileType = useComponentContext ? 'component' : (this.getCurrentFileType?.() || 'page');
-    const fileName = useComponentContext ? ctx.componentContext! : (this.getCurrentPageName ? this.getCurrentPageName() : 'page');
-    const pathForClass = useComponentContext && ctx.componentRootPath
-      ? ctx.elementPath.slice(ctx.componentRootPath.length)
-      : ctx.elementPath;
+    const fileType = useComponentContext ? 'component' : this.getCurrentFileType?.() || 'page';
+    const fileName = useComponentContext
+      ? ctx.componentContext!
+      : this.getCurrentPageName
+        ? this.getCurrentPageName()
+        : 'page';
+    const pathForClass =
+      useComponentContext && ctx.componentRootPath
+        ? ctx.elementPath.slice(ctx.componentRootPath.length)
+        : ctx.elementPath;
 
     const elementClassCtx: ElementClassContext = {
       fileType,
@@ -755,7 +869,11 @@ export class ComponentBuilder {
    * objects on attribute values to the active locale's string before
    * downstream template / CMS processing, mirroring the SSR path.
    */
-  private mergeAttributes(props: Record<string, unknown>, node: ComponentNode, ctx: BuilderContext): Record<string, unknown> {
+  private mergeAttributes(
+    props: Record<string, unknown>,
+    node: ComponentNode,
+    ctx: BuilderContext,
+  ): Record<string, unknown> {
     let extractedAttributes = extractAttributesFromNode(node) as Record<string, unknown>;
     const attrI18nConfig = ctx.i18nConfig ?? DEFAULT_I18N_CONFIG;
     const attrEffectiveLocale = ctx.locale || attrI18nConfig.defaultLocale;
@@ -772,7 +890,7 @@ export class ComponentBuilder {
       extractedAttributes = processCMSPropsTemplate(
         extractedAttributes as Record<string, unknown>,
         ctx.cmsContext,
-        ctx.cmsLocale || ctx.locale
+        ctx.cmsLocale || ctx.locale,
       ) as Record<string, string | number | boolean>;
     }
 
@@ -784,25 +902,38 @@ export class ComponentBuilder {
       const i18nResolver: ValueResolver | undefined = effectiveLocale
         ? (value: unknown) => resolveI18nValue(value, effectiveLocale, config)
         : undefined;
-      extractedAttributes = processItemPropsTemplate(extractedAttributes, effectiveItemContext, i18nResolver) as Record<string, string | number | boolean>;
+      extractedAttributes = processItemPropsTemplate(extractedAttributes, effectiveItemContext, i18nResolver) as Record<
+        string,
+        string | number | boolean
+      >;
     }
 
     // Auto-skip attributes that were entirely template expressions and resolved to ""
     if (Object.keys(extractedAttributes).length > 0) {
-      extractedAttributes = skipEmptyTemplateAttributes(originalAttributes, extractedAttributes) as Record<string, string | number | boolean>;
+      extractedAttributes = skipEmptyTemplateAttributes(originalAttributes, extractedAttributes) as Record<
+        string,
+        string | number | boolean
+      >;
     }
 
     if (Object.keys(extractedAttributes).length === 0) {
       return props;
     }
 
-    let result = { ...props };
+    const result = { ...props };
 
     // Handle class/className specially - check key existence, not truthiness (empty string is valid)
     if ('class' in extractedAttributes || 'className' in extractedAttributes) {
       const attrClass = (extractedAttributes.class ?? extractedAttributes.className ?? '') as string;
       const existingClassName = (result.className || '') as string;
       result.className = [existingClassName, attrClass].filter(Boolean).join(' ');
+      // Class-string styling: utility tokens stored in attributes.class (e.g. p-[24px],
+      // tablet:p-[16px]) must inject their CSS into the live canvas, exactly like the
+      // node.style → getCachedStyleClasses path does. Without this the class lands on the
+      // element but renders unstyled. collect() skips foreign tokens (swiper, prose) that
+      // generate no rule, so passing the whole token list is safe.
+      const classTokens = attrClass.split(/\s+/).filter(Boolean);
+      if (classTokens.length > 0) UtilityClassCollector.collect(classTokens);
       delete extractedAttributes.class;
       delete extractedAttributes.className;
     }
@@ -818,6 +949,81 @@ export class ComponentBuilder {
     return { ...result, ...normalizedAttributes };
   }
 
+  /**
+   * Build the canvas placeholder for a "black box" node (Island / Custom) that
+   * meno-core can't actually run. Renders the node's slotted children as normal
+   * content, or a quiet inline marker when there are none. The wrapper carries
+   * `data-element-path` (and CMS-list context, when inside one) via a ref so a
+   * click resolves to this node and selects it like any regular element — even
+   * though the `display:contents` wrapper itself draws no box.
+   */
+  private buildBlackBoxNode(
+    node: ComponentNode,
+    dataAttr: 'data-island' | 'data-custom',
+    extPattern: RegExp,
+    options: BuildComponentOptions,
+  ): ReactElement {
+    const {
+      key = 0,
+      elementPath = [0],
+      parentComponentName = null,
+      viewportWidth = 1920,
+      componentContext = null,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext = null,
+      cmsLocale = null,
+      collectionItemsMap = {},
+      itemContext = null,
+      cmsItemIndexPath = null,
+      cmsListPaths = null,
+      templateContext = null,
+      componentResolvedProps = null,
+    } = options;
+
+    const src = 'src' in node && typeof node.src === 'string' ? node.src : '';
+    const name = src.split('/').pop()?.replace(extPattern, '') || '?';
+    const childNodes = 'children' in node ? node.children : undefined;
+    const hasChildNodes =
+      (Array.isArray(childNodes) && childNodes.length > 0) || (typeof childNodes === 'string' && childNodes.length > 0);
+    const inner = hasChildNodes
+      ? this.buildChildren(childNodes as (string | ComponentNode)[] | string, {
+          elementPath,
+          parentComponentName,
+          viewportWidth,
+          componentContext,
+          componentRootPath,
+          locale,
+          i18nConfig,
+          cmsContext,
+          cmsLocale,
+          collectionItemsMap,
+          itemContext,
+          cmsItemIndexPath,
+          cmsListPaths,
+          templateContext,
+          componentResolvedProps,
+        })
+      : h('span', { style: { color: '#9ca3af', fontSize: '13px' } }, name);
+
+    const ref = (el: HTMLElement | null) => {
+      if (!el) return;
+      el.setAttribute('data-element-path', pathToString(elementPath));
+      if (cmsItemIndexPath && cmsItemIndexPath.length > 0) {
+        el.setAttribute('data-cms-item-index', cmsItemIndexPath.join('.'));
+        if (cmsListPaths && cmsListPaths.length === cmsItemIndexPath.length) {
+          el.setAttribute(
+            'data-cms-context',
+            JSON.stringify({ itemIndexPath: cmsItemIndexPath, listPaths: cmsListPaths }),
+          );
+        }
+      }
+    };
+
+    return h('div', { key, [dataAttr]: src, style: { display: 'contents' }, ref }, inner);
+  }
+
   /**
    * Build a custom component
    */
@@ -826,18 +1032,28 @@ export class ComponentBuilder {
     nodeProps: Record<string, unknown>,
     children: unknown,
     finalProps: Record<string, unknown>,
-    options: BuildComponentOptions
+    options: BuildComponentOptions,
   ): ReactElement | null {
     const {
-      key = 0, elementPath = [0], parentComponentName = null, viewportWidth = 1920,
-      componentContext = null, locale, i18nConfig, cmsContext = null, cmsLocale = null,
-      collectionItemsMap = {}, itemContext = null, cmsItemIndexPath = null,
-      cmsListPaths = null, templateContext = null,
+      key = 0,
+      elementPath = [0],
+      parentComponentName = null,
+      viewportWidth = 1920,
+      componentContext = null,
+      locale,
+      i18nConfig,
+      cmsContext = null,
+      cmsLocale = null,
+      collectionItemsMap = {},
+      itemContext = null,
+      cmsItemIndexPath = null,
+      cmsListPaths = null,
+      templateContext = null,
       // The host (outer) component's resolved props. Forwarded to
       // `processStructure` as `parentProps` so a `{{x}}` in this
       // component's structure falls back to the host's `x` when this
       // component's interface doesn't declare it.
-      componentResolvedProps: parentResolvedProps = null
+      componentResolvedProps: parentResolvedProps = null,
     } = options;
 
     const componentDef = this.componentRegistry.get(componentName);
@@ -870,12 +1086,12 @@ export class ComponentBuilder {
       }
 
       // Resolve props (validate, coerce types, apply defaults) AFTER templates are resolved
-      let resolvedProps = resolvePropsFromDefinition(
+      const resolvedProps = resolvePropsFromDefinition(
         structuredComponentDef,
         propsToResolve,
         children as ComponentNode | string | (ComponentNode | string)[] | null | undefined,
         locale,
-        i18nConfig
+        i18nConfig,
       );
 
       // Process structure
@@ -889,10 +1105,16 @@ export class ComponentBuilder {
           parentProps: parentResolvedProps ?? undefined,
         },
         viewportWidth,
-        markedChildren
+        markedChildren,
       );
 
-      if (!processedStructure || typeof processedStructure === 'string' || typeof processedStructure === 'number' || Array.isArray(processedStructure)) {
+      if (
+        !processedStructure ||
+        typeof processedStructure === 'string' ||
+        typeof processedStructure === 'number' ||
+        Array.isArray(processedStructure) ||
+        !isProcessedComponentNode(processedStructure)
+      ) {
         return null;
       }
 
@@ -910,13 +1132,13 @@ export class ComponentBuilder {
       const nestedParentComponentName = this.getParentComponentNameForNestedComponent(
         componentContext,
         parentComponentName,
-        componentName
+        componentName,
       );
 
       const componentElement = this.buildComponent({
         node: processedStructure,
         key,
-        customProps: { '__componentProps': resolvedProps },
+        customProps: { __componentProps: resolvedProps },
         elementPath,
         parentComponentName: nestedParentComponentName,
         viewportWidth,
@@ -931,12 +1153,11 @@ export class ComponentBuilder {
         cmsItemIndexPath,
         cmsListPaths,
         templateContext,
-        componentResolvedProps: resolvedProps
+        componentResolvedProps: resolvedProps,
       });
 
       return h(ErrorBoundary, { key, componentName, level: 'component' }, componentElement);
-
-    } catch (error) {
+    } catch (_error) {
       return h(ErrorBoundary, { key, componentName, level: 'component' }, null);
     }
   }
@@ -949,19 +1170,30 @@ export class ComponentBuilder {
     props: Record<string, unknown>,
     children: unknown,
     customProps: ComponentProps,
-    options: BuildComponentOptions
+    options: BuildComponentOptions,
   ): ReactElement | null {
     const {
-      key = 0, elementPath = [0], parentComponentName = null, viewportWidth = 1920,
-      componentContext = null, componentRootPath, locale, i18nConfig,
-      cmsContext = null, cmsLocale = null, collectionItemsMap = {},
-      itemContext = null, cmsItemIndexPath = null, cmsListPaths = null,
-      templateContext = null, componentResolvedProps = null,
-      isSlotContent = false
+      key = 0,
+      elementPath = [0],
+      parentComponentName = null,
+      viewportWidth = 1920,
+      componentContext = null,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext = null,
+      cmsLocale = null,
+      collectionItemsMap = {},
+      itemContext = null,
+      cmsItemIndexPath = null,
+      cmsListPaths = null,
+      templateContext = null,
+      componentResolvedProps = null,
+      isSlotContent = false,
     } = options;
 
     const requestedTag = (tag || 'div').toLowerCase();
-    const finalTag = DOCUMENT_STRUCTURE_TAGS.has(requestedTag) ? 'div' : (tag || 'div');
+    const finalTag = DOCUMENT_STRUCTURE_TAGS.has(requestedTag) ? 'div' : tag || 'div';
     const effectiveParentComponentName = this.getEffectiveParentComponentName(componentContext, parentComponentName);
 
     // Remove __componentProps from customProps before spreading
@@ -975,8 +1207,11 @@ export class ComponentBuilder {
     // (buildCustomComponent reads finalProps.style via mergeNodeStyles).
     let propsForElement = props;
     const nodeStyle = props.style;
-    if (nodeStyle && typeof nodeStyle === 'object' &&
-        ('base' in (nodeStyle as object) || 'tablet' in (nodeStyle as object) || 'mobile' in (nodeStyle as object))) {
+    if (
+      nodeStyle &&
+      typeof nodeStyle === 'object' &&
+      ('base' in (nodeStyle as object) || 'tablet' in (nodeStyle as object) || 'mobile' in (nodeStyle as object))
+    ) {
       const { style: _, ...rest } = props;
       propsForElement = rest;
     }
@@ -984,7 +1219,7 @@ export class ComponentBuilder {
     const processedProps: Record<string, unknown> = {
       ...propsForElement,
       ...customPropsForDOM,
-      key
+      key,
     };
 
     // Add is-current class for <a> tags when href matches current page path
@@ -1004,10 +1239,13 @@ export class ComponentBuilder {
           el.setAttribute('data-cms-item-index', cmsItemIndexPath.join('.'));
           // Set full CMS context as JSON for nested CMS list support
           if (cmsListPaths && cmsListPaths.length === cmsItemIndexPath.length) {
-            el.setAttribute('data-cms-context', JSON.stringify({
-              itemIndexPath: cmsItemIndexPath,
-              listPaths: cmsListPaths
-            }));
+            el.setAttribute(
+              'data-cms-context',
+              JSON.stringify({
+                itemIndexPath: cmsItemIndexPath,
+                listPaths: cmsListPaths,
+              }),
+            );
           }
         }
         if (isComponentRoot) el.setAttribute('data-component-root', 'true');
@@ -1021,9 +1259,7 @@ export class ComponentBuilder {
           const componentDef = this.componentRegistry.get(componentContext);
           const defineVars = componentDef?.component?.defineVars;
           if (defineVars && customProps.__componentProps) {
-            const varsToExpose = defineVars === true
-              ? Object.keys(componentDef.component.interface || {})
-              : defineVars;
+            const varsToExpose = defineVars === true ? Object.keys(componentDef.component.interface || {}) : defineVars;
 
             const propsForJS: Record<string, unknown> = {};
             const resolvedProps = customProps.__componentProps as Record<string, unknown>;
@@ -1047,17 +1283,25 @@ export class ComponentBuilder {
         }
       }
 
-      const componentProps = isComponentRoot && customProps.__componentProps
-        ? customProps.__componentProps as Record<string, unknown>
-        : undefined;
+      const componentProps =
+        isComponentRoot && customProps.__componentProps
+          ? (customProps.__componentProps as Record<string, unknown>)
+          : undefined;
       const componentNameForRegistry = isComponentRoot ? componentContext : parentComponentName;
 
       const metadata = {
         parentComponentName: parentComponentName ?? null,
-        componentContext: componentContext ?? null
+        componentContext: componentContext ?? null,
       };
 
-      this.elementRegistry.register(elementPath, el, componentNameForRegistry, isComponentRoot, componentProps, metadata);
+      this.elementRegistry.register(
+        elementPath,
+        el,
+        componentNameForRegistry,
+        isComponentRoot,
+        componentProps,
+        metadata,
+      );
     };
 
     // Add onClick handler
@@ -1066,7 +1310,22 @@ export class ComponentBuilder {
     }
 
     // HTML void elements
-    const VOID_ELEMENTS = ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'];
+    const VOID_ELEMENTS = [
+      'area',
+      'base',
+      'br',
+      'col',
+      'embed',
+      'hr',
+      'img',
+      'input',
+      'link',
+      'meta',
+      'param',
+      'source',
+      'track',
+      'wbr',
+    ];
     if (VOID_ELEMENTS.includes(finalTag.toLowerCase())) {
       const { children: _ignored, ...voidElementProps } = processedProps;
       return h(finalTag, voidElementProps);
@@ -1074,8 +1333,21 @@ export class ComponentBuilder {
 
     // Build children
     const childElements = this.buildChildren(children as (ComponentNode | string)[], {
-      elementPath, parentComponentName: effectiveParentComponentName, viewportWidth, componentContext, componentRootPath,
-      locale, i18nConfig, cmsContext, cmsLocale, collectionItemsMap, itemContext, cmsItemIndexPath, cmsListPaths, templateContext, componentResolvedProps
+      elementPath,
+      parentComponentName: effectiveParentComponentName,
+      viewportWidth,
+      componentContext,
+      componentRootPath,
+      locale,
+      i18nConfig,
+      cmsContext,
+      cmsLocale,
+      collectionItemsMap,
+      itemContext,
+      cmsItemIndexPath,
+      cmsListPaths,
+      templateContext,
+      componentResolvedProps,
     });
 
     return h(finalTag, processedProps, childElements);