webcake-storefront-mcp 1.33.2 → 1.34.0

package/dist/api.js

@@ -9,6 +9,7 @@ export class WebcakeCmsApi {
     sessionId;
     _adminToken;
     _cmsApiKey;
+    _siteBps = null;
     constructor({ baseUrl, token, siteId, sessionId }) {
         this.baseUrl = (baseUrl || "").replace(/\/$/, "");
         this.token = token;
@@ -101,6 +102,28 @@ export class WebcakeCmsApi {
         this.siteId = siteId;
         this._adminToken = null;
         this._cmsApiKey = null;
+        this._siteBps = null;
+    }
+    // ── Section template library (designer-made blocks behind the editor's template picker) ──
+    listTemplateCategories() {
+        return this.request("GET", `/api/v1/templates/categories`);
+    }
+    /** Templates (each { id, name, thumbnail, source: JSON string of ONE node, usually a SECTION }).
+     *  Query: id = category id (omit for all), term, page, limit. */
+    listTemplates(query = {}) {
+        return this.request("GET", `/api/v1/templates`, { query });
+    }
+    /** The site's breakpoints ({ bpN: [minW, maxW] } from settings, which may be a JSON string),
+     *  or null when unset/unreadable — callers then use the standard four. Cached per site. */
+    getSiteBreakpoints() {
+        this._siteBps ??= this.getSite()
+            .then((res) => {
+            const site = res?.data ?? res;
+            const settings = typeof site?.settings === "string" ? JSON.parse(site.settings || "{}") : site?.settings;
+            return settings?.breakpoints || null;
+        })
+            .catch(() => null);
+        return this._siteBps;
     }
     /** Update auth token (in-memory) */
     switchToken(token) {

package/dist/builder/attributes.js

@@ -23,7 +23,7 @@ export const SHARED_SPECIALS = {
     element_async: "Mark the element async/lazy (advanced — usually leave unset).",
     event_name_custom: "Custom analytics event name fired on interaction.",
     tabIndex: "Bind this element to a tab item (TAB-ITEM-…) so a tabs element shows/hides it.",
-    text_animation_type: "Entrance animation for the element's text (none|…).",
+    text_animation_type: "Animated words in text/button: set to the type used by the <span class=\"animationText\" data-type …> inside specials.text (typed|typed2|clip|rotate3|animate.css name). See get_build_guide → Motion.",
 };
 // Generic layout keys every node's runtime.config may carry (documented in the build
 // guide); listed here so describeAttributes can flag them as 'generic, not element-specific'.
@@ -48,7 +48,7 @@ export const SHARED_KEY_DICT = {
     src: "Media URL (hosted).",
     image_alt: "Alt text (SEO / accessibility).",
     typographyTheme: "Apply a site typography preset.",
-    text_animation_type: "Text entrance animation.",
+    text_animation_type: "Animated-words type (typed|typed2|clip|rotate3|…), paired with an animationText span in the text.",
     marker: "List marker style (none/dotList/numberList/imageList).",
     tabIndex: "Tab/focus order.",
     shapeType: "Shape kind (rectangle/etc.).",
@@ -157,7 +157,7 @@ export const ELEMENT_ATTRS = {
     "video-dataset": { specials: { autoRotateInMobile: "Rotate to landscape on mobile (boolean).", show_list_video_lesson: "Show the lesson playlist (boolean).", show_next_video_lesson: "Show the next-lesson button (boolean)." }, events: "none", bindings: ["lesson::lesson_video"], notes: "Video bound to a dataset field (course lesson video)." },
     rectangle: {
         specials: { shapeType: "Shape kind.", custom_css: "Raw CSS for the shape." },
-        config: { mask: "Mask SVG/shape (clips the box into an icon).", maskId: "Mask reference.", custom_mask: "Custom mask SVG markup.", fixedPosition: "Pin/float the shape (bottom_right|…) — e.g. a floating badge.", animation: "Entrance animation." },
+        config: { mask: "Mask SVG/shape (clips the box into an icon).", maskId: "Mask reference.", custom_mask: "Custom mask SVG markup.", fixedPosition: "With position:'pinned' (+ style.position:'fixed'): where it floats — bottom_right|bottom_left|top_right|… — e.g. a floating badge. See get_build_guide → Sticky & pinned.", animation: "Entrance/attention animation { type, delay, duration, repeat }: type = animate.css name (fadeInUp, zoomIn, bounceIn, pulse…), delay/duration in s, repeat 1|2|3|'infinite'. See get_build_guide → Motion." },
         events: "click, hover — often used as a clickable card/background.",
         notes: "Coloured box / divider / background. Style via runtime.style (background, border*, boxShadow).",
     },
@@ -178,7 +178,7 @@ export const ELEMENT_ATTRS = {
         events: "none",
         notes: "Top-level band; centred 3-column grid. Children go in the centre column (new_section handles this). Make a header section sticky with config.stickyPosition; add a video/pattern background via config.",
     },
-    container: { specials: { tabIndex: "Tab order.", custom_class: "CSS class.", custom_css: "Raw CSS." }, config: { maxWidth: "Max width.", maxWidthUnit: "Max-width unit.", fixedPosition: "Float/pin the box (e.g. bottom_right) — for back-to-top / chat bubbles.", fixedRight: "Pinned offset from right (px).", fixedBottom: "Pinned offset from bottom (px).", fixedLeft: "Pinned offset from left (px).", stickyPosition: "Sticky mode.", stickyTop: "Sticky offset from top (px).", stickyBottom: "Sticky offset from bottom (px).", pinnedPoint: "Section id where pinning starts.", unpinnedPoint: "Section id where pinning ends.", useAutoScroll: "Auto-scroll the box (boolean).", initMaxHeight: "Collapsed max-height (px).", isUseInitMaxHeight: "Animate from initMaxHeight (boolean).", maxHeight: "Expanded max-height (px).", animation: "Entrance animation." }, events: "click, hover — clickable groups are common.", notes: "Generic grid box; nest children with their own grid. Pin a floating button/sidebar via config.fixedPosition; sticky filters via stickyTop + pinnedPoint/unpinnedPoint." },
+    container: { specials: { tabIndex: "Tab order.", custom_class: "CSS class.", custom_css: "Raw CSS." }, config: { maxWidth: "Max width.", maxWidthUnit: "Max-width unit.", fixedPosition: "Float/pin the box (e.g. bottom_right) — for back-to-top / chat bubbles.", fixedRight: "Pinned offset from right (px).", fixedBottom: "Pinned offset from bottom (px).", fixedLeft: "Pinned offset from left (px).", stickyPosition: "Sticky mode.", stickyTop: "Sticky offset from top (px).", stickyBottom: "Sticky offset from bottom (px).", pinnedPoint: "Section id where pinning starts.", unpinnedPoint: "Section id where pinning ends.", useAutoScroll: "Auto-scroll the box (boolean).", initMaxHeight: "Collapsed max-height (px).", isUseInitMaxHeight: "Animate from initMaxHeight (boolean).", maxHeight: "Expanded max-height (px).", animation: "Entrance/attention animation { type, delay, duration, repeat }: type = animate.css name (fadeInUp, zoomIn, bounceIn, pulse…), delay/duration in s, repeat 1|2|3|'infinite'. See get_build_guide → Motion." }, events: "click, hover — clickable groups are common.", notes: "Generic grid box; nest children with their own grid. Pin a floating button/sidebar via config.fixedPosition; sticky filters via stickyTop + pinnedPoint/unpinnedPoint." },
     row: { events: "none", notes: "Simple horizontal wrapper." },
     tabs: { specials: { activeTab: "Default active tab index.", tabs: "Tab definitions [{id,name}].", navMode: "How tabs switch: toggle | …", showNav: "Show the tab nav (boolean).", showBullet: "Show bullets (boolean).", showDivider: "Show a divider (boolean)." }, config: { navPosition: "top|left|right|bottom.", alignNav: "Nav alignment.", nav_display_style: "Nav style." }, events: "tab — fires when the active tab changes.", notes: "Tabbed container; each tab maps to a tab item the content reacts to (e.g. account panels, product detail/description/reviews)." },
     collapse: { events: "none", notes: "Accordion container (collapse-item children)." },
@@ -288,7 +288,10 @@ export const ELEMENT_ATTRS = {
     "grid-category": { specials: { showCategories: "Categories to show [{id,...}] (else all).", isAutoCatchMenuLevelFirst: "Auto-pick top-level categories (boolean)." }, config: { columns: "Categories per row.", minimum_card_width: "Min card width (autofit, px).", sizeThumbnail: "{width,height} of the category image.", responsive: "fixed | autofit.", imageBorderRadius: "Image radius (px).", cardBackground: "Card background.", cardBorderRadius: "Card radius.", name_padding_y: "Padding around the name." }, events: "none", notes: "Lists product categories. Create categories first (create_product_category)." },
     "slider-category": { specials: { showCategories: "Categories to show [{id,...}].", on_hover: "Card hover effect (zoom-in|…)." }, config: { columns: "Visible categories.", minimum_card_width: "Min card width (px).", sizeThumbnail: "{width,height} of the image.", imageBorderRadius: "Image radius.", navSize: "Arrow size (px).", arrowColor: "Arrow colour." }, events: "none" },
     "customer-address": { events: "none", bindings: ["customer_address::full_name", "customer_address::address", "customer_address::phone_number", "customer_address::pdc", "customer_address::is_default"], notes: "Member saved addresses." },
-    wishlist: { specials: { svg: "Icon SVG.", itemCount: "Badge count." }, config: { itemCountColor: "Badge text colour.", itemBackgroundColor: "Badge background.", itemCountFontSize: "Badge size.", itemCountFontWeight: "Badge weight.", itemCountBorderRadius: "Badge radius.", itemCountFontFamily: "Badge font." }, events: "click — opens the wishlist." },
+    wishlist: { specials: { svg: "Icon SVG.", itemCount: "Badge count." }, config: { itemCountColor: "Badge text colour.", itemBackgroundColor: "Badge background.", itemCountFontSize: "Badge size.", itemCountFontWeight: "Badge weight.", itemCountBorderRadius: "Badge radius.", itemCountFontFamily: "Badge font." }, events: "No built-in click: add an open_page event to your wishlist page (one holding a wishlist-container)." },
+    "wishlist-container": { notes: "Wishlist page block (store page). Children: ONE wishlist-item (template, repeated per saved product) + ONE wishlist-empty (shown when none). Editor default item = row of image-dataset (wishlist_item::product_image) | text-dataset name + price | button with event wishlist_remove_item; empty = text + button open_page back to the shop." },
+    "wishlist-item": { notes: "Per-product template inside wishlist-container — bind children to wishlist_item::product_name / product_price / product_original_price / product_image / product_short_description; a button with action wishlist_remove_item removes the product." },
+    "wishlist-empty": { notes: "Empty state inside wishlist-container (e.g. 'Chưa có sản phẩm yêu thích' + a button open_page to the shop)." },
     "favorite-icon": { config: { mask: "Heart icon SVG mask.", colorActive: "Colour when favourited." }, events: "click — toggle favourite (add_wishlist_product / wishlist_remove_item).", notes: "Heart toggle on a product card; pairs with the wishlist element in the header." },
     "bonus-items": { specials: { typeBonus: "combo_product | other." }, events: "none" },
     // ── navigation ──

package/dist/builder/bindings.js

@@ -41,6 +41,16 @@ export const BINDING_DATASETS = {
         summary: "Sale/discount badge overlaid on a product card.",
         fields: ["product-overlay::product_sale", "product-overlay::product_discount", "product-overlay::product_total_sold", "product-overlay::product_url"],
     },
+    wishlist_item: {
+        name: "wishlist_item",
+        page_type: "store",
+        repeater_parents: ["wishlist-item"],
+        summary: "A product the shopper saved to their wishlist (children of wishlist-item).",
+        fields: [
+            "wishlist_item::product_name", "wishlist_item::product_price", "wishlist_item::product_original_price",
+            "wishlist_item::product_image", "wishlist_item::product_short_description",
+        ],
+    },
     cart_item: {
         name: "cart_item",
         page_type: "store",
@@ -292,7 +302,7 @@ export function describeBindingsCatalog() {
     return {
         note: "Dataset elements (text-dataset/image-dataset/…) and children of a repeater (grid-product, cart-items, post-list…) carry bindings:[{ id, name, target, ...meta }]. Build via new_element opts.bindings (ids auto-minted) — e.g. new_element('text-dataset',{ bindings:[{ target:'product::product_price', show_tax:true }] }). A target only resolves on a page whose type enables its dataset (store→use_store, member→use_member, blog→use_blog) — build_page handles the flag. The optional meta keys (name_style, prefix_content, value, attr_id, …) control HOW the value renders/combines — see meta_keys.",
         meta_keys: BINDING_META_KEYS,
-        page_type_required: { store: ["product", "product-overlay", "cart_item", "order", "order_item", "category", "bonus_item", "promotion_item", "attr", "search_result"], member: ["customer", "customer_address"], blog: ["post", "blog"], any: ["form", "general_info", "agency"] },
+        page_type_required: { store: ["product", "product-overlay", "cart_item", "wishlist_item", "order", "order_item", "category", "bonus_item", "promotion_item", "attr", "search_result"], member: ["customer", "customer_address"], blog: ["post", "blog"], any: ["form", "general_info", "agency"] },
         repeater_context: REPEATER_CONTEXT,
         datasets: Object.values(BINDING_DATASETS).map((ds) => ({
             name: ds.name,

package/dist/builder/catalog.js

@@ -59,7 +59,7 @@ const CATEGORY_MEMBERS = {
         "detect-address", "postal-code", "country", "input-file", "input-number",
         "input-date", "input-search", "input-product-note", "otp-input", "rating-input",
         "two-point-range", "identity", "search-form", "search-droppable", "color-group",
-        "switch",
+        "switch", "otp-method",
     ],
     commerce: [
         "grid-product", "slider-product", "product-gallery", "product-image-carousel",
@@ -69,7 +69,7 @@ const CATEGORY_MEMBERS = {
         "bonus-items", "flash-sale", "promotions", "promotions-short", "grid-category",
         "slider-category", "number-step", "warehouse", "warehouse-dataset",
         "customer-address", "reward-point", "referral-code", "lucky-wheel", "tee-form",
-        "wishlist", "favorite-icon",
+        "wishlist", "favorite-icon", "wishlist-container", "wishlist-item", "wishlist-empty",
     ],
     navigation: [
         "menu", "menu-item", "menu-anchor-item", "submenu", "menu-droppable", "member-bar",
@@ -84,6 +84,7 @@ const CATEGORY_MEMBERS = {
     ],
     course: [
         "lesson-sidebar", "lesson-items", "next-lesson-droppable", "list-lesson-droppable",
+        "list-courses",
     ],
 };
 const CATEGORY_BY_TYPE = {};
@@ -122,6 +123,9 @@ const SUMMARY = {
     "grid-product": "Product grid (lists products from the store).",
     "slider-product": "Product slider/carousel.",
     "cart-items": "Shopping cart line items.",
+    "wishlist-container": "Wishlist page list: holds a wishlist-item template + a wishlist-empty state.",
+    "wishlist-item": "Template repeated per saved product (bind children to wishlist_item::…).",
+    "wishlist-empty": "Shown instead of the items when the wishlist is empty.",
     "cart-icon": "Cart icon with item count.",
     "quantity-input": "Quantity stepper for products.",
     payment: "Payment methods block.",

package/dist/builder/events.js

@@ -92,6 +92,21 @@ export const EVENT_ACTIONS = [
     { action: "lightbox", trigger: "click", category: "media", summary: "Open an image in a lightbox.", optional: ["lightboxLink"] },
     { action: "set_address_default", trigger: "click", category: "account", summary: "Mark a saved address as the default." },
     { action: "change_avatar", trigger: "click", category: "account", summary: "Change the member avatar." },
+    // From builderx_spa EventSetting.vue actions(); handled in the renderer (events.js, or
+    // common.ex / swiper.js / form.js / lesson-sidebar.js where noted).
+    { action: "filter", trigger: "click", category: "ui", summary: "Apply the product filters listed in `filters` (filter element ids; their selections become URL params) — e.g. an 'Apply' button on a filter panel. and_filters must all be chosen, or_filters at least one. redirect_type page|category (+ page_id / category_id) sends the shopper to that listing.", required: ["filters"], optional: ["and_filters", "or_filters", "or_filter_is_select_only_one", "product_id_auto_redirect", "redirect_type", "page_id", "category_id"], target_in_page: ["filters", "and_filters", "or_filters"] },
+    { action: "change_language", trigger: "click", category: "navigation", summary: "Language switcher: reopen the current page/product/category in another language. change_language = target language code (e.g. 'en').", required: ["change_language"] },
+    { action: "change_text_style", trigger: "click", category: "content", summary: "Restyle another text element (e.g. highlight the active option). text_style = style object.", required: ["target_id", "text_style"], target_in_page: ["target_id"] },
+    { action: "open_product_link", trigger: "click", category: "navigation", summary: "Open one of the product's custom links (target_custom_links = 1-based index), else default_url. target_href _self|_blank.", optional: ["target_custom_links", "default_url", "target_href"] },
+    { action: "add_bonus_product_to_cart", trigger: "click", category: "cart", summary: "Add a promotion's bonus/gift product to the cart (button inside a promotion bonus item).", optional: ["open_page", "productNoteElId"] },
+    { action: "send_botcake_mess", trigger: "click", category: "contact", summary: "Open a Botcake chatbot conversation.", required: ["botcake_ref_url"] },
+    { action: "delete_customer_address", trigger: "click", category: "account", summary: "Delete this saved address (inside a customer-address list on the member profile page)." },
+    { action: "course_submit", trigger: "click", category: "form", summary: "Submit a course assignment (uploads files). The customer must be logged in and have bought the course." },
+    { action: "auto_next_track", trigger: "click", category: "media", summary: "Course lesson sidebar switch: when on, auto-play the next lesson after a video ends (lesson-sidebar.js)." },
+    { action: "play_video", trigger: "tab", category: "media", summary: "When a slider reaches slide target_slide (1-based), play video element target_video (swiper.js).", required: ["target_slide", "target_video"], target_in_page: ["target_video"] },
+    { action: "close_search_droppable", trigger: "onenter", category: "ui", summary: "Close the search suggestions dropdown when Enter is pressed in the search box." },
+    { action: "bold", trigger: "hover", category: "hover", summary: "Make the text bold on hover (common.ex)." },
+    { action: "create_article", trigger: "submit", category: "form", summary: "Form submit creates a blog article from the form fields — user-submitted posts (form.js)." },
 ];
 const ACTION_BY_NAME = {};
 for (const a of EVENT_ACTIONS)
@@ -169,9 +184,9 @@ export function validateEvents(node, allIds) {
                 warnings.push(`Event "${ev.action}" on "${where}" is missing required field "${f}".`);
         }
         for (const f of def.target_in_page || []) {
-            const v = ev[f];
-            if (v && !allIds.has(v))
-                warnings.push(`Event "${ev.action}" on "${where}" targets missing element "${v}" (field ${f}).`);
+            for (const v of [].concat(ev[f] ?? [])) // a field may hold one id or a list (filter's filters)
+                if (v && !allIds.has(v))
+                    warnings.push(`Event "${ev.action}" on "${where}" targets missing element "${v}" (field ${f}).`);
         }
     }
     return { errors, warnings };

package/dist/builder/factory.js

@@ -528,6 +528,22 @@ export const createWishlist = ({ svg, itemCount, config, children, style } = {})
         wistlist.children = children || [];
     return wistlist;
 };
+// Wishlist page blocks. The editor has no factory for these (it seeds them from
+// common/wishlist-container.json); the renderer clones the wishlist-item <template> once per
+// saved product (assets/render/wishlist-container.js) and shows wishlist-empty when there are none.
+const plainContainer = (prefix, type) => (opts = {}) => {
+    const el = cloneDeep(SKELETON);
+    el.id = prefix + randomString(8);
+    el.type = type;
+    el.runtime.style = { ...opts.style };
+    el.runtime.config = { ...opts.config };
+    el.children = opts.children || [];
+    el.specials = { ...opts.specials };
+    return el;
+};
+export const createWishlistContainer = plainContainer('WISHLIST-CONTAINER-', 'wishlist-container');
+export const createWishlistItem = plainContainer('WISHLIST-ITEM-', 'wishlist-item');
+export const createWishlistEmpty = plainContainer('WISHLIST-EMPTY-', 'wishlist-empty');
 export const createFavoriteIcon = (opts = {}) => {
     const favorite = cloneDeep(SKELETON);
     favorite.id = 'FAVORITE-ICON-' + randomString(8);
@@ -1763,3 +1779,24 @@ export const createLessonItems = (opts = {}) => {
     nextlesson.specials = { ...opts.specials };
     return nextlesson;
 };
+// Ported from builderx_spa factory.js (4ea6dd53e, e107a53e5).
+export const createOtpMethod = (opts = {}) => {
+    const otpMethod = cloneDeep(SKELETON);
+    otpMethod.id = 'OTP-METHOD-' + randomString(8);
+    otpMethod.type = 'otp-method';
+    otpMethod.children = opts.children || [];
+    otpMethod.runtime.style = { ...opts.style };
+    otpMethod.runtime.config = { ...opts.config };
+    otpMethod.specials = { ...opts.specials };
+    return otpMethod;
+};
+export const createListCourses = (opts = {}) => {
+    const el = cloneDeep(SKELETON);
+    el.id = 'LIST-COURSES-' + randomString(8);
+    el.type = 'list-courses';
+    el.runtime.style = { ...opts.style };
+    el.runtime.config = { ...opts.config };
+    el.children = opts.children || [];
+    el.specials = { ...opts.specials };
+    return el;
+};

package/dist/builder/guide.js

@@ -4,7 +4,9 @@ export const BUILD_GUIDE = `# BuilderX page authoring guide
 
 ## DESIGN SYSTEM — lock this FIRST, every build (this is what makes free composition look DESIGNED)
 There are NO page templates here and NO seeded data — you COMPOSE every page from elements
-based on the user's actual goal. To make that composition look intentional (not a random pile
+based on the user's actual goal. (One optional shortcut: a single section may start from the
+designer section library — list_section_templates → add_section({ template }) — then restyle it
+to the locked system below.) To make that composition look intentional (not a random pile
 of default elements), LOCK a small design system before you place anything, and reuse it on
 EVERY section and EVERY page:
 - PALETTE — from the site THEME matrix vars \`var(--color_RC)\` (see Colours below). Pick: page
@@ -347,7 +349,7 @@ create the globals — they embed into each page's source. If you later overwrit
 (delete_global_section by the section NODE id, then create once) to re-embed cleanly. Edit a global
 later with update_global_section_element(s) and it updates on every page at once.
 
-STICKY & PINNED (runtime.config, on a section or any element):
+STICKY & PINNED (runtime.config, on a section or a text/image/button/shape/container element):
   position:"sticky"  sticks while scrolling — the usual sticky header: the header section gets
                      { position:"sticky", stickyPosition:"autotop", stickyTop:0 }. stickyPosition:
                      autotop (default) | autobottom | default (both); offsets stickyTop / stickyBottom (px).
@@ -357,6 +359,23 @@ STICKY & PINNED (runtime.config, on a section or any element):
                      fixedTop / fixedLeft / fixedRight / fixedBottom (px, default 20).
   Anything else (or unset) = normal flow. stickyPosition alone does nothing without position:"sticky".
 
+MOTION (text, image, button, shape, container) — tasteful: one entrance per block, short delays:
+  runtime.config.animation = { type:"fadeInUp", delay:0.2, duration:1, repeat:1 }   // seconds; repeat 1|2|3|"infinite"
+  type = an animate.css name: fadeIn / fadeInUp / fadeInLeft / zoomIn / bounceIn / backInUp / slideInUp /
+  flipInX … (attention seekers pulse / heartBeat / tada / shakeX — "infinite" only on one small CTA).
+  Stagger a row of cards with delay 0, 0.15, 0.3 … so they cascade in.
+  ANIMATED WORDS (typing / rotating headline, text or button): wrap the words in specials.text with
+    <span class="animationText" data-type="typed" data-word="Cà phê\\nBánh ngọt\\nTrà sữa"
+          data-delay="0" data-duration="1" data-repeat="infinite">Cà phê</span>
+  and set specials.text_animation_type to the same type. data-type: typed | typed2 | clip | rotate3 (or an
+  animate.css name); data-word = the words to cycle, one per line.
+  HOVER feedback is an event: { eventName:"hover", action:"scale" | "transform_y" | "change_background" |
+  "change_text_color" | "bold" …, duration:0.2 } (duration = transition seconds, default 0.1).
+
+TYPOGRAPHY PRESETS: the theme defines 9 text styles — use them so text follows the site theme:
+  style:{ font:"var(--font_N)", color:"var(--font_color_N)" }  N: 0-5 = H1-H6, 6-8 = paragraph large/normal/small.
+  Don't also set fontSize/fontWeight/fontFamily on that node (they'd override the preset).
+
 ### HEADER must be RESPONSIVE — add a MOBILE MENUBAR, don't just let nav stack
 A header built as one horizontal row of nav links looks fine on desktop but on a phone the links
 squash or collapse into an ugly vertical pile. Build a header that carries TWO navs and swap them

package/dist/builder/page.js

@@ -4,11 +4,11 @@
 // their children in a CSS grid driven by runtime.config (grid / columns / rows) and each
 // child's runtime.config (columnStart/End, rowStart/End, constraintX/Y). The helpers here
 // produce that structure the same way the builder does, so generated pages render.
-import { buildElement, isKnownType, ELEMENT_TYPES } from "./catalog.js";
+import { buildElement, isKnownType, ELEMENT_TYPES, CONTAINER_TYPE_SET } from "./catalog.js";
 import { randomString } from "./factory.js";
 import { validateEvents } from "./events.js";
 import { validateBindings } from "./bindings.js";
-import { BREAKPOINTS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
+import { BREAKPOINTS, BREAKPOINT_KEYS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
 const clone = (o) => structuredClone(o);
 /** Parse a CSS px length ("52px") or a bare number (52) → number, else null. */
 function pxToNum(v) {
@@ -349,6 +349,25 @@ export function validatePage(source) {
             warnings.push(...r.warnings);
         }
     });
+    // Third pass (needs ancestry): structures the renderer silently mishandles. Warnings only.
+    const checkTree = (node, ancestors) => {
+        if (!node || typeof node !== "object")
+            return;
+        const type = node.type;
+        const kids = Array.isArray(node.children) ? node.children : [];
+        if (!ancestors.length && type && type !== "section" && type !== "popup")
+            warnings.push(`Top-level node "${node.id}" is a ${type}: pages render only sections at the top level — wrap it in a section.`);
+        if (kids.length && type && isKnownType(type) && !CONTAINER_TYPE_SET.has(type))
+            warnings.push(`"${node.id}" (${type}) has ${kids.length} child node(s), but ${type} is not a container — they won't render.`);
+        if (type === "submit-button" && !ancestors.some((t) => /form/.test(t)))
+            warnings.push(`Submit button "${node.id}" is not inside a form — it has nothing to submit.`);
+        if ((node.bindings || []).some((b) => b?.name === "wishlist_item") && !ancestors.includes("wishlist-item"))
+            warnings.push(`"${node.id}" binds wishlist_item::… outside a wishlist-item — those fields only resolve per saved product.`);
+        for (const c of kids)
+            checkTree(c, [...ancestors, type]);
+    };
+    for (const s of source.sections)
+        checkTree(s, []);
     return {
         valid: errors.length === 0,
         ...(errors.length ? { errors } : {}),
@@ -356,15 +375,39 @@ export function validatePage(source) {
         stats: { sections: source.sections.length, total_elements: total, element_types: typeCounts },
     };
 }
-/**
- * Expand one node's `runtime.{style,config}` into the per-breakpoint keys the storefront
- * renderer reads (bp1..bp4). Mirrors builderx_spa's syncBreakpoint: the authored
- * (desktop) values are copied onto every breakpoint. Sections additionally get their
- * centred 3-column grid recomputed per breakpoint via genGridByBp (the side-margin
- * widths shrink on smaller screens). Nodes already in breakpoint shape are left as-is,
- * so this is safe to run over a mixed source (e.g. add_section onto an existing page).
- */
-function expandNodeToBreakpoints(node) {
+/** The site's breakpoints if they're a usable map that differs from the standard four, else null. */
+function customBreakpoints(site) {
+    if (!site || typeof site !== "object")
+        return null;
+    const entries = Object.entries(site);
+    if (!entries.length || !entries.every(([, r]) => Array.isArray(r) && typeof r[0] === "number" && typeof r[1] === "number"))
+        return null;
+    const standard = entries.length === BREAKPOINT_KEYS.length &&
+        entries.every(([k, [lo, hi]]) => BREAKPOINTS[k] && BREAKPOINTS[k][0] === lo && BREAKPOINTS[k][1] === hi);
+    return standard ? null : site;
+}
+/** Re-key a freshly expanded node from bp1..bp4 onto the site's breakpoints. The renderer emits
+ *  CSS only for the site's keys, and users can split/delete breakpoints in the editor (a split
+ *  of bp1 at 1600 gives bp1:[1320,1600] + bp5:[1601,1e9]; a deleted name can be reused for a
+ *  different range) — so match by WIDTH, never by name: each site breakpoint takes the standard
+ *  breakpoint containing its min width; sections regenerate their grid for that width. */
+function remapToSiteBreakpoints(node, site) {
+    const std = Object.entries(BREAKPOINTS);
+    const pick = (minW) => (std.find(([, [lo, hi]]) => minW >= lo && minW <= hi) || std[std.length - 1])[0];
+    const out = {};
+    for (const [key, [minW]] of Object.entries(site)) {
+        const from = node[pick(minW)];
+        if (!from)
+            continue;
+        out[key] = clone(from);
+        if (node.type === "section")
+            out[key].config.columns = clone(genGridByBp(minW).columns);
+    }
+    for (const k of BREAKPOINT_KEYS)
+        delete node[k];
+    Object.assign(node, out);
+}
+function expandNodeToBreakpoints(node, site) {
     const rt = node && node.runtime;
     if (rt && (rt.style || rt.config || rt.responsive)) {
         const baseConfig = { ...(rt.config || {}), loaded: true };
@@ -429,9 +472,11 @@ function expandNodeToBreakpoints(node) {
             node[bp] = { style, config };
         }
         delete node.runtime;
+        if (site)
+            remapToSiteBreakpoints(node, site);
     }
     for (const child of node.children || [])
-        expandNodeToBreakpoints(child);
+        expandNodeToBreakpoints(child, site);
     return node;
 }
 /**
@@ -440,10 +485,11 @@ function expandNodeToBreakpoints(node) {
  * is removed. MUST be called before saving a page built with new_section/new_element —
  * otherwise the page renders with no styling or grid placement.
  */
-export function finalizeForRender(source) {
+export function finalizeForRender(source, siteBreakpoints) {
     const sections = source && Array.isArray(source.sections) ? source.sections : [];
+    const custom = customBreakpoints(siteBreakpoints);
     for (const s of sections)
-        expandNodeToBreakpoints(s);
+        expandNodeToBreakpoints(s, custom);
     return source;
 }
 export { ELEMENT_TYPES };

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.34.0",
+    "d": "14/10/2026",
+    "type": "Added",
+    "en": "New list_section_templates tool browses the designer-made section template library (categories, search by term, thumbnails) for starting a section…",
+    "vi": "Tool mới list_section_templates để duyệt thư viện mẫu section do designer tạo (theo danh mục, tìm kiếm bằng term, có thumbnail) làm điểm khởi đầu…"
+  },
   {
     "v": "1.33.2",
     "d": "14/10/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "create_product, update_product, create_product_category, update_product_category, and create_blog_category accept a new seo object to write…",
     "vi": "create_product, update_product, create_product_category, update_product_category và create_blog_category nay nhận thêm đối tượng seo để ghi…"
-  },
-  {
-    "v": "1.31.12",
-    "d": "09/10/2026",
-    "type": "Added",
-    "en": "create_article and update_article accept a new seo object (page_title, meta_description, page_keywords, og_title, og_description, og_image) that…",
-    "vi": "create_article và update_article nay nhận thêm đối tượng seo (page_title, meta_description, page_keywords, og_title, og_description, og_image) để…"
   }
 ]

package/dist/server.js

@@ -20,7 +20,7 @@ Tool discovery: the common tools (pages, builder, products, orders, blog, custom
 
 You can also BUILD pages: use get_build_guide, list_elements, get_element to learn the BuilderX component model, new_section/new_element to compose, validate_page to check, then build_page (dry_run first) to create. Publishing is site-level via publish_site.
 
-Build the WHOLE site by FREE COMPOSITION FROM ELEMENTS — there are NO page templates and NO seeded data. You compose every page from elements (new_section/new_element/new_row → build_page) based on the user's actual goal. Enrich EVERY page (home, category, product detail, cart, checkout, thank-you, …) to the same e-commerce standard with the same palette/header/footer. Make the Header and Footer GLOBAL (create_global_section type:"header"/"footer") so they're consistent on every page — don't inline them per page. For newsletter/promo offers, build a popup node (new_element "popup") and save it via create_global_source({component:"popup"}), then open it with an open_popup event. See get_build_guide for the design system, the per-page section archetypes, the global-section order rules, and the popup workflow.
+Build the WHOLE site by FREE COMPOSITION FROM ELEMENTS — there are NO page templates and NO seeded data (a single section MAY start from the designer section library: list_section_templates → add_section({ template }), restyled to the brand). You compose every page from elements (new_section/new_element/new_row → build_page) based on the user's actual goal. Enrich EVERY page (home, category, product detail, cart, checkout, thank-you, …) to the same e-commerce standard with the same palette/header/footer. Make the Header and Footer GLOBAL (create_global_section type:"header"/"footer") so they're consistent on every page — don't inline them per page. For newsletter/promo offers, build a popup node (new_element "popup") and save it via create_global_source({component:"popup"}), then open it with an open_popup event. See get_build_guide for the design system, the per-page section archetypes, the global-section order rules, and the popup workflow.
 
 To make a generated site look real, also CREATE DATA so dataset bindings resolve: create_product_category + create_product (storefront), create_blog_category + create_article (blog). Get image URLs from search_images / upload_images first, then reference them. A good flow for a fresh site: create_site → create a few categories → create products in them → build_page (home + store/blog pages) → publish_site.
 

package/dist/tools/builder-extras.js

@@ -231,7 +231,13 @@ Two-step safety: dry_run=true (default) describes what will happen; dry_run=fals
         // is exactly that link (resolvePreviewUrl == link(): primary_domain wins, else subdomain).
         const res = await api.publishSite(preview_url ? { domain: preview_url } : {});
         const data = (res && res.data) || res;
-        return { success: true, published_at: data && data.published_at, site: data && data.name, preview_url };
+        return {
+            success: true,
+            published_at: data && data.published_at,
+            site: data && data.name,
+            preview_url,
+            screenshots: "Homepage screenshots (desktop 1920_1080 + mobile 430_932) are captured in the background after a publish (at most once an hour). About a minute later get_site_info returns them in preview_img — open one with invoke_tool('read_image', { url }) to check the live result visually.",
+        };
     }));
     // ── Ingest reference HTML / URL into a blueprint ────────────────────────────
     function blueprintFromHtml(html) {

package/dist/tools/builder.js

@@ -275,7 +275,7 @@ ONE page per site for type main (homepage) / error / maintain, and slugs are uni
             }
         }
         // Expand runtime -> bp1..bp4 so the saved source actually renders on the storefront.
-        finalizeForRender(parsed);
+        finalizeForRender(parsed, await api.getSiteBreakpoints());
         // createPage saves the page AND its source in one call (source is required there).
         const created = await api.createPage({ name, source: parsed, ...(typeNum != null ? { type: typeNum } : {}) });
         const pageId = newPageId(created);
@@ -295,13 +295,64 @@ ONE page per site for type main (homepage) / error / maintain, and slugs are uni
             ...(metaWarning ? { warning: metaWarning } : {}),
         };
     }));
+    const templateRoot = (t) => {
+        try {
+            return JSON.parse(t.source || "null");
+        }
+        catch {
+            return null;
+        }
+    };
+    server.tool("list_section_templates", `Browse the designer-made section library (the editor's template picker): ready, styled blocks (hero, product showcase, testimonials, footer…) to start from instead of composing from scratch.
+No args → categories. With category_id and/or term → templates { id, name, thumbnail, kind }. Look at a thumbnail with invoke_tool('read_image', { url }), then insert a kind:"section" template with add_section({ page_id, template:{ category_id, id } }) and restyle it to the brand.`, {
+        category_id: z.string().optional().describe("Category id (from the no-arg call)"),
+        term: z.string().optional().describe("Search template names"),
+        page: z.number().optional().describe("Page (default 1)"),
+        limit: z.number().optional().describe("Per page (default 12)"),
+    }, ({ category_id, term, page, limit }) => handle(async () => {
+        if (!category_id && !term) {
+            const res = await api.listTemplateCategories();
+            const cats = res?.templates ?? res?.data?.templates ?? res?.data ?? [];
+            return { categories: (Array.isArray(cats) ? cats : []).map((c) => ({ id: c.id, name: c.name })) };
+        }
+        const res = await api.listTemplates({ id: category_id, term, page: page || 1, limit: limit || 12 });
+        const data = res?.data ?? res;
+        return {
+            templates: (data?.templates || []).map((t) => {
+                const root = templateRoot(t);
+                return { id: t.id, name: t.name, thumbnail: t.thumbnail, kind: root?.type === "section" ? "section" : root?.type || "unknown" };
+            }),
+            page: data?.page,
+            total: data?.total_entries,
+        };
+    }));
     server.tool("add_section", `Append a section to an EXISTING page's source. Reads the current source, appends your section, validates, and (when dry_run=false) saves.
-The section is re-id'd to avoid collisions. Build it with new_section.
+The section is re-id'd to avoid collisions. Pass a section built with new_section, OR template:{ category_id, id } to insert a library section (list_section_templates).
 Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
         page_id: z.string().describe("Target page id"),
-        section: z.any().describe("A section node (from new_section) — object or JSON string"),
+        section: z.any().optional().describe("A section node (from new_section) — object or JSON string"),
+        template: z
+            .object({ category_id: z.string().optional(), id: z.string() })
+            .optional()
+            .describe("Insert a library section instead (ids from list_section_templates)"),
         dry_run: z.boolean().default(true).describe("Preview only (true) or save (false)"),
-    }, ({ page_id, section, dry_run }) => handle(async () => {
+    }, ({ page_id, section, template, dry_run }) => handle(async () => {
+        if (template) {
+            // No get-by-id route: page through the category until the template turns up.
+            let found = null;
+            for (let p = 1; p <= 10 && !found; p++) {
+                const res = await api.listTemplates({ id: template.category_id, page: p, limit: 50 });
+                const list = (res?.data ?? res)?.templates || [];
+                found = list.find((t) => t.id === template.id);
+                if (list.length < 50)
+                    break;
+            }
+            if (!found)
+                return { error: `Template "${template.id}" not found${template.category_id ? " in that category" : ""}.` };
+            section = templateRoot(found);
+        }
+        if (!section)
+            return { error: "Pass a section (from new_section) or a template { category_id, id }." };
         const pagesRes = await api.listPages();
         const pages = (pagesRes && pagesRes.data) || pagesRes || [];
         const page = Array.isArray(pages) ? pages.find((p) => p.id === page_id) : null;
@@ -330,7 +381,7 @@ Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
             return { error: "Validation failed — not saving.", validation };
         // Expand the newly-added section's runtime -> bp1..bp4 (existing sections are
         // already in breakpoint shape and are left untouched).
-        finalizeForRender(source);
+        finalizeForRender(source, await api.getSiteBreakpoints());
         const saved = await api.updatePageSource(page_id, { source });
         return {
             success: true,

package/dist/tools/global-section-write.js

@@ -77,7 +77,7 @@ Two-step safety: dry_run=true (default) previews which pages change; dry_run=fal
         const validation = validatePage(wrap);
         if (!validation.valid)
             return { error: "Section failed validation.", validation };
-        finalizeForRender(wrap);
+        finalizeForRender(wrap, await api.getSiteBreakpoints());
         const finalNode = wrap.sections[0];
         // Resolve target pages + inject the node into each one's source.
         const allPages = await loadPages(api);

package/dist/tools/page-draft.js

@@ -134,7 +134,7 @@ RESUMABLE: if a request fails mid-commit, the draft keeps its page_id + committe
             }
         }
         // Expand runtime -> bp1..bp4 so the saved nodes actually render.
-        finalizeForRender(full);
+        finalizeForRender(full, await api.getSiteBreakpoints());
         const finalizedSections = full.sections;
         try {
             // Create the page with only the FIRST section (a SMALL first request) if not already created.

package/dist/tools/site-style.js

@@ -76,7 +76,7 @@ function parseThemeDescription(d) {
     }
 }
 export function registerSiteStyleTools(server, api, handle) {
-    server.tool("get_site_info", "Get full site information: name, domain, settings (colors, typography, layout, language, payment methods, etc.)", {}, () => handle(async () => {
+    server.tool("get_site_info", "Get full site information: name, domain, settings (colors, typography, layout, language, payment methods, etc.) and preview_img — the latest homepage screenshots (1920_1080 desktop / 430_932 mobile), refreshed after publish_site.", {}, () => handle(async () => {
         const res = await api.getSite();
         const site = (res && res.data) || res;
         if (!site)
@@ -89,6 +89,7 @@ export function registerSiteStyleTools(server, api, handle) {
             logo: site.logo || undefined,
             favicon: site.favicon || undefined,
             settings: site.settings || {},
+            preview_img: site.preview_img || undefined,
             created_at: site.created_at,
         };
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.33.2",
+  "version": "1.34.0",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",