@o2vend/theme-cli 1.0.33 → 1.0.35

package/lib/lib/dev-server.js

@@ -1,6 +1,11 @@
 /**
  * Development Server
  * Express server for local theme development with hot reload
+ *
+ * Developer guideline: Do NOT add theme-specific CSS class hardcodes (e.g. targeting
+ * .mobile-bottom-nav, .site-header, etc.) in this file. Such fixes would force theme
+ * developers to use those exact class names. Theme behavior and styling must remain
+ * entirely under the theme; the CLI only serves assets, proxies, and generic tooling.
  */
 
 const express = require('express');
@@ -11,6 +16,7 @@ const WidgetService = require('./widget-service');
 const O2VendApiClient = require('./api-client');
 const { setupHotReload } = require('./hot-reload');
 const chalk = require('chalk');
+const webstoreApi = require('./webstoreapi-fetcher');
 
 class DevServer {
   constructor(options = {}) {
@@ -130,29 +136,33 @@ class DevServer {
         // Only process if it contains actual Liquid variables, not just comments
         if (cssContent.includes('{{') && cssContent.includes('settings.')) {
           try {
-            // Load settings from theme config (already extracts 'current' section)
             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 ${relativePath}:`, 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(normalizedPath);
+        res.sendFile(relativePath, { root: path.join(this.themePath, 'assets') });
       } catch (error) {
         console.error(`[CSS] Error processing ${req.path}:`, error.message);
         next();
       }
     });
+
+    // Explicit logo route so /assets/logo.png always serves correctly (avoids broken image)
+    this.app.get('/assets/logo.png', (req, res) => {
+      const logoPath = path.join(this.themePath, 'assets', 'logo.png');
+      if (!fs.existsSync(logoPath)) {
+        return res.status(404).setHeader('Content-Type', 'text/plain').end('Logo not found');
+      }
+      res.setHeader('Content-Type', 'image/png');
+      res.sendFile('logo.png', { root: path.join(this.themePath, 'assets') });
+    });
     
     // Static files (theme assets) with proper MIME types
     this.app.use('/assets', express.static(path.join(this.themePath, 'assets'), {
@@ -225,37 +235,36 @@ class DevServer {
 
   /**
    * Setup API client and widget service
+   * Real mode: no apiClient (use webstoreapi-fetcher only). WidgetService with null for getTemplateSlug.
+   * Mock mode: apiClient created in start() after mock API; WidgetService uses it.
    */
   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'));
+      if (!baseUrl) {
+        console.warn(chalk.yellow('⚠️  Real API mode requires O2VEND_API_BASE_URL (storefront URL, e.g. https://store.myo2vend.com)'));
         console.warn(chalk.yellow('   Falling back to mock mode'));
         this.mode = 'mock';
       } else {
-        this.apiClient = new O2VendApiClient(tenantId, apiKey, baseUrl);
+        this.apiClient = null;
+        this.widgetService = new WidgetService(null, {
+          theme: path.basename(this.themePath),
+          themePath: this.themePath
+        });
       }
     }
-    
-    // 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
-      });
+
+    if (this.mode === 'mock' || !this.widgetService) {
+      if (this.apiClient) {
+        this.widgetService = new WidgetService(this.apiClient, {
+          theme: path.basename(this.themePath),
+          themePath: this.themePath
+        });
+      }
     }
     
     // Create Liquid engine
@@ -420,9 +429,15 @@ class DevServer {
         if (!context.products || context.products.length === 0) {
           console.warn('[HOME] No products in context, attempting reload...');
           try {
-            if (this.apiClient) {
+            if (this.mode === 'real') {
+              const res = await webstoreApi.fetchProducts({ limit: 50, offset: 0 }, { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+              context.products = res?.products || res?.Products || [];
+              context.products = this.enrichProductsData(context.products);
+              console.log(`[HOME] Reloaded ${context.products.length} products (real)`);
+            } else if (this.apiClient) {
               const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
               context.products = productsResponse.products || productsResponse.data?.products || [];
+              context.products = this.enrichProductsData(context.products);
               console.log(`[HOME] Reloaded ${context.products.length} products`);
             } else {
               console.error('[HOME] API client not available');
@@ -431,12 +446,15 @@ class DevServer {
             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) {
+            if (this.mode === 'real') {
+              const opts = { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} };
+              context.widgets = await webstoreApi.fetchWidgetsBySections('home', webstoreApi.DEFAULT_SECTIONS, opts) || { hero: [], content: [], footer: [] };
+              console.log(`[HOME] Reloaded widgets: ${Object.keys(context.widgets).join(', ')} (real)`);
+            } else 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(', ')}`);
@@ -449,7 +467,7 @@ class DevServer {
             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.setHeader('Cache-Control', 'no-cache');
@@ -462,8 +480,8 @@ class DevServer {
     // Products listing page
     this.app.get('/products', async (req, res, next) => {
       try {
-        // Check for category filter in query parameters
-        const categoryFilter = req.query.category;
+        // Check for category filter in query parameters (handle both 'category' and 'Category')
+        const categoryFilter = req.query.category || req.query.Category;
         
         let context = await this.buildContext(req, 'products');
         
@@ -471,44 +489,61 @@ class DevServer {
         if (categoryFilter) {
           console.log(`[PRODUCTS PAGE] Filtering by category: ${categoryFilter}`);
           
-          // Find category by name or handle (case-insensitive)
-          const category = context.categories?.find(c => 
-            (c.name && c.name.toLowerCase() === categoryFilter.toLowerCase()) ||
-            (c.handle && c.handle.toLowerCase() === categoryFilter.toLowerCase())
-          );
+          const cf = (categoryFilter || '').toLowerCase();
+          const category = context.categories?.find(c => {
+            const ch = (c.handle || '').toLowerCase();
+            const cs = (c.slug || '').toLowerCase();
+            const cn = (c.name || '').toLowerCase();
+            const cnNorm = (c.name || '').toLowerCase().replace(/\s+/g, '-');
+            return ch === cf || cs === cf || cn === cf || cnNorm === cf;
+          });
           
           if (category) {
             console.log(`[PRODUCTS PAGE] Found category: ${category.name} (ID: ${category.id})`);
             
-            // Filter products by categoryId
-            const filteredProducts = context.products.filter(p => 
-              p.categoryId === category.id || 
-              String(p.categoryId).toLowerCase() === String(category.id).toLowerCase()
-            );
+            const filtered = context.products.filter(p => this.productMatchesCategory(p, category));
+            const filteredProducts = this.mode === 'real'
+              ? filtered
+              : filtered.map(p => this.enrichProductData(p));
             
+            // CRITICAL: Set both context.products and context.collection.products to the SAME enriched array
+            // This ensures they always reference the same objects (like widgets do)
             context.products = filteredProducts;
-            console.log(`[PRODUCTS PAGE] Filtered products: ${filteredProducts.length} products in category`);
-            
-            // Update collection context
             context.collection = context.collection || {};
+            context.collection.products = context.products; // Same reference as context.products
             context.collection.title = category.name || 'Products';
             context.collection.handle = category.handle || categoryFilter;
             context.collection.description = category.description;
             context.collection.totalProducts = filteredProducts.length;
+            
+            console.log(`[PRODUCTS PAGE] Filtered products: ${filteredProducts.length} products in category`);
+            console.log(`[PRODUCTS PAGE] ✅ collection.products === context.products: ${context.collection.products === context.products}`);
+            
+            console.log(`[PRODUCTS PAGE] ✅ Category filtered: ${filteredProducts.length} enriched products in collection`);
           } else {
             console.warn(`[PRODUCTS PAGE] Category not found: ${categoryFilter}, showing all products`);
           }
         }
         
-        // Ensure all products have proper URL field if missing
-        context.products = (context.products || []).map(product => {
-          if (!product.url && !product.link) {
-            const handle = product.handle || product.slug || product.id;
-            product.url = `/products/${handle}`;
-            product.link = `/products/${handle}`;
+        if (context.products && context.products.length > 0 && this.mode !== 'real') {
+          if (!context.products[0].url && !context.products[0].link) {
+            console.log(`[PRODUCTS PAGE] Products need enrichment - enriching now...`);
+            context.products = this.enrichProductsData(context.products);
           }
-          return product;
-        });
+        }
+        
+        // Debug: Log sample product data to verify enrichment
+        if (context.products.length > 0) {
+          const sample = context.products[0];
+          console.log(`[PRODUCTS PAGE] Sample product data:`, {
+            title: sample.title || sample.name,
+            url: sample.url || sample.link,
+            price: sample.price || sample.sellingPrice,
+            stock: sample.stock,
+            inStock: sample.inStock,
+            hasImage: !!(sample.imageUrl || sample.thumbnailImage1)
+          });
+        }
         
         // DEBUG: Log context data for /products page
         console.log(`[PRODUCTS PAGE] Context summary:`);
@@ -523,31 +558,37 @@ class DevServer {
         if (!context.products || context.products.length === 0) {
           console.warn('[PRODUCTS PAGE] ⚠️  No products in context, attempting to reload...');
           try {
-            const queryParams = {};
+            const queryParams = { limit: 50, offset: 0 };
             if (categoryFilter) {
-              // Find category and filter by categoryId
-              const category = context.categories?.find(c => 
-                (c.name && c.name.toLowerCase() === categoryFilter.toLowerCase()) ||
-                (c.handle && c.handle.toLowerCase() === categoryFilter.toLowerCase())
-              );
-              if (category) {
-                queryParams.categoryId = category.id;
-              }
+              const cf = (categoryFilter || '').toLowerCase();
+              const cat = context.categories?.find(c => {
+                const ch = (c.handle || '').toLowerCase();
+                const cs = (c.slug || '').toLowerCase();
+                const cn = (c.name || '').toLowerCase();
+                const cnNorm = (c.name || '').toLowerCase().replace(/\s+/g, '-');
+                return ch === cf || cs === cf || cn === cf || cnNorm === cf;
+              });
+              if (cat) queryParams.categoryId = cat.id;
+            }
+            if (this.mode === 'real') {
+              const res = await webstoreApi.fetchProducts(queryParams, { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+              context.products = this.normalizeProductsForRealMode(res?.products || res?.Products || []);
+            } else if (this.apiClient) {
+              const productsResponse = await this.apiClient.getProducts(queryParams);
+              context.products = productsResponse.products || productsResponse.data?.products || [];
+              context.products = this.enrichProductsData(context.products);
             }
-            const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0, ...queryParams });
-            context.products = productsResponse.products || productsResponse.data?.products || [];
-            
-            // Ensure URLs are set
-            context.products = context.products.map(product => {
-              if (!product.url && !product.link) {
-                const handle = product.handle || product.slug || product.id;
-                product.url = `/products/${handle}`;
-                product.link = `/products/${handle}`;
-              }
-              return product;
-            });
-            
             console.log(`[PRODUCTS PAGE] ✅ Reloaded ${context.products.length} products`);
+            if (context.products.length > 0) {
+              const sample = context.products[0];
+              console.log(`[PRODUCTS PAGE] Sample reloaded product:`, {
+                title: sample.title || sample.name,
+                url: sample.url || sample.link,
+                price: sample.price || sample.sellingPrice,
+                stock: sample.stock,
+                inStock: sample.inStock
+              });
+            }
           } catch (error) {
             console.error('[PRODUCTS PAGE] ❌ Failed to load products:', error.message);
           }
@@ -575,12 +616,15 @@ class DevServer {
         if (!context.widgets || Object.keys(context.widgets).length === 0) {
           console.warn('[PRODUCTS PAGE] ⚠️  No widgets in context, attempting to reload...');
           try {
-            if (this.widgetService) {
+            if (this.mode === 'real') {
+              const opts = { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} };
+              context.widgets = await webstoreApi.fetchWidgetsBySections('products', webstoreApi.DEFAULT_SECTIONS, opts) || { hero: [], content: [], footer: [], header: [] };
+              console.log(`[PRODUCTS PAGE] ✅ Reloaded widgets: ${Object.keys(context.widgets).join(', ')} (real)`);
+            } else 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) {
@@ -588,16 +632,22 @@ class DevServer {
             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`);
+            if (this.mode === 'real') {
+              context.menus = await webstoreApi.fetchMenus({ headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+              context.menus = Array.isArray(context.menus) ? context.menus : [];
+              console.log(`[PRODUCTS PAGE] ✅ Reloaded ${context.menus.length} menus (real)`);
+            } else {
+              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 = [];
@@ -605,9 +655,14 @@ class DevServer {
         }
         
         // Ensure collection.products is set for products template
+        // CRITICAL: Always sync collection.products with context.products AFTER enrichment
+        // This ensures collection.products always has the same enriched objects as context.products
         if (context.products && context.products.length > 0) {
+          // Always reassign collection.products to match context.products (they should be the same)
           context.collection = context.collection || {};
-          context.collection.products = context.products;
+          context.collection.products = context.products; // Use the same enriched array
+          
+          // Update collection metadata if not set
           if (!context.collection.title) {
             context.collection.title = categoryFilter ? `${categoryFilter} Products` : 'All Products';
           }
@@ -617,6 +672,56 @@ class DevServer {
           if (!context.collection.totalProducts) {
             context.collection.totalProducts = context.products.length;
           }
+          
+          // Debug: Verify collection.products has same reference as context.products
+          const sameReference = context.collection.products === context.products;
+          console.log(`[PRODUCTS PAGE] collection.products sync: same reference=${sameReference}, length=${context.collection.products?.length || 0}`);
+          
+          // Debug: Log sample product from collection to verify enrichment
+          if (context.collection.products && context.collection.products.length > 0) {
+            const sample = context.collection.products[0];
+            console.log(`[PRODUCTS PAGE] ✅ Sample collection product before render:`, {
+              id: sample.id,
+              title: sample.title || sample.name,
+              url: sample.url || sample.link || 'MISSING',
+              price: sample.price || sample.sellingPrice || 'MISSING',
+              prices: sample.prices ? { price: sample.prices.price, mrp: sample.prices.mrp } : 'MISSING',
+              stock: sample.stock !== undefined ? sample.stock : 'MISSING',
+              stockQuantity: sample.stockQuantity !== undefined ? sample.stockQuantity : 'MISSING',
+              inStock: sample.inStock !== undefined ? sample.inStock : 'MISSING',
+              available: sample.available !== undefined ? sample.available : 'MISSING',
+              hasImage: !!(sample.imageUrl || sample.thumbnailImage1),
+              imageUrl: sample.imageUrl || sample.thumbnailImage1?.url || 'MISSING',
+              hasThumbnailImage1: !!sample.thumbnailImage1,
+              hasImagesArray: !!(sample.images && sample.images.length > 0)
+            });
+          } else {
+            console.warn(`[PRODUCTS PAGE] ⚠️  collection.products is empty or undefined!`);
+            console.warn(`[PRODUCTS PAGE] context.products.length: ${context.products?.length || 0}`);
+            console.warn(`[PRODUCTS PAGE] context.collection:`, context.collection ? Object.keys(context.collection) : 'undefined');
+          }
+        } else {
+          console.warn(`[PRODUCTS PAGE] ⚠️  No products in context!`);
+        }
+        
+        // Debug: Log final context before rendering
+        console.log(`[PRODUCTS PAGE] Final context before rendering:`);
+        console.log(`  - Products count: ${context.products?.length || 0}`);
+        if (context.products && context.products.length > 0) {
+          const firstProduct = context.products[0];
+          console.log(`  - First product:`, {
+            id: firstProduct.id,
+            title: firstProduct.title || firstProduct.name,
+            url: firstProduct.url || firstProduct.link,
+            price: firstProduct.price || firstProduct.sellingPrice,
+            stock: firstProduct.stock,
+            inStock: firstProduct.inStock,
+            hasImage: !!(firstProduct.imageUrl || firstProduct.thumbnailImage1),
+            imageUrl: firstProduct.imageUrl || firstProduct.thumbnailImage1?.url
+          });
+        }
+        if (context.collection) {
+          console.log(`  - Collection: ${context.collection.title || context.collection.name}, Products: ${context.collection.products?.length || 0}`);
         }
         
         const html = await renderWithLayout(this.liquid, 'templates/products', context, this.themePath);
@@ -795,51 +900,31 @@ class DevServer {
     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
-        );
+        const h = (req.params.handle || '').toLowerCase();
+        const category = context.categories?.find(c => {
+          const ch = (c.handle || '').toLowerCase();
+          const cs = (c.slug || '').toLowerCase();
+          const cn = (c.name || '').toLowerCase().replace(/\s+/g, '-');
+          return ch === h || cs === h || cn === h;
+        });
         if (category) {
           context.category = category;
           context.collection = category;
-          
-          // Filter products by this category
-          const filteredProducts = (context.products || []).filter(p => 
-            p.categoryId === category.id || 
-            String(p.categoryId).toLowerCase() === String(category.id).toLowerCase()
-          );
-          
-          // Ensure all products have proper URL field if missing
-          filteredProducts.forEach(product => {
-            if (!product.url && !product.link) {
-              const handle = product.handle || product.slug || product.id;
-              product.url = `/products/${handle}`;
-              product.link = `/products/${handle}`;
-            }
-          });
-          
+          const filtered = (context.products || []).filter(p => this.productMatchesCategory(p, category));
+          const filteredProducts = this.mode === 'real' ? filtered : filtered.map(p => this.enrichProductData(p));
           context.collection.products = filteredProducts;
           context.collection.totalProducts = filteredProducts.length;
-          context.products = filteredProducts; // Also set in products array for consistency
-          
+          context.products = filteredProducts;
           console.log(`[COLLECTION PAGE] Category: ${category.name}, Products: ${filteredProducts.length}`);
         } else {
-          // No category found, use all products
-          context.products = (context.products || []).map(product => {
-            if (!product.url && !product.link) {
-              const handle = product.handle || product.slug || product.id;
-              product.url = `/products/${handle}`;
-              product.link = `/products/${handle}`;
-            }
-            return product;
-          });
+          if (this.mode !== 'real') context.products = this.enrichProductsData(context.products || []);
           context.collection = context.collection || {};
           context.collection.products = context.products;
         }
         
+        // Prioritize products template to show product list, not categories list
         let html;
-        const templateOptions = ['templates/categories', 'templates/category', 'templates/collection'];
+        const templateOptions = ['templates/products', 'templates/collection', 'templates/category', 'templates/categories'];
         for (const template of templateOptions) {
           try {
             html = await renderWithLayout(this.liquid, template, context, this.themePath);
@@ -891,50 +976,31 @@ class DevServer {
     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
-        );
+        const h = (req.params.handle || '').toLowerCase();
+        const category = context.categories?.find(c => {
+          const ch = (c.handle || '').toLowerCase();
+          const cs = (c.slug || '').toLowerCase();
+          const cn = (c.name || '').toLowerCase().replace(/\s+/g, '-');
+          return ch === h || cs === h || cn === h;
+        });
         if (category) {
           context.category = category;
           context.collection = category;
-          
-          // Filter products by this category
-          const filteredProducts = (context.products || []).filter(p => 
-            p.categoryId === category.id || 
-            String(p.categoryId).toLowerCase() === String(category.id).toLowerCase()
-          );
-          
-          // Ensure all products have proper URL field if missing
-          filteredProducts.forEach(product => {
-            if (!product.url && !product.link) {
-              const handle = product.handle || product.slug || product.id;
-              product.url = `/products/${handle}`;
-              product.link = `/products/${handle}`;
-            }
-          });
-          
+          const filtered = (context.products || []).filter(p => this.productMatchesCategory(p, category));
+          const filteredProducts = this.mode === 'real' ? filtered : filtered.map(p => this.enrichProductData(p));
           context.collection.products = filteredProducts;
           context.collection.totalProducts = filteredProducts.length;
-          context.products = filteredProducts; // Also set in products array for consistency
-          
+          context.products = filteredProducts;
           console.log(`[CATEGORY PAGE] Category: ${category.name}, Products: ${filteredProducts.length}`);
         } else {
-          // No category found, use all products
-          context.products = (context.products || []).map(product => {
-            if (!product.url && !product.link) {
-              const handle = product.handle || product.slug || product.id;
-              product.url = `/products/${handle}`;
-              product.link = `/products/${handle}`;
-            }
-            return product;
-          });
+          if (this.mode !== 'real') context.products = this.enrichProductsData(context.products || []);
           context.collection = context.collection || {};
           context.collection.products = context.products;
         }
         
+        // Prioritize products template to show product list, not categories list
         let html;
-        const templateOptions = ['templates/categories', 'templates/category', 'templates/collection'];
+        const templateOptions = ['templates/products', 'templates/collection', 'templates/category', 'templates/categories'];
         for (const template of templateOptions) {
           try {
             html = await renderWithLayout(this.liquid, template, context, this.themePath);
@@ -1055,41 +1121,38 @@ class DevServer {
       try {
         const context = await this.buildContext(req, 'page', { pageHandle: req.params.handle });
         
-        // Load page content from shopfront API (mock)
+        // Load page content
         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) {
+          if (this.mode === 'real') {
+            const pageData = await webstoreApi.fetchPage(req.params.handle, { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+            if (pageData) {
               context.page = {
                 ...context.page,
-                ...pageResponse.data,
-                body_html: pageResponse.data.content,
-                content: pageResponse.data.content
+                ...pageData,
+                body_html: pageData.content || pageData.body_html,
+                content: pageData.content || pageData.body_html
               };
             }
-          } 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>`
-            };
+          } else {
+            const axios = require('axios');
+            try {
+              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 (e) {
+              const fallback = await axios.get(`http://localhost:${this.mockApiPort}/webstoreapi/pages/${req.params.handle}`);
+              if (fallback.data) {
+                context.page = { ...context.page, ...fallback.data, body_html: fallback.data.content, content: fallback.data.content };
+              }
+            }
           }
+        } catch (error) {
+          console.warn(`[PAGE] Failed to load page for ${req.params.handle}:`, error.message);
+        }
+        if (!context.page.body_html && !context.page.content) {
+          const t = req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ');
+          context.page = { ...context.page, title: t, handle: req.params.handle, body_html: `<h2>${t}</h2><p>Landing page content coming soon.</p>`, content: `<h2>${t}</h2><p>Landing page content coming soon.</p>` };
         }
         
         // Try page.liquid template first, then fallback to rendering raw HTML
@@ -1116,30 +1179,27 @@ class DevServer {
       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
-            };
+          if (this.mode === 'real') {
+            const pageData = await webstoreApi.fetchPage(req.params.handle, { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+            if (pageData) {
+              context.page = { ...context.page, ...pageData, body_html: pageData.content || pageData.body_html, content: pageData.content || pageData.body_html };
+            }
+          } else {
+            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>`
-          };
         }
-        
+        if (!context.page.body_html && !context.page.content) {
+          const t = req.params.handle.charAt(0).toUpperCase() + req.params.handle.slice(1).replace(/-/g, ' ');
+          context.page = { ...context.page, title: t, handle: req.params.handle, body_html: `<h2>${t}</h2><p>Page content coming soon.</p>`, content: `<h2>${t}</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.setHeader('Cache-Control', 'no-cache');
@@ -1197,10 +1257,13 @@ class DevServer {
         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) {
+            if (this.mode === 'real') {
+              const res = await webstoreApi.fetchProducts({ limit: 50, offset: 0 }, { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} });
+              context.products = this.normalizeProductsForRealMode(res?.products || res?.Products || []);
+              console.log(`[DEV WIDGET] Loaded ${context.products.length} products (real)`);
+            } else 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`);
@@ -1353,44 +1416,143 @@ class DevServer {
           return next();
         }
         
-        // Build context to get categories and products
+        // Build context to get categories, brands, and products
         const context = await this.buildContext(req, 'collection', { collectionHandle: handle });
         
-        // Try to find category by handle (case-insensitive)
-        const category = context.categories?.find(c => 
-          (c.handle && c.handle.toLowerCase() === handle.toLowerCase()) ||
-          (c.name && c.name.toLowerCase().replace(/\s+/g, '-') === handle.toLowerCase())
-        );
+        // Try to find category by handle or slug (case-insensitive)
+        const h = handle.toLowerCase();
+        const category = context.categories?.find(c => {
+          const ch = (c.handle || '').toLowerCase();
+          const cs = (c.slug || '').toLowerCase();
+          const cn = (c.name || '').toLowerCase().replace(/\s+/g, '-');
+          return ch === h || cs === h || cn === h;
+        });
         
         if (category) {
-          // Found a category - render collection page
           context.category = category;
           context.collection = category;
+          console.log(`[ROOT COLLECTION] Found category: ${category.name} (ID: ${category.id})`);
+          console.log(`[ROOT COLLECTION] Total products in context: ${context.products?.length || 0}`);
+          const filtered = (context.products || []).filter(p => this.productMatchesCategory(p, category));
+          const filteredProducts = this.mode === 'real' ? filtered : filtered.map(p => this.enrichProductData(p));
+          console.log(`[ROOT COLLECTION] Filtered products count: ${filteredProducts.length}`);
           
-          // Filter products by this category
-          const filteredProducts = (context.products || []).filter(p => 
-            p.categoryId === category.id || 
-            String(p.categoryId).toLowerCase() === String(category.id).toLowerCase()
-          );
-          
-          // Ensure all products have proper URL field if missing
-          filteredProducts.forEach(product => {
-            if (!product.url && !product.link) {
-              const productHandle = product.handle || product.slug || product.id;
-              product.url = `/products/${productHandle}`;
-              product.link = `/products/${productHandle}`;
-            }
-          });
+          // Log sample enriched products
+          if (filteredProducts.length > 0) {
+            filteredProducts.slice(0, 3).forEach((product, index) => {
+              console.log(`[ROOT COLLECTION] Product ${index} AFTER enrichment:`, {
+                id: product.id,
+                title: product.title || product.name,
+                url: product.url || product.link,
+                price: product.price || product.sellingPrice,
+                stock: product.stock,
+                inStock: product.inStock,
+                hasImage: !!(product.imageUrl || product.thumbnailImage1),
+                imageUrl: product.imageUrl || product.thumbnailImage1?.url
+              });
+            });
+          }
           
+          // Set products in multiple places to ensure templates can access them
           context.collection.products = filteredProducts;
           context.collection.totalProducts = filteredProducts.length;
           context.products = filteredProducts; // Also set in products array for consistency
           
-          console.log(`[ROOT COLLECTION] Category: ${category.name}, Products: ${filteredProducts.length}`);
+          // Also set in collection object for template compatibility
+          if (!context.collection.products) {
+            context.collection.products = filteredProducts;
+          }
+          
+          console.log(`[ROOT COLLECTION] Final context setup:`);
+          console.log(`  - context.products.length: ${context.products?.length || 0}`);
+          console.log(`  - context.collection.products.length: ${context.collection.products?.length || 0}`);
+          console.log(`  - context.collection.totalProducts: ${context.collection.totalProducts || 0}`);
           
-          // Try to render collection template
+          if (filteredProducts.length > 0) {
+            const sample = filteredProducts[0];
+            console.log(`[ROOT COLLECTION] Sample enriched product:`, {
+              id: sample.id,
+              title: sample.title || sample.name,
+              url: sample.url || sample.link,
+              price: sample.price || sample.sellingPrice,
+              stock: sample.stock,
+              inStock: sample.inStock,
+              hasImage: !!(sample.imageUrl || sample.thumbnailImage1),
+              imageUrl: sample.imageUrl || sample.thumbnailImage1?.url,
+              allKeys: Object.keys(sample).slice(0, 20)
+            });
+          } else {
+            console.warn(`[ROOT COLLECTION] ⚠️  No products found for category ${category.name}!`);
+            console.warn(`[ROOT COLLECTION] Available products in context: ${context.products?.length || 0}`);
+            if (context.products && context.products.length > 0) {
+              console.warn(`[ROOT COLLECTION] Sample product categoryIds:`, context.products.slice(0, 3).map(p => ({
+                id: p.id,
+                title: p.title || p.name,
+                categoryId: p.categoryId
+              })));
+            }
+          }
+          
+          // Debug: Log final context before rendering
+          console.log(`[ROOT COLLECTION] Final context before rendering:`);
+          console.log(`  - Products count: ${context.products?.length || 0}`);
+          if (context.products && context.products.length > 0) {
+            const firstProduct = context.products[0];
+            console.log(`  - First product:`, {
+              id: firstProduct.id,
+              title: firstProduct.title || firstProduct.name,
+              url: firstProduct.url || firstProduct.link,
+              price: firstProduct.price || firstProduct.sellingPrice,
+              stock: firstProduct.stock,
+              inStock: firstProduct.inStock,
+              hasImage: !!(firstProduct.imageUrl || firstProduct.thumbnailImage1)
+            });
+          }
+          
+          // Try to render products template first (to show product list, not categories list)
           let html;
-          const templateOptions = ['templates/categories', 'templates/category', 'templates/collection', 'templates/products'];
+          const templateOptions = ['templates/products', 'templates/collection', 'templates/category', 'templates/categories'];
+          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) {
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.setHeader('Cache-Control', 'no-cache');
+            return res.send(html);
+          }
+        }
+        
+        // Not a category - try to find brand by handle
+        const brand = context.brands?.find(b => 
+          (b.handle && b.handle.toLowerCase() === handle.toLowerCase()) ||
+          (b.name && b.name.toLowerCase().replace(/\s+/g, '-') === handle.toLowerCase())
+        );
+        
+        if (brand) {
+          context.brand = brand;
+          const filtered = (context.products || []).filter(p =>
+            p.brandId === brand.id ||
+            String(p.brandId).toLowerCase() === String(brand.id).toLowerCase() ||
+            (p.brand && p.brand.toLowerCase() === brand.name.toLowerCase())
+          );
+          const filteredProducts = this.mode === 'real' ? filtered : filtered.map(p => this.enrichProductData(p));
+          
+          context.brand.products = filteredProducts;
+          context.products = filteredProducts;
+          
+          console.log(`[ROOT BRAND] Brand: ${brand.name}, Products: ${filteredProducts.length}`);
+          
+          // Try to render products template
+          let html;
+          const templateOptions = ['templates/products', 'templates/brand', 'templates/collection', 'templates/brands'];
           for (const template of templateOptions) {
             try {
               html = await renderWithLayout(this.liquid, template, context, this.themePath);
@@ -1447,20 +1609,16 @@ class DevServer {
       }
     });
 
-    // Favicon handler
+    // Favicon handler: serve from theme assets if present, else 204
     this.app.get('/favicon.ico', (req, res) => {
-      res.status(204).end(); // No Content
+      const faviconPath = path.join(this.themePath, 'assets', 'favicon.ico');
+      if (fs.existsSync(faviconPath)) {
+        res.setHeader('Content-Type', 'image/x-icon');
+        return res.sendFile('favicon.ico', { root: path.join(this.themePath, 'assets') });
+      }
+      res.status(204).end();
     });
 
-    // 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)
@@ -1677,48 +1835,29 @@ class DevServer {
           const productsResponse = await this.apiClient.getProducts({ limit: 50, offset: 0 });
           context.products = productsResponse.products || productsResponse.data?.products || [];
           
-          // Ensure all products have proper URL, images, and stock fields
-          context.products = context.products.map((product, index) => {
-            // Ensure URL field exists
-            if (!product.url && !product.link) {
-              const handle = product.handle || product.slug || product.id;
-              product.url = `/products/${handle}`;
-              product.link = `/products/${handle}`;
-              
-              // Debug first few products to verify URL generation
-              if (index < 3) {
-                console.log(`[CONTEXT] Product ${index + 1} URL: ${product.url} (handle: ${product.handle || 'none'}, slug: ${product.slug || 'none'}, id: ${product.id || 'none'})`);
-              }
-            }
-            // Ensure stock fields exist (they should from mock-data, but double-check)
-            if (product.stock === undefined && product.stockQuantity === undefined) {
-              // Calculate from variants if available
-              if (product.variants && product.variants.length > 0) {
-                const totalStock = product.variants.reduce((sum, v) => sum + (v.stock || 0), 0);
-                product.stock = totalStock;
-                product.stockQuantity = totalStock;
-                product.inStock = totalStock > 0;
-                product.available = totalStock > 0;
-              } else {
-                // Default to in stock if no stock info
-                product.stock = 10;
-                product.stockQuantity = 10;
-                product.inStock = true;
-                product.available = true;
-              }
-            }
-            // Ensure image fields exist (they should from mock-data, but double-check)
-            if (!product.thumbnailImage1 && !product.imageUrl && (!product.images || product.images.length === 0)) {
-              // Fallback to picsum placeholder
-              const imageId = product.id ? String(product.id).replace(/\D/g, '') || '1' : '1';
-              product.imageUrl = `https://picsum.photos/seed/${imageId}/800/800`;
-              product.thumbnailImage1 = {
-                url: product.imageUrl,
-                altText: product.title || product.name || 'Product image'
-              };
-            }
-            return product;
-          });
+          // Enrich all products using the reusable enrichment function
+          // This ensures consistency with products used in widgets and pages
+          context.products = this.enrichProductsData(context.products);
+          
+          // Debug first few products to verify enrichment
+          if (context.products.length > 0) {
+            context.products.slice(0, 3).forEach((product, index) => {
+              console.log(`[CONTEXT] Product ${index + 1} after enrichment:`, {
+                id: product.id,
+                handle: product.handle || 'none',
+                url: product.url || product.link || 'MISSING',
+                title: product.title || product.name || 'MISSING',
+                price: product.price || product.sellingPrice || 'MISSING',
+                hasPrices: !!product.prices,
+                stock: product.stock !== undefined ? product.stock : 'MISSING',
+                stockQuantity: product.stockQuantity !== undefined ? product.stockQuantity : 'MISSING',
+                inStock: product.inStock !== undefined ? product.inStock : 'MISSING',
+                available: product.available !== undefined ? product.available : 'MISSING',
+                hasImage: !!(product.imageUrl || product.thumbnailImage1),
+                imageUrl: product.imageUrl || product.thumbnailImage1?.url || 'MISSING'
+              });
+            });
+          }
           
           console.log(`[CONTEXT] Loaded ${context.products.length} products`);
           
@@ -1746,6 +1885,18 @@ class DevServer {
           try {
             const categoriesResponse = await this.apiClient.getCategories({ limit: 50, offset: 0 });
             context.categories = categoriesResponse.categories || categoriesResponse.data?.categories || categoriesResponse || [];
+            
+            // Ensure all categories have proper URL fields for navigation
+            context.categories = context.categories.map(category => {
+              // Set URL to category handle (e.g., /accessories)
+              if (!category.url && !category.link) {
+                const handle = category.handle || category.name?.toLowerCase().replace(/\s+/g, '-') || category.id;
+                category.url = `/${handle}`;
+                category.link = `/${handle}`;
+              }
+              return category;
+            });
+            
             context.collections = context.categories; // Also set collections for compatibility
             console.log(`[CONTEXT] Loaded ${context.categories.length} categories`);
           } catch (error) {
@@ -1789,6 +1940,14 @@ class DevServer {
             console.error('[CONTEXT] Error details:', error.response?.status, error.response?.data);
             context.menus = [];
           }
+
+          // Set mainMenu for mega-menu fallback (header when no HeaderMenu widget)
+          let mainMenu = null;
+          if (context.menus && context.menus.length > 0) {
+            const main = context.menus.find((m) => (m.type || '').toLowerCase().trim() === 'main menu');
+            mainMenu = main || context.menus[0];
+          }
+          context.mainMenu = mainMenu;
           
           // Load cart data
           try {
@@ -1885,59 +2044,164 @@ class DevServer {
           content: []
         };
       }
-    } else if (this.apiClient) {
-      // Use real API
+    } else if (this.mode === 'real') {
+      // Real mode: use webstoreapi-fetcher only (no apiClient). Thin HTTP calls to /webstoreapi/*.
+      const opts = { headers: req.headers.cookie ? { Cookie: req.headers.cookie } : {} };
+      const baseHost = (process.env.O2VEND_API_BASE_URL || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '') || 'localhost';
+      const themeSettings = context.settings || {};
+      let storeInfo = null;
       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;
+        storeInfo = await webstoreApi.fetchStoreInfo();
+      } catch (e) {
+        /* use fallbacks */
+      }
+      const logo = (storeInfo && storeInfo.logoUrl) ? storeInfo.logoUrl : '/assets/logo.png';
+      const favicon = (storeInfo && storeInfo.favouriteIconUrl) ? storeInfo.favouriteIconUrl : '/favicon.ico';
+      const storeName = (storeInfo && storeInfo.name) ? storeInfo.name : 'Store';
+      const storeSettings = (storeInfo && storeInfo.settings) || {};
+      try {
+        context.shop = {
+          name: storeName,
+          domain: baseHost,
+          description: 'O2VEND Store',
+          email: storeSettings.companyEmail || 'store@example.com',
+          logo,
+          favicon,
+          currency: storeSettings.currency || themeSettings.currency || 'USD',
+          language: storeSettings.language || themeSettings.language || 'en',
+          locale: themeSettings.locale || 'en-US',
+          settings: {
+            currency: storeSettings.currency || themeSettings.currency || 'USD',
+            currencySymbol: storeSettings.currencySymbol || storeSettings.currency_symbol || themeSettings.currency_symbol || themeSettings.currencySymbol || '$',
+            logo,
+            favicon
+          }
+        };
+        context.tenant = { id: process.env.O2VEND_TENANT_ID || 'real' };
+
+        if (process.env.O2VEND_LAYOUT_FULL === '1' || process.env.O2VEND_LAYOUT_FULL === 'true') {
+          context.settings = context.settings || {};
+          context.settings.layout_style = 'full-width';
+        }
+
+        const page = pageType === 'home' ? 'home' : (pageType === 'products' ? 'products' : 'home');
+        context.widgets = await webstoreApi.fetchWidgetsBySections(page, webstoreApi.DEFAULT_SECTIONS, opts);
+        context.widgets = context.widgets || { hero: [], products: [], footer: [], content: [], header: [] };
+
+        if (this.widgetService) {
+          Object.keys(context.widgets).forEach((section) => {
+            if (Array.isArray(context.widgets[section])) {
+              context.widgets[section].forEach((widget) => {
+                if (!widget.template_path && widget.template) widget.template_path = `widgets/${widget.template}`;
+                if (!widget.template_path && widget.type) {
+                  const slug = this.widgetService.getTemplateSlug(widget.type);
+                  widget.template_path = `widgets/${slug}`;
+                  widget.template = slug;
+                }
+              });
+            }
+          });
+        }
+
+        const productsRes = await webstoreApi.fetchProducts({ limit: 50, offset: 0 }, opts);
+        context.products = productsRes?.products || productsRes?.Products || [];
+        context.products = this.normalizeProductsForRealMode(context.products);
+
+        try {
+          const catRes = await webstoreApi.fetchCategories({ limit: 50, offset: 0 }, opts);
+          const raw = catRes?.categories || catRes?.data?.categories || catRes || [];
+          context.categories = raw.map((c) => {
+            const h = (c.handle || (c.name || '').toLowerCase().replace(/\s+/g, '-') || c.id || '').toString().replace(/^\s+|\s+$/g, '') || null;
+            if (h) {
+              c.handle = c.handle || h;
+              c.slug = c.slug || h;
+              c.url = `/${h}`;
+              c.link = `/${h}`;
+            }
+            return c;
+          });
+          context.collections = context.categories;
+        } catch (e) {
+          context.categories = [];
+          context.collections = [];
+        }
+
+        try {
+          const brandRes = await webstoreApi.fetchBrands({ limit: 50, offset: 0 }, opts);
+          context.brands = brandRes?.brands || brandRes?.data?.brands || brandRes || [];
+        } catch (e) {
+          context.brands = [];
+        }
+
+        try {
+          context.menus = await webstoreApi.fetchMenus(opts);
+          context.menus = Array.isArray(context.menus) ? context.menus : [];
+          let mainMenu = null;
+          if (context.menus.length > 0) {
+            const main = context.menus.find((m) => (m.type || '').toLowerCase().trim() === 'main menu');
+            const candidate = main || context.menus[0];
+            if (candidate && candidate.id) {
+              try {
+                mainMenu = await webstoreApi.fetchMenuById(candidate.id, opts);
+              } catch (e) {
+                /* ignore */
               }
-            });
+            }
           }
-        });
-        
-        // 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;
+          context.mainMenu = mainMenu;
+        } catch (e) {
+          context.menus = [];
+          context.mainMenu = null;
+        }
+
+        try {
+          const cartRes = await webstoreApi.fetchCart(opts);
+          const data = cartRes?.data || cartRes;
+          if (data) {
+            context.cart = {
+              ...context.cart,
+              ...data,
+              itemCount: data.items?.length ?? data.itemCount ?? 0,
+              total: data.total ?? data.subTotal ?? 0
+            };
           }
-        } else if (pageType === 'product' && extra.productHandle) {
-          // Load product data
-          // context.product = await this.loadProduct(extra.productHandle);
+        } catch (e) {
+          /* cart optional */
+        }
+
+        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 === '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;
+        } else if (pageType === 'product' && extra.productHandle) {
+          const handle = String(extra.productHandle).toLowerCase().trim();
+          let product = context.products.find((p) => {
+            const h = (p.handle || '').toLowerCase().trim();
+            const s = (p.slug || '').toLowerCase().trim();
+            const id = String(p.id || '').toLowerCase().trim();
+            const pid = String(p.productId || '').toLowerCase().trim();
+            if (h === handle || s === handle || id === handle) return true;
+            if (handle.startsWith('product-') && (pid === handle.replace(/^product-/, '') || id === handle.replace(/^product-/, ''))) return true;
+            return false;
+          });
+          if (!product) {
+            try {
+              const idToFetch = handle.startsWith('product-') ? handle.replace(/^product-/, '') : handle;
+              product = await webstoreApi.fetchProductById(idToFetch, opts);
+              if (product) product = this.normalizeProductForRealMode(product);
+            } catch (e) {
+              /* ignore */
+            }
+          }
+          if (product) context.product = product;
         }
       } catch (error) {
-        console.warn('[CONTEXT] Failed to load from API:', error.message);
+        console.warn('[CONTEXT] Real mode fetch failed:', error.message);
       }
     }
 
@@ -1975,19 +2239,18 @@ class DevServer {
         // 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
+          const formatted = this.mode === 'real'
+            ? this.normalizeProductsForRealMode(widgetProducts)
+            : this.enrichProductsData(widgetProducts);
+
+          widget.data.products = formatted;
+          widget.data.Products = formatted;
+          widget.products = formatted;
           widget.data.content = widget.data.content || {};
-          widget.data.content.products = widgetProducts;
-          widget.data.content.Products = widgetProducts;
-          
+          widget.data.content.products = formatted;
+          widget.data.content.Products = formatted;
           enrichedCount++;
-          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${widgetProducts.length} products`);
+          console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${formatted.length} products`);
         }
         
         // Enrich CategoryList and CategoryListCarousel widgets with categories
@@ -2024,11 +2287,16 @@ class DevServer {
         
         // 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);
+          const recent = products.slice(0, 6);
+          const recentProducts = this.mode === 'real'
+            ? this.normalizeProductsForRealMode(recent)
+            : this.enrichProductsData(recent);
           widget.data.products = recentProducts;
           widget.data.Products = recentProducts;
           widget.products = recentProducts;
-          
+          widget.data.content = widget.data.content || {};
+          widget.data.content.products = recentProducts;
+          widget.data.content.Products = recentProducts;
           enrichedCount++;
           console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${recentProducts.length} recently viewed products`);
         }
@@ -2038,37 +2306,322 @@ class DevServer {
     console.log(`[CONTEXT] ✅ Enriched ${enrichedCount} widgets with data`);
   }
   
+  /**
+   * Check if a product belongs to a category (for collection/category filtering).
+   * Handles categoryId, primaryCategoryId, categoryHandle, and categories[].
+   * @param {Object} p - Product
+   * @param {Object} category - Category { id, handle }
+   * @returns {boolean}
+   */
+  productMatchesCategory(p, category) {
+    const cid = category.id;
+    const ch = (category.handle || category.slug || '').toLowerCase();
+    if (p.categoryId != null && (p.categoryId === cid || String(p.categoryId).toLowerCase() === String(cid).toLowerCase())) return true;
+    if (p.primaryCategoryId != null && (p.primaryCategoryId === cid || String(p.primaryCategoryId).toLowerCase() === String(cid).toLowerCase())) return true;
+    const ph = (p.categoryHandle || p.category?.handle || '').toLowerCase();
+    if (ch && ph && ph === ch) return true;
+    const arr = p.categories || p.categoryIds || [];
+    if (Array.isArray(arr) && arr.some(cat => {
+      const o = typeof cat === 'object' ? cat : { id: cat };
+      return o.id === cid || (o.handle || o.slug || '').toLowerCase() === ch;
+    })) return true;
+    return false;
+  }
+
+  /**
+   * Enrich a single product with all required data (URL, name/title, price, images, stock)
+   * This ensures consistency between widgets and pages
+   * @param {Object} product - Product object to enrich
+   * @returns {Object} Enriched product (creates a copy to avoid mutation)
+   */
+  enrichProductData(product) {
+    // Create a copy to avoid mutating the original
+    const enriched = { ...product };
+    
+    // CRITICAL: Ensure productId exists - it's the most reliable identifier
+    if (!enriched.productId && enriched.id) {
+      // Try to extract numeric ID from string ID (e.g., "product-1" -> 1)
+      const numericMatch = String(enriched.id).match(/\d+/);
+      if (numericMatch) {
+        enriched.productId = parseInt(numericMatch[0], 10);
+      } else {
+        // Use the ID as-is if it's already numeric
+        enriched.productId = enriched.id;
+      }
+    } else if (!enriched.productId && !enriched.id) {
+      console.warn(`[ENRICH] ⚠️  Product missing both id and productId:`, {
+        keys: Object.keys(enriched).slice(0, 15),
+        title: enriched.title || enriched.name
+      });
+    }
+    
+    // DEBUG: Log incoming product to diagnose missing fields
+    if (!product.id && !product.handle && !product.slug && !product.productId) {
+      console.warn(`[ENRICH] ⚠️  Product missing all identifiers (id/handle/slug/productId):`, {
+        keys: Object.keys(product).slice(0, 15),
+        title: product.title || product.name
+      });
+    }
+    
+    // Ensure URL field exists - CRITICAL for product navigation
+    // Always use /products/{handle} so links target dev server (never external URLs)
+    const handle = enriched.handle || enriched.slug || enriched.id;
+    const effectiveHandle = (handle && String(handle).trim() && String(handle) !== '#')
+      ? String(handle).trim().toLowerCase()
+      : (enriched.productId ? `product-${enriched.productId}`.toLowerCase() : null);
+    if (effectiveHandle) {
+      enriched.url = `/products/${effectiveHandle}`;
+      enriched.link = `/products/${effectiveHandle}`;
+      if (!enriched.handle || enriched.handle === '#' || enriched.handle === '') enriched.handle = effectiveHandle;
+      if (!enriched.slug || enriched.slug === '#' || enriched.slug === '') enriched.slug = effectiveHandle;
+    } else {
+      enriched.url = '#';
+      enriched.link = '#';
+      console.warn(`[ENRICH] ⚠️  Product has no id/handle/slug/productId, URL set to '#'`, {
+        productKeys: Object.keys(enriched).slice(0, 10)
+      });
+    }
+
+    // Ensure handle/slug exist if missing (for template fallback logic)
+    // Also normalize them (remove '#' or empty strings)
+    if (!enriched.handle || enriched.handle === '#' || enriched.handle === '') {
+      if (enriched.slug && enriched.slug !== '#' && enriched.slug !== '') {
+        enriched.handle = enriched.slug;
+      } else if (enriched.id && enriched.id !== '#') {
+        enriched.handle = String(enriched.id).toLowerCase();
+      } else if (enriched.productId) {
+        enriched.handle = `product-${enriched.productId}`.toLowerCase();
+      } else if (!enriched.handle) {
+        // Generate from URL if it was set above
+        if (enriched.url && enriched.url !== '#') {
+          enriched.handle = enriched.url.replace(/^\/products\//, '').toLowerCase();
+        }
+      }
+    }
+    
+    if (!enriched.slug || enriched.slug === '#' || enriched.slug === '') {
+      if (enriched.handle && enriched.handle !== '#' && enriched.handle !== '') {
+        enriched.slug = enriched.handle;
+      } else if (enriched.id && enriched.id !== '#') {
+        enriched.slug = String(enriched.id).toLowerCase();
+      } else if (enriched.productId) {
+        enriched.slug = `product-${enriched.productId}`.toLowerCase();
+      } else if (!enriched.slug) {
+        // Generate from URL if it was set above
+        if (enriched.url && enriched.url !== '#') {
+          enriched.slug = enriched.url.replace(/^\/products\//, '').toLowerCase();
+        }
+      }
+    }
+    
+    // Ensure name/title exists - CRITICAL for product display
+    if (!enriched.name && !enriched.title) {
+      enriched.name = `Product ${enriched.id || 'Unknown'}`;
+      enriched.title = enriched.name;
+    } else if (!enriched.name) {
+      enriched.name = enriched.title || `Product ${enriched.id || 'Unknown'}`;
+    } else if (!enriched.title) {
+      enriched.title = enriched.name;
+    }
+    
+    // Ensure both variations and variants exist (product-card uses variations)
+    if (enriched.variants && !enriched.variations) {
+      enriched.variations = enriched.variants;
+    } else if (enriched.variations && !enriched.variants) {
+      enriched.variants = enriched.variations;
+    }
+    
+    // Ensure price exists - CRITICAL for product display
+    if (!enriched.price && !enriched.sellingPrice) {
+      // Try to get from variants/variations first
+      const variantsOrVariations = enriched.variants || enriched.variations;
+      if (variantsOrVariations && variantsOrVariations.length > 0) {
+        enriched.price = variantsOrVariations[0].price || variantsOrVariations[0].sellingPrice || 0;
+        enriched.sellingPrice = enriched.price;
+      } else {
+        enriched.price = 0;
+        enriched.sellingPrice = 0;
+      }
+    } else if (!enriched.price) {
+      enriched.price = enriched.sellingPrice;
+    } else if (!enriched.sellingPrice) {
+      enriched.sellingPrice = enriched.price;
+    }
+    
+    // Ensure prices object exists for product-card compatibility - CRITICAL
+    // Make sure price is NOT 0 unless it's actually 0 (check if undefined/null)
+    const finalPrice = (enriched.price !== undefined && enriched.price !== null) 
+      ? enriched.price 
+      : ((enriched.sellingPrice !== undefined && enriched.sellingPrice !== null) 
+          ? enriched.sellingPrice 
+          : 0);
+    
+    if (!enriched.prices) {
+      const mrpValue = enriched.compareAtPrice || enriched.comparePrice || enriched.mrp || 0;
+      enriched.prices = {
+        price: finalPrice,
+        mrp: mrpValue,
+        currency: enriched.currency || 'USD'
+      };
+    } else {
+      // Update prices object if it exists but is missing fields
+      if (enriched.prices.price === undefined || enriched.prices.price === null) {
+        enriched.prices.price = finalPrice;
+      }
+      if (enriched.prices.mrp === undefined || enriched.prices.mrp === null) {
+        enriched.prices.mrp = enriched.compareAtPrice || enriched.comparePrice || enriched.mrp || 0;
+      }
+      if (!enriched.prices.currency) {
+        enriched.prices.currency = enriched.currency || 'USD';
+      }
+    }
+    
+    // Ensure price/sellingPrice fields also exist (not just prices object)
+    if (enriched.price === undefined || enriched.price === null) {
+      enriched.price = finalPrice;
+    }
+    if (enriched.sellingPrice === undefined || enriched.sellingPrice === null) {
+      enriched.sellingPrice = finalPrice;
+    }
+    
+    // Ensure image exists - CRITICAL for product display
+    if (!enriched.imageUrl && !enriched.thumbnailImage1 && (!enriched.images || enriched.images.length === 0)) {
+      // Fallback to picsum placeholder
+      const imageId = enriched.id ? String(enriched.id).replace(/\D/g, '') || '1' : '1';
+      enriched.imageUrl = `https://picsum.photos/seed/${imageId}/800/800`;
+      enriched.thumbnailImage1 = {
+        url: enriched.imageUrl,
+        altText: enriched.title || enriched.name || 'Product image'
+      };
+    }
+    
+    // Ensure stock/availability data exists - CRITICAL to prevent incorrect "SOLD OUT" display
+    if (enriched.stock === undefined && enriched.stockQuantity === undefined) {
+      // Calculate from variants/variations if available
+      const variantsOrVariations = enriched.variants || enriched.variations;
+      if (variantsOrVariations && variantsOrVariations.length > 0) {
+        const totalStock = variantsOrVariations.reduce((sum, v) => sum + (v.stock || v.quantity || 0), 0);
+        enriched.stock = totalStock;
+        enriched.stockQuantity = totalStock;
+        enriched.inStock = totalStock > 0;
+        enriched.available = totalStock > 0;
+      } else {
+        // Default to in stock if no stock info (prevents false "SOLD OUT" display)
+        enriched.stock = 10;
+        enriched.stockQuantity = 10;
+        enriched.inStock = true;
+        enriched.available = true;
+      }
+    } else {
+      // Ensure inStock/available flags are set based on stock value
+      // CRITICAL: Use nullish coalescing to handle 0 values correctly
+      const stockValue = enriched.stock !== undefined ? enriched.stock : (enriched.stockQuantity !== undefined ? enriched.stockQuantity : 0);
+      enriched.inStock = stockValue > 0;
+      enriched.available = stockValue > 0;
+      
+      // Also ensure stockQuantity is set if only stock is set (and vice versa)
+      if (enriched.stock !== undefined && enriched.stockQuantity === undefined) {
+        enriched.stockQuantity = enriched.stock;
+      } else if (enriched.stockQuantity !== undefined && enriched.stock === undefined) {
+        enriched.stock = enriched.stockQuantity;
+      }
+    }
+    
+    return enriched;
+  }
+
+  /**
+   * Normalize real-API product for template use (no enrichment).
+   * Aliases API keys (Description, Images, etc.) to template-expected keys,
+   * sets url/link for dev navigation, and normalizes image items to { url, altText }.
+   * @param {Object} p - Product from real API
+   * @returns {Object} Normalized product (shallow copy + aliases)
+   */
+  normalizeProductForRealMode(p) {
+    if (!p || typeof p !== 'object') return p;
+    const n = { ...p };
+    if (n.Description != null && n.description == null) n.description = n.Description;
+    if (n.HtmlContent != null && n.htmlContent == null) n.htmlContent = n.HtmlContent;
+    if (n.ShortDescription != null && n.shortDescription == null) n.shortDescription = n.ShortDescription;
+    if (n.Name != null && n.name == null) n.name = n.Name;
+    if (n.Title != null && n.title == null) n.title = n.Title;
+    if (n.Attributes != null && n.attributes == null) n.attributes = n.Attributes;
+    const t1 = n.ThumbnailImage1 || n.thumbnailImage1;
+    if (t1 != null) {
+      const u = typeof t1 === 'string' ? t1 : (t1.url || t1.Url || t1.imageUrl || t1.ImageUrl);
+      if (u) {
+        const a = typeof t1 === 'string' ? (n.name || n.title) : (t1.altText || t1.AltText || n.name || n.title);
+        n.thumbnailImage1 = { url: u, altText: a };
+        if (!n.thumbnailImage) n.thumbnailImage = n.thumbnailImage1;
+      } else if (!n.thumbnailImage1) n.thumbnailImage1 = t1;
+    }
+    let imgs = n.images || n.Images;
+    if (Array.isArray(imgs) && imgs.length > 0) {
+      n.images = imgs.map((img) => {
+        if (typeof img === 'string') return { url: img, altText: n.name || n.title };
+        const u = img.url || img.Url || img.imageUrl || img.ImageUrl;
+        const a = img.altText || img.AltText || n.name || n.title;
+        return u ? { url: u, altText: a } : (typeof img === 'object' ? { url: img, altText: a } : { url: String(img), altText: a });
+      });
+    } else if (imgs) {
+      n.images = Array.isArray(imgs) ? imgs : [imgs];
+    } else {
+      const single = n.imageUrl || n.ImageUrl;
+      if (single) n.images = [{ url: single, altText: n.name || n.title }];
+    }
+    const handle = (n.handle || n.slug || n.id || '').toString().trim();
+    const h = handle && handle !== '#' ? handle.toLowerCase() : (n.productId ? `product-${n.productId}` : null);
+    if (h) {
+      n.url = `/products/${h}`;
+      n.link = `/products/${h}`;
+    }
+    return n;
+  }
+
+  normalizeProductsForRealMode(products) {
+    if (!Array.isArray(products)) return [];
+    return products.map((p) => this.normalizeProductForRealMode(p));
+  }
+  
+  /**
+   * Enrich multiple products with all required data
+   * @param {Array} products - Array of products to enrich
+   * @returns {Array} Array of enriched products
+   */
+  enrichProductsData(products) {
+    if (!Array.isArray(products)) return [];
+    return products.map(product => this.enrichProductData(product));
+  }
+
   /**
    * 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;
+    const limit = widget.settings?.limit || widget.data?.content?.Limit || widget.settings?.numberOfProducts || widget.settings?.NumberOfProducts || 12;
     
     // Get products based on widget type
     const type = (widget.type || '').toLowerCase();
     
+    let widgetProducts = [];
+    
     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') {
+      widgetProducts = featured.length > 0 ? featured.slice(0, limit) : products.slice(0, limit);
+    } else 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') {
+      widgetProducts = products.slice(0, limit);
+    } else 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);
+      widgetProducts = sorted.slice(0, limit);
+    } else {
+      widgetProducts = products.slice(0, limit);
     }
-    
-    // Default: return first N products
-    return products.slice(0, limit);
+    return widgetProducts;
   }
 
   /**
@@ -2873,6 +3426,22 @@ class DevServer {
           logLevel: 'silent',
           timeout: 2000
         }));
+      } else if (this.mode === 'real') {
+        const base = (process.env.O2VEND_API_BASE_URL || '').replace(/\/$/, '').replace(/\/shopfront\/api\/v2\/?$/i, '').replace(/\/webstoreapi\/?$/i, '');
+        if (base) {
+          const { createProxyMiddleware } = require('http-proxy-middleware');
+          const proxyOpts = {
+            target: base,
+            changeOrigin: true,
+            logLevel: 'silent',
+            timeout: parseInt(process.env.O2VEND_API_TIMEOUT, 10) || 10000,
+            onProxyReq: (proxyReq, req) => {
+              if (req.headers.cookie) proxyReq.setHeader('Cookie', req.headers.cookie);
+            }
+          };
+          this.app.use('/webstoreapi', createProxyMiddleware(proxyOpts));
+          this.app.use('/shopfront/api', createProxyMiddleware(proxyOpts));
+        }
       }
 
       // Inject hot reload script into HTML responses