@o2vend/theme-cli 1.0.36 → 1.0.38

package/README.md

@@ -4,6 +4,10 @@
 
 The O2VEND Theme CLI is a complete development environment for creating, testing, and packaging O2VEND themes. It works independently and doesn't require access to the main O2VEND webstore solution.
 
+## Prerequisites
+
+- **Node.js 24.0 or later** is required. Download from [nodejs.org](https://nodejs.org/).
+
 ## Installation
 
 Install globally via npm:

package/lib/lib/dev-server.js

@@ -137,7 +137,7 @@ class DevServer {
         // Only process if it contains actual Liquid variables, not just comments
         if (cssContent.includes('{{') && cssContent.includes('settings.')) {
           try {
-            const settings = this.loadThemeSettings();
+            const settings = { ...this.loadThemeSettings(), ...(this._realStoreSettings || {}) };
             const processedCss = await this.liquid.parseAndRender(cssContent, { settings });
             res.setHeader('Content-Type', 'text/css; charset=utf-8');
             res.setHeader('Cache-Control', 'no-cache');
@@ -356,7 +356,6 @@ class DevServer {
           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 }
@@ -380,7 +379,6 @@ class DevServer {
         
         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 }
@@ -1056,6 +1054,19 @@ class DevServer {
       }
     });
 
+    // Checkout page (use pageType 'checkout' so only header/footer widgets load, not home widgets)
+    this.app.get('/checkout', async (req, res, next) => {
+      try {
+        const context = await this.buildContext(req, 'checkout');
+        const html = await renderWithLayout(this.liquid, 'templates/checkout', context, this.themePath);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.send(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+
     // Search page
     this.app.get('/search', async (req, res, next) => {
       try {
@@ -1244,7 +1255,7 @@ class DevServer {
           content: sectionContent,
           type: 'section',
           name: sectionName,
-          backUrl: '/dev'
+          backUrl: '/dev#sections'
         });
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.setHeader('Cache-Control', 'no-cache');
@@ -1276,13 +1287,14 @@ class DevServer {
           }
         }
         
-        // Get mock widget data for this type
+        // Get mock widget data for this type (widgetType is usually template slug, e.g. spacebar-carousel)
         const mockWidgets = this.mockApi?.mockData?.widgets || [];
-        const mockWidget = mockWidgets.find(w => 
-          w.type === widgetType || 
-          w.type.toLowerCase() === widgetType.toLowerCase() ||
-          w.id?.includes(widgetType)
-        ) || {
+        const mockWidget = mockWidgets.find(w => {
+          if (w.type === widgetType || w.id?.includes(widgetType)) return true;
+          if (w.type && typeof w.type === 'string' && w.type.toLowerCase().replace(/-/g, '') === widgetType.toLowerCase().replace(/-/g, '')) return true;
+          if (this.widgetService && w.type && this.widgetService.getTemplateSlug(w.type) === widgetType) return true;
+          return false;
+        }) || {
           id: `widget-${widgetType}-1`,
           type: widgetType,
           section: 'content',
@@ -1299,6 +1311,8 @@ class DevServer {
         if (this.widgetService) {
           widgetToRender = this.widgetService.normalizeWidget(mockWidget);
         }
+        // Enrich single widget with products/news/etc so preview has data
+        this.enrichSingleWidget(widgetToRender, context);
         
         const widgetContent = await this.renderWidget(widgetToRender, context);
         
@@ -1307,7 +1321,7 @@ class DevServer {
           content: widgetContent,
           type: 'widget',
           name: widgetType,
-          backUrl: '/dev'
+          backUrl: '/dev#widgets'
         });
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.setHeader('Cache-Control', 'no-cache');
@@ -1336,18 +1350,10 @@ class DevServer {
         }
         
         const context = await this.buildContext(req, 'home');
-        
-        // Try to render snippet with common variables
-        const snippetContext = {
+        const snippetContext = this.getSnippetMockContext(snippetName, {
           ...context,
-          snippet: {
-            name: snippetName
-          },
-          // Add common snippet variables
-          product: context.products?.[0] || context.product,
-          collection: context.collections?.[0] || context.collection,
-          cart: context.cart
-        };
+          snippet: { name: snippetName }
+        });
         
         const snippetContent = await this.liquid.renderFile(snippetPath, snippetContext);
         
@@ -1356,7 +1362,8 @@ class DevServer {
           content: snippetContent,
           type: 'snippet',
           name: snippetName,
-          backUrl: '/dev'
+          backUrl: '/dev#snippets',
+          includeThemeCss: true
         });
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.setHeader('Cache-Control', 'no-cache');
@@ -1392,7 +1399,7 @@ class DevServer {
         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';
+        else if (templateName.includes('checkout')) pageType = 'checkout';
         
         const context = await this.buildContext(req, pageType);
         const html = await renderWithLayout(this.liquid, `templates/${templateName}`, context, this.themePath);
@@ -1411,7 +1418,7 @@ class DevServer {
         const handle = req.params.handle;
         
         // Skip if it's a known route path or static file extension
-        const knownPaths = ['assets', 'images', 'api', 'dev', 'favicon.ico', 'products', 'collections', 'categories', 'brands', 'cart', 'search', 'page', 'pages'];
+        const knownPaths = ['assets', 'images', 'api', 'dev', 'favicon.ico', 'products', 'collections', 'categories', 'brands', 'cart', 'checkout', 'search', 'page', 'pages'];
         const staticExtensions = ['.css', '.js', '.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp', '.woff', '.woff2', '.ttf', '.eot', '.ico'];
         const hasStaticExtension = staticExtensions.some(ext => handle.toLowerCase().endsWith(ext));
         
@@ -1840,7 +1847,7 @@ class DevServer {
         };
         
         // Load widgets filtered by page type (matches production behavior)
-        const pageIdMap = { home: 'home', product: 'product', collection: 'category', category: 'category', products: 'products', categories: 'categories', brand: 'brand', checkout: 'checkout', page: 'home' };
+        const pageIdMap = { home: 'home', product: 'product', collection: 'category', category: 'category', products: 'products', categories: 'categories', collections: 'categories', brand: 'brand', cart: 'cart', checkout: 'checkout', page: 'home' };
         const widgetPageId = pageIdMap[pageType] || 'home';
         if (this.widgetService) {
           try {
@@ -2079,6 +2086,9 @@ class DevServer {
       const favicon = (storeInfo && storeInfo.favouriteIconUrl) ? storeInfo.favouriteIconUrl : '/favicon.ico';
       const storeName = (storeInfo && storeInfo.name) ? storeInfo.name : 'Store';
       const storeSettings = (storeInfo && storeInfo.settings) || {};
+      if (Object.keys(storeSettings).length > 0) {
+        this._realStoreSettings = storeSettings;
+      }
       try {
         context.shop = {
           name: storeName,
@@ -2118,7 +2128,8 @@ class DevServer {
           context.settings.layout_style = 'full-width';
         }
 
-        const page = pageType === 'home' ? 'home' : (pageType === 'products' ? 'products' : 'home');
+        const pageIdMap = { home: 'home', product: 'product', collection: 'category', category: 'category', products: 'products', categories: 'categories', collections: 'categories', brand: 'brand', cart: 'cart', checkout: 'checkout', page: 'home' };
+        const page = pageIdMap[pageType] || 'home';
         context.widgets = await webstoreApi.fetchWidgetsBySections(page, webstoreApi.DEFAULT_SECTIONS, opts);
         context.widgets = context.widgets || { hero: [], products: [], footer: [], content: [], header: [] };
 
@@ -2143,20 +2154,23 @@ class DevServer {
 
         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 raw = catRes?.categories || catRes?.data?.categories || catRes?.data?.items || catRes?.items || (Array.isArray(catRes) ? catRes : []);
+          context.categories = Array.isArray(raw) ? raw.map((c) => {
             const h = (c.handle || (c.name || '').toLowerCase().replace(/\s+/g, '-') || c.id || '').toString().trim() || null;
             if (h) {
               c.handle = c.handle || h;
               c.slug = c.slug || h;
             }
             return c;
-          });
+          }) : [];
           context.collections = context.categories;
         } catch (e) {
           context.categories = [];
           context.collections = [];
         }
+        if (pageType === 'collections' && !context.collections) {
+          context.collections = context.categories || [];
+        }
 
         try {
           const brandRes = await webstoreApi.fetchBrands({ limit: 50, offset: 0 }, opts);
@@ -2250,12 +2264,35 @@ class DevServer {
       }
     }
 
+    // Align with mock: hide Splash on pages (show only in /dev); in mock only, hide Footer type in footer (only FooterMenu)
+    this.filterWidgetsForDisplay(context.widgets, this.mode);
+
     // Enrich widgets with products, categories, and brands data
     this.enrichWidgetsWithData(context);
-    
+
     return context;
   }
-  
+
+  /**
+   * Filter widgets for display: remove Splash from all sections (preview only in /dev).
+   * In mock mode only, remove Footer type from footer section (only FooterMenu in footer). Real mode shows all footer widgets.
+   */
+  filterWidgetsForDisplay(widgets, mode) {
+    if (!widgets || typeof widgets !== 'object') return;
+    const isMock = mode !== 'real';
+    Object.keys(widgets).forEach(section => {
+      const list = widgets[section];
+      if (!Array.isArray(list)) return;
+      const filtered = list.filter((w) => {
+        const type = (w.type || '').toLowerCase().trim();
+        if (type === 'splash') return false;
+        if (isMock && section === 'footer' && type === 'footer') return false;
+        return true;
+      });
+      widgets[section] = filtered;
+    });
+  }
+
   /**
    * Enrich widgets with actual data (products, categories, brands)
    * This is essential for product carousels, category lists, etc. to display content
@@ -2345,11 +2382,165 @@ class DevServer {
           enrichedCount++;
           console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${recentProducts.length} recently viewed products`);
         }
+        
+        // Enrich News widgets with items (use existing or default)
+        if (type === 'news') {
+          let items = widget.data.items || widget.data.newsItems || widget.data.content?.items || widget.data.content?.Items;
+          if (!items || !Array.isArray(items) || items.length === 0) {
+            items = this.getDefaultMockNewsItems();
+            enrichedCount++;
+            console.log(`[ENRICH] ${widget.type} (${widget.id}): Added ${items.length} news items`);
+          }
+          widget.data.items = items;
+          widget.data.newsItems = items;
+          widget.data.content = widget.data.content || {};
+          widget.data.content.items = items;
+          widget.data.content.Items = items;
+        }
       });
     });
     
     console.log(`[CONTEXT] ✅ Enriched ${enrichedCount} widgets with data`);
   }
+
+  /**
+   * Enrich a single widget with products, categories, brands, or news items.
+   * Used by /dev/widget/:type so the preview has data without being in context.widgets.
+   */
+  enrichSingleWidget(widget, context) {
+    if (!widget) return;
+    widget.data = widget.data || {};
+    const type = (widget.type || '').toLowerCase();
+    const products = context.products || [];
+    const categories = context.categories || [];
+    const brands = context.brands || [];
+
+    if (type.includes('product') || type === 'featuredproducts' || type === 'bestsellerproducts' || type === 'newproducts' || type === 'simpleproduct' || type === 'singleproduct') {
+      const widgetProducts = this.getProductsForWidget(widget, products);
+      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 = formatted;
+      widget.data.content.Products = formatted;
+    }
+
+    if (type === 'recentlyviewed' || type === 'recently-viewed') {
+      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;
+    }
+
+    if (type.includes('category') || type === 'categorylist' || type === 'categorylistcarousel') {
+      const widgetCategories = categories.slice(0, 10);
+      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;
+    }
+
+    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;
+    }
+
+    if (type === 'news') {
+      let items = widget.data.items || widget.data.newsItems || widget.data.content?.items || widget.data.content?.Items;
+      if (!items || !Array.isArray(items) || items.length === 0) {
+        items = context.mockNewsItems || this.getDefaultMockNewsItems();
+      }
+      widget.data.items = items;
+      widget.data.newsItems = items;
+      widget.data.content = widget.data.content || {};
+      widget.data.content.items = items;
+      widget.data.content.Items = items;
+    }
+  }
+
+  /** Default news items for dev preview when no mock data is present */
+  getDefaultMockNewsItems() {
+    return [
+      { id: 1, title: 'Welcome to Our Store', slug: 'welcome', excerpt: 'Learn about our new collection and special offers.', thumbnailImage: { url: 'https://picsum.photos/seed/n1/400/220' }, publishedAt: new Date().toISOString() },
+      { id: 2, title: 'Summer Sale 2025', slug: 'summer-sale', excerpt: 'Up to 50% off on selected items.', thumbnailImage: { url: 'https://picsum.photos/seed/n2/400/220' }, publishedAt: new Date().toISOString() },
+      { id: 3, title: 'New Arrivals', slug: 'new-arrivals', excerpt: 'Check out the latest products in our catalog.', thumbnailImage: { url: 'https://picsum.photos/seed/n3/400/220' }, publishedAt: new Date().toISOString() },
+      { id: 4, title: 'Tips & Guides', slug: 'tips-guides', excerpt: 'How to get the most from your purchase.', thumbnailImage: { url: 'https://picsum.photos/seed/n4/400/220' }, publishedAt: new Date().toISOString() }
+    ];
+  }
+
+  /**
+   * Build mock context for snippet preview so all snippets have data to render.
+   * Ensures product, collection, cart, news_item, pagination, page, etc. are present.
+   */
+  getSnippetMockContext(snippetName, baseContext) {
+    const ctx = { ...baseContext };
+    const product = ctx.products?.[0] || ctx.product;
+    const collection = ctx.collections?.[0] || ctx.collection || ctx.categories?.[0];
+    const cart = ctx.cart || { items: [], itemCount: 0, total: 0, subTotal: 0 };
+
+    if (product) {
+      ctx.product = this.mode === 'real' ? product : this.enrichProductData(product);
+      if (!ctx.product.prices) {
+        ctx.product.prices = { price: ctx.product.price || 0, mrp: ctx.product.compareAtPrice || 0, priceString: `$${Number(ctx.product.price || 0).toFixed(2)}`, mrpString: ctx.product.compareAtPrice ? `$${Number(ctx.product.compareAtPrice).toFixed(2)}` : '' };
+      }
+      if (!ctx.product.variations && !ctx.product.variants) {
+        ctx.product.variations = [{ id: 1, productId: ctx.product.id, price: ctx.product.price, inStock: true, title: 'Default' }];
+        ctx.product.variants = ctx.product.variations;
+      }
+    } else {
+      const mockProduct = { id: 1, title: 'Sample Product', name: 'Sample Product', handle: 'sample-product', slug: 'sample-product', url: '/products/sample-product', price: 29.99, compareAtPrice: 39.99, imageUrl: 'https://picsum.photos/seed/p1/400/400', thumbnailImage: 'https://picsum.photos/seed/p1/400/400', prices: { price: 29.99, mrp: 39.99, priceString: '$29.99', mrpString: '$39.99' }, variations: [{ id: 1, productId: 1, price: 29.99, inStock: true, title: 'Default' }], variants: null, rating: 4.5, averageRating: 4.5, reviewCount: 12, reviewsCount: 12 };
+      mockProduct.variants = mockProduct.variations;
+      ctx.product = mockProduct;
+    }
+    if (ctx.product && (ctx.product.rating == null && ctx.product.averageRating == null)) {
+      ctx.product.rating = ctx.product.rating ?? 4.5;
+      ctx.product.averageRating = ctx.product.averageRating ?? ctx.product.rating;
+    }
+    if (ctx.product && (ctx.product.reviewCount == null && ctx.product.reviewsCount == null)) {
+      ctx.product.reviewCount = ctx.product.reviewCount ?? 12;
+      ctx.product.reviewsCount = ctx.product.reviewsCount ?? ctx.product.reviewCount;
+    }
+
+    if (collection) {
+      ctx.collection = { ...collection, title: collection.title || collection.name, handle: collection.handle || collection.slug, url: `/categories/${collection.handle || collection.slug}` };
+    } else {
+      ctx.collection = { id: 1, title: 'Sample Collection', name: 'Sample Collection', handle: 'sample', slug: 'sample', url: '/categories/sample' };
+    }
+
+    ctx.cart = cart && typeof cart === 'object' ? cart : { items: [], itemCount: 0, total: 0, subTotal: 0 };
+    if (!ctx.cart.items) ctx.cart.items = [];
+    if (ctx.cart.items.length === 0 && ctx.product) {
+      ctx.cart.items = [{ id: '1', productId: ctx.product.id, title: ctx.product.title || ctx.product.name, quantity: 1, price: ctx.product.price, image: ctx.product.imageUrl || ctx.product.thumbnailImage }];
+      ctx.cart.itemCount = 1;
+      ctx.cart.total = ctx.product.price;
+      ctx.cart.subTotal = ctx.product.price;
+    }
+
+    ctx.news_item = ctx.news_item || this.getDefaultMockNewsItems()[0];
+    ctx.pagination = ctx.pagination || { totalPages: 5, currentPage: 1, total: 50, pageSize: 10 };
+    ctx.page = ctx.page || { title: 'Sample Page', handle: 'sample-page' };
+    ctx.article = ctx.article || null;
+    ctx.line_item = ctx.cart.items?.[0] || null;
+    if (ctx.shop && !ctx.shop.currency) ctx.shop.currency = 'USD';
+    if (ctx.shop && !ctx.shop.settings) ctx.shop.settings = { currencySymbol: '$' };
+
+    return ctx;
+  }
   
   /**
    * Check if a product belongs to a category (for collection/category filtering).
@@ -2467,35 +2658,58 @@ class DevServer {
   normalizeProductForRealMode(p) {
     if (!p || typeof p !== 'object') return p;
     const n = { ...p };
+    const apiBase = (process.env.O2VEND_API_BASE_URL || '').replace(/\/$/, '');
+
     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;
+    if (n.Variations != null && n.variations == null) n.variations = n.Variations;
+    if (n.Combinations != null && n.combinations == null) n.combinations = n.Combinations;
+    if (n.Subscriptions != null && n.subscriptions == null) n.subscriptions = n.Subscriptions;
+    if (n.ProductType != null && n.productType == null) n.productType = n.ProductType;
+
+    const resolveImageUrl = (u) => {
+      if (!u || typeof u !== 'string') return u;
+      if (u.startsWith('http://') || u.startsWith('https://') || u.startsWith('//')) return u;
+      if (u.startsWith('/') && apiBase) return apiBase + u;
+      return u;
+    };
 
-    const t1 = n.ThumbnailImage1 || n.thumbnailImage || n.thumbnailImage;
+    const extractUrl = (obj) => {
+      if (!obj) return null;
+      if (typeof obj === 'string') return obj;
+      return obj.url || obj.Url || obj.imageUrl || obj.ImageUrl || obj.fileName || obj.FileName || obj.filePath || obj.FilePath || obj.imagePath || obj.ImagePath || null;
+    };
+
+    const t1 = n.ThumbnailImage1 || n.thumbnailImage1 || n.thumbnailImage;
     if (t1 != null) {
-      const u = typeof t1 === 'string' ? t1 : (t1.url || t1.Url || t1.imageUrl || t1.ImageUrl);
+      const u = resolveImageUrl(extractUrl(t1));
       if (u) {
         n.thumbnailImage = u;
         if (!n.imageUrl) n.imageUrl = u;
       }
     }
 
-    let imgs = n.images || n.Images;
+    let imgs = n.images || n.Images || n.ProductImages || n.productImages;
     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;
+        const u = resolveImageUrl(typeof img === 'string' ? img : extractUrl(img));
+        const a = (typeof img === 'object' ? (img.altText || img.AltText) : null) || n.name || n.title;
         return { url: u || '', altText: a };
       });
     } else {
-      const single = n.imageUrl || n.ImageUrl;
+      const single = resolveImageUrl(n.imageUrl || n.ImageUrl);
       if (single) n.images = [{ url: single, altText: n.name || n.title }];
     }
 
+    if (n.images && n.images.length > 0) {
+      n.featured_image = n.images[0];
+      if (!n.imageUrl) n.imageUrl = n.images[0].url;
+    }
+
     const handle = (n.handle || n.slug || n.id || '').toString().trim();
     const h = handle && handle !== '#' ? handle.toLowerCase() : (n.productId ? String(n.productId) : null);
     if (h) {
@@ -2854,10 +3068,14 @@ class DevServer {
     
     try {
       const templateSlug = this.widgetService.getTemplateSlug(widget.type);
-      const widgetPath = path.join(this.themePath, 'widgets', `${templateSlug}.liquid`);
-      
+      let widgetPath = path.join(this.themePath, 'widgets', `${templateSlug}.liquid`);
       if (!fs.existsSync(widgetPath)) {
-        return `<div class="error">Widget template not found: ${templateSlug}.liquid</div>`;
+        const sharedPath = path.join(this.themePath, 'widgets', 'shared', `${templateSlug}.liquid`);
+        if (fs.existsSync(sharedPath)) {
+          widgetPath = sharedPath;
+        } else {
+          return `<div class="error">Widget template not found: ${templateSlug}.liquid</div>`;
+        }
       }
       
       const widgetContent = fs.readFileSync(widgetPath, 'utf8');
@@ -3099,7 +3317,7 @@ class DevServer {
       </div>
     </header>
 
-    <div class="section">
+    <div class="section" id="templates">
       <h2>📄 Templates <span class="section-count">(${templates.length})</span></h2>
       ${templates.length > 0 ? `
         <div class="file-grid">
@@ -3113,7 +3331,7 @@ class DevServer {
       ` : '<div class="empty">No templates found</div>'}
     </div>
 
-    <div class="section">
+    <div class="section" id="sections">
       <h2>🧩 Sections <span class="section-count">(${sections.length})</span></h2>
       ${sections.length > 0 ? `
         <div class="file-grid">
@@ -3127,7 +3345,7 @@ class DevServer {
       ` : '<div class="empty">No sections found</div>'}
     </div>
 
-    <div class="section">
+    <div class="section" id="widgets">
       <h2>🎯 Widgets <span class="section-count">(${widgets.length})</span></h2>
       ${widgets.length > 0 ? `
         <div class="file-grid">
@@ -3141,7 +3359,7 @@ class DevServer {
       ` : '<div class="empty">No widgets found</div>'}
     </div>
 
-    <div class="section">
+    <div class="section" id="snippets">
       <h2>✂️ Snippets <span class="section-count">(${snippets.length})</span></h2>
       ${snippets.length > 0 ? `
         <div class="file-grid">
@@ -3163,14 +3381,91 @@ class DevServer {
       <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>
+  <script>
+    (function() {
+      var hash = window.location.hash;
+      if (hash) {
+        var el = document.querySelector(hash);
+        if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      }
+    })();
+  </script>
 </body>
 </html>`;
   }
 
+  /**
+   * Return link tags for theme CSS files that exist (so snippet/section preview gets theme styles).
+   * Includes theme, components, sections, and any other .css in assets (e.g. delivery-zone.css).
+   */
+  getThemeCssLinkTags() {
+    const assetsDir = path.join(this.themePath, 'assets');
+    const links = [];
+    const seen = new Set();
+    const add = (base) => {
+      if (seen.has(base)) return;
+      seen.add(base);
+      const minPath = path.join(assetsDir, `${base}.min.css`);
+      const cssPath = path.join(assetsDir, `${base}.css`);
+      if (fs.existsSync(minPath)) {
+        links.push(`<link rel="stylesheet" href="/assets/${base}.min.css">`);
+      } else if (fs.existsSync(cssPath)) {
+        links.push(`<link rel="stylesheet" href="/assets/${base}.css">`);
+      }
+    };
+    ['theme', 'components', 'sections'].forEach(add);
+    if (fs.existsSync(assetsDir)) {
+      try {
+        fs.readdirSync(assetsDir)
+          .filter((f) => f.endsWith('.css') && !f.endsWith('.min.css'))
+          .forEach((f) => add(f.replace(/\.css$/, '')));
+      } catch (_) { /* ignore */ }
+    }
+    return links.join('\n  ');
+  }
+
   /**
    * Generate preview page HTML
    */
-  generatePreviewPage({ title, content, type, name, backUrl }) {
+  generatePreviewPage({ title, content, type, name, backUrl, includeThemeCss = false }) {
+    const themeCssLinks = includeThemeCss ? this.getThemeCssLinkTags() : '';
+    const modalSnippets = ['login-modal', 'delivery-zone-modal', 'add-to-cart-modal'];
+    const isModalSnippet = type === 'snippet' && name && modalSnippets.includes(name);
+    const modalVisibilityCss = isModalSnippet ? `
+    /* Force modal visible in /dev snippet preview (no trigger to open; overrides [aria-hidden="true"] { display: none }) */
+    .preview-container .login-modal,
+    .preview-container .login-modal[aria-hidden="true"],
+    .preview-container .login-modal.login-modal--active {
+      display: flex !important;
+      align-items: center;
+      justify-content: center;
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      visibility: visible !important;
+    }
+    .preview-container .delivery-zone-modal,
+    .preview-container .delivery-zone-modal[aria-hidden="true"],
+    .preview-container .delivery-zone-modal.active {
+      display: flex !important;
+      align-items: center;
+      justify-content: center;
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      visibility: visible !important;
+    }
+    .preview-container .add-to-cart-modal,
+    .preview-container .add-to-cart-modal[aria-hidden="true"] {
+      display: flex !important;
+      align-items: center;
+      justify-content: center;
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      visibility: visible !important;
+    }
+    ` : '';
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -3178,7 +3473,7 @@ class DevServer {
   <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>
+  ${themeCssLinks ? `  ${themeCssLinks}\n  ` : ''}<style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     :root {
       --o2vend-primary: #F9A825;
@@ -3251,6 +3546,7 @@ class DevServer {
       border-radius: 6px;
       color: #c62828;
     }
+    ${modalVisibilityCss}
   </style>
 </head>
 <body>

package/lib/lib/liquid-engine.js

@@ -233,9 +233,11 @@ function registerCustomTags(liquid, themePath) {
         if (widget.template_path) {
           const widgetPath = path.join(themePath, `${widget.template_path}.liquid`);
           const altPath = path.join(themePath, widget.template_path);
+          const baseName = (widget.template_path.replace(/^widgets\//, '').replace(/\.liquid$/, '') || widget.template_path).split('/').pop();
+          const sharedPath = path.join(themePath, 'widgets', 'shared', `${baseName}.liquid`);
           
           const finalPath = fs.existsSync(widgetPath) ? widgetPath : 
-                           (fs.existsSync(altPath) ? altPath : null);
+                           (fs.existsSync(altPath) ? altPath : (fs.existsSync(sharedPath) ? sharedPath : null));
           
           if (finalPath) {
             const fullContext = currentRenderingContext