webcake-storefront-mcp 1.33.1 → 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) {
@@ -186,8 +209,15 @@ export class WebcakeCmsApi {
     listPageContents(query) {
         return this.request("GET", `/api/v1/site/${this.siteId}/page_contents`, { query });
     }
-    updatePageContent(params) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/page_contents/page_content`, { body: params });
+    /** One page's translation in one language: { content: { [elementId]: {...} } } ({} when none yet). Read-only. */
+    getPageContent(page_id, lang) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/page_contents/page_content`, { body: { page_id, lang } });
+    }
+    /** Upsert one page translation (matched by page_id + language_code) — the editor's multilingual save. */
+    updatePageContent({ page_id, language_code, content, meta_tags }) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/multilingual/update_page_contents`, {
+            body: { pages: [{ contents: [{ page_id, language_code, content, meta_tags, site_id: this.siteId }] }] },
+        });
     }
     listGlobalSections() {
         return this.request("GET", `/api/v1/site/${this.siteId}/global_sections`);
@@ -647,14 +677,25 @@ export class WebcakeCmsApi {
     listCustomers(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/customer/all`, { query });
     }
+    /** /api/v1/cms_function/:site_id/* sits behind builderx_api's CmsFunctionAuth plug, which only
+     *  accepts the site's CMS admin token (db_collections/token) as the Bearer — the session JWT 401s. */
+    async cmsFunction(method, path, body) {
+        await this.fetchCmsTokens();
+        if (!this._adminToken)
+            throw new Error("This site has no CMS admin token, so cms_function routes are unavailable.");
+        return this.request(method, `/api/v1/cms_function/${this.siteId}${path}`, {
+            body,
+            headers: { Authorization: `Bearer ${this._adminToken}` },
+        });
+    }
     findCustomerById(id) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/identity/${id}`);
+        return this.cmsFunction("GET", `/customer/identity/${encodeURIComponent(id)}`);
     }
     findCustomerByPhone(phone) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/phone/${phone}`);
+        return this.cmsFunction("GET", `/customer/phone/${encodeURIComponent(phone)}`);
     }
     findCustomerByEmail(email) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/email/${email}`);
+        return this.cmsFunction("GET", `/customer/email/${encodeURIComponent(email)}`);
     }
     // ── Global Sources (cart, popup, overview, etc.) ──
     getSourceCart() {
@@ -704,7 +745,7 @@ export class WebcakeCmsApi {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/delete`, { body: { ids } });
     }
     sendMail(params) {
-        return this.request("POST", `/api/v1/cms_function/${this.siteId}/application/automation/send_mail`, { body: params });
+        return this.cmsFunction("POST", "/application/automation/send_mail", params);
     }
     // ── App lifecycle (applications/subcriptions) ──
     /** Uninstall an app by its subscription id (the `id` from list_apps / get_app). */
@@ -1143,13 +1184,7 @@ export class WebcakeCmsApi {
     getCourseMembers(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/course-app/members`, { query });
     }
-    // ── Sale channels: sitemap + partner feeds + catalogs ──
-    sitemapSync(kind) {
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/sale_channels/sitemap/sync_${kind}`, { body: {} });
-    }
-    sitemapRebuild(type) {
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/sale_channels/sitemap/rebuild`, { body: { type } });
-    }
+    // ── Sale channels: partner feeds + catalogs ──
     listPartnerFeeds(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/sale_channels/partner_feeds/all`, { query });
     }

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).",
     },
