meno-core 1.0.21 → 1.0.22

package/lib/client/core/ComponentBuilder.ts

@@ -362,7 +362,7 @@ export class ComponentBuilder {
     const processedProps = this.processPropsTemplates(props, ctx);
 
     // Convert styles to utility classes
-    const propsWithClasses = this.applyStyleClasses(processedProps, node);
+    const propsWithClasses = this.applyStyleClasses(processedProps, node, ctx);
 
     // Apply interactive styles
     const propsWithInteractive = this.applyInteractiveStyles(propsWithClasses, node, ctx);
@@ -502,11 +502,22 @@ export class ComponentBuilder {
   /**
    * Apply style classes to props
    */
-  private applyStyleClasses(props: Record<string, unknown>, node: ComponentNode): 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') {
-      const utilityClasses = this.getCachedStyleClasses(nodeStyle);
+      // Process item templates in style values (for List context)
+      let processedStyle = nodeStyle as Record<string, unknown>;
+      const templateCtx = ctx.templateContext || ctx.itemContext;
+      if (templateCtx) {
+        const effectiveLocale = ctx.cmsLocale || ctx.locale;
+        const config = ctx.i18nConfig || DEFAULT_I18N_CONFIG;
+        const i18nResolver: ValueResolver | undefined = effectiveLocale
+          ? (value: unknown) => resolveI18nValue(value, effectiveLocale, config)
+          : undefined;
+        processedStyle = processItemPropsTemplate(processedStyle, templateCtx, i18nResolver);
+      }
+      const utilityClasses = this.getCachedStyleClasses(processedStyle);
       if (utilityClasses.length > 0) {
         const existingClassName = (props.className || '') as string;
         const classArray = existingClassName ? existingClassName.split(/\s+/) : [];

package/lib/client/core/builders/embedBuilder.ts

@@ -15,7 +15,8 @@ import { hasInteractiveStyleMappings, extractInteractiveStyleMappings, resolveEx
 import DOMPurify from "isomorphic-dompurify";
 import type { ElementRegistry } from "../../elementRegistry";
 import type { BuilderContext } from "./types";
-import { hasItemTemplates, processItemTemplate } from "../../../shared/itemTemplateUtils";
+import { hasItemTemplates, processItemTemplate, processItemPropsTemplate, type ValueResolver } from "../../../shared/itemTemplateUtils";
+import { resolveI18nValue, DEFAULT_I18N_CONFIG } from "../../../shared/i18n";
 
 export interface EmbedBuilderDeps {
   elementRegistry: ElementRegistry;
@@ -55,7 +56,13 @@ export function buildEmbed(
 
   // Process item template strings (for List context) - e.g., {{item.icon}}, {{feature.title}}
   if (ctx.templateContext && hasItemTemplates(htmlContent)) {
-    htmlContent = processItemTemplate(htmlContent, ctx.templateContext);
+    // Create i18n resolver for template processing (matching SSR behavior)
+    const effectiveLocale = ctx.cmsLocale || ctx.locale;
+    const i18nConfig = ctx.i18nConfig || DEFAULT_I18N_CONFIG;
+    const i18nResolver: ValueResolver | undefined = effectiveLocale
+      ? (value: unknown) => resolveI18nValue(value, effectiveLocale, i18nConfig)
+      : undefined;
+    htmlContent = processItemTemplate(htmlContent, ctx.templateContext, i18nResolver);
   }
 
   // Sanitize HTML with allowlist
@@ -95,7 +102,22 @@ export function buildEmbed(
 
   // Convert embed styles to utility classes
   if (node.style) {
-    const utilityClasses = responsiveStylesToClasses(node.style as StyleObject | ResponsiveStyleObject);
+    // Process item templates in style values (for List context)
+    let processedStyle = node.style;
+    if (ctx.templateContext) {
+      // Create i18n resolver for style template processing (matching SSR behavior)
+      const effectiveLocale = ctx.cmsLocale || ctx.locale;
+      const i18nConfig = ctx.i18nConfig || DEFAULT_I18N_CONFIG;
+      const i18nResolver: ValueResolver | undefined = effectiveLocale
+        ? (value: unknown) => resolveI18nValue(value, effectiveLocale, i18nConfig)
+        : undefined;
+      processedStyle = processItemPropsTemplate(
+        node.style as Record<string, unknown>,
+        ctx.templateContext,
+        i18nResolver
+      ) as StyleObject | ResponsiveStyleObject;
+    }
+    const utilityClasses = responsiveStylesToClasses(processedStyle as StyleObject | ResponsiveStyleObject);
     classNames.push(...utilityClasses);
   }
 

package/lib/client/core/builders/linkNodeBuilder.ts

@@ -12,6 +12,8 @@ import { pathToString } from "../../../shared/pathArrayUtils";
 import { generateElementClassName, type ElementClassContext } from "../../../shared/elementClassName";
 import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
 import { hasInteractiveStyleMappings, extractInteractiveStyleMappings, resolveExtractedMappings } from "../../../shared/interactiveStyleMappings";
+import { processItemPropsTemplate, type ValueResolver } from "../../../shared/itemTemplateUtils";
+import { resolveI18nValue, DEFAULT_I18N_CONFIG } from "../../../shared/i18n";
 import type { ElementRegistry } from "../../elementRegistry";
 import type { BuilderContext, BuildResult, BuildChildrenContext } from "./types";
 
@@ -80,7 +82,22 @@ export function buildLinkNode(
 
   // Convert link node styles to utility classes
   if (node.style) {
-    const utilityClasses = responsiveStylesToClasses(node.style as StyleObject | ResponsiveStyleObject);
+    // Process item templates in style values (for List context)
+    let processedStyle = node.style;
+    if (ctx.templateContext) {
+      // Create i18n resolver for style template processing (matching SSR behavior)
+      const effectiveLocale = ctx.cmsLocale || ctx.locale;
+      const i18nConfig = ctx.i18nConfig || DEFAULT_I18N_CONFIG;
+      const i18nResolver: ValueResolver | undefined = effectiveLocale
+        ? (value: unknown) => resolveI18nValue(value, effectiveLocale, i18nConfig)
+        : undefined;
+      processedStyle = processItemPropsTemplate(
+        node.style as Record<string, unknown>,
+        ctx.templateContext,
+        i18nResolver
+      ) as StyleObject | ResponsiveStyleObject;
+    }
+    const utilityClasses = responsiveStylesToClasses(processedStyle as StyleObject | ResponsiveStyleObject);
     classNames.push(...utilityClasses);
   }
 

package/lib/client/core/builders/listBuilder.ts

@@ -5,7 +5,7 @@
  * - CMS collections (sourceType: 'collection')
  */
 
-import { createElement as h } from "react";
+import { createElement as h, Fragment } from "react";
 import type { ReactElement } from "react";
 import type { ListNode } from "../../../shared/registry/nodeTypes/ListNodeType";
 import type { CMSItem, CMSFilterCondition, CMSSortConfig, CMSFilterOperator } from "../../../shared/types/cms";
@@ -221,8 +221,8 @@ export function buildList(
   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';
+  // Use configurable tag (defaults to 'div') - null means fragment mode (no wrapper)
+  const tag = node.tag === false ? null : (node.tag || 'div');
 
   if (!source && !sourceIsResolved) {
     // No source - render empty container with placeholder
@@ -239,6 +239,9 @@ export function buildList(
         textAlign: 'center'
       }
     }, `${label}: No source - No items`);
+    if (tag === null) {
+      return emptyState;
+    }
     return h(tag, containerProps, emptyState);
   }
 
@@ -257,6 +260,9 @@ export function buildList(
         textAlign: 'center'
       }
     }, `${label}: ${source || 'resolved'} - No items`);
+    if (tag === null) {
+      return emptyState;
+    }
     return h(tag, containerProps, emptyState);
   }
 
@@ -316,6 +322,9 @@ export function buildList(
     }
   }
 
+  if (tag === null) {
+    return h(Fragment, null, renderedItems);
+  }
   return h(tag, containerProps, renderedItems);
 }
 

package/lib/client/templateEngine.ts

@@ -167,6 +167,71 @@ export function resolveStyleMapping(
   return mappedValue !== undefined ? mappedValue : undefined;
 }
 
+/**
+ * Process a single style value - resolves mappings and evaluates templates.
+ * Skips item templates ({{item.field}}, {{varName.field}}) which are resolved later during rendering.
+ *
+ * @param styleValue - The style value to process (may be string, number, or mapping object)
+ * @param props - Component props for resolving mappings and templates
+ * @returns The processed style value, or undefined if the value should be skipped
+ */
+function processStyleValue(
+  styleValue: unknown,
+  props: Record<string, unknown> | undefined
+): string | number | undefined {
+  // First try style mapping resolution
+  const resolved = resolveStyleMapping(styleValue, props);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+
+  // String values - evaluate templates (but skip item templates)
+  if (typeof styleValue === 'string') {
+    if (hasTemplates(styleValue) && !hasItemTemplates(styleValue)) {
+      return processCodeTemplates(styleValue, props);
+    }
+    return styleValue;
+  }
+
+  // Number values - pass through
+  if (typeof styleValue === 'number') {
+    return styleValue;
+  }
+
+  return undefined;
+}
+
+/**
+ * Build evaluation context for template processing.
+ * Merges global context, props, componentDef, and optionally itemContext.
+ *
+ * @param context - The TemplateContext containing props and componentDef
+ * @param includeItemContext - Whether to include itemContext from the context object
+ * @returns A flat object suitable for template evaluation
+ */
+function buildEvalContext(
+  context: TemplateContext,
+  includeItemContext: boolean = false
+): Record<string, unknown> {
+  const evalContext: Record<string, unknown> = {
+    ...getGlobalTemplateContext(),
+    ...context.props
+  };
+
+  if (context.componentDef && typeof context.componentDef === 'object') {
+    Object.assign(evalContext, context.componentDef as Record<string, unknown>);
+  }
+
+  if (includeItemContext) {
+    const itemContext = (context as Record<string, unknown>).itemContext as Record<string, unknown> | undefined;
+    if (itemContext) {
+      Object.assign(evalContext, itemContext);
+    }
+  }
+
+  return evalContext;
+}
+
 /** Maximum allowed expression length to prevent DoS via complex expressions */
 const MAX_EXPRESSION_LENGTH = 500;
 
@@ -315,22 +380,8 @@ export function processStructure(
     }
 
     if (typeof structure === 'string') {
-      // Build evaluation context from TemplateContext
-      // Start with global context, then merge props (props take precedence)
-      const evalContext: Record<string, unknown> = { ...getGlobalTemplateContext(), ...context.props };
-
-      // Add componentDef properties to context (for backward compatibility)
-      if (context.componentDef && typeof context.componentDef === 'object') {
-        Object.assign(evalContext, context.componentDef as Record<string, unknown>);
-      }
-
-      // Add parent cms-list item context for nested template resolution
-      // This enables {{item.field}} in components rendered inside cms-list
-      const itemContext = (context as Record<string, unknown>).itemContext as Record<string, unknown> | undefined;
-      if (itemContext) {
-        Object.assign(evalContext, itemContext);
-      }
-
+      // Build evaluation context with item context for nested template resolution
+      const evalContext = buildEvalContext(context, true);
 
       // Check if entire string is a complete template {{expr}}
       // Use evaluateTemplate to preserve type (objects, arrays, numbers)
@@ -504,12 +555,12 @@ export function processStructure(
             if (isHtmlNode(processed) || isListNode(processed)) {
               if (typeof value === 'string') {
                 // Process template in tag (e.g., "h{{size}}" -> "h1")
-                const evalContext: Record<string, unknown> = { ...getGlobalTemplateContext(), ...context.props };
-                if (context.componentDef && typeof context.componentDef === 'object') {
-                  Object.assign(evalContext, context.componentDef as Record<string, unknown>);
-                }
+                const evalContext = buildEvalContext(context, false);
                 // Use processCodeTemplates to handle partial templates like "h{{size}}"
                 (processed as any).tag = processCodeTemplates(value, evalContext);
+              } else if (value === false) {
+                // Preserve boolean false for fragment mode (no container)
+                (processed as any).tag = false;
               } else {
                 (processed as any).tag = String(value);
               }
@@ -526,16 +577,8 @@ export function processStructure(
             // Handle html property for embed nodes - process templates like {{propName}}
             if (preservedType === NODE_TYPE.EMBED) {
               if (typeof value === 'string') {
-                // Build evaluation context from props (same as tag processing)
-                const evalContext: Record<string, unknown> = { ...getGlobalTemplateContext(), ...context.props };
-                if (context.componentDef && typeof context.componentDef === 'object') {
-                  Object.assign(evalContext, context.componentDef as Record<string, unknown>);
-                }
-                // Add parent cms-list item context for nested template resolution
-                const itemContext = (context as Record<string, unknown>).itemContext as Record<string, unknown> | undefined;
-                if (itemContext) {
-                  Object.assign(evalContext, itemContext);
-                }
+                // Build evaluation context with item context for nested template resolution
+                const evalContext = buildEvalContext(context, true);
                 // Check if entire string is a complete template {{expr}}
                 if (/^\{\{.+\}\}$/.test(value) && !hasItemTemplates(value)) {
                   const result = evaluateTemplate(value, evalContext);
@@ -583,78 +626,29 @@ export function processStructure(
             if (processedStyle && typeof processedStyle === 'object' && !Array.isArray(processedStyle)) {
               // Check if it's a responsive style object
               if (isResponsiveStyle(processedStyle as StyleValue)) {
-                if (preserveResponsiveStyles) {
-                  // Preserve responsive styles as-is (for SSR)
-                  // Just resolve templates and mappings within each breakpoint
-                  const resolvedResponsive: ResponsiveStyleObject = {};
-                  for (const [bkeyName, bkeyValue] of Object.entries(processedStyle)) {
-                    if (typeof bkeyValue === 'object' && bkeyValue !== null) {
-                      resolvedResponsive[bkeyName] = {};
-                      for (const [styleKey, styleValue] of Object.entries(bkeyValue)) {
-                        const resolved = resolveStyleMapping(styleValue, context.props);
-                        if (resolved !== undefined) {
-                          resolvedResponsive[bkeyName]![styleKey] = resolved;
-                        } else if (typeof styleValue === 'string') {
-                          if (hasTemplates(styleValue)) {
-                            const evaluated = processCodeTemplates(styleValue, context.props);
-                            resolvedResponsive[bkeyName]![styleKey] = evaluated;
-                          } else {
-                            resolvedResponsive[bkeyName]![styleKey] = styleValue;
-                          }
-                        } else if (typeof styleValue === 'number') {
-                          resolvedResponsive[bkeyName]![styleKey] = styleValue;
-                        }
-                      }
-                    }
-                  }
-                  resolvedStyle = resolvedResponsive;
-                } else {
-                  // Preserve responsive styles for editor (same as SSR)
-                  // responsiveStylesToClasses will generate prefixed classes (t-, mob-)
-                  // CSS media queries will handle displaying the correct styles based on viewport
-                  const resolvedResponsive: ResponsiveStyleObject = {};
-                  for (const [bkeyName, bkeyValue] of Object.entries(processedStyle)) {
-                    if (typeof bkeyValue === 'object' && bkeyValue !== null) {
-                      resolvedResponsive[bkeyName] = {};
-                      for (const [styleKey, styleValue] of Object.entries(bkeyValue)) {
-                        const resolved = resolveStyleMapping(styleValue, context.props);
-                        if (resolved !== undefined) {
-                          resolvedResponsive[bkeyName]![styleKey] = resolved;
-                        } else if (typeof styleValue === 'string') {
-                          if (hasTemplates(styleValue)) {
-                            const evaluated = processCodeTemplates(styleValue, context.props);
-                            resolvedResponsive[bkeyName]![styleKey] = evaluated;
-                          } else {
-                            resolvedResponsive[bkeyName]![styleKey] = styleValue;
-                          }
-                        } else if (typeof styleValue === 'number') {
-                          resolvedResponsive[bkeyName]![styleKey] = styleValue;
-                        }
+                // Preserve responsive styles (for both SSR and editor)
+                // responsiveStylesToClasses will generate prefixed classes (t-, mob-)
+                // CSS media queries will handle displaying the correct styles based on viewport
+                const resolvedResponsive: ResponsiveStyleObject = {};
+                for (const [bkeyName, bkeyValue] of Object.entries(processedStyle)) {
+                  if (typeof bkeyValue === 'object' && bkeyValue !== null) {
+                    resolvedResponsive[bkeyName] = {};
+                    for (const [styleKey, styleValue] of Object.entries(bkeyValue)) {
+                      const processedValue = processStyleValue(styleValue, context.props);
+                      if (processedValue !== undefined) {
+                        resolvedResponsive[bkeyName]![styleKey] = processedValue;
                       }
                     }
                   }
-                  resolvedStyle = resolvedResponsive;
                 }
+                resolvedStyle = resolvedResponsive;
               } else {
                 // Legacy flat style object - resolve mappings and evaluate templates
                 resolvedStyle = {};
                 for (const [styleKey, styleValue] of Object.entries(processedStyle)) {
-                  // First resolve style mappings
-                  const resolved = resolveStyleMapping(styleValue, context.props);
-                  if (resolved !== undefined) {
-                    resolvedStyle[styleKey] = resolved;
-                  } else if (typeof styleValue === 'string') {
-                    // Evaluate template strings in style values (supports partial templates like "{{size}}px")
-                    // Use processCodeTemplates to handle templates with text before/after
-                    if (hasTemplates(styleValue)) {
-                      const evaluated = processCodeTemplates(styleValue, context.props);
-                      resolvedStyle[styleKey] = evaluated;
-                    } else {
-                      // No templates, keep original value
-                      resolvedStyle[styleKey] = styleValue;
-                    }
-                  } else if (typeof styleValue === 'number') {
-                    resolvedStyle[styleKey] = styleValue;
+                  const processedValue = processStyleValue(styleValue, context.props);
+                  if (processedValue !== undefined) {
+                    resolvedStyle[styleKey] = processedValue;
                   }
                 }
               }
@@ -712,10 +706,7 @@ export function processStructure(
             // Special handling for attributes - process templates but don't treat as node structure
             // This preserves type="checkbox" etc. which would otherwise be caught by node type handling
             const processedAttributes: Record<string, unknown> = {};
-            const evalContext: Record<string, unknown> = { ...getGlobalTemplateContext(), ...context.props };
-            if (context.componentDef && typeof context.componentDef === 'object') {
-              Object.assign(evalContext, context.componentDef as Record<string, unknown>);
-            }
+            const evalContext = buildEvalContext(context, false);
             for (const [attrKey, attrValue] of Object.entries(value)) {
               if (typeof attrValue === 'string' && hasTemplates(attrValue)) {
                 // Check if entire string is a complete template {{expr}} - preserve type (boolean, number)

package/lib/server/index.ts

@@ -15,9 +15,9 @@ export { generateBuildErrorPage, type BuildError, type BuildErrorsData } from '.
 
 // Services
 export { PageService } from './services/pageService';
-export { ComponentService } from './services/componentService';
+export { ComponentService, type ComponentInfo } from './services/componentService';
 export { CMSService, type ReferenceLocation } from './services/cmsService';
-export { configService, ConfigService } from './services/configService';
+export { configService, ConfigService, type EnumsConfig } from './services/configService';
 export { ColorService } from './services/ColorService';
 
 // Providers

package/lib/server/jsonLoader.ts

@@ -118,69 +118,147 @@ async function loadFileAsText(filePath: string): Promise<string | null> {
 }
 
 /**
- * Load all component definitions from components directory
- * Automatically loads corresponding .js files if they exist
+ * Component with category metadata from folder structure
+ */
+export interface ComponentWithCategory extends ComponentDefinition {
+  _category?: string;
+  _relativePath?: string;
+}
+
+/**
+ * Load a single component from a file path
+ * @internal
+ */
+async function loadSingleComponent(
+  filePath: string,
+  componentName: string,
+  category?: string
+): Promise<ComponentWithCategory | null> {
+  const content = await loadJSONFile(filePath);
+  if (!content) return null;
+
+  try {
+    const parsed = parseJSON<ComponentDefinition>(content);
+
+    // Validate component definition (logs warnings but doesn't fail - graceful degradation)
+    const validationResult = validateComponentDefinition(parsed);
+    if (!validationResult.valid) {
+      console.warn(`[jsonLoader] Component validation failed for ${componentName}:`,
+        validationResult.errors.map(e => `${e.path}: ${e.message}`).join('; '));
+    }
+    const componentDef: ComponentWithCategory = validationResult.valid ? validationResult.data : parsed;
+
+    // Determine the directory where the component file is located
+    const dirPath = filePath.substring(0, filePath.lastIndexOf('/'));
+
+    // Check if there's a corresponding .js file
+    const jsFilePath = `${dirPath}/${componentName}.js`;
+    const jsContent = await loadFileAsText(jsFilePath);
+
+    // Check if there's a corresponding .css file
+    const cssFilePath = `${dirPath}/${componentName}.css`;
+    const cssContent = await loadFileAsText(cssFilePath);
+
+    if (!componentDef.component) {
+      componentDef.component = {};
+    }
+
+    // If .js file exists, use its content for javascript field
+    // This takes precedence over any javascript field in the JSON
+    if (jsContent) {
+      componentDef.component.javascript = jsContent;
+
+      // Auto-enable defineVars when .js file exists (unless explicitly set to false)
+      if (componentDef.component.defineVars === undefined) {
+        componentDef.component.defineVars = true;
+      }
+    }
+
+    // If .css file exists, use its content for css field
+    // This takes precedence over any css field in the JSON
+    if (cssContent) {
+      componentDef.component.css = cssContent;
+    }
+
+    // Add category metadata from folder structure
+    if (category) {
+      componentDef._category = category;
+      componentDef._relativePath = `${category}/${componentName}`;
+    }
+
+    return componentDef;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Load all component definitions from components directory (recursive)
+ * Scans subdirectories as category folders. Component names must be unique across all folders.
+ *
+ * Folder structure:
+ * - /components/Button.json → name: "Button", category: undefined
+ * - /components/ui/Card.json → name: "Card", category: "ui"
+ *
+ * @param dirPath - Root components directory path
+ * @returns Map of component names to ComponentDefinition with category metadata
  */
 export async function loadComponentDirectory(
   dirPath: string = './components'
-): Promise<Map<string, ComponentDefinition>> {
-  const components = new Map<string, ComponentDefinition>();
+): Promise<Map<string, ComponentWithCategory>> {
+  const components = new Map<string, ComponentWithCategory>();
 
   if (!existsSync(dirPath)) {
     return components;
   }
 
-  const files = readdirSync(dirPath);
+  const entries = readdirSync(dirPath, { withFileTypes: true });
 
-  for (const file of files) {
-    if (file.endsWith('.json')) {
-      const componentName = file.replace('.json', '');
-      const content = await loadJSONFile(`${dirPath}/${file}`);
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // This is a category folder - scan it for components
+      const category = entry.name;
+      const categoryPath = `${dirPath}/${category}`;
+      const categoryFiles = readdirSync(categoryPath);
 
-      if (content) {
-        try {
-          const parsed = parseJSON<ComponentDefinition>(content);
-
-          // Validate component definition (logs warnings but doesn't fail - graceful degradation)
-          const validationResult = validateComponentDefinition(parsed);
-          if (!validationResult.valid) {
-            console.warn(`[jsonLoader] Component validation failed for ${componentName}:`,
-              validationResult.errors.map(e => `${e.path}: ${e.message}`).join('; '));
-          }
-          const componentDef = validationResult.valid ? validationResult.data : parsed;
-
-          // Check if there's a corresponding .js file
-          const jsFilePath = `${dirPath}/${componentName}.js`;
-          const jsContent = await loadFileAsText(jsFilePath);
+      for (const file of categoryFiles) {
+        if (file.endsWith('.json')) {
+          const componentName = file.replace('.json', '');
 
-          // Check if there's a corresponding .css file
-          const cssFilePath = `${dirPath}/${componentName}.css`;
-          const cssContent = await loadFileAsText(cssFilePath);
-
-          if (!componentDef.component) {
-            componentDef.component = {};
+          // Check for duplicate component names
+          if (components.has(componentName)) {
+            console.warn(`[jsonLoader] Duplicate component name "${componentName}" found in category "${category}". Skipping.`);
+            continue;
           }
 
-          // If .js file exists, use its content for javascript field
-          // This takes precedence over any javascript field in the JSON
-          if (jsContent) {
-            componentDef.component.javascript = jsContent;
+          const componentDef = await loadSingleComponent(
+            `${categoryPath}/${file}`,
+            componentName,
+            category
+          );
 
-            // Auto-enable defineVars when .js file exists (unless explicitly set to false)
-            if (componentDef.component.defineVars === undefined) {
-              componentDef.component.defineVars = true;
-            }
+          if (componentDef) {
+            components.set(componentName, componentDef);
           }
+        }
+      }
+    } else if (entry.name.endsWith('.json')) {
+      // Root-level component (uncategorized)
+      const componentName = entry.name.replace('.json', '');
+
+      // Check for duplicate component names
+      if (components.has(componentName)) {
+        console.warn(`[jsonLoader] Duplicate component name "${componentName}" at root level. Skipping.`);
+        continue;
+      }
 
-          // If .css file exists, use its content for css field
-          // This takes precedence over any css field in the JSON
-          if (cssContent) {
-            componentDef.component.css = cssContent;
-          }
+      const componentDef = await loadSingleComponent(
+        `${dirPath}/${entry.name}`,
+        componentName
+      );
 
-          components.set(componentName, componentDef);
-        } catch (error) {
-        }
+      if (componentDef) {
+        components.set(componentName, componentDef);
       }
     }
   }

package/lib/server/routes/api/components.ts

@@ -9,10 +9,21 @@ import { jsonResponse } from './shared';
 
 /**
  * Handle components API endpoint - GET /api/components
+ * Returns components with category metadata derived from folder structure
  */
 export function handleComponentsRoute(componentService: ComponentService): Response {
-  const components = componentService.getAllComponents();
-  return jsonResponse(components);
+  const componentsWithCategories = componentService.getAllComponentsWithCategories();
+
+  // Transform to API format: { name: { ...definition, _category } }
+  const result: Record<string, any> = {};
+  for (const [name, info] of Object.entries(componentsWithCategories)) {
+    result[name] = {
+      ...info.definition,
+      _category: info.category
+    };
+  }
+
+  return jsonResponse(result);
 }
 
 /**