@o2vend/theme-cli 1.0.32

package/lib/lib/dev-server.js

@@ -0,0 +1,2618 @@
+/**
+ * Development Server
+ * Express server for local theme development with hot reload
+ */
+
+const express = require('express');
+const path = require('path');
+const fs = require('fs-extra');
+const { createLiquidEngine, renderWithLayout } = require('./liquid-engine');
+const WidgetService = require('./widget-service');
+const O2VendApiClient = require('./api-client');
+const { setupHotReload } = require('./hot-reload');
+const chalk = require('chalk');
+
+class DevServer {
+  constructor(options = {}) {
+    this.themePath = options.themePath || process.cwd();
+    this.port = options.port || 3000;
+    this.host = options.host || 'localhost';
+    this.mode = options.mode || 'mock'; // 'mock' or 'real'
+    this.mockApiPort = options.mockApiPort || 3001;
+    this.openBrowser = options.open !== false;
+    
+    this.app = express();
+    this.server = null;
+    this.io = null;
+    this.liquid = null;
+    this.widgetService = null;
+    this.apiClient = null;
+    this.mockApi = null;
+    
+    // Setup server
+    this.setupMiddleware();
+    this.setupRoutes();
+  }
+
+  /**
+   * Setup Express middleware
+   */
+  setupMiddleware() {
+    // Body parser with error handling for aborted requests
+    this.app.use((req, res, next) => {
+      // Handle request aborted errors gracefully
+      req.on('aborted', () => {
+        // Request was aborted - this is normal (e.g., navigation, refresh)
+        // Don't log as error
+      });
+      next();
+    });
+    
+    // Body parser
+    this.app.use(express.json());
+    this.app.use(express.urlencoded({ extended: true }));
+    
+    // Error handler for body parser (catches aborted requests)
+    this.app.use((error, req, res, next) => {
+      // Ignore request aborted errors - they're harmless
+      if (error && (error.code === 'ECONNRESET' || error.message === 'request aborted' || error.type === 'entity.parse.failed')) {
+        return res.status(400).end();
+      }
+      next(error);
+    });
+    
+    // Middleware to rewrite .min.css to .css and .min.js to .js
+    // This allows templates to reference minified files but serve non-minified in dev
+    this.app.use((req, res, next) => {
+      if (req.path && req.path.match(/\.min\.(css|js)$/)) {
+        // Rewrite the request URL to remove .min (req.path is read-only, so we modify req.url)
+        req.url = req.url.replace(/\.min\.(css|js)$/, '.$1');
+      }
+      next();
+    });
+    
+    // Middleware to rewrite /themes/default/assets/ to /assets/
+    // This handles cases where templates output full theme paths
+    this.app.use((req, res, next) => {
+      if (req.path && req.path.match(/^\/themes\/[^\/]+\/assets\//)) {
+        // Rewrite /themes/default/assets/logo.png to /assets/logo.png
+        req.url = req.url.replace(/^\/themes\/[^\/]+\/assets\//, '/assets/');
+      }
+      next();
+    });
+    
+    // Middleware to fallback .min.css to .css and .min.js to .js if minified version doesn't exist
+    // This is useful for development when minified assets haven't been generated
+    this.app.use('/assets', (req, res, next) => {
+      const fs = require('fs');
+      const assetPath = path.join(this.themePath, 'assets', req.path);
+      
+      // Check if requesting a minified file that doesn't exist
+      if (req.path.includes('.min.')) {
+        if (!fs.existsSync(assetPath)) {
+          // Try the non-minified version
+          const nonMinPath = req.path.replace('.min.', '.');
+          const nonMinFullPath = path.join(this.themePath, 'assets', nonMinPath);
+          
+          if (fs.existsSync(nonMinFullPath)) {
+            // Rewrite to non-minified version
+            req.url = nonMinPath;
+            console.log(`[DEV SERVER] Fallback: ${req.path} → ${nonMinPath}`);
+          }
+        }
+      }
+      next();
+    });
+    
+    // Process CSS files through Liquid to support theme variables
+    // This handles CSS files that contain Liquid syntax like {{ settings.color_primary }}
+    this.app.get('/assets/:filename.css', async (req, res, next) => {
+      try {
+        // Get filename from params
+        const filename = req.params.filename + '.css';
+        const cssPath = path.join(this.themePath, 'assets', filename);
+        
+        if (!fs.existsSync(cssPath)) {
+          return next();
+        }
+        
+        const cssContent = fs.readFileSync(cssPath, 'utf8');
+        
+        // Check if CSS contains Liquid variable syntax ({{ }})
+        // Only process if it contains actual Liquid variables, not just comments
+        if (cssContent.includes('{{') && cssContent.includes('settings.')) {
+          try {
+            // Load settings from theme config
+            const settings = this.loadThemeSettings();
+            
+            // Process through Liquid
+            const processedCss = await this.liquid.parseAndRender(cssContent, { settings });
+            
+            res.setHeader('Content-Type', 'text/css; charset=utf-8');
+            res.setHeader('Cache-Control', 'no-cache');
+            return res.send(processedCss);
+          } catch (liquidError) {
+            console.error(`[CSS] Liquid processing error for ${filename}:`, liquidError.message);
+            // Fall through to serve static file
+          }
+        }
+        
+        // Serve static file if no Liquid processing needed or if processing failed
+        res.setHeader('Content-Type', 'text/css; charset=utf-8');
+        res.sendFile(cssPath);
+      } catch (error) {
+        console.error(`[CSS] Error processing ${req.path}:`, error.message);
+        next();
+      }
+    });
+    
+    // Static files (theme assets) with proper MIME types
+    this.app.use('/assets', express.static(path.join(this.themePath, 'assets'), {
+      setHeaders: (res, filePath) => {
+        // Set correct MIME types for all asset types
+        const ext = path.extname(filePath).toLowerCase();
+        const mimeTypes = {
+          '.css': 'text/css; charset=utf-8',
+          '.js': 'application/javascript; charset=utf-8',
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+          '.png': 'image/png',
+          '.gif': 'image/gif',
+          '.svg': 'image/svg+xml',
+          '.webp': 'image/webp',
+          '.woff': 'font/woff',
+          '.woff2': 'font/woff2',
+          '.ttf': 'font/ttf',
+          '.eot': 'application/vnd.ms-fontobject'
+        };
+        
+        if (mimeTypes[ext]) {
+          res.setHeader('Content-Type', mimeTypes[ext]);
+        }
+      }
+    }));
+    
+    // Handle 404 for missing assets - ensure correct MIME type
+    this.app.use('/assets', (req, res, next) => {
+      // Only handle if response hasn't been sent (file not found)
+      if (!res.headersSent) {
+        const ext = path.extname(req.path).toLowerCase();
+        if (ext === '.css') {
+          res.setHeader('Content-Type', 'text/css; charset=utf-8');
+        } else if (ext === '.js') {
+          res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+        }
+        res.status(404).end();
+      } else {
+        next();
+      }
+    });
+    
+    // Serve images from assets
+    this.app.use('/images', express.static(path.join(this.themePath, 'assets')));
+    
+    // Serve O2VEND assets (logo, favicon) for dev dashboard
+    // Try CLI package assets first (for installed package), then shared folder (for development)
+    const cliAssetsPath = path.join(__dirname, '..', '..', 'assets');
+    const sharedAssetsPath = path.join(__dirname, '..', '..', '..', '..', 'shared', 'assets');
+    const o2vendAssetsPath = fs.existsSync(cliAssetsPath) ? cliAssetsPath : sharedAssetsPath;
+    this.app.use('/o2vend-assets', express.static(o2vendAssetsPath, {
+      setHeaders: (res, filePath) => {
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === '.png') res.setHeader('Content-Type', 'image/png');
+        if (ext === '.svg') res.setHeader('Content-Type', 'image/svg+xml');
+        if (ext === '.ico') res.setHeader('Content-Type', 'image/x-icon');
+      }
+    }));
+    
+    // Request logging
+    this.app.use((req, res, next) => {
+      const method = req.method;
+      const url = req.url;
+      const status = res.statusCode;
+      console.log(chalk.gray(`${method} ${url} ${status}`));
+      next();
+    });
+  }
+
+  /**
+   * Setup API client and widget service
+   */
+  async setupServices() {
+    if (this.mode === 'real') {
+      // Real API mode - create API client from environment
+      const tenantId = process.env.O2VEND_TENANT_ID;
+      const apiKey = process.env.O2VEND_API_KEY;
+      const baseUrl = process.env.O2VEND_API_BASE_URL;
+      
+      if (!tenantId || !apiKey || !baseUrl) {
+        console.warn(chalk.yellow('⚠️  Real API mode requires O2VEND_TENANT_ID, O2VEND_API_KEY, and O2VEND_API_BASE_URL'));
+        console.warn(chalk.yellow('   Falling back to mock mode'));
+        this.mode = 'mock';
+      } else {
+        this.apiClient = new O2VendApiClient(tenantId, apiKey, baseUrl);
+      }
+    }
+    
+    // In mock mode, create API client - will be updated after mock API starts
+    // We create a placeholder here, actual client will be created in start() after mock API is running
+    if (this.mode === 'mock') {
+      // Create a temporary client - will be replaced in start() method
+      this.apiClient = null;
+    }
+    
+    // Create widget service (works with mock or real API)
+    // Note: In mock mode, this will be recreated after mock API starts
+    if (this.apiClient) {
+      this.widgetService = new WidgetService(this.apiClient, {
+        theme: path.basename(this.themePath),
+        themePath: this.themePath
+      });
+    }
+    
+    // Create Liquid engine
+    this.liquid = createLiquidEngine(this.themePath, {
+      cache: false // Disable cache in dev mode
+    });
+    
+    // Register widget render filter
+    this.setupWidgetFilter();
+  }
+
+  /**
+   * Register widget render filter
+   */
+  setupWidgetFilter() {
+    // Get reference to currentRenderingContext from liquid-engine
+    const liquidEngine = require('./liquid-engine');
+    
+    // Store reference to this for use in filter
+    const self = this;
+    
+    // Register the filter - LiquidJS supports async filters
+    // IMPORTANT: The filter must be registered AFTER widgetService is available
+    console.log('[DEV SERVER] Registering render_widget filter...');
+    console.log(`[DEV SERVER] WidgetService available: ${!!this.widgetService}`);
+    console.log(`[DEV SERVER] Theme path: ${this.themePath}`);
+    
+    // TEST: Register a simple test filter first to verify filter mechanism works
+    this.liquid.registerFilter('test_widget', function(widget) {
+      console.log(chalk.magenta(`[TEST FILTER] test_widget filter called with: ${typeof widget}`));
+      if (typeof widget === 'object' && widget !== null) {
+        console.log(chalk.magenta(`[TEST FILTER] Widget object keys: ${Object.keys(widget).join(', ')}`));
+      }
+      return `[TEST: ${typeof widget}]`;
+    });
+    
+    // Register async filter - LiquidJS 10.7.0 supports async filters that return Promises
+    // CRITICAL: LiquidJS may not call async filters in output tags {{ }} properly
+    // If this doesn't work, templates should use {% render_widget widget %} tag instead
+    // 
+    // IMPORTANT: We're using a synchronous wrapper that returns a Promise
+    // This ensures LiquidJS recognizes it as a filter, but we handle async internally
+    this.liquid.registerFilter('render_widget', function(widget, context) {
+      // Return a Promise - LiquidJS should await it
+      return Promise.resolve().then(async () => {
+        try {
+          console.log(chalk.cyan(`[WIDGET] ⚡ render_widget filter called`));
+          console.log(chalk.gray(`[WIDGET] Input type: ${typeof widget}, value: ${widget === null ? 'null' : widget === undefined ? 'undefined' : (typeof widget === 'object' ? `object with keys: ${Object.keys(widget || {}).join(', ')}` : String(widget).substring(0, 50))}`));
+          
+          // Handle case where LiquidJS might pass a string representation
+          if (typeof widget === 'string' && widget === '[object Object]') {
+            console.warn(chalk.yellow(`[WIDGET] ⚠️  Widget was converted to string '[object Object]' - LiquidJS may not support object filters`));
+            return '<div class="widget-error">Widget filter received string instead of object. Use {% render_widget widget %} tag instead.</div>';
+          }
+          
+          // DEBUG: Log widget object structure
+          if (widget && typeof widget === 'object') {
+            console.log(chalk.gray(`[WIDGET] Widget type: ${widget?.type || 'undefined'}, ID: ${widget?.id || 'undefined'}`));
+            console.log(chalk.gray(`[WIDGET] Widget keys: ${Object.keys(widget).join(', ')}`));
+          }
+        
+        if (!widget || !widget.type) {
+          console.warn(chalk.yellow(`[WIDGET] ⚠️  No widget or widget.type provided`));
+          console.warn(chalk.gray(`[WIDGET] Widget object: ${widget ? JSON.stringify(Object.keys(widget)) : 'null'}`));
+          return '';
+        }
+        
+        // Ensure widgetService is available - use self to access instance
+        if (!self.widgetService) {
+          console.error('[WIDGET] ❌ WidgetService not initialized - cannot render widget');
+          console.error('[WIDGET] This may happen if widgetService was not created properly');
+          return `<div class="widget-error" style="padding: 10px; background: #ffebee; border-left: 3px solid #f44336; margin: 10px 0;">
+            <strong>Widget Service Error:</strong> WidgetService not initialized<br>
+            <small>Widget type: ${widget.type}, ID: ${widget.id}</small>
+          </div>`;
+        }
+        
+        try {
+        const templateSlug = self.widgetService.getTemplateSlug(widget.type);
+        const widgetPath = path.join(self.themePath, 'widgets', `${templateSlug}.liquid`);
+        
+        console.log(`[WIDGET] Looking for widget template: ${widgetPath}`);
+        
+        if (!fs.existsSync(widgetPath)) {
+          // Try alternative paths (e.g., shared/product-grid.liquid)
+          const altPath = path.join(self.themePath, 'widgets', 'shared', `${templateSlug}.liquid`);
+          console.log(`[WIDGET] Template not found at ${widgetPath}, trying: ${altPath}`);
+          if (fs.existsSync(altPath)) {
+            console.log(`[WIDGET] ✅ Using shared widget: ${templateSlug}.liquid`);
+            const widgetContent = fs.readFileSync(altPath, 'utf8');
+            // Get full context - use current rendering context if available, otherwise use passed context
+            const fullContext = liquidEngine.getCurrentContext ? liquidEngine.getCurrentContext() : null;
+            const widgetContext = fullContext 
+              ? { ...fullContext, widget: widget }
+              : (typeof context === 'object' && context !== null 
+                ? { ...context, widget: widget }
+                : { widget: widget });
+            const rendered = await self.liquid.parseAndRender(widgetContent, widgetContext);
+            console.log(`[WIDGET] ✅ Rendered widget ${widget.type} (${rendered.length} bytes)`);
+            return rendered;
+          }
+          
+          console.error(`[WIDGET] ❌ Template not found: ${templateSlug}.liquid (tried: ${widgetPath}, ${altPath})`);
+          console.error(`[WIDGET] Theme path: ${self.themePath}`);
+          console.error(`[WIDGET] Widget type: ${widget.type}, Template slug: ${templateSlug}`);
+          return `<div class="widget-error" style="padding: 10px; background: #ffebee; border-left: 3px solid #f44336; margin: 10px 0;">
+            <strong>Widget template not found:</strong> ${templateSlug}.liquid<br>
+            <small>Widget type: ${widget.type}, ID: ${widget.id}</small><br>
+            <small>Tried paths: ${widgetPath}, ${altPath}</small>
+          </div>`;
+        }
+        
+        console.log(`[WIDGET] ✅ Found widget template: ${widgetPath}`);
+        const widgetContent = fs.readFileSync(widgetPath, 'utf8');
+        // Get full context - use current rendering context if available
+        const fullContext = liquidEngine.getCurrentContext ? liquidEngine.getCurrentContext() : null;
+        const widgetContext = fullContext 
+          ? { ...fullContext, widget: widget }
+          : (typeof context === 'object' && context !== null 
+            ? { ...context, widget: widget }
+            : { widget: widget });
+        
+        console.log(`[WIDGET] Rendering ${widget.type} (${templateSlug}) with context keys: ${Object.keys(widgetContext).join(', ')}`);
+        const rendered = await self.liquid.parseAndRender(widgetContent, widgetContext);
+        console.log(`[WIDGET] ✅ Successfully rendered widget ${widget.type} (${rendered.length} bytes)`);
+        return rendered;
+        } catch (error) {
+          console.error(`[WIDGET] Error rendering widget ${widget.type}:`, error.message);
+          console.error(`[WIDGET] Stack:`, error.stack);
+          return `<div class="widget-error" style="padding: 10px; background: #ffebee; border-left: 3px solid #f44336; margin: 10px 0;">
+            <strong>Error rendering widget:</strong> ${error.message}<br>
+            <small>Widget type: ${widget.type}, ID: ${widget.id}</small>
+          </div>`;
+        }
+        } catch (outerError) {
+          // Catch any errors in filter registration or invocation
+          console.error(`[WIDGET] ❌ CRITICAL: Filter invocation error:`, outerError.message);
+          console.error(`[WIDGET] Stack:`, outerError.stack);
+          return `<div class="widget-error" style="padding: 10px; background: #ff0000; color: white; border-left: 3px solid #cc0000; margin: 10px 0;">
+            <strong>CRITICAL: Filter Error:</strong> ${outerError.message}<br>
+            <small>This indicates a problem with the render_widget filter itself</small>
+          </div>`;
+        }
+      });
+    });
+  }
+
+  /**
+   * Setup Express routes
+   */
+  setupRoutes() {
+    // Homepage
+    this.app.get('/', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'home');
+        // Log context data for debugging
+        const widgetSections = Object.keys(context.widgets || {});
+        const widgetCounts = widgetSections.map(s => `${s}:${context.widgets[s]?.length || 0}`).join(', ');
+        console.log(`[HOME] Products: ${context.products?.length || 0}, Widgets: [${widgetCounts}], Menus: ${context.menus?.length || 0}`);
+        
+        // Ensure products are available
+        if (!context.products || context.products.length === 0) {
+          console.warn('[HOME] No products in context, attempting reload...');
+          try {
+            if (this.apiClient) {
+              const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+              context.products = productsResponse.products || productsResponse.data?.products || [];
+              console.log(`[HOME] Reloaded ${context.products.length} products`);
+            } else {
+              console.error('[HOME] API client not available');
+            }
+          } catch (error) {
+            console.error('[HOME] Failed to reload products:', error.message);
+          }
+        }
+        
+        // Ensure widgets are available
+        if (!context.widgets || Object.keys(context.widgets).length === 0) {
+          console.warn('[HOME] No widgets in context, attempting reload...');
+          try {
+            if (this.widgetService) {
+              const widgets = await this.widgetService.getWidgetsBySections();
+              context.widgets = widgets || { hero: [], content: [], footer: [] };
+              console.log(`[HOME] Reloaded widgets: ${Object.keys(context.widgets).join(', ')}`);
+            } else {
+              console.error('[HOME] Widget service not available');
+              context.widgets = { hero: [], content: [], footer: [] };
+            }
+          } catch (error) {
+            console.error('[HOME] Failed to reload widgets:', error.message);
+            context.widgets = { hero: [], content: [], footer: [] };
+          }
+        }
+        
+        const html = await renderWithLayout(this.liquid, 'templates/index', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Products listing page
+    this.app.get('/products', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'products');
+        
+        // DEBUG: Log context data for /products page
+        console.log(`[PRODUCTS PAGE] Context summary:`);
+        console.log(`  - Products count: ${context.products?.length || 0}`);
+        console.log(`  - Widgets sections: ${Object.keys(context.widgets || {}).join(', ') || 'none'}`);
+        console.log(`  - Widgets counts: ${Object.keys(context.widgets || {}).map(s => `${s}:${context.widgets[s]?.length || 0}`).join(', ') || 'none'}`);
+        console.log(`  - Menus count: ${context.menus?.length || 0}`);
+        console.log(`  - Categories count: ${context.categories?.length || 0}`);
+        console.log(`  - Brands count: ${context.brands?.length || 0}`);
+        
+        // Ensure products are loaded for products page
+        if (!context.products || context.products.length === 0) {
+          console.warn('[PRODUCTS PAGE] ⚠️  No products in context, attempting to reload...');
+          try {
+            const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+            context.products = productsResponse.products || productsResponse.data?.products || [];
+            console.log(`[PRODUCTS PAGE] ✅ Reloaded ${context.products.length} products`);
+          } catch (error) {
+            console.error('[PRODUCTS PAGE] ❌ Failed to load products:', error.message);
+          }
+        } else {
+          // DEBUG: Verify products have quantity/stock on products page
+          if (context.products.length > 0) {
+            const sampleProduct = context.products[0];
+            const hasStock = 'stock' in sampleProduct || 'quantity' in sampleProduct;
+            // Use nullish coalescing to show 0 values correctly
+            const stockValue = sampleProduct.stock ?? sampleProduct.quantity ?? 'N/A';
+            console.log(`[PRODUCTS PAGE DEBUG] Sample product - Title: ${sampleProduct.title || sampleProduct.name}, Has stock: ${hasStock}, Stock: ${stockValue}`);
+            console.log(`[PRODUCTS PAGE DEBUG] Product stock details: stock=${sampleProduct.stock}, quantity=${sampleProduct.quantity}, inStock=${sampleProduct.inStock}`);
+            
+            // Check a few more products to see stock distribution
+            const stockCounts = context.products.slice(0, 5).map(p => p.stock ?? 0);
+            console.log(`[PRODUCTS PAGE DEBUG] Stock values for first 5 products: ${stockCounts.join(', ')}`);
+          }
+        }
+        
+        // Ensure widgets are available (they should be from buildContext, but double-check)
+        if (!context.widgets || Object.keys(context.widgets).length === 0) {
+          console.warn('[PRODUCTS PAGE] ⚠️  No widgets in context, attempting to reload...');
+          try {
+            if (this.widgetService) {
+              const widgets = await this.widgetService.getWidgetsBySections();
+              context.widgets = widgets || { hero: [], content: [], footer: [], header: [] };
+              console.log(`[PRODUCTS PAGE] ✅ Reloaded widgets: ${Object.keys(context.widgets).join(', ')}`);
+            } else {
+              console.error('[PRODUCTS PAGE] ❌ Widget service not available');
+              context.widgets = { hero: [], content: [], footer: [], header: [] };
+            }
+          } catch (error) {
+            console.error('[PRODUCTS PAGE] ❌ Failed to reload widgets:', error.message);
+            context.widgets = { hero: [], content: [], footer: [], header: [] };
+          }
+        }
+        
+        // Ensure menus are available
+        if (!context.menus || context.menus.length === 0) {
+          console.warn('[PRODUCTS PAGE] ⚠️  No menus in context, attempting to reload...');
+          try {
+            const axios = require('axios');
+            const menusResponse = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/menus`);
+            const menusData = menusResponse.data;
+            context.menus = Array.isArray(menusData) ? menusData : (menusData.data?.menus || menusData.menus || []);
+            console.log(`[PRODUCTS PAGE] ✅ Reloaded ${context.menus.length} menus`);
+          } catch (error) {
+            console.error('[PRODUCTS PAGE] ❌ Failed to reload menus:', error.message);
+            context.menus = [];
+          }
+        }
+        
+        // Ensure collection.products is set for products template
+        if (context.products && context.products.length > 0) {
+          context.collection = context.collection || {};
+          context.collection.products = context.products;
+          context.collection.title = 'All Products';
+          context.collection.handle = 'all';
+          context.collection.totalProducts = context.products.length;
+        }
+        
+        const html = await renderWithLayout(this.liquid, 'templates/products', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        // If products template doesn't exist, try collections template as fallback
+        if (error.message && error.message.includes('Template not found')) {
+          try {
+            const context = await this.buildContext(req, 'collection');
+            const html = await renderWithLayout(this.liquid, 'templates/collection', context, this.themePath);
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.send(html);
+          } catch (fallbackError) {
+            next(error);
+          }
+        } else {
+          next(error);
+        }
+      }
+    });
+
+    // Product detail page
+    this.app.get('/products/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'product', { productHandle: req.params.handle });
+        // Try multiple template names: product-detail, product, product-page
+        let html;
+        const templateOptions = ['templates/product-detail', 'templates/product', 'templates/product-page'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Product template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Alternative product URL formats (some themes use these)
+    // Format: /product-{id}
+    this.app.get('/product-:id', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'product', { productHandle: `product-${req.params.id}` });
+        let html;
+        const templateOptions = ['templates/product-detail', 'templates/product', 'templates/product-page'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Product template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Format: /product/{id} (alternative without hyphen)
+    this.app.get('/product/:id', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'product', { productHandle: `product-${req.params.id}` });
+        let html;
+        const templateOptions = ['templates/product-detail', 'templates/product', 'templates/product-page'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Product template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Collections listing page (uses categories.liquid template per webstore)
+    this.app.get('/collections', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'collections');
+        // Try categories.liquid first (as per webstore), then collections.liquid, then collection.liquid
+        let html;
+        try {
+          html = await renderWithLayout(this.liquid, 'templates/categories', context, this.themePath);
+        } catch (error) {
+          if (error.message && error.message.includes('Template not found')) {
+            try {
+              html = await renderWithLayout(this.liquid, 'templates/collections', context, this.themePath);
+            } catch (error2) {
+              html = await renderWithLayout(this.liquid, 'templates/collection', context, this.themePath);
+            }
+          } else {
+            throw error;
+          }
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Collection detail page - Try categories first, then collection
+    this.app.get('/collections/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'collection', { collectionHandle: req.params.handle });
+        // Set category in context based on handle
+        const category = context.categories?.find(c => 
+          c.handle === req.params.handle || 
+          c.name?.toLowerCase().replace(/\s+/g, '-') === req.params.handle
+        );
+        if (category) {
+          context.category = category;
+          context.collection = category;
+        }
+        
+        let html;
+        const templateOptions = ['templates/categories', 'templates/category', 'templates/collection'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Category/Collection template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Category routes (alias for collections - some themes use /categories/)
+    this.app.get('/categories', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'collections');
+        let html;
+        const templateOptions = ['templates/categories', 'templates/collections', 'templates/collection'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Categories template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    this.app.get('/categories/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'collection', { collectionHandle: req.params.handle });
+        const category = context.categories?.find(c => 
+          c.handle === req.params.handle || 
+          c.name?.toLowerCase().replace(/\s+/g, '-') === req.params.handle
+        );
+        if (category) {
+          context.category = category;
+          context.collection = category;
+        }
+        
+        let html;
+        const templateOptions = ['templates/categories', 'templates/category', 'templates/collection'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          throw new Error(`Category template not found. Tried: ${templateOptions.join(', ')}`);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Brand routes
+    this.app.get('/brands', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'brands');
+        let html;
+        const templateOptions = ['templates/brands', 'templates/brand-list', 'templates/collections'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          // Create a simple brands listing page
+          html = this.createSimpleBrandsPage(context);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    this.app.get('/brands/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'brand', { brandHandle: req.params.handle });
+        const brand = context.brands?.find(b => 
+          b.handle === req.params.handle || 
+          b.name?.toLowerCase().replace(/\s+/g, '-') === req.params.handle
+        );
+        if (brand) {
+          context.brand = brand;
+          // Filter products by this brand
+          context.collection = {
+            ...brand,
+            products: context.products?.filter(p => p.brandId === brand.id) || []
+          };
+        }
+        
+        let html;
+        const templateOptions = ['templates/brand', 'templates/brands', 'templates/collection'];
+        for (const template of templateOptions) {
+          try {
+            html = await renderWithLayout(this.liquid, template, context, this.themePath);
+            break;
+          } catch (error) {
+            if (!error.message?.includes('Template not found')) {
+              throw error;
+            }
+          }
+        }
+        if (!html) {
+          html = this.createSimpleBrandPage(context, brand);
+        }
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Cart page
+    this.app.get('/cart', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'cart');
+        const html = await renderWithLayout(this.liquid, 'templates/cart', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Search page
+    this.app.get('/search', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'search', { query: req.query.q });
+        const html = await renderWithLayout(this.liquid, 'templates/search', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Landing pages - O2VEND uses /page/:handle for CMS landing pages
+    // These are HTML pages created in CMS and rendered via shopfront API
+    this.app.get('/page/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'page', { pageHandle: req.params.handle });
+        
+        // Load page content from shopfront API (mock)
+        try {
+          const axios = require('axios');
+          const pageResponse = await axios.get(`http://localhost:${this.mockApiPort}/shopfront/api/v2/page/${req.params.handle}`);
+          if (pageResponse.data) {
+            context.page = {
+              ...context.page,
+              ...pageResponse.data,
+              body_html: pageResponse.data.content || pageResponse.data.htmlContent,
+              content: pageResponse.data.content || pageResponse.data.htmlContent
+            };
+          }
+        } catch (error) {
+          console.warn(`[PAGE] Failed to load landing page for ${req.params.handle}:`, error.message);
+          // Fallback to mock API pages endpoint
+          try {
+            const axios = require('axios');
+            const pageResponse = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/pages/${req.params.handle}`);
+            if (pageResponse.data) {
+              context.page = {
+                ...context.page,
+                ...pageResponse.data,
+                body_html: pageResponse.data.content,
+                content: pageResponse.data.content
+              };
+            }
+          } catch (fallbackError) {
+            context.page = {
+              ...context.page,
+              title: req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' '),
+              handle: req.params.handle,
+              body_html: `<h2>${req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ')}</h2><p>Landing page content coming soon.</p>`,
+              content: `<h2>${req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ')}</h2><p>Landing page content coming soon.</p>`
+            };
+          }
+        }
+        
+        // Try page.liquid template first, then fallback to rendering raw HTML
+        try {
+          const html = await renderWithLayout(this.liquid, 'templates/page', context, this.themePath);
+          res.setHeader('Content-Type', 'text/html; charset=utf-8');
+          res.send(html);
+        } catch (templateError) {
+          // If no page template, render raw HTML content within layout
+          console.log(`[PAGE] No page template found, rendering raw HTML for ${req.params.handle}`);
+          const html = this.renderLandingPage(context);
+          res.setHeader('Content-Type', 'text/html; charset=utf-8');
+          res.send(html);
+        }
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Also support /pages/:handle for backward compatibility
+    this.app.get('/pages/:handle', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'page', { pageHandle: req.params.handle });
+        
+        // Load page content from mock API
+        try {
+          const axios = require('axios');
+          const pageResponse = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/pages/${req.params.handle}`);
+          if (pageResponse.data) {
+            context.page = {
+              ...context.page,
+              ...pageResponse.data,
+              body_html: pageResponse.data.content,
+              content: pageResponse.data.content
+            };
+          }
+        } catch (error) {
+          console.warn(`[PAGE] Failed to load page content for ${req.params.handle}:`, error.message);
+          // Set default page content
+          context.page = {
+            ...context.page,
+            title: req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' '),
+            handle: req.params.handle,
+            body_html: `<h2>${req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ')}</h2><p>Page content coming soon.</p>`,
+            content: `<h2>${req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ')}</h2><p>Page content coming soon.</p>`
+          };
+        }
+        
+        const html = await renderWithLayout(this.liquid, 'templates/page', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Development Dashboard - List all theme components
+    this.app.get('/dev', async (req, res, next) => {
+      try {
+        const templates = this.getThemeFiles('templates');
+        const sections = this.getThemeFiles('sections');
+        const widgets = this.getThemeFiles('widgets');
+        const snippets = this.getThemeFiles('snippets');
+        
+        const html = this.generateDevDashboard({ templates, sections, widgets, snippets });
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Preview Section
+    this.app.get('/dev/section/:name', async (req, res, next) => {
+      try {
+        const sectionName = req.params.name.replace(/\.liquid$/, '');
+        const context = await this.buildContext(req, 'home');
+        const sectionContent = await this.liquid.renderFile(
+          path.join(this.themePath, 'sections', `${sectionName}.liquid`),
+          context
+        );
+        
+        const html = this.generatePreviewPage({
+          title: `Section: ${sectionName}`,
+          content: sectionContent,
+          type: 'section',
+          name: sectionName,
+          backUrl: '/dev'
+        });
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Preview Widget
+    this.app.get('/dev/widget/:type', async (req, res, next) => {
+      try {
+        const widgetType = req.params.type.replace(/\.liquid$/, '');
+        const context = await this.buildContext(req, 'home');
+        
+        // Ensure products are loaded for widget context (needed for product widgets)
+        if (!context.products || context.products.length === 0) {
+          try {
+            if (this.apiClient) {
+              const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+              context.products = productsResponse.products || productsResponse.data?.products || [];
+              console.log(`[DEV WIDGET] Loaded ${context.products.length} products for widget context`);
+            }
+          } catch (error) {
+            console.warn('[DEV WIDGET] Failed to load products:', error.message);
+          }
+        }
+        
+        // Get mock widget data for this type
+        const mockWidgets = this.mockApi?.mockData?.widgets || [];
+        const mockWidget = mockWidgets.find(w => 
+          w.type === widgetType || 
+          w.type.toLowerCase() === widgetType.toLowerCase() ||
+          w.id?.includes(widgetType)
+        ) || {
+          id: `widget-${widgetType}-1`,
+          type: widgetType,
+          section: 'content',
+          sectionName: 'content',
+          status: 'active',
+          position: 1,
+          title: `Test ${widgetType}`,
+          settings: {},
+          data: { content: {} }
+        };
+        
+        // Normalize widget using widget service if available
+        let widgetToRender = mockWidget;
+        if (this.widgetService) {
+          widgetToRender = this.widgetService.normalizeWidget(mockWidget);
+        }
+        
+        const widgetContent = await this.renderWidget(widgetToRender, context);
+        
+        const html = this.generatePreviewPage({
+          title: `Widget: ${widgetType}`,
+          content: widgetContent,
+          type: 'widget',
+          name: widgetType,
+          backUrl: '/dev'
+        });
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Preview Snippet
+    this.app.get('/dev/snippet/:name', async (req, res, next) => {
+      try {
+        let snippetName = req.params.name;
+        
+        // Handle URL encoding and object string issues
+        if (snippetName.includes('[object') || snippetName.includes('%5Bobject')) {
+          return res.status(400).send('Invalid snippet name. Please use the dashboard to navigate to snippets.');
+        }
+        
+        snippetName = decodeURIComponent(snippetName).replace(/\.liquid$/, '');
+        
+        // Check if snippet exists
+        const snippetPath = path.join(this.themePath, 'snippets', `${snippetName}.liquid`);
+        if (!fs.existsSync(snippetPath)) {
+          return res.status(404).send(`Snippet not found: ${snippetName}.liquid`);
+        }
+        
+        const context = await this.buildContext(req, 'home');
+        
+        // Try to render snippet with common variables
+        const snippetContext = {
+          ...context,
+          snippet: {
+            name: snippetName
+          },
+          // Add common snippet variables
+          product: context.products?.[0] || context.product,
+          collection: context.collections?.[0] || context.collection,
+          cart: context.cart
+        };
+        
+        const snippetContent = await this.liquid.renderFile(snippetPath, snippetContext);
+        
+        const html = this.generatePreviewPage({
+          title: `Snippet: ${snippetName}`,
+          content: snippetContent,
+          type: 'snippet',
+          name: snippetName,
+          backUrl: '/dev'
+        });
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // View Template
+    this.app.get('/dev/template/*', async (req, res, next) => {
+      try {
+        const templatePath = req.params[0] || req.params.name;
+        const templateName = templatePath.replace(/\.liquid$/, '');
+        
+        // Check if it's a subdirectory template (e.g., account/dashboard)
+        let fullPath = path.join(this.themePath, 'templates', `${templateName}.liquid`);
+        if (!fs.existsSync(fullPath)) {
+          // Try as subdirectory with index.liquid
+          const subPath = path.join(this.themePath, 'templates', templateName, 'index.liquid');
+          if (fs.existsSync(subPath)) {
+            fullPath = subPath;
+          } else {
+            return res.status(404).send(`Template not found: ${templateName}`);
+          }
+        }
+        
+        // Build appropriate context based on template type
+        let pageType = 'home';
+        if (templateName.includes('product')) pageType = 'product';
+        else if (templateName.includes('collection') || templateName.includes('categor')) pageType = 'collection';
+        else if (templateName.includes('cart')) pageType = 'cart';
+        else if (templateName.includes('search')) pageType = 'search';
+        else if (templateName.includes('page')) pageType = 'page';
+        else if (templateName.includes('account') || templateName.includes('login')) pageType = 'page';
+        else if (templateName.includes('checkout')) pageType = 'cart';
+        
+        const context = await this.buildContext(req, pageType);
+        const html = await renderWithLayout(this.liquid, `templates/${templateName}`, context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
+    // Favicon handler
+    this.app.get('/favicon.ico', (req, res) => {
+      res.status(204).end(); // No Content
+    });
+
+    // API proxy (for real API mode)
+    if (this.mode === 'real' && this.apiClient) {
+      this.app.use('/api', (req, res, next) => {
+        // Proxy API requests to real API
+        // This is handled by mock API in mock mode
+        next();
+      });
+    }
+
+    // Error handler
+    this.app.use((error, req, res, next) => {
+      // Ignore request aborted errors - they're harmless (client cancelled request)
+      if (error && (error.code === 'ECONNRESET' || 
+                    error.message === 'request aborted' || 
+                    error.message?.includes('aborted') ||
+                    error.type === 'entity.parse.failed' ||
+                    error.name === 'BadRequestError')) {
+        // Request was aborted - don't log as error
+        if (!res.headersSent) {
+          res.status(400).end();
+        }
+        return;
+      }
+      
+      console.error(chalk.red('[ERROR]'), error.message || error);
+      if (process.env.DEBUG) {
+        console.error(error.stack);
+      }
+      
+      // Return JSON for API/asset requests, HTML for page requests
+      const isApiRequest = req.path.startsWith('/api') || 
+                          req.path.startsWith('/webstoreapi') || 
+                          req.path.startsWith('/assets') ||
+                          req.path.startsWith('/shopfront/api');
+      
+      if (isApiRequest && !res.headersSent) {
+        res.status(500).json({ 
+          error: error.message || 'Internal server error',
+          path: req.path 
+        });
+        return;
+      }
+      
+      if (!res.headersSent) {
+        res.status(500).send(`
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>Error</title>
+            <style>
+              body { font-family: monospace; padding: 2rem; }
+              h1 { color: #d32f2f; }
+              pre { background: #f5f5f5; padding: 1rem; border-radius: 4px; }
+            </style>
+          </head>
+          <body>
+            <h1>Error Rendering Page</h1>
+            <pre>${error.message}\n\n${error.stack}</pre>
+          </body>
+          </html>
+        `);
+      }
+    });
+  }
+
+  /**
+   * Build template context
+   * 
+   * IMPORTANT NOTES ABOUT DATA FLOW:
+   * 
+   * 1. PRODUCTS WITH QUANTITY/STOCK:
+   *    - Mock data generates products with 'stock' field (see mock-data.js)
+   *    - Products also have variants with 'stock' field
+   *    - The API client normalizes keys (PascalCase -> camelCase) but 'stock' is already lowercase
+   *    - Products should maintain 'stock' field when passed to templates
+   *    - If template expects 'quantity' instead of 'stock', consider adding both fields
+   * 
+   * 2. WIDGETS LOADING:
+   *    - Widgets are loaded via widgetService.getWidgetsBySections()
+   *    - Widgets are organized by section (header, hero, content, footer)
+   *    - Widgets should be available for ALL page types (home, products, collection, etc.)
+   *    - If widgets are missing, check:
+   *      a) widgetService is initialized (should be created in setupServices)
+   *      b) Mock API is returning widgets correctly
+   *      c) Widget service is properly organizing widgets by section
+   * 
+   * 3. MENUS LOADING:
+   *    - Menus are loaded from /webstoreapi/menus endpoint
+   *    - Menus should be available for navigation in header/footer sections
+   *    - If menus are missing, check:
+   *      a) Mock API is running and responding to /webstoreapi/menus
+   *      b) Menu data structure matches expected format
+   * 
+   * @param {Object} req - Express request
+   * @param {string} pageType - Page type (home, product, collection, etc.)
+   * @param {Object} extra - Extra context data
+   * @returns {Promise<Object>} Template context
+   */
+  async buildContext(req, pageType, extra = {}) {
+    const context = {
+      shop: {},
+      tenant: {},
+      page: {
+        type: pageType,
+        ...extra
+      },
+      products: [],
+      collections: [],
+      categories: [],
+      brands: [],
+      cart: { 
+        id: 'mock-cart-1',
+        items: [], 
+        total: 0, 
+        itemCount: 0,
+        currency: 'USD',
+        subtotal: 0,
+        tax: 0,
+        shipping: 0
+      },
+      // Mock authenticated customer for dev mode (allows add-to-cart without login)
+      customer: {
+        id: 'mock-customer-1',
+        isAuthenticated: true,
+        firstName: 'Test',
+        lastName: 'User',
+        email: 'test@example.com',
+        phone: '+1234567890',
+        name: 'Test User'
+      },
+      widgets: {},
+      settings: {},
+      menus: [],
+      ...extra
+    };
+
+    try {
+      // Load settings from settings_data.json
+      const settingsPath = path.join(this.themePath, 'config', 'settings_data.json');
+      if (fs.existsSync(settingsPath)) {
+        const settingsData = fs.readFileSync(settingsPath, 'utf8');
+        context.settings = JSON.parse(settingsData);
+      }
+    } catch (error) {
+      console.warn('[CONTEXT] Failed to load settings:', error.message);
+    }
+
+    // Load data based on mode
+    // Note: In mock mode, apiClient is created in start() method after mock API starts
+    if (this.mode === 'mock' && this.apiClient) {
+      // Widget service should be available, but continue even if it's not
+      if (!this.widgetService) {
+        console.warn('[CONTEXT] Widget service not initialized yet in mock mode');
+      }
+      // Use mock API (API client points to mock API via proxy)
+      try {
+        const storeInfo = await this.apiClient.getStoreInfo(true);
+        context.shop = storeInfo || {
+          name: 'My Store',
+          description: 'O2VEND Store',
+          domain: 'localhost:3000',
+          email: 'store@example.com'
+        };
+        
+        // Get widgets for sections from mock API
+        // NOTE: Widgets should be loaded for ALL page types (home, products, collection, etc.)
+        // The widget service filters widgets by section, so all sections should be available
+        if (this.widgetService) {
+          try {
+            console.log(`[CONTEXT] Loading widgets for page type: ${pageType}`);
+            const widgets = await this.widgetService.getWidgetsBySections();
+            context.widgets = widgets || {
+              hero: [],
+              products: [],
+              footer: [],
+              content: [],
+              header: []
+            };
+            // Log widget counts by section
+            const widgetCounts = Object.keys(context.widgets).map(section => 
+              `${section}: ${context.widgets[section]?.length || 0}`
+            ).join(', ');
+            console.log(`[CONTEXT] ✅ Widgets loaded: ${widgetCounts}`);
+            
+            // DEBUG: Log detailed widget information
+            Object.keys(context.widgets).forEach(section => {
+              if (context.widgets[section] && context.widgets[section].length > 0) {
+                console.log(`[CONTEXT DEBUG] Section '${section}' has ${context.widgets[section].length} widget(s):`);
+                context.widgets[section].slice(0, 3).forEach((w, idx) => {
+                  console.log(`  - Widget ${idx + 1}: ${w.type || 'Unknown'} (ID: ${w.id || 'no-id'})`);
+                });
+              }
+            });
+          } catch (error) {
+            console.error('[CONTEXT] ❌ Failed to load widgets:', error.message);
+            console.error('[CONTEXT] Error stack:', error.stack);
+            context.widgets = {
+              hero: [],
+              products: [],
+              footer: [],
+              content: [],
+              header: []
+            };
+          }
+        } else {
+          console.warn('[CONTEXT] ⚠️  Widget service not available, using empty widgets');
+          console.warn('[CONTEXT] This may happen if widgetService was not initialized properly');
+          context.widgets = {
+            hero: [],
+            products: [],
+            footer: [],
+            content: [],
+            header: []
+          };
+        }
+        
+        // Always load products, categories, brands, menus, and cart for navigation and widgets
+        try {
+          // Load products
+          const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+          context.products = productsResponse.products || productsResponse.data?.products || [];
+          console.log(`[CONTEXT] Loaded ${context.products.length} products`);
+          
+          // DEBUG: Verify products have quantity/stock field
+          if (context.products.length > 0) {
+            const firstProduct = context.products[0];
+            const hasStock = 'stock' in firstProduct || 'quantity' in firstProduct;
+            // Use nullish coalescing to show 0 values correctly (0 || 'N/A' would show N/A incorrectly)
+            const stockValue = firstProduct.stock ?? firstProduct.quantity ?? 'N/A';
+            console.log(`[CONTEXT DEBUG] First product sample - Has stock field: ${hasStock}, Stock value: ${stockValue}`);
+            console.log(`[CONTEXT DEBUG] First product keys: ${Object.keys(firstProduct).join(', ')}`);
+            console.log(`[CONTEXT DEBUG] First product stock details: stock=${firstProduct.stock}, quantity=${firstProduct.quantity}, inStock=${firstProduct.inStock}`);
+            
+            // Check if variants have stock
+            if (firstProduct.variants && firstProduct.variants.length > 0) {
+              const firstVariant = firstProduct.variants[0];
+              const variantHasStock = 'stock' in firstVariant || 'quantity' in firstVariant;
+              const variantStockValue = firstVariant.stock ?? firstVariant.quantity ?? 'N/A';
+              console.log(`[CONTEXT DEBUG] First variant sample - Has stock field: ${variantHasStock}, Stock value: ${variantStockValue}`);
+              console.log(`[CONTEXT DEBUG] First variant stock details: stock=${firstVariant.stock}, quantity=${firstVariant.quantity}, inStock=${firstVariant.inStock}, available=${firstVariant.available}`);
+            }
+          }
+          
+          // Load categories for navigation
+          try {
+            const categoriesResponse = await this.apiClient.getCategories({ limit: 50, offset: 0 });
+            context.categories = categoriesResponse.categories || categoriesResponse.data?.categories || categoriesResponse || [];
+            context.collections = context.categories; // Also set collections for compatibility
+            console.log(`[CONTEXT] Loaded ${context.categories.length} categories`);
+          } catch (error) {
+            console.warn('[CONTEXT] Failed to load categories:', error.message);
+            context.categories = [];
+            context.collections = [];
+          }
+          
+          // Load brands for navigation
+          try {
+            const brandsResponse = await this.apiClient.getBrands({ limit: 50, offset: 0 });
+            context.brands = brandsResponse.brands || brandsResponse.data?.brands || brandsResponse || [];
+            console.log(`[CONTEXT] Loaded ${context.brands.length} brands`);
+          } catch (error) {
+            console.warn('[CONTEXT] Failed to load brands:', error.message);
+            context.brands = [];
+          }
+          
+          // Load menus (via webstoreapi) - use axios from apiClient
+          // NOTE: Menus are loaded for navigation in header/footer sections
+          // They should be available in context for all page types
+          try {
+            const axios = require('axios');
+            console.log(`[CONTEXT] Loading menus from http://localhost:${this.mockApiPort}/webstoreapi/menus`);
+            const menusResponse = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/menus`);
+            const menusData = menusResponse.data;
+            context.menus = Array.isArray(menusData) ? menusData : (menusData.data?.menus || menusData.menus || []);
+            console.log(`[CONTEXT] ✅ Loaded ${context.menus.length} menus`);
+            
+            // DEBUG: Log menu details
+            if (context.menus.length > 0) {
+              context.menus.forEach((menu, idx) => {
+                const itemCount = menu.items?.length || 0;
+                console.log(`[CONTEXT DEBUG] Menu ${idx + 1}: ${menu.name || menu.id || 'unnamed'} (${itemCount} items)`);
+              });
+            } else {
+              console.warn('[CONTEXT DEBUG] ⚠️  No menus loaded - menus array is empty');
+            }
+          } catch (error) {
+            console.error('[CONTEXT] ❌ Failed to load menus:', error.message);
+            console.error('[CONTEXT] Error details:', error.response?.status, error.response?.data);
+            context.menus = [];
+          }
+          
+          // Load cart data
+          try {
+            const axios = require('axios');
+            const cartResponse = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/carts`);
+            if (cartResponse.data && cartResponse.data.data) {
+              const cartData = cartResponse.data.data;
+              context.cart = {
+                ...context.cart,
+                ...cartData,
+                itemCount: cartData.items?.length || cartData.itemCount || 0,
+                total: cartData.total || cartData.subTotal || 0
+              };
+            }
+          } catch (error) {
+            // Cart might not exist yet, that's okay - use default empty cart
+            console.log('[CONTEXT] Using default empty cart');
+          }
+        } catch (error) {
+          console.warn('[CONTEXT] Failed to load data:', error.message);
+          context.products = [];
+        }
+        
+        // Load page-specific data
+        if (pageType === 'product' && extra.productHandle) {
+          // Load single product data
+          try {
+            // First try to find in already loaded products
+            let product = context.products?.find(p => 
+              (p.handle && p.handle.toLowerCase() === extra.productHandle.toLowerCase()) || 
+              (p.slug && p.slug.toLowerCase() === extra.productHandle.toLowerCase()) ||
+              (p.id && String(p.id).toLowerCase() === extra.productHandle.toLowerCase())
+            );
+            
+            // If not found, try loading more products
+            if (!product) {
+              const productsResponse = await this.apiClient.getProducts({ limit: 100 });
+              const allProducts = productsResponse.products || productsResponse.data?.products || [];
+              product = allProducts.find(p => 
+                (p.handle && p.handle.toLowerCase() === extra.productHandle.toLowerCase()) || 
+                (p.slug && p.slug.toLowerCase() === extra.productHandle.toLowerCase()) ||
+                (p.id && String(p.id).toLowerCase() === extra.productHandle.toLowerCase())
+              );
+            }
+            
+            if (product) {
+              context.product = product;
+              console.log(`[CONTEXT] Found product: ${product.title || product.name} (handle: ${product.handle || product.slug})`);
+            } else {
+              console.warn(`[CONTEXT] Product not found with handle/slug/id: ${extra.productHandle}`);
+              // Fallback to first product if handle not found
+              if (context.products && context.products.length > 0) {
+                context.product = context.products[0];
+                console.log(`[CONTEXT] Using fallback product: ${context.product.title || context.product.name}`);
+              }
+            }
+          } catch (error) {
+            console.warn('[CONTEXT] Failed to load product:', error.message);
+            if (context.products && context.products.length > 0) {
+              context.product = context.products[0];
+            }
+          }
+        }
+      } catch (error) {
+        console.warn('[CONTEXT] Failed to load from mock API:', error.message);
+        // Fallback to default values
+        context.shop = {
+          name: 'My Store',
+          description: 'O2VEND Store',
+          domain: 'localhost:3000',
+          email: 'store@example.com'
+        };
+        context.widgets = {
+          hero: [],
+          products: [],
+          footer: [],
+          content: []
+        };
+      }
+    } else if (this.apiClient) {
+      // Use real API
+      try {
+        const storeInfo = await this.apiClient.getStoreInfo(true);
+        context.shop = storeInfo;
+        context.tenant = { id: this.apiClient.tenantId };
+        
+        // Get widgets for sections
+        const widgets = await this.widgetService.getWidgetsBySections();
+        context.widgets = widgets;
+        
+        // Ensure all widgets have template_path set for rendering
+        Object.keys(widgets).forEach(section => {
+          if (Array.isArray(widgets[section])) {
+            widgets[section].forEach(widget => {
+              if (!widget.template_path && widget.template) {
+                widget.template_path = `widgets/${widget.template}`;
+              }
+              if (!widget.template_path && widget.type) {
+                const templateSlug = this.widgetService.getTemplateSlug(widget.type);
+                widget.template_path = `widgets/${templateSlug}`;
+                widget.template = templateSlug;
+              }
+            });
+          }
+        });
+        
+        // Load page-specific data
+        if (pageType === 'products' || pageType === 'home') {
+          // Load products for products listing page or homepage
+          const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+          context.products = productsResponse.products || [];
+          // For products page, also set collection.products
+          if (pageType === 'products') {
+            context.collection = context.collection || {};
+            context.collection.products = context.products;
+            context.collection.title = 'All Products';
+            context.collection.handle = 'all';
+            context.collection.totalProducts = context.products.length;
+          }
+        } else if (pageType === 'product' && extra.productHandle) {
+          // Load product data
+          // context.product = await this.loadProduct(extra.productHandle);
+        } else if (pageType === 'collection') {
+          // Load products for collection
+          const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
+          context.products = productsResponse.products || [];
+          // Set collection.products for collection pages
+          context.collection = context.collection || {};
+          context.collection.products = context.products;
+        }
+      } catch (error) {
+        console.warn('[CONTEXT] Failed to load from API:', error.message);
+      }
+    }
+
+    // Enrich widgets with products, categories, and brands data
+    this.enrichWidgetsWithData(context);
+    
+    return context;
+  }
+  
+  /**
+   * Enrich widgets with actual data (products, categories, brands)
+   * This is essential for product carousels, category lists, etc. to display content
+   * Widget templates expect data in widget.data.products (not widget.data.content.Products)
+   */
+  enrichWidgetsWithData(context) {
+    if (!context.widgets) return;
+    
+    const products = context.products || [];
+    const categories = context.categories || [];
+    const brands = context.brands || [];
+    
+    let enrichedCount = 0;
+    
+    // Process all widgets in all sections
+    Object.keys(context.widgets).forEach(section => {
+      if (!Array.isArray(context.widgets[section])) return;
+      
+      context.widgets[section].forEach(widget => {
+        const type = (widget.type || '').toLowerCase();
+        
+        // Initialize widget.data if not present
+        widget.data = widget.data || {};
+        
+        // Enrich ProductCarousel, ProductGrid, and Product widgets with products
+        // Widget templates use: widget.data.products, widget_data.products
+        if (type.includes('product') || type === 'featuredproducts' || type === 'bestsellerproducts' || type === 'newproducts' || type === 'simpleproduct' || type === 'singleproduct') {
+          const widgetProducts = this.getProductsForWidget(widget, products);
+          
+          // Set products at multiple levels for template compatibility
+          widget.data.products = widgetProducts;
+          widget.data.Products = widgetProducts;
+          widget.products = widgetProducts;
+          
+          // Also set in content for some template variations
+          widget.data.content = widget.data.content || {};
+          widget.data.content.products = widgetProducts;
+          widget.data.content.Products = widgetProducts;
+          
+          enrichedCount++;
+          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${widgetProducts.length} products`);
+        }
+        
+        // Enrich CategoryList and CategoryListCarousel widgets with categories
+        // Widget templates use: widget.data.categories, widget.categories
+        if (type.includes('category') || type === 'categorylist' || type === 'categorylistcarousel') {
+          const widgetCategories = categories.slice(0, 10);
+          
+          // Set categories at multiple levels
+          widget.data.categories = widgetCategories;
+          widget.data.Categories = widgetCategories;
+          widget.categories = widgetCategories;
+          
+          widget.data.content = widget.data.content || {};
+          widget.data.content.categories = widgetCategories;
+          widget.data.content.Categories = widgetCategories;
+          
+          enrichedCount++;
+          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${widgetCategories.length} categories`);
+        }
+        
+        // Enrich BrandCarousel and Brand widgets with brands
+        if (type.includes('brand') || type === 'brandcarousel' || type === 'brandlist') {
+          widget.data.brands = brands;
+          widget.data.Brands = brands;
+          widget.brands = brands;
+          
+          widget.data.content = widget.data.content || {};
+          widget.data.content.brands = brands;
+          widget.data.content.Brands = brands;
+          
+          enrichedCount++;
+          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${brands.length} brands`);
+        }
+        
+        // Enrich RecentlyViewed widgets with products (use first 6 products as mock recent views)
+        if (type === 'recentlyviewed' || type === 'recently-viewed') {
+          const recentProducts = products.slice(0, 6);
+          widget.data.products = recentProducts;
+          widget.data.Products = recentProducts;
+          widget.products = recentProducts;
+          
+          enrichedCount++;
+          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${recentProducts.length} recently viewed products`);
+        }
+      });
+    });
+    
+    console.log(`[CONTEXT] ✅ Enriched ${enrichedCount} widgets with data`);
+  }
+  
+  /**
+   * Get products for a specific widget based on its settings
+   */
+  getProductsForWidget(widget, products) {
+    // Get the limit from widget settings, default to 12
+    const limit = widget.settings?.limit || widget.data?.content?.Limit || 12;
+    
+    // Get products based on widget type
+    const type = (widget.type || '').toLowerCase();
+    
+    if (type.includes('featured') || type === 'featuredproducts') {
+      // Featured products - filter by featured tag or just take first N
+      const featured = products.filter(p => p.tags?.includes('featured') || p.featured);
+      return featured.length > 0 ? featured.slice(0, limit) : products.slice(0, limit);
+    }
+    
+    if (type.includes('bestseller') || type === 'bestsellerproducts') {
+      // Best seller products - sort by sales or just take random N
+      return products.slice(0, limit);
+    }
+    
+    if (type.includes('new') || type === 'newproducts') {
+      // New products - sort by created date
+      const sorted = [...products].sort((a, b) => 
+        new Date(b.createdAt || 0) - new Date(a.createdAt || 0)
+      );
+      return sorted.slice(0, limit);
+    }
+    
+    // Default: return first N products
+    return products.slice(0, limit);
+  }
+
+  /**
+   * Create a simple brands listing page (fallback)
+   */
+  createSimpleBrandsPage(context) {
+    const brands = context.brands || [];
+    const brandCards = brands.map(brand => `
+      <div style="background: #fff; border-radius: 8px; padding: 1rem; text-align: center; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+        <a href="/brands/${brand.handle || brand.name?.toLowerCase().replace(/\s+/g, '-') || brand.id}">
+          <img src="${brand.image || brand.imageUrl || 'https://picsum.photos/seed/' + brand.id + '/200/100'}" 
+               alt="${brand.name}" 
+               style="max-width: 150px; height: auto; margin-bottom: 0.5rem;">
+          <h3 style="margin: 0.5rem 0; color: #333;">${brand.name}</h3>
+        </a>
+      </div>
+    `).join('');
+    
+    return `
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <title>Brands - ${context.shop?.name || 'Store'}</title>
+        <style>
+          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; margin: 0; padding: 2rem; }
+          h1 { text-align: center; margin-bottom: 2rem; }
+          .brands-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1.5rem; max-width: 1200px; margin: 0 auto; }
+        </style>
+      </head>
+      <body>
+        <h1>Brands</h1>
+        <div class="brands-grid">${brandCards}</div>
+        <p style="text-align: center; margin-top: 2rem;"><a href="/">← Back to Home</a></p>
+      </body>
+      </html>
+    `;
+  }
+  
+  /**
+   * Create a simple brand detail page (fallback)
+   */
+  createSimpleBrandPage(context, brand) {
+    if (!brand) {
+      return `
+        <!DOCTYPE html>
+        <html>
+        <head><title>Brand Not Found</title></head>
+        <body>
+          <h1>Brand Not Found</h1>
+          <p><a href="/brands">← Back to Brands</a></p>
+        </body>
+        </html>
+      `;
+    }
+    
+    const products = context.collection?.products || [];
+    const productCards = products.map(p => `
+      <div style="background: #fff; border-radius: 8px; padding: 1rem; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+        <a href="/products/${p.handle || p.id}">
+          <img src="${p.images?.[0] || p.imageUrl || 'https://picsum.photos/seed/' + p.id + '/300/300'}" 
+               alt="${p.title || p.name}" style="width: 100%; height: 200px; object-fit: cover; border-radius: 4px;">
+          <h4 style="margin: 0.5rem 0;">${p.title || p.name}</h4>
+          <p style="color: #2563eb; font-weight: bold;">$${((p.price || 0) / 100).toFixed(2)}</p>
+        </a>
+      </div>
+    `).join('');
+    
+    return `
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <title>${brand.name} - ${context.shop?.name || 'Store'}</title>
+        <style>
+          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; margin: 0; padding: 2rem; }
+          h1 { text-align: center; }
+          .products-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 1.5rem; max-width: 1200px; margin: 0 auto; }
+        </style>
+      </head>
+      <body>
+        <h1>${brand.name}</h1>
+        <p style="text-align: center;">${brand.description || ''}</p>
+        ${products.length > 0 ? `<div class="products-grid">${productCards}</div>` : '<p style="text-align: center;">No products found for this brand.</p>'}
+        <p style="text-align: center; margin-top: 2rem;"><a href="/brands">← Back to Brands</a></p>
+      </body>
+      </html>
+    `;
+  }
+
+  /**
+   * Render a CMS landing page with the theme's layout
+   * Landing pages are HTML content from CMS rendered within the theme layout
+   */
+  renderLandingPage(context) {
+    const page = context.page || {};
+    const htmlContent = page.body_html || page.htmlContent || page.content || '<p>Page content not available.</p>';
+    const title = page.title || 'Page';
+    
+    return `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>${title} - ${context.shop?.name || 'Store'}</title>
+        <meta name="description" content="${page.metaDescription || ''}">
+        <style>
+          * { margin: 0; padding: 0; box-sizing: border-box; }
+          body { 
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif; 
+            background: #fff; 
+            color: #333;
+            line-height: 1.6;
+          }
+          .container { max-width: 1200px; margin: 0 auto; padding: 0 20px; }
+          .landing-page { padding: 40px 0; min-height: 60vh; }
+          .page-header { 
+            background: #f8f9fa; 
+            padding: 20px 0; 
+            border-bottom: 1px solid #eee;
+            margin-bottom: 40px;
+          }
+          .page-header nav { max-width: 1200px; margin: 0 auto; padding: 0 20px; }
+          .page-header nav a { 
+            color: #333; 
+            text-decoration: none; 
+            margin-right: 20px;
+            font-weight: 500;
+          }
+          .page-header nav a:hover { color: #667eea; }
+          .page-footer {
+            background: #333;
+            color: #fff;
+            padding: 40px 0;
+            margin-top: 60px;
+            text-align: center;
+          }
+          @media (max-width: 768px) {
+            .landing-page [style*="grid-template-columns: 1fr 1fr"] {
+              grid-template-columns: 1fr !important;
+            }
+            .landing-page [style*="grid-template-columns: repeat(4"] {
+              grid-template-columns: repeat(2, 1fr) !important;
+            }
+          }
+        </style>
+      </head>
+      <body>
+        <header class="page-header">
+          <nav>
+            <a href="/">Home</a>
+            <a href="/products">Products</a>
+            <a href="/categories">Categories</a>
+            <a href="/page/about">About</a>
+            <a href="/page/contact">Contact</a>
+          </nav>
+        </header>
+        
+        <main class="landing-page">
+          ${htmlContent}
+        </main>
+        
+        <footer class="page-footer">
+          <div class="container">
+            <p>&copy; ${new Date().getFullYear()} ${context.shop?.name || 'My Store'}. All rights reserved.</p>
+          </div>
+        </footer>
+      </body>
+      </html>
+    `;
+  }
+
+  /**
+   * Load theme settings from config/settings_data.json
+   * These settings are used to process CSS files with Liquid variables
+   */
+  loadThemeSettings() {
+    try {
+      const settingsPath = path.join(this.themePath, 'config', 'settings_data.json');
+      if (fs.existsSync(settingsPath)) {
+        const settingsData = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        // Use 'current' settings, fallback to 'default' preset
+        const settings = settingsData.current || settingsData.presets?.default || {};
+        return settings;
+      }
+    } catch (error) {
+      console.warn('[SETTINGS] Failed to load theme settings:', error.message);
+    }
+    
+    // Return default settings if file doesn't exist
+    return {
+      color_primary: '#2563eb',
+      color_primary_light: '#3b82f6',
+      color_primary_dark: '#1d4ed8',
+      color_secondary: '#64748b',
+      color_accent: '#f59e0b',
+      color_accent_light: '#fbbf24',
+      color_accent_dark: '#d97706',
+      color_background: '#ffffff',
+      color_surface: '#f8fafc',
+      color_border: '#e2e8f0',
+      color_text: '#1e293b',
+      color_text_muted: '#64748b',
+      color_text_light: '#94a3b8',
+      color_success: '#22c55e',
+      color_error: '#ef4444',
+      color_warning: '#f59e0b',
+      color_info: '#3b82f6',
+      font_primary: 'Inter',
+      font_display: 'Playfair Display',
+      font_heading: 'Inter',
+      font_body: 'Inter',
+      font_mono: 'SF Mono',
+      font_size_base: 16,
+      font_size_heading: 32,
+      font_weight_normal: '400',
+      font_weight_medium: '500',
+      font_weight_bold: '700',
+      line_height_base: 1.6,
+      line_height_heading: 1.2,
+      letter_spacing_heading: '-0.02',
+      letter_spacing_uppercase: '0.05',
+      container_width: 1200,
+      container_padding: 24,
+      spacing_section: 64,
+      spacing_large: 32,
+      spacing_component: 24,
+      spacing_element: 16,
+      spacing_small: 8,
+      spacing_xsmall: 4,
+      border_radius_small: 4,
+      border_radius_medium: 8,
+      border_radius_large: 12,
+      animation_speed: 'normal',
+      enable_animations: true,
+      enable_parallax: false,
+      enable_hover_effects: true,
+      enable_fade_in: true,
+      enable_stagger_animation: true,
+      shadow_opacity: 0.1,
+      shadow_blur: 8,
+      shadow_spread: 0,
+      depth_level_1: 1,
+      depth_level_2: 4,
+      depth_level_3: 8,
+      button_style: 'modern',
+      button_padding_vertical: 12,
+      button_padding_tal: 24,
+      button_hover_lift: true,
+      button_ripple_effect: false,
+      button_transition_speed: 200,
+      lazy_load_images: true,
+      preload_critical_css: true,
+      optimize_animations: true,
+      show_loading_skeletons: true,
+      loading_animation: 'spinner'
+    };
+  }
+
+  /**
+   * Get theme files from a directory
+   */
+  getThemeFiles(directory) {
+    const dirPath = path.join(this.themePath, directory);
+    if (!fs.existsSync(dirPath)) {
+      return [];
+    }
+    
+    const files = [];
+    const scanDir = (dir, basePath = '') => {
+      const items = fs.readdirSync(dir);
+      items.forEach(item => {
+        const itemPath = path.join(dir, item);
+        const stat = fs.statSync(itemPath);
+        if (stat.isDirectory()) {
+          scanDir(itemPath, path.join(basePath, item));
+        } else if (item.endsWith('.liquid')) {
+          const name = item.replace(/\.liquid$/, '');
+          const fullPath = basePath ? `${basePath}/${name}` : name;
+          files.push({
+            name: name,
+            path: fullPath,
+            fullPath: itemPath
+          });
+        }
+      });
+    };
+    
+    scanDir(dirPath);
+    return files.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Render a widget
+   */
+  async renderWidget(widget, context) {
+    if (!widget || !widget.type) {
+      return '';
+    }
+    
+    try {
+      const templateSlug = this.widgetService.getTemplateSlug(widget.type);
+      const widgetPath = path.join(this.themePath, 'widgets', `${templateSlug}.liquid`);
+      
+      if (!fs.existsSync(widgetPath)) {
+        return `<div class="error">Widget template not found: ${templateSlug}.liquid</div>`;
+      }
+      
+      const widgetContent = fs.readFileSync(widgetPath, 'utf8');
+      const widgetContext = {
+        ...context,
+        widget: widget
+      };
+      
+      return await this.liquid.parseAndRender(widgetContent, widgetContext);
+    } catch (error) {
+      return `<div class="error">Error rendering widget: ${error.message}</div>`;
+    }
+  }
+
+  /**
+   * Generate development dashboard HTML
+   */
+  generateDevDashboard({ templates, sections, widgets, snippets }) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>O2VEND Theme Development Dashboard</title>
+  <link rel="icon" type="image/png" href="/o2vend-assets/favicon.png">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    :root {
+      --o2vend-primary: #F9A825;
+      --o2vend-primary-dark: #E59100;
+      --o2vend-primary-light: #FFCA28;
+      --o2vend-dark: #1A1A1A;
+      --o2vend-text: #333333;
+      --o2vend-bg: #FFFDF7;
+      --o2vend-surface: #FFFFFF;
+      --o2vend-border: #FFF3D0;
+    }
+    body {
+      font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      background: var(--o2vend-bg);
+      color: var(--o2vend-text);
+      line-height: 1.6;
+    }
+    .container {
+      max-width: 1400px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    header {
+      background: linear-gradient(135deg, var(--o2vend-primary) 0%, var(--o2vend-primary-dark) 100%);
+      color: var(--o2vend-dark);
+      padding: 40px 30px;
+      margin: -20px -20px 30px -20px;
+      border-radius: 0 0 16px 16px;
+      box-shadow: 0 4px 20px rgba(249, 168, 37, 0.3);
+    }
+    .header-content {
+      display: flex;
+      align-items: center;
+      gap: 20px;
+      margin-bottom: 15px;
+    }
+    .logo-container {
+      display: flex;
+      align-items: center;
+      gap: 15px;
+    }
+    .logo-img {
+      height: 50px;
+      width: auto;
+    }
+    header h1 {
+      font-size: 2.2em;
+      font-weight: 700;
+      color: var(--o2vend-dark);
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+    .brand-text {
+      font-weight: 800;
+      letter-spacing: -0.5px;
+    }
+    header p {
+      color: var(--o2vend-dark);
+      opacity: 0.8;
+      font-size: 1.1em;
+      margin-left: 75px;
+    }
+    .nav-links {
+      margin-top: 20px;
+      display: flex;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .nav-links a {
+      color: var(--o2vend-dark);
+      text-decoration: none;
+      padding: 10px 18px;
+      background: rgba(255,255,255,0.9);
+      border-radius: 8px;
+      transition: all 0.3s;
+      font-weight: 500;
+      font-size: 0.95em;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+    .nav-links a:hover {
+      background: white;
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    }
+    .section {
+      background: var(--o2vend-surface);
+      border-radius: 12px;
+      padding: 28px;
+      margin-bottom: 25px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+      border: 1px solid var(--o2vend-border);
+    }
+    .section h2 {
+      color: var(--o2vend-dark);
+      margin-bottom: 15px;
+      font-size: 1.6em;
+      font-weight: 700;
+      border-bottom: 3px solid var(--o2vend-primary);
+      padding-bottom: 12px;
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+    .section-count {
+      color: #888;
+      font-size: 0.85em;
+      font-weight: 500;
+      background: var(--o2vend-border);
+      padding: 4px 10px;
+      border-radius: 20px;
+    }
+    .file-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+      gap: 16px;
+      margin-top: 20px;
+    }
+    .file-item {
+      background: var(--o2vend-bg);
+      border: 2px solid var(--o2vend-border);
+      border-radius: 10px;
+      padding: 18px;
+      transition: all 0.3s;
+      text-decoration: none;
+      color: var(--o2vend-text);
+      display: block;
+    }
+    .file-item:hover {
+      border-color: var(--o2vend-primary);
+      transform: translateY(-3px);
+      box-shadow: 0 6px 16px rgba(249, 168, 37, 0.2);
+      background: white;
+    }
+    .file-item h3 {
+      font-size: 1.05em;
+      margin-bottom: 6px;
+      color: var(--o2vend-dark);
+      font-weight: 600;
+    }
+    .file-item:hover h3 {
+      color: var(--o2vend-primary-dark);
+    }
+    .file-item .path {
+      font-size: 0.82em;
+      color: #777;
+      word-break: break-all;
+      font-family: 'SF Mono', 'Monaco', 'Consolas', monospace;
+    }
+    .empty {
+      color: #999;
+      font-style: italic;
+      padding: 30px;
+      text-align: center;
+      background: var(--o2vend-bg);
+      border-radius: 8px;
+    }
+    .quick-links {
+      display: flex;
+      gap: 12px;
+      margin-top: 20px;
+      flex-wrap: wrap;
+    }
+    .quick-link {
+      padding: 12px 24px;
+      background: var(--o2vend-primary);
+      color: var(--o2vend-dark);
+      text-decoration: none;
+      border-radius: 8px;
+      transition: all 0.3s;
+      font-weight: 600;
+      box-shadow: 0 2px 8px rgba(249, 168, 37, 0.3);
+    }
+    .quick-link:hover {
+      background: var(--o2vend-primary-dark);
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(249, 168, 37, 0.4);
+    }
+    .footer-credit {
+      text-align: center;
+      padding: 30px;
+      color: #888;
+      font-size: 0.9em;
+    }
+    .footer-credit a {
+      color: var(--o2vend-primary-dark);
+      text-decoration: none;
+      font-weight: 600;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-content">
+        <div class="logo-container">
+          <img src="/o2vend-assets/Logo_o2vend.png" alt="O2VEND" class="logo-img">
+          <h1>Theme Dev</h1>
+        </div>
+      </div>
+      <p>Development Dashboard - View and test all your theme components</p>
+      <div class="nav-links">
+        <a href="/">🏠 Homepage</a>
+        <a href="/products">📦 Products</a>
+        <a href="/products/product-1">📱 Product Detail</a>
+        <a href="/categories">📁 Categories</a>
+        <a href="/categories/electronics">⚡ Electronics</a>
+        <a href="/brands">🏷️ Brands</a>
+        <a href="/cart">🛒 Cart</a>
+        <a href="/search?q=wireless">🔍 Search</a>
+        <a href="/page/about">📄 About</a>
+        <a href="/page/contact">📞 Contact</a>
+      </div>
+    </header>
+
+    <div class="section">
+      <h2>📄 Templates <span class="section-count">(${templates.length})</span></h2>
+      ${templates.length > 0 ? `
+        <div class="file-grid">
+          ${templates.map(t => `
+            <a href="/dev/template/${t.path}" class="file-item">
+              <h3>${t.name}</h3>
+              <div class="path">${t.path}</div>
+            </a>
+          `).join('')}
+        </div>
+      ` : '<div class="empty">No templates found</div>'}
+    </div>
+
+    <div class="section">
+      <h2>🧩 Sections <span class="section-count">(${sections.length})</span></h2>
+      ${sections.length > 0 ? `
+        <div class="file-grid">
+          ${sections.map(s => `
+            <a href="/dev/section/${s.name}" class="file-item">
+              <h3>${s.name}</h3>
+              <div class="path">sections/${s.name}.liquid</div>
+            </a>
+          `).join('')}
+        </div>
+      ` : '<div class="empty">No sections found</div>'}
+    </div>
+
+    <div class="section">
+      <h2>🎯 Widgets <span class="section-count">(${widgets.length})</span></h2>
+      ${widgets.length > 0 ? `
+        <div class="file-grid">
+          ${widgets.map(w => `
+            <a href="/dev/widget/${w.name}" class="file-item">
+              <h3>${w.name}</h3>
+              <div class="path">widgets/${w.name}.liquid</div>
+            </a>
+          `).join('')}
+        </div>
+      ` : '<div class="empty">No widgets found</div>'}
+    </div>
+
+    <div class="section">
+      <h2>✂️ Snippets <span class="section-count">(${snippets.length})</span></h2>
+      ${snippets.length > 0 ? `
+        <div class="file-grid">
+          ${snippets.map(s => {
+            const snippetName = typeof s === 'string' ? s : (s.name || s.path || '');
+            return `
+            <a href="/dev/snippet/${encodeURIComponent(snippetName)}" class="file-item">
+              <h3>${snippetName}</h3>
+              <div class="path">snippets/${snippetName}.liquid</div>
+            </a>
+          `;
+          }).join('')}
+        </div>
+      ` : '<div class="empty">No snippets found</div>'}
+    </div>
+    
+    <div class="footer-credit">
+      <p>Powered by <a href="https://www.o2vend.com" target="_blank">O2VEND</a> Theme Development Tools</p>
+      <p style="margin-top: 8px; font-size: 0.85em; opacity: 0.7;">Version 1.0.0 | Running on port ${this.port || 3000}</p>
+    </div>
+  </div>
+</body>
+</html>`;
+  }
+
+  /**
+   * Generate preview page HTML
+   */
+  generatePreviewPage({ title, content, type, name, backUrl }) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title} - O2VEND Dev</title>
+  <link rel="icon" type="image/png" href="/o2vend-assets/favicon.png">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    :root {
+      --o2vend-primary: #F9A825;
+      --o2vend-primary-dark: #E59100;
+      --o2vend-dark: #1A1A1A;
+      --o2vend-bg: #FFFDF7;
+    }
+    body {
+      font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      background: var(--o2vend-bg);
+    }
+    .header {
+      background: linear-gradient(135deg, var(--o2vend-primary) 0%, var(--o2vend-primary-dark) 100%);
+      color: var(--o2vend-dark);
+      padding: 20px;
+      box-shadow: 0 4px 12px rgba(249, 168, 37, 0.3);
+    }
+    .header-content {
+      max-width: 1400px;
+      margin: 0 auto;
+      display: flex;
+      align-items: center;
+      gap: 20px;
+    }
+    .back-btn {
+      background: rgba(255,255,255,0.9);
+      color: var(--o2vend-dark);
+      text-decoration: none;
+      padding: 10px 20px;
+      border-radius: 8px;
+      transition: all 0.3s;
+      font-weight: 500;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+    .back-btn:hover {
+      background: white;
+      transform: translateY(-2px);
+      box-shadow: 0 4px 8px rgba(0,0,0,0.15);
+    }
+    .header h1 {
+      font-size: 1.6em;
+      font-weight: 700;
+    }
+    .preview-container {
+      max-width: 1400px;
+      margin: 20px auto;
+      background: white;
+      border-radius: 12px;
+      padding: 30px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+      border: 1px solid #FFF3D0;
+    }
+    .info {
+      background: #FFF8E1;
+      border-left: 4px solid var(--o2vend-primary);
+      padding: 15px 20px;
+      margin-bottom: 25px;
+      border-radius: 6px;
+      font-size: 0.95em;
+    }
+    .info strong {
+      color: var(--o2vend-primary-dark);
+      font-weight: 600;
+    }
+    .error {
+      background: #ffebee;
+      border-left: 4px solid #f44336;
+      padding: 15px;
+      margin: 20px 0;
+      border-radius: 6px;
+      color: #c62828;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-content">
+      <a href="${backUrl}" class="back-btn">← Back to Dashboard</a>
+      <h1>${title}</h1>
+    </div>
+  </div>
+  <div class="preview-container">
+    <div class="info">
+      <strong>Type:</strong> ${type} &nbsp;|&nbsp; <strong>Name:</strong> ${name}
+    </div>
+    ${content}
+  </div>
+</body>
+</html>`;
+  }
+
+  /**
+   * Start development server
+   */
+  async start() {
+    try {
+      // Start mock API first if in mock mode (before setting up services)
+      if (this.mode === 'mock') {
+        const MockApiServer = require('./mock-api-server');
+        this.mockApi = new MockApiServer({ port: this.mockApiPort });
+        await this.mockApi.start();
+        // Update mockApiPort in case it changed
+        this.mockApiPort = this.mockApi.port;
+      }
+      
+      // Setup services (after mock API is running)
+      await this.setupServices();
+
+      // In mock mode, ensure API client points directly to mock API
+      if (this.mode === 'mock' && this.mockApi) {
+        // Update API client to point directly to mock API with shorter timeout
+        const originalTimeout = process.env.O2VEND_API_TIMEOUT;
+        process.env.O2VEND_API_TIMEOUT = '2000'; // 2 seconds for local mock API
+        this.apiClient = new O2VendApiClient('mock-tenant', 'mock-key', `http://localhost:${this.mockApiPort}`);
+        if (originalTimeout) {
+          process.env.O2VEND_API_TIMEOUT = originalTimeout;
+        }
+        
+        // Update widget service with new API client
+        this.widgetService = new WidgetService(this.apiClient, {
+          theme: path.basename(this.themePath),
+          themePath: this.themePath
+        });
+        
+        // Re-register widget filter now that widget service is available
+        // IMPORTANT: This must be called AFTER widgetService is created
+        console.log('[DEV SERVER] Re-registering widget filter with widgetService');
+        this.setupWidgetFilter();
+        
+        // Verify filter is registered
+        // LiquidJS stores filters in engine.filters object
+        const registeredFilters = Object.keys(this.liquid.filters || {});
+        const hasRenderWidget = registeredFilters.includes('render_widget');
+        console.log(`[DEV SERVER] Filter registration check: render_widget filter ${hasRenderWidget ? '✅ registered' : '❌ NOT registered'}`);
+        console.log(`[DEV SERVER] Total registered filters: ${registeredFilters.length}`);
+        
+        // Test if filter function exists and test it
+        if (hasRenderWidget) {
+          const filterFunc = this.liquid.filters['render_widget'];
+          const isAsync = filterFunc && filterFunc.constructor && filterFunc.constructor.name === 'AsyncFunction';
+          const isGenerator = filterFunc && filterFunc.constructor && filterFunc.constructor.name === 'GeneratorFunction';
+          console.log(`[DEV SERVER] Filter function type: ${isAsync ? 'AsyncFunction ✅' : isGenerator ? 'GeneratorFunction' : typeof filterFunc}`);
+          
+          // Test the filter with a mock widget to see if it's callable
+          try {
+            const testWidget = { type: 'TestWidget', id: 'test-1' };
+            console.log(`[DEV SERVER] Testing filter with mock widget...`);
+            // Don't actually call it (would fail), just verify it's a function
+            if (typeof filterFunc === 'function') {
+              console.log(`[DEV SERVER] ✅ Filter is a callable function`);
+            } else {
+              console.error(`[DEV SERVER] ❌ Filter is not a function: ${typeof filterFunc}`);
+            }
+          } catch (error) {
+            console.error(`[DEV SERVER] ❌ Error testing filter: ${error.message}`);
+          }
+        }
+        
+        if (registeredFilters.length > 0 && registeredFilters.length < 20) {
+          console.log(`[DEV SERVER] Sample registered filters: ${registeredFilters.slice(0, 10).join(', ')}${registeredFilters.length > 10 ? '...' : ''}`);
+        }
+        
+        // Setup API proxy to mock API (for direct browser requests)
+        const { createProxyMiddleware } = require('http-proxy-middleware');
+        this.app.use('/shopfront/api', createProxyMiddleware({
+          target: `http://localhost:${this.mockApiPort}`,
+          changeOrigin: true,
+          logLevel: 'silent',
+          timeout: 2000
+        }));
+        
+        // Proxy webstoreapi endpoints to mock API
+        this.app.use('/webstoreapi', createProxyMiddleware({
+          target: `http://localhost:${this.mockApiPort}`,
+          changeOrigin: true,
+          logLevel: 'silent',
+          timeout: 2000
+        }));
+      }
+
+      // Inject hot reload script into HTML responses
+      const { injectHotReloadScript } = require('./hot-reload');
+      const self = this;
+      this.app.use((req, res, next) => {
+        const originalSend = res.send;
+        res.send = function(data) {
+          if (typeof data === 'string' && (data.includes('<!DOCTYPE') || data.includes('<html'))) {
+            data = injectHotReloadScript(data, self.host, self.port);
+          }
+          return originalSend.call(res, data);
+        };
+        next();
+      });
+
+      // Create HTTP server and attach Socket.IO
+      const http = require('http');
+      this.server = http.createServer(this.app);
+      
+      // Setup hot reload (WebSocket) - attach to HTTP server
+      this.io = new (require('socket.io').Server)(this.server, {
+        path: '/socket.io',
+        serveClient: true,
+        cors: {
+          origin: '*',
+          methods: ['GET', 'POST']
+        }
+      });
+      
+      this.io.on('connection', (socket) => {
+        console.log(chalk.magenta('[Hot Reload] Client connected'));
+        socket.on('disconnect', () => {
+          console.log(chalk.magenta('[Hot Reload] Client disconnected'));
+        });
+      });
+      
+      // Setup file watching
+      const { setupFileWatcher } = require('./file-watcher');
+      this.fileWatcher = setupFileWatcher(this.themePath, (changedFiles) => {
+        // Notify clients via WebSocket
+        if (this.io) {
+          this.io.emit('file-changed', changedFiles);
+        }
+        
+        // Log changes
+        if (changedFiles.some(f => f.endsWith('.liquid'))) {
+          console.log(chalk.cyan('🔄 Liquid templates changed - reloading...'));
+        } else if (changedFiles.some(f => f.endsWith('.css'))) {
+          console.log(chalk.cyan('🎨 CSS changed - injecting...'));
+        } else if (changedFiles.some(f => f.endsWith('.js'))) {
+          console.log(chalk.cyan('📜 JavaScript changed - reloading...'));
+        }
+      });
+
+      // Start HTTP server
+      return new Promise((resolve, reject) => {
+        this.server.listen(this.port, this.host, (error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          
+          const url = `http://${this.host}:${this.port}`;
+          console.log(chalk.green(`\n✅ Server started successfully!`));
+          console.log(chalk.cyan(`📡 Server: ${url}`));
+          console.log(chalk.cyan(`🌐 Mode: ${this.mode === 'mock' ? 'Mock API' : 'Real API'}`));
+          
+          if (this.mode === 'mock') {
+            console.log(chalk.cyan(`🎯 Mock API: http://${this.host}:${this.mockApiPort}`));
+          }
+          
+          console.log(chalk.magenta(`\n🎨 Development Dashboard: ${url}/dev`));
+          console.log(chalk.gray(`   View and test all templates, sections, widgets, and snippets`));
+          
+          console.log(chalk.yellow(`\n📝 Watching for changes...`));
+          console.log(chalk.yellow(`💡 Press 'q' to quit\n`));
+          
+          // Open browser if requested
+          if (this.openBrowser) {
+            const open = require('open');
+            open(url).catch(() => {
+              console.log(chalk.yellow(`💡 Open your browser: ${url}`));
+            });
+          }
+          
+          resolve(this.server);
+        });
+      });
+    } catch (error) {
+      console.error(chalk.red('❌ Failed to start server:'), error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop development server
+   */
+  async stop() {
+    return new Promise((resolve) => {
+      // Stop file watcher
+      if (this.fileWatcher && typeof this.fileWatcher.close === 'function') {
+        this.fileWatcher.close();
+      }
+      
+      // Close Socket.IO
+      if (this.io && typeof this.io.close === 'function') {
+        this.io.close();
+      }
+      
+      // Stop mock API
+      if (this.mockApi && typeof this.mockApi.stop === 'function') {
+        this.mockApi.stop().catch(() => {});
+      }
+      
+      // Close HTTP server
+      if (this.server) {
+        this.server.close(() => {
+          console.log(chalk.yellow('\n👋 Server stopped'));
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+}
+
+module.exports = DevServer;
+