@@ -174,11 +174,11 @@ export const ELEMENT_ATTRS = {
     // ── layout ──
     section: {
         specials: { global: "Mark as a global/shared section (reused across pages).", custom_class: "CSS class.", layout: "Nested layout payload (advanced)." },
-        config: { stickyPosition: "Make the section sticky: default | autobottom | none.", stickyTop: "Sticky offset from top (px).", showShadowWhenSticky: "Add a shadow when stuck (0/1).", video_background: "Section video background {background_display,…}.", pattern_overlay: "Overlay pattern image url.", apply_pattern_overlay: "Apply the overlay pattern (boolean).", nameLineClamp: "Clamp the section title to N lines." },
+        config: { position: "Scroll behaviour: default | sticky (sticks while scrolling — sticky header) | pinned (fixed to the viewport). See get_build_guide → Sticky & pinned.", stickyPosition: "With position:'sticky': autotop (default) | autobottom | default (both edges).", stickyTop: "Sticky offset from top (px, default 0).", stickyBottom: "Sticky offset from bottom (px, default 0).", showShadowWhenSticky: "Keep the section's boxShadow only while stuck (1, default) or always (0).", video_background: "Section video background {background_display,…}.", pattern_overlay: "Overlay pattern image url.", apply_pattern_overlay: "Apply the overlay pattern (boolean).", nameLineClamp: "Clamp the section title to N lines." },
         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 ──
@@ -322,7 +325,7 @@ export const ELEMENT_ATTRS = {
     "next-lesson-droppable": { events: "none", notes: "Next-lesson panel (course app)." },
     "list-lesson-droppable": { events: "none", notes: "Lessons droppable list (course app)." },
     // ── marketing / popups / misc widgets (rarely in page sources; built via apps/global_sources) ──
-    popup: { specials: { effect: "Open animation (fade-in|slide|…).", timeAnim: "Animation duration (s).", trigger: "When it opens: load | delay | exit_intent | scroll.", delay: "Seconds before auto-open (trigger=delay).", onlyOnce: "Show once per visitor (boolean).", overlay: "Dim the page behind (boolean)." }, config: { popupHorizontalPosition: "left | center | right.", popupVerticalPosition: "top | center | bottom." }, events: "hide — fires when the popup closes.", notes: "Modal/overlay. NOT a page section — wrap a section in a popup node and save it as a global_source (component:'popup'). Open/close from any element via events open_popup/close_popup {popup_id}. See get_build_guide → Popups." },
+    popup: { specials: { effect: "Open animation (fade-in|slide|…).", timeAnim: "Animation duration (s).", openPopupAction: "Auto-open: none | openPopupWithTime (after timeOpenPopup s) | openPopupWhenScroll (when the element in `target` scrolls into view) | openWhenNonLogin (after timeOpenPopup s, only for logged-out visitors).", timeOpenPopup: "Delay in seconds for openPopupWithTime / openWhenNonLogin (default 0).", target: "Element id for openPopupWhenScroll.", page_ids: "Pages it auto-opens on (default ['all']).", countOpenPopup: "Max auto-opens per browser session (0/unset = unlimited)." }, config: { popupHorizontalPosition: "left | center | right.", popupVerticalPosition: "top | center | bottom." }, events: "hide — fires when the popup closes.", notes: "Modal/overlay. NOT a page section — wrap a section in a popup node and save it as a global_source (component:'popup'). Open/close from any element via events open_popup/close_popup {popup_id}. See get_build_guide → Popups." },
     notify: { specials: { type: "Toast/banner kind.", autoClose: "Auto-dismiss (boolean).", duration: "Visible time (s)." }, events: "none", notes: "Notification / toast banner (e.g. add-to-cart confirmation). Often referenced by add_to_cart's activeNotify." },
     "random-number": { specials: { min: "Lowest value.", max: "Highest value." }, events: "none", notes: "Displays a random number (minigame / fake-stock urgency widget)." },
     table: { specials: { datagrid_id: "Linked data-grid id (the table's data source).", tableItems: "Column definitions [{name,key}]." }, config: { titleBackground: "Header background.", titleColor: "Header text colour.", oddBackground: "Odd-row background.", evenBackground: "Even-row background." }, events: "none", notes: "Data table bound to a data grid (specs / comparison)." },

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

@@ -507,6 +507,9 @@ export const createCartIcon = ({ svg, itemCount, config, style, children } = {})
     cart.specials.itemCount = itemCount ?? 0;
     if (children)
         cart.children = children || [];
+    // The renderer's cart-icon has no click handler of its own — opening the cart IS this event
+    // (SPA factory.js 9877f2c99). Without it a built cart icon does nothing when clicked.
+    cart.events = [{ id: 'EVENT-' + randomString(6), eventName: 'click', action: 'open_cart' }];
     return cart;
 };
 export const createWishlist = ({ svg, itemCount, config, children, style } = {}) => {
@@ -525,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);
@@ -1760,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,6 +349,33 @@ 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 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).
+  position:"pinned"  fixed to the viewport — floating hotline/Zalo button, back-to-top. ALSO set
+                     runtime.style.position:"fixed". fixedPosition: top_left | top_center | top_right |
+                     bottom_left | bottom_center | bottom_right | center_left | center_right; offsets
+                     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
@@ -373,7 +402,7 @@ A popup is a GLOBAL SOURCE, not a page section. Compose it from elements (there
 shortcut), then save it as a "popup" global source:
 1. Build the popup node: new_element("popup", { children:[…heading,text,form,close button…], style:{ width:480, background:"#fff", borderRadius:"12px" }, config:{ popupHorizontalPosition:"center", popupVerticalPosition:"center" }, specials:{ effect:"fade-in", timeAnim:0.5 } }).
    - SIZE + POSITION live in the popup's runtime style/config (width/height/background + popupHorizontalPosition/popupVerticalPosition), NOT in specials. createPopup seeds a centred-modal default.
-   - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. (There is no exit-intent/only-once flag in the node — those are app settings.)
+   - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. Other triggers: \`openPopupWhenScroll\` + \`target:"<elementId>"\` (opens when that element scrolls into view), \`openWhenNonLogin\` (logged-out visitors only, after \`timeOpenPopup\`). \`countOpenPopup:<n>\` caps auto-opens per browser session (unset = every page view). There is no exit-intent trigger.
    - OVERLAY is NOT on the popup node — it's a field on the open_popup EVENT (popup_overlay:true).
 2. Save it: create_global_source({ component:"popup", source:{ sections:[<popupNode>] } }) -> returns its id.
 3. Open/close from any element via events: a button { action:"open_popup", popup_id:"<id>", popup_overlay:true };

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,18 @@
 [
+  {
+    "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",
+    "type": "Added",
+    "en": "list_orders responses now include a status_name field alongside the numeric status.",
+    "vi": "Kết quả trả về của list_orders nay có thêm trường status_name bên cạnh status dạng số."
+  },
   {
     "v": "1.33.1",
     "d": "14/10/2026",
@@ -26,19 +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) để…"
-  },
-  {
-    "v": "1.31.11",
-    "d": "11/09/2026",
-    "type": "Changed",
-    "en": "create_site and create_site_from_template now stamp the new site with by_ai: \"mcp\" (persisted to the backend sites.by_ai column), extending the…",
-    "vi": "create_site và create_site_from_template nay đánh dấu site mới với by_ai: \"mcp\" (lưu vào cột sites.by_ai ở backend), mở rộng dấu hiệu AI-tạo vốn chỉ…"
   }
 ]

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/orders.js

@@ -1,9 +1,16 @@
 import { z } from "zod";
+/** builderx_api Enum.OrderStatus (lib/builderx_api/enum.ex). */
+const ORDER_STATUS = {
+    0: "new", 1: "submitted", 2: "shipped", 3: "delivered", 4: "returning", 5: "returned", 6: "canceled",
+    7: "removed", 8: "packing", 9: "pending", 11: "waiting", 12: "wait_print", 13: "printed",
+    15: "part_returned", 16: "received_money", 17: "wait_submit", 20: "ordered", 22: "draft", 50: "blocked",
+};
+const STATUS_HELP = Object.entries(ORDER_STATUS).map(([k, v]) => `${k}=${v}`).join(", ");
 export function registerOrderTools(server, api, handle) {
     server.tool("list_orders", "List orders of the site (metadata only). Use get_order for full details including items", {
         page: z.number().optional().describe("Page number"),
         limit: z.number().optional().describe("Items per page"),
-        status: z.number().optional().describe("Filter by status (0=pending, 50=confirmed, 100=shipping, 150=delivered, -1=cancelled)"),
+        status: z.number().optional().describe(`Filter by status: ${STATUS_HELP}. Omit or -1 = all (except removed/blocked).`),
     }, ({ page, limit, status }) => handle(async () => {
         const res = await api.listOrders({ page, limit, status });
         // Real shape: { orders: { data:[…], total_entries, count_status } }.
@@ -16,6 +23,7 @@ export function registerOrderTools(server, api, handle) {
                 bill_full_name: o.bill_full_name,
                 bill_phone_number: o.bill_phone_number,
                 status: o.status,
+                status_name: ORDER_STATUS[o.status] ?? null,
                 payment_status: o.payment_status,
                 payment_method: o.payment_method,
                 invoice_value: o.invoice_value || o.total,

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/pages.js

@@ -453,31 +453,39 @@ For full rewrites, use update_site_custom_code instead.`, {
     server.tool("get_page_versions", "View version history of a page", {
         page_id: z.string().describe("Page ID"),
     }, ({ page_id }) => handle(() => api.getPageVersions(page_id)));
-    server.tool("list_page_contents", "List multi-language contents of a page", {
-        page_id: z.string().optional().describe("Filter by Page ID"),
-    }, ({ page_id }) => handle(() => api.listPageContents({ page_id })));
+    server.tool("list_page_contents", "List multi-language contents (translations) of the site's pages and global sections. Pass page_id + language_code to read one page's translation.", {
+        page_id: z.string().optional().describe("Page ID — narrows the result to that page"),
+        language_code: z.string().optional().describe("With page_id: return just that language's content map"),
+    }, ({ page_id, language_code }) => handle(async () => {
+        if (page_id && language_code) {
+            const res = await api.getPageContent(page_id, language_code);
+            return res?.data ?? res;
+        }
+        const res = await api.listPageContents(); // backend ignores page_id here, so filter client-side
+        const data = res?.data ?? res;
+        return page_id ? { pages: (data?.pages || []).filter((p) => p.id === page_id) } : data;
+    }));
     server.tool("update_page_content", `Create/update page content for a specific language.
 IMPORTANT: Before calling, you MUST read existing content with list_page_contents first, then show the user what will change and get explicit confirmation. NEVER update without user approval.`, {
         page_id: z.string().describe("Page ID"),
         language_code: z.string().describe("Language code (e.g. 'en', 'vi')"),
-        content: z.record(z.any()).describe("Page content"),
+        content: z
+            .record(z.any())
+            .describe('Translations keyed by element id → field, e.g. { "<elementId>": { "text": "Hello" } } (also "placeholder", or "options": [{ id, name }]). Replaces this language\'s whole map — merge into the existing one.'),
         meta_tags: z.array(z.record(z.any())).optional().describe("SEO meta tags"),
     }, ({ page_id, language_code, content, meta_tags }) => handle(async () => {
         // Safeguard: read existing content and block if new content is suspiciously smaller
-        const existingRes = await api.listPageContents({ page_id });
-        const existingContents = (existingRes && existingRes.data) || existingRes || [];
-        if (Array.isArray(existingContents)) {
-            const existing = existingContents.find((c) => c.language_code === language_code);
-            if (existing && existing.content) {
-                const existingStr = JSON.stringify(existing.content);
-                const newStr = JSON.stringify(content);
-                if (existingStr.length > 200 && newStr.length < existingStr.length * 0.5) {
-                    return {
-                        error: `BLOCKED: New content (${newStr.length} chars) is much smaller than existing (${existingStr.length} chars) — ${Math.round((newStr.length / existingStr.length) * 100)}% of original. This may indicate fabricated data or data loss. Read existing content with list_page_contents first, then merge your changes.`,
-                        existing_length: existingStr.length,
-                        new_length: newStr.length,
-                    };
-                }
+        const existingRes = await api.getPageContent(page_id, language_code);
+        const existing = existingRes?.data ?? existingRes;
+        if (existing && existing.content) {
+            const existingStr = JSON.stringify(existing.content);
+            const newStr = JSON.stringify(content);
+            if (existingStr.length > 200 && newStr.length < existingStr.length * 0.5) {
+                return {
+                    error: `BLOCKED: New content (${newStr.length} chars) is much smaller than existing (${existingStr.length} chars) — ${Math.round((newStr.length / existingStr.length) * 100)}% of original. This may indicate fabricated data or data loss. Read it with list_page_contents(page_id, language_code) first, then merge your changes.`,
+                    existing_length: existingStr.length,
+                    new_length: newStr.length,
+                };
             }
         }
         return api.updatePageContent({ page_id, language_code, content, meta_tags });

package/dist/tools/sale-channels.js

@@ -1,12 +1,9 @@
 import { z } from "zod";
-// Sale-channels app: sitemap generation, partner product feeds (Google/Facebook/etc.),
-// and catalog syncs. Google Ads / OAuth-connect flows are intentionally omitted —
+// Sale-channels app: partner product feeds (Google/Facebook/etc.) and catalog syncs.
+// Sitemaps need no tool: the backend builds them at render time (<domain>/root_sitemaps.xml). Google Ads / OAuth-connect flows are intentionally omitted —
 // they require an externally-authorized Google/Facebook partner.
 export function registerSaleChannelTools(server, api, handle) {
     const unwrap = (res, key) => (key && (res?.data?.[key] ?? res?.[key])) ?? res?.data ?? res;
-    // ── Sitemap ──
-    server.tool("sync_sitemap", "Sync a resource type into the site's sitemap. Requires sitemap enabled in site settings.", { kind: z.enum(["products", "categories", "articles", "pages"]).describe("What to sync into the sitemap") }, ({ kind }) => handle(() => api.sitemapSync(kind)));
-    server.tool("rebuild_sitemap", "Rebuild the whole sitemap (async background job).", { type: z.string().optional().describe("Optional rebuild scope hint") }, ({ type }) => handle(() => api.sitemapRebuild(type)));
     // ── Partner feeds ──
     server.tool("list_partner_feeds", "List product feeds for sale channels (Google Shopping, Facebook, etc.).", {
         page: z.number().optional().describe("Page number"),

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.1",
+  "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",