@o2vend/theme-cli 1.0.32

package/lib/lib/liquid-engine.js

@@ -0,0 +1,822 @@
+/**
+ * LiquidJS Engine Setup
+ * Configures LiquidJS with all O2VEND filters and custom tags
+ */
+
+const { Liquid } = require('liquidjs');
+const path = require('path');
+const LiquidHelperService = require('./liquid-filters');
+const fs = require('fs');
+const chalk = require('chalk');
+
+/**
+ * Create and configure LiquidJS engine
+ * @param {string} themePath - Path to theme directory
+ * @param {Object} options - Engine options
+ * @returns {Liquid} Configured LiquidJS engine
+ */
+// Store the current rendering context globally so sections can access it
+let currentRenderingContext = null;
+
+// Track widgets currently being rendered to prevent infinite recursion
+const renderingStack = new Set();
+const MAX_RENDER_DEPTH = 50; // Maximum number of nested renders allowed
+let currentRenderDepth = 0;
+
+function createLiquidEngine(themePath, options = {}) {
+  const {
+    cache = false, // Disable cache in dev mode
+    extname = '.liquid'
+  } = options;
+
+  // Create Liquid engine
+  // NOTE: Do NOT use outputEscape: 'escape' as it breaks JSON output in script tags
+  // Templates should use explicit escaping when needed (e.g., {{ variable | escape }})
+  const liquid = new Liquid({
+    root: themePath,
+    extname: extname,
+    cache: cache,
+    strictFilters: false,
+    strictVariables: false,
+    ownPropertyOnly: false,
+    // Enable dynamic properties to access array methods
+    dynamicPartials: true,
+    // Ensure arrays are properly handled
+    jsTruthy: true,
+    // Enable async filters
+    async: true
+  });
+
+  // Register all filters from LiquidHelperService
+  const liquidHelperService = new LiquidHelperService();
+  const filters = liquidHelperService.getFilters();
+  
+  Object.keys(filters).forEach(filterName => {
+    liquid.registerFilter(filterName, filters[filterName]);
+  });
+
+  // Register custom filters for JSON output compatibility
+  // These help handle edge cases where templates output JSON directly
+  
+  // json_value: Outputs a JSON-safe value (handles null, undefined, objects)
+  liquid.registerFilter('json_value', (value) => {
+    if (value === null || value === undefined) {
+      return 'null';
+    }
+    if (typeof value === 'object') {
+      return JSON.stringify(value);
+    }
+    if (typeof value === 'string') {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  });
+  
+  // safe_json: Ensures proper JSON encoding without double-encoding strings
+  liquid.registerFilter('safe_json', (value) => {
+    if (value === null || value === undefined) {
+      return 'null';
+    }
+    // If it's already a JSON string, don't double-encode
+    if (typeof value === 'string') {
+      try {
+        JSON.parse(value);
+        return value; // Already valid JSON
+      } catch {
+        return JSON.stringify(value); // Encode the string
+      }
+    }
+    return JSON.stringify(value);
+  });
+
+  // Register custom tags
+  registerCustomTags(liquid, themePath);
+
+  return liquid;
+}
+
+/**
+ * Register custom Liquid tags (section, hook, schema)
+ * @param {Liquid} liquid - LiquidJS engine instance
+ * @param {string} themePath - Theme path
+ */
+function registerCustomTags(liquid, themePath) {
+  // Register section tag
+  liquid.registerTag('section', {
+    parse: function(tagToken, remainTokens) {
+      this.sectionPath = tagToken.args.trim().replace(/^['"]|['"]$/g, '');
+    },
+    render: async function(scope, hash) {
+      let sectionPath = this.sectionPath;
+      if (!sectionPath) {
+        console.error('[SECTION] No section path provided');
+        return '';
+      }
+      
+      try {
+        // Normalize section path - remove 'sections/' prefix if present
+        // Handle both 'hero' and 'sections/hero' formats
+        sectionPath = sectionPath.replace(/^sections\//, '').replace(/^sections\\/, '');
+        
+        const sectionFile = path.join(themePath, 'sections', `${sectionPath}.liquid`);
+        if (fs.existsSync(sectionFile)) {
+          let sectionContent = fs.readFileSync(sectionFile, 'utf8');
+          
+          // Pre-process section to convert render_widget filter to tag
+          const originalContent = sectionContent;
+          try {
+            sectionContent = preprocessTemplate(sectionContent);
+          } catch (error) {
+            console.error(chalk.red(`[SECTION] ❌ Error preprocessing ${sectionPath}: ${error.message}`));
+            sectionContent = originalContent;
+          }
+          
+          const scopeContexts = Array.isArray(scope?.contexts) ? scope.contexts : [];
+          const primaryScope = scopeContexts.length > 0
+            ? scopeContexts[0]
+            : (scope?.environments || scope?.context || {});
+          
+          // Merge with current rendering context to ensure all data is available
+          const fullContext = currentRenderingContext 
+            ? { ...currentRenderingContext, ...primaryScope }
+            : primaryScope;
+          
+          const context = {
+            ...fullContext,
+            section: fullContext.section || {}
+          };
+          
+          // Render section
+          try {
+            const rendered = await liquid.parseAndRender(sectionContent, context);
+            return rendered;
+          } catch (renderError) {
+            console.error(chalk.red(`[SECTION] ❌ Error rendering ${sectionPath}: ${renderError.message}`));
+            throw renderError;
+          }
+        } else {
+          console.warn(`[SECTION] Section file not found: ${sectionFile}`);
+          return '';
+        }
+      } catch (error) {
+        console.error(`[SECTION] Error rendering section ${sectionPath}:`, error.message);
+        return '';
+      }
+    }
+  });
+
+  // Register hook tag (simplified for CLI - plugins not supported)
+  liquid.registerTag('hook', {
+    parse: function(tagToken, remainTokens) {
+      const args = tagToken.args;
+      if (typeof args === 'string') {
+        this.hookName = args.trim().replace(/^['"]|['"]$/g, '');
+      } else {
+        this.hookName = String(args || '').trim().replace(/^['"]|['"]$/g, '');
+      }
+    },
+    render: async function(scope, hash) {
+      // In CLI, hooks are not supported (no plugin system)
+      // Return empty string
+      return '';
+    }
+  });
+
+  // Register schema tag as a block tag
+  // Schema blocks contain JSON configuration and should not be rendered
+  liquid.registerTag('schema', {
+    parse: function(tagToken, remainTokens) {
+      // Consume all tokens until endschema
+      this.tokens = [];
+      let token;
+      while ((token = remainTokens.shift())) {
+        if (token.name === 'endschema') {
+          break;
+        }
+        this.tokens.push(token);
+      }
+    },
+    render: async function(scope, hash) {
+      // Schema blocks are for configuration only - don't render anything
+      return '';
+    }
+  });
+
+  // Register endschema tag (closing tag for schema)
+  liquid.registerTag('endschema', {
+    parse: function(tagToken, remainTokens) {
+      // No-op - just marks the end of schema block
+    },
+    render: async function(scope, hash) {
+      return '';
+    }
+  });
+
+  // Register render_widget tag as an alternative to the filter
+  // This allows templates to use: {% render_widget widget %}
+  liquid.registerTag('render_widget', {
+    parse: function(tagToken, remainTokens) {
+      const args = tagToken.args.trim();
+      this.widgetVar = args || 'widget';
+    },
+    render: async function(scope, hash) {
+      try {
+        // Get widget from scope using scope.get() for proper variable resolution
+        let widget = await scope.get(this.widgetVar.split('.'));
+        
+        if (!widget || !widget.type) {
+          return '';
+        }
+        
+        // Render widget template
+        if (widget.template_path) {
+          const widgetPath = path.join(themePath, `${widget.template_path}.liquid`);
+          const altPath = path.join(themePath, widget.template_path);
+          
+          const finalPath = fs.existsSync(widgetPath) ? widgetPath : 
+                           (fs.existsSync(altPath) ? altPath : null);
+          
+          if (finalPath) {
+            const fullContext = currentRenderingContext 
+              ? { ...currentRenderingContext, widget: widget }
+              : { widget: widget };
+            const widgetContent = fs.readFileSync(finalPath, 'utf8');
+            return await liquid.parseAndRender(widgetContent, fullContext);
+          }
+          return `<div class="widget-error">Widget template not found: ${widget.template_path}</div>`;
+        }
+        return `<div class="widget-error">Widget missing template_path</div>`;
+      } catch (error) {
+        console.error(chalk.red(`[RENDER_WIDGET] Error: ${error.message}`));
+        return `<div class="widget-error">Error: ${error.message}</div>`;
+      }
+    }
+  });
+
+  // Override include/render tags to handle widget paths
+  // This allows sections to use {% include 'widgets/banner' %} or {% render 'widgets/banner' %}
+  const originalRenderFile = liquid.renderFile.bind(liquid);
+  
+  // Override renderFile to handle widget paths
+  liquid.renderFile = async function(file, ctx, opts) {
+    // If the file path starts with 'widgets/', resolve it correctly
+    if (typeof file === 'string' && file.startsWith('widgets/')) {
+      const widgetName = file.replace(/^widgets\//, '').replace(/\.liquid$/, '');
+      const widgetPath = path.join(themePath, 'widgets', `${widgetName}.liquid`);
+      if (fs.existsSync(widgetPath)) {
+        return originalRenderFile(widgetPath, ctx, opts);
+      }
+    }
+    // Also handle snippets
+    if (typeof file === 'string' && file.startsWith('snippets/')) {
+      const snippetName = file.replace(/^snippets\//, '').replace(/\.liquid$/, '');
+      const snippetPath = path.join(themePath, 'snippets', `${snippetName}.liquid`);
+      if (fs.existsSync(snippetPath)) {
+        return originalRenderFile(snippetPath, ctx, opts);
+      }
+    }
+    // Default behavior
+    return originalRenderFile(file, ctx, opts);
+  };
+
+  // Override the include tag to handle widget and snippet paths
+  liquid.registerTag('include', {
+    parse: function(tagToken, remainTokens) {
+      // Parse arguments - handle both 'snippets/pagination' and 'snippets/pagination', pagination formats
+      const args = tagToken.args.trim();
+      // Extract file path (first argument before comma if present)
+      const fileMatch = args.match(/^['"]([^'"]+)['"]/);
+      this.file = fileMatch ? fileMatch[1] : args.split(',')[0].trim().replace(/^['"]|['"]$/g, '');
+    },
+    render: async function(scope, hash) {
+      let filePath = this.file;
+      if (!filePath) {
+        console.warn('[INCLUDE] No file path provided');
+        return '';
+      }
+      
+      // Clean up file path
+      filePath = filePath.trim().replace(/^['"]|['"]$/g, '');
+      
+      // Get full context for snippets/widgets
+      const scopeContexts = Array.isArray(scope?.contexts) ? scope.contexts : [];
+      const primaryScope = scopeContexts.length > 0
+        ? scopeContexts[0]
+        : (scope?.environments || scope?.context || {});
+      
+      // Merge with current rendering context to ensure all data is available
+      const fullContext = currentRenderingContext 
+        ? { ...currentRenderingContext, ...primaryScope }
+        : primaryScope;
+      
+      // Handle widget paths
+      if (filePath.startsWith('widgets/')) {
+        const widgetName = filePath.replace(/^widgets\//, '').replace(/\.liquid$/, '');
+        const widgetPath = path.join(themePath, 'widgets', `${widgetName}.liquid`);
+        if (fs.existsSync(widgetPath)) {
+          return await liquid.parseAndRender(fs.readFileSync(widgetPath, 'utf8'), fullContext);
+        }
+      }
+      
+      // Handle snippet paths
+      if (filePath.startsWith('snippets/')) {
+        const snippetName = filePath.replace(/^snippets\//, '').replace(/\.liquid$/, '');
+        const snippetPath = path.join(themePath, 'snippets', `${snippetName}.liquid`);
+        if (fs.existsSync(snippetPath)) {
+          return await liquid.parseAndRender(fs.readFileSync(snippetPath, 'utf8'), fullContext);
+        } else {
+          console.warn(`[INCLUDE] Snippet not found: ${snippetPath}`);
+        }
+      }
+      
+      // Try to resolve file in snippets directory (default location)
+      const snippetPath = path.join(themePath, 'snippets', `${filePath}.liquid`);
+      if (fs.existsSync(snippetPath)) {
+        return await liquid.parseAndRender(fs.readFileSync(snippetPath, 'utf8'), fullContext);
+      }
+      
+      // Try direct path
+      const resolvedPath = path.join(themePath, filePath);
+      if (fs.existsSync(resolvedPath)) {
+        return await liquid.parseAndRender(fs.readFileSync(resolvedPath, 'utf8'), fullContext);
+      }
+      
+      // Try with .liquid extension
+      const resolvedPathWithExt = `${resolvedPath}.liquid`;
+      if (fs.existsSync(resolvedPathWithExt)) {
+        return await liquid.parseAndRender(fs.readFileSync(resolvedPathWithExt, 'utf8'), fullContext);
+      }
+      
+      console.warn(`[INCLUDE] File not found: ${filePath} (tried: ${snippetPath}, ${resolvedPath}, ${resolvedPathWithExt})`);
+      return '';
+    }
+  });
+
+  // Override the render tag (similar to include but with isolated scope)
+  liquid.registerTag('render', {
+    parse: function(tagToken, remainTokens) {
+      // Parse the tag arguments
+      // Format: {% render 'path' %} or {% render variable.path, param: value %}
+      const args = tagToken.args.trim();
+      
+      // Split by comma to separate file path from hash parameters
+      const commaIndex = args.indexOf(',');
+      if (commaIndex > 0) {
+        this.fileArg = args.substring(0, commaIndex).trim();
+        this.hashArgs = args.substring(commaIndex + 1).trim();
+      } else {
+        this.fileArg = args;
+        this.hashArgs = '';
+      }
+    },
+    render: async function(scope, hash) {
+      // RECURSION GUARD: Check render depth to prevent infinite loops
+      currentRenderDepth++;
+      if (currentRenderDepth > MAX_RENDER_DEPTH) {
+        console.error(chalk.red(`[RENDER TAG] ❌ Maximum render depth (${MAX_RENDER_DEPTH}) exceeded - possible infinite loop`));
+        console.error(chalk.red(`[RENDER TAG] Current rendering stack: ${Array.from(renderingStack).join(' -> ')}`));
+        currentRenderDepth--;
+        return `<div class="widget-error">Error: Maximum render depth exceeded</div>`;
+      }
+      
+      // CRITICAL: Use scope.get() to properly resolve variables from the LiquidJS scope chain
+      // This correctly handles loop variables like 'widget' in {% for widget in widgets.hero %}
+      
+      // Build context starting with currentRenderingContext
+      let fullContext = {};
+      if (currentRenderingContext) {
+        fullContext = { ...currentRenderingContext };
+      }
+      
+      // Resolve file path - could be a string literal or a variable
+      let filePath = this.fileArg;
+      
+      // If it's wrapped in quotes, it's a string literal
+      if ((filePath.startsWith('"') && filePath.endsWith('"')) || 
+          (filePath.startsWith("'") && filePath.endsWith("'"))) {
+        filePath = filePath.slice(1, -1);
+      } else {
+        // It's a variable - use scope.get() to resolve it properly (this handles loop variables!)
+        try {
+          // For paths like 'widget.template_path', we need to resolve via scope.get()
+          const resolvedValue = await scope.get(filePath.split('.'));
+          if (resolvedValue && typeof resolvedValue === 'string') {
+            filePath = resolvedValue;
+          } else {
+            currentRenderDepth--;
+            return '';
+          }
+        } catch (error) {
+          currentRenderDepth--;
+          return '';
+        }
+      }
+      
+      // Parse hash parameters (e.g., widget: widget, settings: settings)
+      const renderContext = { ...fullContext };
+      if (this.hashArgs) {
+        // Parse hash args like "widget: widget, settings: settings"
+        const hashPairs = this.hashArgs.split(',').map(pair => pair.trim());
+        for (const pair of hashPairs) {
+          const colonIndex = pair.indexOf(':');
+          if (colonIndex > 0) {
+            const key = pair.substring(0, colonIndex).trim();
+            const valueVar = pair.substring(colonIndex + 1).trim();
+            if (key && valueVar) {
+              // Use scope.get() to resolve the value variable (handles loop variables correctly!)
+              try {
+                const value = await scope.get(valueVar.split('.'));
+                if (value !== undefined && value !== null) {
+                  renderContext[key] = value;
+                }
+              } catch (error) {
+                // Silently skip unresolved hash params
+              }
+            }
+          }
+        }
+      }
+      
+      // Handle widget paths
+      if (filePath.startsWith('widgets/')) {
+        const widgetName = filePath.replace(/^widgets\//, '').replace(/\.liquid$/, '');
+        const widgetPath = path.join(themePath, 'widgets', `${widgetName}.liquid`);
+        
+        // Create unique render key based on widget ID (if available) or path
+        const widgetId = renderContext.widget?.id || widgetName;
+        const renderKey = `${widgetName}:${widgetId}`;
+        
+        // Check for recursive rendering of the same widget
+        if (renderingStack.has(renderKey)) {
+          // Only log in debug mode to reduce noise - the guard is working correctly
+          if (process.env.DEBUG) {
+            console.warn(chalk.yellow(`[RENDER TAG] Skipping duplicate render of ${renderKey}`));
+          }
+          currentRenderDepth--;
+          return ''; // Skip duplicate render
+        }
+        
+        // Add to rendering stack
+        renderingStack.add(renderKey);
+        
+        try {
+          if (fs.existsSync(widgetPath)) {
+            // Render with isolated scope (render tag behavior) - use renderContext which includes hash params
+            const widgetContent = fs.readFileSync(widgetPath, 'utf8');
+            const rendered = await liquid.parseAndRender(widgetContent, renderContext);
+            return rendered;
+          } else {
+            // Try alternative paths
+            const altPath = path.join(themePath, 'widgets', 'shared', `${widgetName}.liquid`);
+            if (fs.existsSync(altPath)) {
+              const widgetContent = fs.readFileSync(altPath, 'utf8');
+              const rendered = await liquid.parseAndRender(widgetContent, renderContext);
+              return rendered;
+            }
+            console.error(chalk.red(`[RENDER TAG] ❌ Widget template not found: ${widgetPath}`));
+          }
+        } finally {
+          // Remove from rendering stack
+          renderingStack.delete(renderKey);
+          currentRenderDepth--;
+        }
+        return '';
+      }
+      
+      // Handle snippet paths
+      if (filePath.startsWith('snippets/')) {
+        const snippetName = filePath.replace(/^snippets\//, '').replace(/\.liquid$/, '');
+        const snippetPath = path.join(themePath, 'snippets', `${snippetName}.liquid`);
+        try {
+          if (fs.existsSync(snippetPath)) {
+            const rendered = await liquid.parseAndRender(fs.readFileSync(snippetPath, 'utf8'), renderContext);
+            return rendered;
+          }
+        } finally {
+          currentRenderDepth--;
+        }
+        return '';
+      }
+      
+      // Default behavior - try to resolve file
+      try {
+        const resolvedPath = path.join(themePath, filePath);
+        if (fs.existsSync(resolvedPath)) {
+          const rendered = await liquid.parseAndRender(fs.readFileSync(resolvedPath, 'utf8'), renderContext);
+          currentRenderDepth--;
+          return rendered;
+        }
+        // Try with .liquid extension
+        const resolvedPathWithExt = `${resolvedPath}.liquid`;
+        if (fs.existsSync(resolvedPathWithExt)) {
+          const rendered = await liquid.parseAndRender(fs.readFileSync(resolvedPathWithExt, 'utf8'), renderContext);
+          currentRenderDepth--;
+          return rendered;
+        }
+      } catch (error) {
+        console.warn(`[RENDER] Error rendering file ${filePath}:`, error.message);
+      }
+      
+      currentRenderDepth--;
+      return '';
+    }
+  });
+}
+
+/**
+ * Render a single widget to HTML
+ * @param {Object} widget - Widget object
+ * @param {Object} context - Rendering context
+ * @param {string} themePath - Theme path
+ * @returns {Promise<string>} Rendered widget HTML
+ */
+async function renderWidget(widget, context, themePath) {
+  if (!widget || !widget.template_path) {
+    return `<div class="widget-error">Widget missing template_path</div>`;
+  }
+
+  try {
+    const widgetPath = path.join(themePath, `${widget.template_path}.liquid`);
+    if (!fs.existsSync(widgetPath)) {
+      // Try without .liquid extension
+      const altPath = path.join(themePath, widget.template_path);
+      if (!fs.existsSync(altPath)) {
+        return `<div class="widget-error">Widget template not found: ${widget.template_path}</div>`;
+      }
+      // Use alt path
+      const widgetContent = fs.readFileSync(altPath, 'utf8');
+      const widgetContext = {
+        ...context,
+        widget: widget
+      };
+      return await liquid.parseAndRender(widgetContent, widgetContext);
+    }
+
+    const widgetContent = fs.readFileSync(widgetPath, 'utf8');
+    const widgetContext = {
+      ...context,
+      widget: widget
+    };
+    const rendered = await liquid.parseAndRender(widgetContent, widgetContext);
+    return rendered;
+  } catch (error) {
+    console.error(chalk.red(`[WIDGET RENDER] ❌ Error rendering widget ${widget.type}: ${error.message}`));
+    return `<div class="widget-error">Error rendering widget: ${error.message}</div>`;
+  }
+}
+
+/**
+ * Render template with layout support
+ * @param {Liquid} liquid - LiquidJS engine
+ * @param {string} templatePath - Template path (relative to theme, e.g., 'templates/index')
+ * @param {Object} context - Template context
+ * @param {string} themePath - Theme path
+ * @returns {Promise<string>} Rendered HTML
+ */
+/**
+ * Pre-process template content to transform render_widget filter calls into tag calls
+ * This allows the filter syntax {{ widget | render_widget }} to work without modifying theme files
+ */
+function preprocessTemplate(content) {
+  if (!content || typeof content !== 'string') {
+    return content;
+  }
+  
+  // Replace {{ widget | render_widget }} with {% render_widget widget %}
+  const filterPattern = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\|\s*render_widget\s*\}\}/gs;
+  
+  // Pattern for widget loops that might need rendering code injected
+  const widgetLoopPattern = /(\{%\s*for\s+widget\s+in\s+[\w.]+\s*%\})([\s\S]*?)(\{%\s*endfor\s*%\})/g;
+  
+  // Transform filter syntax to tag syntax
+  let transformed = content.replace(filterPattern, (match, variable) => {
+    return `{% render_widget ${variable} %}`;
+  });
+  
+  // Check for widget loops with empty wrappers and inject rendering code
+  widgetLoopPattern.lastIndex = 0;
+  let loopMatch;
+  while ((loopMatch = widgetLoopPattern.exec(transformed)) !== null) {
+    const [fullMatch, forTag, loopBody, endforTag] = loopMatch;
+    const hasWrapper = loopBody.includes('theme-widget-wrapper');
+    const hasRendering = loopBody.includes('render_widget') || loopBody.includes('{% render');
+    
+    if (hasWrapper && !hasRendering) {
+      const wrapperDivPattern = /(<div[^>]*theme-widget-wrapper[^>]*>)([\s\S]*?)(<\/div>)/;
+      const wrapperMatch = loopBody.match(wrapperDivPattern);
+      
+      if (wrapperMatch) {
+        const [wrapperFull, openingDiv, innerContent, closingDiv] = wrapperMatch;
+        if (!innerContent.trim() || innerContent.trim().length < 10) {
+          const injectedContent = `${openingDiv}
+        {% if widget and widget.template_path %}
+          {% render widget.template_path, widget: widget, settings: settings %}
+        {% else %}
+          <div class="widget-error">Widget template not found</div>
+        {% endif %}
+      ${closingDiv}`;
+          transformed = transformed.replace(wrapperFull, injectedContent);
+        }
+      }
+    }
+  }
+  
+  return transformed;
+}
+
+/**
+ * Render a single widget to HTML
+ * @param {Object} widget - Widget object
+ * @param {Object} context - Rendering context
+ * @param {string} themePath - Theme path
+ * @returns {Promise<string>} Rendered widget HTML
+ */
+async function renderWidget(widget, context, themePath) {
+  if (!widget || !widget.template_path) {
+    return `<div class="widget-error">Widget missing template_path</div>`;
+  }
+
+  try {
+    const widgetPath = path.join(themePath, `${widget.template_path}.liquid`);
+    if (!fs.existsSync(widgetPath)) {
+      // Try without .liquid extension
+      const altPath = path.join(themePath, widget.template_path);
+      if (!fs.existsSync(altPath)) {
+        return `<div class="widget-error">Widget template not found: ${widget.template_path}</div>`;
+      }
+      // Use alt path
+      const widgetContent = fs.readFileSync(altPath, 'utf8');
+      const widgetContext = {
+        ...context,
+        widget: widget
+      };
+      return await liquid.parseAndRender(widgetContent, widgetContext);
+    }
+
+    const widgetContent = fs.readFileSync(widgetPath, 'utf8');
+    const widgetContext = {
+      ...context,
+      widget: widget
+    };
+    const rendered = await liquid.parseAndRender(widgetContent, widgetContext);
+    return rendered;
+  } catch (error) {
+    console.error(chalk.red(`[WIDGET RENDER] ❌ Error rendering widget ${widget.type}: ${error.message}`));
+    return `<div class="widget-error">Error rendering widget: ${error.message}</div>`;
+  }
+}
+
+async function renderWithLayout(liquid, templatePath, context, themePath) {
+  try {
+    // Store context globally so sections can access it
+    const previousContext = currentRenderingContext;
+    currentRenderingContext = context;
+    
+  try {
+    const fullTemplatePath = path.join(themePath, `${templatePath}.liquid`);
+    
+    if (!fs.existsSync(fullTemplatePath)) {
+      throw new Error(`Template not found: ${fullTemplatePath}`);
+    }
+      
+      // Debug: Log context data for templates
+      const contextSummary = {
+        products: context.products?.length || 0,
+        widgets: Object.keys(context.widgets || {}).map(s => `${s}:${context.widgets[s]?.length || 0}`).join(', '),
+        categories: context.categories?.length || 0,
+        brands: context.brands?.length || 0,
+        menus: context.menus?.length || 0,
+        cart: context.cart?.itemCount || 0
+      };
+      console.log(`[RENDER] ${templatePath} - Context:`, JSON.stringify(contextSummary));
+    
+    let templateContent = fs.readFileSync(fullTemplatePath, 'utf-8');
+    
+    // Pre-process template to convert render_widget filter to tag
+    templateContent = preprocessTemplate(templateContent);
+    
+    // DEBUG: Check if template uses render_widget filter
+    const usesRenderWidgetFilter = templateContent.includes('render_widget');
+    if (usesRenderWidgetFilter) {
+      console.log(chalk.yellow(`[RENDER] ⚠️  Template uses render_widget filter - checking if filter is available...`));
+      const hasFilter = liquid.filters && liquid.filters['render_widget'];
+      console.log(chalk.yellow(`[RENDER] Filter available: ${hasFilter ? '✅' : '❌'}`));
+    }
+    
+    // Check for layout directive
+    const layoutMatch = templateContent.match(/\{%\s*layout\s+['"](.+?)['"]\s*%\}/);
+    
+    if (layoutMatch) {
+      let layoutPath = layoutMatch[1]; // e.g., 'layout/theme' or 'theme'
+      
+      // Remove layout directive from template
+      const contentWithoutLayout = templateContent.replace(/\{%\s*layout\s+['"](.+?)['"]\s*%\}/, '').trim();
+      
+      // Render template content first
+      // Wrap in try-catch to catch any filter-related errors
+      let renderedContent;
+      try {
+        renderedContent = await liquid.parseAndRender(contentWithoutLayout, context);
+      } catch (renderError) {
+        console.error(chalk.red(`[RENDER] ❌ Error rendering template content:`));
+        console.error(chalk.red(`  Error: ${renderError.message}`));
+        if (renderError.stack) {
+          console.error(chalk.red(`  Stack: ${renderError.stack.split('\n').slice(0, 5).join('\n')}`));
+        }
+        // Check if error is related to render_widget filter
+        if (renderError.message && renderError.message.includes('render_widget')) {
+          console.error(chalk.yellow(`[RENDER] ⚠️  This error is related to render_widget filter - filter may not be working correctly`));
+        }
+        throw renderError;
+      }
+      
+      // Render layout with content
+      const layoutContext = {
+        ...context,
+        content: renderedContent
+      };
+      
+      // Resolve layout path
+      // If layoutPath doesn't include 'layout/', assume it's just the layout name
+      // and prepend 'layout/'
+      if (!layoutPath.includes('/')) {
+        layoutPath = `layout/${layoutPath}`;
+      }
+      
+      // Build full layout file path
+      const layoutFile = path.join(themePath, `${layoutPath}.liquid`);
+      
+      if (fs.existsSync(layoutFile)) {
+        let layoutContent = fs.readFileSync(layoutFile, 'utf-8');
+        
+        // Set content_for_layout in context (Shopify-compatible approach)
+        // This is the proper way to pass content to layouts
+        layoutContext.content_for_layout = renderedContent;
+        layoutContext.content = renderedContent;
+        
+        // Parse and render the layout with content in context
+        // The layout should use {{ content_for_layout }} or {{ content }} to output
+        return await liquid.parseAndRender(layoutContent, layoutContext);
+      } else {
+        // Try to create default layout if it doesn't exist
+        const layoutDir = path.dirname(layoutFile);
+        const layoutName = path.basename(layoutPath);
+        
+        if (layoutName === 'theme' && !fs.existsSync(layoutFile)) {
+          console.warn(`[Liquid Engine] Layout not found: ${layoutFile}`);
+          console.warn(`[Liquid Engine] Creating default theme layout...`);
+          fs.ensureDirSync(layoutDir);
+          
+          const defaultLayout = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{ shop.name }}{% if page.title %} - {{ page.title }}{% endif %}</title>
+</head>
+<body>
+  {{ content }}
+</body>
+</html>`;
+          fs.writeFileSync(layoutFile, defaultLayout);
+          
+          // Read the newly created layout
+          let layoutContent = fs.readFileSync(layoutFile, 'utf-8');
+          // Set content in context
+          layoutContext.content_for_layout = renderedContent;
+          layoutContext.content = renderedContent;
+        return await liquid.parseAndRender(layoutContent, layoutContext);
+      } else {
+        throw new Error(`Layout not found: ${layoutFile}`);
+        }
+      }
+    } else {
+      // No layout directive, render template directly
+      return await liquid.parseAndRender(templateContent, context);
+    }
+    } finally {
+      // Restore previous context
+      currentRenderingContext = previousContext;
+    }
+  } catch (error) {
+    console.error('Error rendering template with layout:', error);
+    throw error;
+  } finally {
+    // Ensure context is cleared on error
+    currentRenderingContext = null;
+  }
+}
+
+/**
+ * Get current rendering context (for use in filters)
+ * @returns {Object|null} Current rendering context
+ */
+function getCurrentContext() {
+  return currentRenderingContext;
+}
+
+module.exports = {
+  createLiquidEngine,
+  renderWithLayout,
+  getCurrentContext
+};