webcake-storefront-mcp 1.13.0 → 1.15.0

package/dist/api.js

@@ -178,6 +178,30 @@ export class WebcakeCmsApi {
     listGlobalSections() {
         return this.request("GET", `/api/v1/site/${this.siteId}/global_sections`);
     }
+    /** Upsert/delete global sections (Header/Footer/reusable blocks) via the site /save
+     *  pipeline — the SAME endpoint the builder uses. Each entry carries a `status`
+     *  ("new"|"update"|"delete") and is matched by (site_id, section_id). `section` is sent
+     *  as an OBJECT (backend Jason.encode!s it). Optionally pass `pages` (each { id, source }
+     *  with source a JSON STRING) to embed the section node into page sources in the same
+     *  atomic save — required for a header/footer to actually render. `settings` MUST be the
+     *  current site settings (string) or /save would null them; we fetch them when omitted. */
+    async saveGlobalSections({ global_sections = [], pages = [], settings, changes } = {}) {
+        let s = settings;
+        if (s === undefined)
+            s = await this.getSiteSettings().catch(() => ({}));
+        const settingsStr = typeof s === "string" ? s : JSON.stringify(s || {});
+        return this.request("POST", `/api/v1/site/${this.siteId}/save`, {
+            body: {
+                settings: settingsStr,
+                global_sources: [],
+                page_contents: [],
+                changes: changes || {},
+                pages,
+                global_sections,
+            },
+            timeout: 120000,
+        });
+    }
     getSite() {
         return this.request("GET", `/api/v1/site/${this.siteId}/`);
     }

package/dist/builder/attributes.js

@@ -335,6 +335,8 @@ export function describeAttributes(type, skeleton) {
         notes: curated.notes,
         common_specials_note: "custom_class/custom_css/element_async/event_name_custom work on almost every element.",
         layout_hint: "runtime.style holds CSS (width/height/color/fontSize/background/border…); runtime.config holds grid placement (see get_build_guide). On save these expand into bp1..bp4.",
+        events_hint: "Attach interactions via opts.events (ids auto-minted). Call list_events for the trigger/action catalog + required fields.",
+        bindings_hint: "Attach dynamic data via opts.bindings (ids auto-minted). Call list_bindings for the dataset/field catalog. Inside a repeater (grid-product/cart-items/post-list…) children bind to the per-item dataset.",
         coverage: obs.seen ? `${obs.seen} real instances mined` : "factory default only",
     };
 }

package/dist/builder/bindings.js

@@ -0,0 +1,253 @@
+// Authoritative BINDINGS catalog + helpers for the BuilderX component model.
+//
+// A dataset element (text-dataset, image-dataset, …) and the children of a repeater
+// (grid-product, cart-items, post-list, …) pull LIVE data via a `bindings` array. Each
+// binding is a FLAT object:
+//   { id, name, target, ...metadata }
+// - name   = the dataset/source ("product", "cart_item", "order", "post", …)
+// - target = "<name>::<field>" (e.g. "product::product_price")
+// Source of truth: builderx_spa/src/composable/bind.js (runtime resolver),
+// builderx_spa/src/components/editor/traits/{BindingSetting,ConnectData}.vue (the field
+// menus), builderx_api/assets/render/*-binding.js (storefront resolve). A binding only
+// resolves on a page whose `type` enables the dataset (product/cart → use_store, etc).
+// This module mirrors that so the MCP can MINT, VALIDATE and TEACH valid bindings.
+import { randomString } from "./factory.js";
+// Curated to the fields an AI realistically uses, lifted verbatim from the editor field
+// menus. (The full lists run longer; these cover storefront page building.)
+export const BINDING_DATASETS = {
+    product: {
+        name: "product",
+        page_type: "store",
+        repeater_parents: ["grid-product", "slider-product", "custom-layout", "layout-dataset"],
+        summary: "A product (detail page, or per-item inside a product grid/slider).",
+        fields: [
+            "product::product_name", "product::product_price", "product::product_original_price",
+            "product::product_image", "product::product_url", "product::short_description",
+            "product::product_categories", "product::brand_name", "product::product_tag",
+            "product::product_remain_quantity", "product::total_sold_web", "product::rating_point",
+            "product::rating_count", "product::variation_sku", "product::product_wholesale_price",
+            "product::discount_price_from_original_price", "product::preorder_text", "product::product_note",
+        ],
+    },
+    "product-overlay": {
+        name: "product-overlay",
+        page_type: "store",
+        repeater_parents: ["grid-product", "slider-product"],
+        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"],
+    },
+    cart_item: {
+        name: "cart_item",
+        page_type: "store",
+        repeater_parents: ["cart-items"],
+        summary: "A line item in the cart, plus cart totals.",
+        fields: [
+            "cart_item::cart_item_image", "cart_item::cart_item_name", "cart_item::cart_item_price",
+            "cart_item::cart_item_original_price", "cart_item::cart_item_subtotal", "cart_item::cart_item_total_price",
+            "cart_item::cart_item_total_quantity", "cart_item::cart_item_prod_attr", "cart_item::sku",
+            "cart_item::cart_total_price", "cart_item::cart_total_tax", "cart_item::cart_shipping_fee",
+            "cart_item::cart_promotion_discount", "cart_item::subtotal_before_discount", "cart_item::product_note",
+        ],
+    },
+    order: {
+        name: "order",
+        page_type: "store",
+        summary: "The order summary (checkout / thank-you page).",
+        fields: [
+            "order::order_full_name", "order::order_phone_number", "order::order_email", "order::address",
+            "order::order_payment_method", "order::shipping_fee", "order::subtotal", "order::total_price",
+            "order::total_tax", "order::code_order", "order::order_status", "order::payment_status",
+            "order::order_quantity", "order::order_date", "order::order_coupon", "order::order_promotion_discount",
+        ],
+    },
+    order_item: {
+        name: "order_item",
+        page_type: "store",
+        repeater_parents: ["order-items"],
+        summary: "A line item inside an order summary.",
+        fields: [
+            "order_item::product_name", "order_item::product_price", "order_item::original_price",
+            "order_item::product_image", "order_item::product_attrs", "order_item::product_quantity",
+            "order_item::items_sum_up_price", "order_item::tag_bonus", "order_item::preorder_text",
+        ],
+    },
+    post: {
+        name: "post",
+        page_type: "blog",
+        repeater_parents: ["post-list", "slider-post", "grid-blog", "slider-blog"],
+        summary: "A blog article/post (list item or detail).",
+        fields: [
+            "post::post_title", "post::post_description", "post::post_content", "post::post_image",
+            "post::post_publish_date", "post::category_name", "post::category_description", "post::category_image",
+            "post::post_creator", "post::tag_article", "post::total_views",
+        ],
+    },
+    category: {
+        name: "category",
+        page_type: "store",
+        repeater_parents: ["grid-category", "slider-category"],
+        summary: "A product category (per-item inside a category grid/slider).",
+        fields: ["category::category_name", "category::category_image", "category::category_description"],
+    },
+    customer: {
+        name: "customer",
+        page_type: "member",
+        summary: "The logged-in customer profile + loyalty.",
+        fields: [
+            "customer::profile_avatar", "customer::profile_name", "customer::phone_number", "customer::email",
+            "customer::gender", "customer::birthday", "customer::order_count", "customer::purchased_amount",
+            "customer::pos_reward_point", "customer::pos_reward_point_level", "customer::pos_level_discount",
+        ],
+    },
+    customer_address: {
+        name: "customer_address",
+        page_type: "member",
+        repeater_parents: ["customer-address"],
+        summary: "A saved customer address (member page).",
+        fields: [
+            "customer_address::full_name", "customer_address::first_name", "customer_address::last_name",
+            "customer_address::phone_number", "customer_address::address", "customer_address::province",
+            "customer_address::district", "customer_address::commune", "customer_address::pdc", "customer_address::is_default",
+        ],
+    },
+    bonus_item: {
+        name: "bonus_item",
+        page_type: "store",
+        repeater_parents: ["bonus-items"],
+        summary: "A combo/gift item (promotion bonus).",
+        fields: [
+            "bonus_item::bonus_item_name", "bonus_item::bonus_item_price", "bonus_item::bonus_item_original_price",
+            "bonus_item::bonus_item_image", "bonus_item::bonus_item_prod_attr", "bonus_item::bonus_item_quantity",
+            "bonus_item::tag_bonus", "bonus_item::combo_name", "bonus_item::sku",
+        ],
+    },
+    promotion_item: {
+        name: "promotion_item",
+        page_type: "store",
+        repeater_parents: ["promotions", "promotions-short"],
+        summary: "A promotion in a promotions list.",
+        fields: ["promotion_item::name", "promotion_item::code", "promotion_item::image", "promotion_item::description", "promotion_item::end_date"],
+    },
+    attr: {
+        name: "attr",
+        page_type: "store",
+        summary: "A product attribute (variation axis) name/value.",
+        fields: ["attr::attr_name", "attr::attr_value"],
+    },
+    form: {
+        name: "form",
+        page_type: "any",
+        summary: "Computed form values (coupon price, reward points).",
+        fields: ["form::coupon_price", "form::send_value", "form::total_reward_point", "form::use_reward_point", "form::remaining_reward_point", "form::submit_errors"],
+    },
+    general_info: {
+        name: "general_info",
+        page_type: "any",
+        summary: "Page / site info.",
+        fields: ["general_info::page_name", "general_info::site_name", "general_info::menu_title"],
+    },
+};
+// Build fast lookups.
+const ALL_TARGETS = new Set();
+const NAME_SET = new Set();
+for (const ds of Object.values(BINDING_DATASETS)) {
+    NAME_SET.add(ds.name);
+    for (const f of ds.fields)
+        ALL_TARGETS.add(f);
+}
+// Repeater parent type → the PRIMARY dataset its children bind to per-item. First write
+// wins so the primary dataset (product) claims grid-product over secondary overlays.
+export const REPEATER_CONTEXT = {};
+for (const ds of Object.values(BINDING_DATASETS)) {
+    for (const p of ds.repeater_parents || [])
+        if (!REPEATER_CONTEXT[p])
+            REPEATER_CONTEXT[p] = ds.name;
+}
+export function isKnownBindingName(name) {
+    return NAME_SET.has(name);
+}
+export function isKnownBindingTarget(target) {
+    return ALL_TARGETS.has(target);
+}
+/**
+ * Mint a structurally-valid binding. Accepts either a full target ("product::product_price")
+ * or a name + field, plus any extra metadata (show_tax, separator, name_style, …).
+ *   makeBinding("product::product_price", { show_tax: true })
+ *   makeBinding({ name: "cart_item", field: "cart_item_name" })
+ */
+export function makeBinding(spec, extra = {}) {
+    let name;
+    let target;
+    if (typeof spec === "string") {
+        target = spec;
+        name = spec.includes("::") ? spec.split("::")[0] : spec;
+    }
+    else if (spec && typeof spec === "object") {
+        name = spec.name;
+        target = spec.target || (spec.name && spec.field ? `${spec.name}::${spec.field}` : undefined);
+        if (!name && target && target.includes("::"))
+            name = target.split("::")[0];
+        const { id, name: _n, target: _t, field: _f, ...rest } = spec;
+        extra = { ...rest, ...extra };
+        if (id)
+            extra.id = id;
+    }
+    if (!name)
+        throw new Error("Binding needs a name or a 'name::field' target.");
+    const { id: keepId, ...meta } = extra;
+    return { id: keepId || `BINDING-${randomString(6)}`, name, ...(target ? { target } : {}), ...meta };
+}
+/** Ensure every binding in an array has an id + a name (mint where missing). */
+export function normalizeBindings(bindings) {
+    if (!Array.isArray(bindings))
+        return bindings;
+    return bindings.map((b) => {
+        if (!b || typeof b !== "object")
+            return b;
+        if (b.id && b.name)
+            return b; // already well-formed
+        return makeBinding(b);
+    });
+}
+/** Validate one element's bindings against the catalog. */
+export function validateBindings(node) {
+    const errors = [];
+    const warnings = [];
+    const where = node?.id || node?.type || "?";
+    for (const b of node?.bindings || []) {
+        if (!b || typeof b !== "object") {
+            warnings.push(`Binding on "${where}" is not an object.`);
+            continue;
+        }
+        if (!b.name) {
+            warnings.push(`Binding on "${where}" has no name (dataset).`);
+        }
+        else if (!isKnownBindingName(b.name)) {
+            warnings.push(`Binding on "${where}" has unknown dataset "${b.name}" (see list_bindings).`);
+        }
+        if (b.target) {
+            if (!/^[a-z_-]+::.+/i.test(b.target)) {
+                warnings.push(`Binding on "${where}" target "${b.target}" is not "name::field" shaped.`);
+            }
+            else if (!isKnownBindingTarget(b.target)) {
+                warnings.push(`Binding on "${where}" target "${b.target}" is not a known field (see list_bindings).`);
+            }
+        }
+    }
+    return { errors, warnings };
+}
+/** Catalog for the list_bindings discovery tool. */
+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 }]. 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.",
+        page_type_required: { store: ["product", "product-overlay", "cart_item", "order", "order_item", "category", "bonus_item", "promotion_item", "attr"], member: ["customer", "customer_address"], blog: ["post"], any: ["form", "general_info"] },
+        repeater_context: REPEATER_CONTEXT,
+        datasets: Object.values(BINDING_DATASETS).map((ds) => ({
+            name: ds.name,
+            page_type: ds.page_type,
+            summary: ds.summary,
+            ...(ds.repeater_parents ? { used_inside: ds.repeater_parents } : {}),
+            fields: ds.fields,
+        })),
+    };
+}

package/dist/builder/catalog.js

@@ -6,6 +6,8 @@
 // so an AI agent can understand the palette, and (3) expose helpers the MCP tools use.
 import * as F from "./factory.js";
 import { describeAttributes } from "./attributes.js";
+import { normalizeBindings } from "./bindings.js";
+import { normalizeEvents } from "./events.js";
 // Probe every factory once with safe default opts to learn the type string it produces
 // and whether it is a container (has a children array). Calling with {children:[]} is
 // safe for all 132 factories (verified) — none throw.
@@ -154,7 +156,18 @@ export function buildElement(type, opts = {}) {
         throw err;
     }
     // Guarantee children-using factories never throw on a missing children array.
-    return fn({ children: [], ...opts });
+    const node = fn({ children: [], ...opts });
+    // Some factories ignore opts.bindings/events — attach them so any element the AI passes
+    // them to gets them — then normalize so each binding/event has a valid id (+ name/eventName).
+    if (opts.bindings && !node.bindings)
+        node.bindings = opts.bindings;
+    if (opts.events && !node.events)
+        node.events = opts.events;
+    if (Array.isArray(node.bindings) && node.bindings.length)
+        node.bindings = normalizeBindings(node.bindings);
+    if (Array.isArray(node.events) && node.events.length)
+        node.events = normalizeEvents(node.events);
+    return node;
 }
 export function isKnownType(type) {
     return Boolean(FACTORY_BY_TYPE[type]);

package/dist/builder/events.js

@@ -0,0 +1,152 @@
+// Authoritative EVENTS catalog + helpers for the BuilderX component model.
+//
+// An interactive element carries an `events: [ <event>, ... ]` array. Each event is a
+// FLAT object the storefront renderer consumes:
+//   { id, eventName, action, ...action-specific fields }
+// - eventName = the TRIGGER (click/hover/success/...). Source of truth:
+//   builderx_spa/src/components/editor/traits/{Events,EventSetting}.vue and the Elixir
+//   renderer builderx_api/lib/qwik/html/common.ex (validates eventName) +
+//   builderx_api/assets/render/events.js (dispatches `action` → PascalCase handler).
+// - action = WHAT happens; each action reads its own extra fields (open_page_id,
+//   toggle_id, popup_id, link_target, …).
+// This module mirrors that shape so the MCP can MINT valid events, VALIDATE them, and
+// TEACH the AI the exact trigger/action/field names (no invented keys).
+import { randomString } from "./factory.js";
+export const EVENT_TRIGGERS = [
+    { name: "click", when: "User clicks the element (the default for buttons/text/images/containers).", applies_to: "most elements" },
+    { name: "hover", when: "Pointer hovers the element — used for hover style actions (scale, change_background, …).", applies_to: "most elements" },
+    { name: "mouseenter", when: "Pointer enters the element." },
+    { name: "mouseleave", when: "Pointer leaves the element." },
+    { name: "success", when: "A form submitted successfully — fire follow-up actions (redirect/popup).", applies_to: "form" },
+    { name: "submit", when: "A submit-button submits its parent form.", applies_to: "submit-button" },
+    { name: "tab", when: "A swiper/tab changed.", applies_to: "swiper, tabs" },
+    { name: "hide", when: "A popup is hidden.", applies_to: "popup" },
+    { name: "onenter", when: "Enter key pressed in a search input.", applies_to: "input-search" },
+];
+const TRIGGER_NAMES = new Set(EVENT_TRIGGERS.map((t) => t.name));
+export const EVENT_ACTIONS = [
+    // navigation
+    { action: "open_page", trigger: "click", category: "navigation", summary: "Go to a page in this site.", required: ["open_page_id"], optional: ["scrollTarget", "scroll_to_id", "scroll_to_element_id", "scrollMore", "no_follow", "active_color"] },
+    { action: "open_link", trigger: "click", category: "navigation", summary: "Open an external URL.", required: ["link_target"], optional: ["link_target_url", "no_follow"] },
+    { action: "open_category", trigger: "click", category: "navigation", summary: "Open a product category page.", required: ["open_category_id"], optional: ["no_follow"] },
+    { action: "open_blog_category", trigger: "click", category: "navigation", summary: "Open a blog category page.", required: ["open_blog_category_id"], optional: ["no_follow"] },
+    { action: "scroll_to", trigger: "click", category: "navigation", summary: "Smooth-scroll to a section/element on this page.", required: ["scroll_to_id"], optional: ["scroll_to_element_id", "scrollMore", "scrollTarget"], target_in_page: ["scroll_to_id", "scroll_to_element_id"] },
+    { action: "direction_login", trigger: "click", category: "navigation", summary: "Redirect by login state: open_page_id if logged in, target_direction_id if not.", required: ["open_page_id"], optional: ["target_direction_id"] },
+    // ui control
+    { action: "toggle", trigger: "click", category: "ui", summary: "Show/hide another element on this page.", required: ["toggle_id"], optional: ["toggle_status", "only_mode"], target_in_page: ["toggle_id"] },
+    { action: "open_popup", trigger: "click", category: "ui", summary: "Open a popup.", required: ["popup_id"], optional: ["popup_overlay", "close_all_other_popup"] },
+    { action: "close_popup", trigger: "click", category: "ui", summary: "Close a popup.", required: ["popup_id"], optional: ["popup_overlay", "close_all_other_popup"] },
+    { action: "open_menu", trigger: "click", category: "ui", summary: "Open a dropdown/submenu.", required: ["open_menu_id"], target_in_page: ["open_menu_id"] },
+    { action: "close_menu", trigger: "click", category: "ui", summary: "Close a menu.", optional: ["close_menu_id"] },
+    { action: "change_tab", trigger: "click", category: "ui", summary: "Switch a swiper/tabs to a given tab.", required: ["change_tab_id"], optional: ["move_to", "tab_index", "tab_color"], target_in_page: ["change_tab_id"] },
+    { action: "load_more", trigger: "click", category: "ui", summary: "Load more items in a list.", optional: ["load_more_id"], target_in_page: ["load_more_id"] },
+    // cart / commerce
+    { action: "add_to_cart", trigger: "click", category: "cart", summary: "Add the current product to the cart.", optional: ["open_page", "auto_add_bonus", "activeNotify", "productNoteElId"] },
+    { action: "buy_now", trigger: "click", category: "cart", summary: "Add to cart and go straight to checkout.", optional: ["open_page", "auto_add_bonus", "activeNotify"] },
+    { action: "add_to_cart_form", trigger: "success", category: "cart", summary: "Add to cart from a form submit (product form).", optional: ["open_page"] },
+    { action: "open_cart", trigger: "click", category: "cart", summary: "Open the cart sidebar/drawer." },
+    { action: "close_cart", trigger: "click", category: "cart", summary: "Close the cart sidebar/drawer." },
+    { action: "apply_promotion", trigger: "click", category: "cart", summary: "Apply a promotion/coupon code.", optional: ["apply_id", "is_hidden", "has_text", "text_change"] },
+    // form / account
+    { action: "required_login", trigger: "click", category: "account", summary: "Require login before proceeding (redirect to a page or popup).", optional: ["login_target", "login_page_id", "login_popup_id"] },
+    { action: "logout", trigger: "click", category: "account", summary: "Log the customer out." },
+    { action: "login_google", trigger: "click", category: "account", summary: "Sign in with Google." },
+    { action: "login_facebook", trigger: "click", category: "account", summary: "Sign in with Facebook." },
+    // content
+    { action: "change_text", trigger: "click", category: "content", summary: "Replace the text of another element.", required: ["target_id"], optional: ["text_value"], target_in_page: ["target_id"] },
+    { action: "see_more", trigger: "click", category: "content", summary: "Expand a clamped/collapsed element.", optional: ["elements"] },
+    { action: "shorten", trigger: "click", category: "content", summary: "Collapse a previously expanded element.", optional: ["elements"] },
+    { action: "copy", trigger: "click", category: "content", summary: "Copy text to the clipboard.", optional: ["copy_type", "copy_data"] },
+    { action: "download", trigger: "click", category: "content", summary: "Download a file.", required: ["download_link"], optional: ["fileType"] },
+    // contact
+    { action: "phone_call", trigger: "click", category: "contact", summary: "Start a phone call (tel:).", required: ["phone_call_number"] },
+    { action: "open_email", trigger: "click", category: "contact", summary: "Open the mail client (mailto:).", required: ["open_email"] },
+    { action: "send_messenger", trigger: "click", category: "contact", summary: "Open Facebook Messenger.", optional: ["messenger_link"] },
+    { action: "send_zalo_mess", trigger: "click", category: "contact", summary: "Open Zalo chat.", optional: ["zalo_oa_id"] },
+    { action: "send_whatsapp_mess", trigger: "click", category: "contact", summary: "Open WhatsApp chat.", optional: ["whatsapp_phone_number"] },
+    { action: "sharing", trigger: "click", category: "contact", summary: "Share to a social network.", optional: ["shareTarget", "shareLink", "shareLinkCustom"] },
+    // hover styles (eventName must be "hover")
+    { action: "scale", trigger: "hover", category: "hover", summary: "Scale the element on hover.", optional: ["el_target_id"] },
+    { action: "change_background", trigger: "hover", category: "hover", summary: "Change background colour on hover." },
+    { action: "change_text_color", trigger: "hover", category: "hover", summary: "Change text colour on hover." },
+    { action: "change_border_color", trigger: "hover", category: "hover", summary: "Change border colour on hover." },
+];
+const ACTION_BY_NAME = {};
+for (const a of EVENT_ACTIONS)
+    ACTION_BY_NAME[a.action] = a;
+export function isKnownTrigger(name) {
+    return TRIGGER_NAMES.has(name);
+}
+export function getEventAction(action) {
+    return ACTION_BY_NAME[action];
+}
+/**
+ * Mint a structurally-valid event object. Pass at least `action`; extra action-specific
+ * fields are merged verbatim. The id and a sensible eventName are filled in.
+ *   makeEvent({ action: "scroll_to", scroll_to_id: "SECTION-x" })
+ *   makeEvent({ action: "open_link", eventName: "click", link_target: "https://…" })
+ */
+export function makeEvent(spec) {
+    if (!spec || typeof spec !== "object")
+        throw new Error("Event spec must be an object with at least an `action`.");
+    const def = spec.action ? ACTION_BY_NAME[spec.action] : undefined;
+    const eventName = spec.eventName || (def ? def.trigger : "click");
+    const { eventName: _e, action: _a, id: _id, ...rest } = spec;
+    return { id: spec.id || `EVENT-${randomString(6)}`, eventName, ...(spec.action ? { action: spec.action } : {}), ...rest };
+}
+/** Ensure every event in an array has an id + an eventName (mint where missing). */
+export function normalizeEvents(events) {
+    if (!Array.isArray(events))
+        return events;
+    return events.map((e) => (e && typeof e === "object" ? makeEvent(e) : e));
+}
+/** Validate one element's events against the catalog + the set of ids present in the page. */
+export function validateEvents(node, allIds) {
+    const errors = [];
+    const warnings = [];
+    const where = node?.id || node?.type || "?";
+    for (const ev of node?.events || []) {
+        if (!ev || typeof ev !== "object") {
+            warnings.push(`Event on "${where}" is not an object.`);
+            continue;
+        }
+        if (ev.eventName && !isKnownTrigger(ev.eventName)) {
+            warnings.push(`Event on "${where}" has unknown eventName "${ev.eventName}" (see list_events triggers).`);
+        }
+        if (!ev.action) {
+            warnings.push(`Event on "${where}" has no action — it does nothing.`);
+            continue;
+        }
+        const def = ACTION_BY_NAME[ev.action];
+        if (!def) {
+            warnings.push(`Event on "${where}" has unknown action "${ev.action}" (see list_events).`);
+            continue;
+        }
+        for (const f of def.required || []) {
+            if (ev[f] == null || ev[f] === "")
+                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}).`);
+        }
+    }
+    return { errors, warnings };
+}
+/** Catalog for the list_events discovery tool. */
+export function describeEventsCatalog() {
+    return {
+        note: "An interactive node carries events:[{ id, eventName, action, ...fields }]. eventName = trigger, action = what happens. Build with new_element opts.events (ids are auto-minted) — e.g. new_element('button',{ text:'Mua', events:[{ action:'add_to_cart', open_page:'cart' }] }).",
+        triggers: EVENT_TRIGGERS,
+        actions: EVENT_ACTIONS.map((a) => ({
+            action: a.action,
+            category: a.category,
+            usual_trigger: a.trigger,
+            summary: a.summary,
+            ...(a.required ? { required: a.required } : {}),
+            ...(a.optional ? { optional: a.optional } : {}),
+            ...(a.target_in_page ? { references_element_on_page: a.target_in_page } : {}),
+        })),
+    };
+}

package/dist/builder/guide.js

@@ -92,14 +92,35 @@ key — only bp1..bp4.)
 - Form: wrap inputs in a \`form\`; set \`form.specials.type\`
   (form_order | form_login | form_signup | form_discount | order_tracking). Each input
   needs \`specials.field_name\`.
-- Dataset elements (text-dataset, image-dataset, rectangle-dataset...) pull live data via
-  a \`bindings\` array. Each binding is \`{ id:"BINDING"+random, name:<source>, target:"<source>::<field>" }\`.
-  Real target field names (use these EXACTLY — there is no \`product::price\`):
-  - product:  \`product::product_image\`, \`product::product_name\`, \`product::product_price\`
+- Dataset elements (text-dataset, image-dataset, rectangle-dataset…) and the CHILDREN of
+  a repeater (grid-product, cart-items, order-items, post-list, grid-category, customer-address)
+  pull live data via a \`bindings\` array. Each binding is
+  \`{ id, name:<dataset>, target:"<dataset>::<field>" }\` — you DON'T set the id, the builder
+  mints it. Just pass \`opts.bindings:[{ target:"product::product_price" }]\` to new_element.
+  Common targets (call \`list_bindings\` for the full catalog — use these EXACTLY, there is no \`product::price\`):
+  - product:  \`product::product_image\`, \`product::product_name\`, \`product::product_price\`, \`product::product_original_price\`, \`product::short_description\`
   - cart_item: \`cart_item::cart_item_image\`, \`cart_item::cart_item_name\`, \`cart_item::cart_item_price\`, \`cart_item::cart_item_total_price\`, \`cart_item::cart_item_prod_attr\`
   - order_item: \`order_item::product_image\`, \`order_item::product_name\`, \`order_item::product_quantity\`, \`order_item::items_sum_up_price\`, \`order_item::product_attrs\`
   - customer_address: \`customer_address::full_name\`, \`customer_address::phone_number\`, \`customer_address::address\`, \`customer_address::pdc\`
-  A target only resolves on a page of the matching \`type\` (see below).
+  REPEATER CONTEXT: inside a \`grid-product\` each cell IS a product, so a child
+  \`text-dataset\` with \`product::product_name\` resolves to that cell's product (no extra
+  wiring). Same for cart-items→cart_item, order-items→order_item, post-list→post,
+  grid-category→category. A target only resolves on a page of the matching \`type\` (below).
+
+## Events (clicks, navigation, cart, popups)
+Interactive nodes (button, text, image, container, rectangle, icons) carry an \`events\`
+array. Each event is \`{ id, eventName, action, ...fields }\` — you set \`action\` (+ its
+fields); the builder mints the id and picks a sensible \`eventName\` (trigger). Pass via
+\`opts.events\`. Call \`list_events\` for the full trigger/action catalog. Most-used:
+- Navigate: \`{ action:"open_page", open_page_id:"<page id>" }\`, \`{ action:"open_link", link_target:"https://…", link_target_url:"_blank" }\`, \`{ action:"open_category", open_category_id:"<id>" }\`.
+- Scroll on this page: \`{ action:"scroll_to", scroll_to_id:"<section id on this page>" }\`.
+- Show/hide: \`{ action:"toggle", toggle_id:"<element id on this page>" }\`, \`{ action:"open_popup", popup_id:"<popup id>" }\`.
+- Commerce: \`{ action:"add_to_cart", open_page:"cart" }\`, \`{ action:"buy_now" }\`, \`{ action:"apply_promotion" }\`.
+- Contact: \`{ action:"phone_call", phone_call_number:"+84…" }\`, \`{ action:"open_email", open_email:"hi@shop.vn" }\`.
+- Hover style (set eventName:"hover"): \`{ eventName:"hover", action:"scale" }\`.
+Example: \`new_element("button", { text:"Mua ngay", style:{…}, events:[{ action:"add_to_cart", open_page:"cart" }] })\`.
+validate_page warns on unknown actions, missing required fields, and events whose
+in-page target (toggle_id/scroll_to_id/…) doesn't exist on the page.
 
 ## Page types & data sources (IMPORTANT for special pages)
 A page's \`type\` decides which live data it can bind to. A SPECIAL page only works if the

package/dist/builder/page.js

@@ -6,6 +6,8 @@
 // produce that structure the same way the builder does, so generated pages render.
 import { buildElement, isKnownType, ELEMENT_TYPES } 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";
 const clone = (o) => structuredClone(o);
 /** Walk every node in a source tree (depth-first). Return false from fn to stop. */
@@ -155,13 +157,19 @@ export function validatePage(source) {
                 warnings.push(`Form field "${node.id}" (${node.type}) has no specials.field_name.`);
         }
     });
-    // Second pass: event targets must point at an element that exists in the page.
+    // Second pass: events + bindings against the authoritative catalogs (unknown
+    // trigger/action/dataset, missing required fields, dangling in-page event targets,
+    // unknown binding fields). These are warnings — they don't block a save.
     walk(source, (node) => {
-        for (const ev of node.events || []) {
-            const target = ev.open_page_id ? null : ev.target || ev.target_id;
-            if (target && !allIds.has(target)) {
-                warnings.push(`Event on "${node.id}" targets missing element "${target}".`);
-            }
+        if (node.events && node.events.length) {
+            const r = validateEvents(node, allIds);
+            errors.push(...r.errors);
+            warnings.push(...r.warnings);
+        }
+        if (node.bindings && node.bindings.length) {
+            const r = validateBindings(node);
+            errors.push(...r.errors);
+            warnings.push(...r.warnings);
         }
     });
     return {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.15.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "New get_global_section tool returns a compact tree representation of a single global section (Header/Footer/block), listing each element's id, type,…",
+    "vi": "Tool mới get_global_section trả về cây phần tử dạng compact của một global section (Header/Footer/block), liệt kê id, type, text, class, binding và…"
+  },
+  {
+    "v": "1.14.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "New list_events tool returns the authoritative interaction-events catalog: 9 triggers (click, hover, submit, success, ...) and 38 actions…",
+    "vi": "Tool mới list_events trả về danh mục sự kiện tương tác đầy đủ: 9 trigger (click, hover, submit, success, ...) và 38 action (open_page, scroll_to,…"
+  },
   {
     "v": "1.13.0",
     "d": "24/06/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "create_site_from_template now calls the dedicated import_store_to_theme API instead of the generic site-duplicate endpoint, correctly cloning the…",
     "vi": "create_site_from_template nay gọi đúng API import_store_to_theme thay vì endpoint nhân bản site thông thường, giúp clone đầy đủ các trang, global…"
-  },
-  {
-    "v": "1.11.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New create_site_from_template tool clones a marketplace template (all its pages, page-sources, and settings) into a new account-owned site, switches…",
-    "vi": "Tool mới create_site_from_template nhân bản một template marketplace (toàn bộ trang, page-source và cài đặt) thành một site mới thuộc tài khoản hiện…"
-  },
-  {
-    "v": "1.10.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New scaffold_store_pages tool creates the standard storefront pages (Category, Product, Cart, Checkout, Thank-you) so navigation links resolve…",
-    "vi": "Tool mới scaffold_store_pages tạo các trang storefront tiêu chuẩn (Category, Product, Cart, Checkout, Thank-you) để các liên kết điều hướng không bị…"
   }
 ]

package/dist/server.js

@@ -14,6 +14,9 @@ import { registerAppTools } from "./tools/apps.js";
 import { registerPromotionTools } from "./tools/promotions.js";
 import { registerComboTools } from "./tools/combos.js";
 import { registerGlobalSourceTools } from "./tools/global-sources.js";
+import { registerGlobalSectionTools } from "./tools/global-sections.js";
+import { registerGlobalSectionWriteTools } from "./tools/global-section-write.js";
+import { registerResultCacheTools } from "./tools/result-cache.js";
 import { registerImageTools } from "./tools/images.js";
 import { registerBuilderTools } from "./tools/builder.js";
 import { registerBuilderExtraTools } from "./tools/builder-extras.js";
@@ -60,6 +63,9 @@ export function createServer(api, opts = {}) {
     registerPromotionTools(server, api, handle);
     registerComboTools(server, api, handle);
     registerGlobalSourceTools(server, api, handle);
+    registerGlobalSectionTools(server, api, handle);
+    registerGlobalSectionWriteTools(server, api, handle);
+    registerResultCacheTools(server, api, handle);
     registerImageTools(server, api, handle);
     registerBuilderTools(server, api, handle);
     registerBuilderExtraTools(server, api, handle, { allowLocalFiles: opts.allowLocalFiles === true });

package/dist/tools/builder.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { BUILD_GUIDE } from "../builder/guide.js";
 import { listElements, getElement, buildElement } from "../builder/catalog.js";
+import { describeEventsCatalog } from "../builder/events.js";
+import { describeBindingsCatalog } from "../builder/bindings.js";
 import { buildSection, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
 // Recursive spec for new_section / build_page children.
 const elementSpec = z.object({
@@ -34,6 +36,8 @@ export function registerBuilderTools(server, api, handle) {
     server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, an ATTRIBUTES reference (the meaningful specials/config keys + their purpose/allowed values, events, and dataset binding targets), and a live skeleton node (the authoritative default shape) you can copy and edit. Read this before authoring/editing an element so you set the right keys.", {
         type: z.string().describe("Element type, e.g. 'text', 'button', 'grid-product'"),
     }, ({ type }) => handle(async () => getElement(type)));
+    server.tool("list_events", "List every interaction EVENT you can attach to a node: the triggers (eventName: click/hover/success/submit/…) and the actions (open_page, scroll_to, toggle, open_popup, add_to_cart, buy_now, phone_call, open_link, …) with the exact extra fields each action needs. Attach via new_element/new_section opts.events (ids are auto-minted, e.g. opts.events=[{ action:'add_to_cart', open_page:'cart' }]).", {}, () => handle(async () => describeEventsCatalog()));
+    server.tool("list_bindings", "List every dynamic-data BINDING target: the datasets (product, cart_item, order, order_item, post, category, customer, customer_address, …) and their exact field names ('product::product_price', …), which page type each needs (store/member/blog), and how repeater children (grid-product, cart-items, post-list) bind per-item. Attach via new_element opts.bindings (ids auto-minted, e.g. opts.bindings=[{ target:'product::product_price' }]).", {}, () => handle(async () => describeBindingsCatalog()));
     server.tool("new_element", "Build a single structurally-valid element node from the real builder factory. Returns the node — edit its specials/style, then place it in a section's children.", {
         type: z.string().describe("Element type (see list_elements)"),
         opts: z.record(z.any()).optional().describe("Factory opts: { text, src, width, height, style, config, specials, events }"),

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

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { validatePage, finalizeForRender } from "../builder/page.js";
+/**
+ * Write tools for global SECTIONS (Header / Footer / reusable blocks).
+ *
+ * Mirrors exactly what builderx_spa does on save (see PagePublish.vue + globalSection.js):
+ * a global section is persisted through the site `/save` pipeline as
+ *   { section_id, name, type(1=header,2=section,3=footer), pages:[pageId...],
+ *     status:"new"|"update"|"delete", section:<node>, contents:[] }
+ * matched by (site_id, section_id). The node is marked with specials.global =
+ * "header"|"section"|"footer" and carries the SAME id on every page that embeds it.
+ *
+ * For a header/footer to actually RENDER, the same node must also be injected into each
+ * page's source.sections (header → top, footer → bottom). We do both in ONE atomic /save:
+ * the global_sections upsert AND the updated page sources (which also rebuilds each page's
+ * app_css). api.saveGlobalSections sends the current site.settings so /save can't null them.
+ */
+const TYPE_NUM = { header: 1, section: 2, footer: 3 };
+function parseSource(src) {
+    if (src == null)
+        return null;
+    return typeof src === "string" ? JSON.parse(src) : src;
+}
+/** All pages with their parsed source. listPages returns each page's source under
+ *  page.source.source (a JSON string), same as the add_section tool relies on. */
+async function loadPages(api) {
+    const res = await api.listPages();
+    const pages = (res && res.data) || res || [];
+    return (Array.isArray(pages) ? pages : []).map((p) => ({
+        id: p.id,
+        name: p.name,
+        source: parseSource(p.source && p.source.source) || { sections: [] },
+    }));
+}
+/** Insert `node` into a page source at the right slot for its global type, replacing any
+ *  existing section with the same id (idempotent). Returns true if the source changed. */
+function injectNode(source, node, type) {
+    if (!source || !Array.isArray(source.sections))
+        source.sections = [];
+    const existingIdx = source.sections.findIndex((s) => s && s.id === node.id);
+    if (existingIdx !== -1)
+        source.sections.splice(existingIdx, 1);
+    if (type === "footer") {
+        source.sections.push(node);
+    }
+    else if (type === "header") {
+        source.sections.unshift(node);
+    }
+    else {
+        // reusable section → after the last header, else at top
+        const lastHeader = source.sections.map((s) => s?.specials?.global).lastIndexOf("header");
+        source.sections.splice(lastHeader + 1, 0, node);
+    }
+    return true;
+}
+export function registerGlobalSectionWriteTools(server, api, handle) {
+    server.tool("create_global_section", `Create a reusable global section (Header / Footer / shared block) the way the builder does:
+persists a global_section record AND embeds the same section node into page sources so it
+actually renders across the site (header → top of every page, footer → bottom).
+Build the section first with new_section (give it a real bg/padding + logo/menu/links), then pass it here.
+Two-step safety: dry_run=true (default) previews which pages change; dry_run=false performs the atomic save.`, {
+        type: z.enum(["header", "section", "footer"]).describe("header = top chrome (logo/nav/cart), footer = bottom chrome, section = reusable content block"),
+        name: z.string().describe("Display name in the editor (e.g. 'Header', 'Footer')"),
+        section: z.any().describe("A section node from new_section (object or JSON string) — the content of the header/footer."),
+        page_ids: z.array(z.string()).optional().describe("Pages to embed into. Omit to apply to ALL pages of the site (typical for header/footer)."),
+        dry_run: z.boolean().default(true).describe("Preview which pages would change (true) or perform the atomic save (false)."),
+    }, ({ type, name, section, page_ids, dry_run }) => handle(async () => {
+        const node = parseSource(section);
+        if (!node || node.type !== "section") {
+            return { error: "`section` must be a section node (type:'section') built with new_section." };
+        }
+        if (!node.id)
+            return { error: "section node has no id." };
+        // Mark it as a global section and expand runtime → bp1..bp4 (renderer reads bpN).
+        node.specials = { ...(node.specials || {}), global: type };
+        const wrap = { sections: [node] };
+        const validation = validatePage(wrap);
+        if (!validation.valid)
+            return { error: "Section failed validation.", validation };
+        finalizeForRender(wrap);
+        const finalNode = wrap.sections[0];
+        // Resolve target pages + inject the node into each one's source.
+        const allPages = await loadPages(api);
+        const targets = page_ids && page_ids.length
+            ? allPages.filter((p) => page_ids.includes(p.id))
+            : allPages;
+        if (!targets.length)
+            return { error: "No matching pages to attach the global section to." };
+        const changedPages = targets.map((p) => {
+            injectNode(p.source, finalNode, type);
+            return { id: p.id, name: p.name, source: JSON.stringify(p.source) };
+        });
+        const targetIds = targets.map((p) => p.id);
+        const globalSection = {
+            section_id: finalNode.id,
+            name,
+            type: TYPE_NUM[type],
+            pages: targetIds,
+            section: finalNode,
+            status: "new",
+            contents: [],
+        };
+        if (dry_run) {
+            return {
+                dry_run: true,
+                section_id: finalNode.id,
+                type,
+                name,
+                embeds_into_pages: targets.map((p) => ({ id: p.id, name: p.name })),
+                page_count: targets.length,
+                hint: "Call again with dry_run=false to create the global section and embed it. Then publish_site to take it live.",
+            };
+        }
+        const changes = targetIds.reduce((o, id) => { o[id] = 1; return o; }, {});
+        const res = await api.saveGlobalSections({ global_sections: [globalSection], pages: changedPages.map(({ id, source }) => ({ id, source })), changes });
+        const ok = !!(res && (res.success || res.data));
+        return {
+            success: ok,
+            section_id: finalNode.id,
+            type,
+            name,
+            embedded_pages: targetIds.length,
+            note: "Publish the site (publish_site) to take the new header/footer live.",
+            raw: ok ? undefined : res,
+        };
+    }));
+    server.tool("delete_global_section", `Delete a global section (Header/Footer/block) and remove its node from every page source.
+Two-step safety: dry_run=true (default) shows which pages would change; dry_run=false performs the atomic save.`, {
+        section_id: z.string().describe("The global section's section_id (the section node id) — from list_global_sections."),
+        dry_run: z.boolean().default(true).describe("Preview (true) or perform the delete + page cleanup (false)."),
+    }, ({ section_id, dry_run }) => handle(async () => {
+        const allPages = await loadPages(api);
+        const affected = allPages.filter((p) => Array.isArray(p.source.sections) && p.source.sections.some((s) => s && s.id === section_id));
+        if (dry_run) {
+            return {
+                dry_run: true,
+                section_id,
+                removes_from_pages: affected.map((p) => ({ id: p.id, name: p.name })),
+                page_count: affected.length,
+                hint: "Call again with dry_run=false to delete the global section and clean it out of those pages.",
+            };
+        }
+        const changedPages = affected.map((p) => {
+            p.source.sections = p.source.sections.filter((s) => !(s && s.id === section_id));
+            return { id: p.id, source: JSON.stringify(p.source) };
+        });
+        const changes = affected.reduce((o, p) => { o[p.id] = 1; return o; }, {});
+        const res = await api.saveGlobalSections({
+            global_sections: [{ section_id, status: "delete", section: null }],
+            pages: changedPages,
+            changes,
+        });
+        const ok = !!(res && (res.success || res.data));
+        return { success: ok, section_id, cleaned_pages: changedPages.length, note: "Publish the site to apply.", raw: ok ? undefined : res };
+    }));
+}

package/dist/tools/global-sections.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { buildOverview, buildTreeText, searchElements, nodeToDetail, findNodeById, } from "./global-sources.js";
+import { cacheLarge } from "./result-cache.js";
+/**
+ * Global SECTIONS tools — reusable page chrome (Header, Footer) + shared content
+ * blocks (breadcrumb, "about", product strips) that pages embed by reference.
+ *
+ * Why this module exists: the raw `GET /global_sections` response is HUGE (a real
+ * site's Header+Footer trees alone are >1MB), which overflows the tool-result token
+ * budget. So instead of dumping the whole tree, we:
+ *   - cache the fetched list for the session (30s TTL) so drill-down is free, and
+ *   - expose SLIM tools: a summary list, a compact per-section tree, and
+ *     element search / element detail — mirroring the global_sources tools.
+ *
+ * Shape note: each global section's element tree lives under `gs.section` (a single
+ * section node with `children`), NOT under `gs.source`. `gs.contents` is the
+ * (usually empty) multilingual override list. `gs.type` is the chrome slot:
+ * 1 = header, 3 = footer, 2 = reusable content block.
+ */
+const TYPE_LABEL = { 1: "header", 2: "block", 3: "footer" };
+const CACHE_TTL = 30000;
+let _cache = null;
+/** Pull the array of global sections out of the various response envelopes. */
+function extractList(res) {
+    if (!res)
+        return [];
+    if (Array.isArray(res))
+        return res;
+    if (Array.isArray(res.global_sections))
+        return res.global_sections;
+    if (res.data) {
+        if (Array.isArray(res.data))
+            return res.data;
+        if (Array.isArray(res.data.global_sections))
+            return res.data.global_sections;
+    }
+    return [];
+}
+async function fetchSections(api, force = false) {
+    if (!force && _cache && Date.now() - _cache.time < CACHE_TTL)
+        return _cache.items;
+    const res = await api.listGlobalSections();
+    const items = extractList(res);
+    _cache = { items, time: Date.now() };
+    return items;
+}
+/** The element-tree root of a global section is its `section` node. */
+function rootOf(gs) {
+    return gs && gs.section ? gs.section : null;
+}
+function summarize(gs) {
+    const root = rootOf(gs);
+    const ov = root ? buildOverview(root) : null;
+    const langs = Array.isArray(gs.contents) ? gs.contents.map((c) => c.language_code).filter(Boolean) : [];
+    return {
+        id: gs.id,
+        name: gs.name,
+        type: gs.type,
+        slot: TYPE_LABEL[gs.type] || "block",
+        elements: ov ? ov.elements : 0,
+        types: ov ? ov.types : {},
+        classes: ov ? ov.classes : [],
+        contents_langs: langs,
+    };
+}
+async function resolveSection(api, id) {
+    let items = await fetchSections(api);
+    let found = items.find((g) => String(g.id) === String(id));
+    if (!found) {
+        items = await fetchSections(api, true); // force refresh once
+        found = items.find((g) => String(g.id) === String(id));
+    }
+    return found || null;
+}
+export function registerGlobalSectionTools(server, api, handle) {
+    server.tool("list_global_sections", `List reusable global sections (Header, Footer, shared content blocks) — SLIM summary only.
+Each entry: id, name, slot (header/footer/block), element count + type histogram + custom classes.
+The full element tree is large, so it is NOT returned here — drill in with get_global_section
+(compact tree), search_global_section_elements, or get_global_section_element.`, {}, () => handle(async () => {
+        const items = await fetchSections(api);
+        return {
+            count: items.length,
+            global_sections: items.map(summarize),
+            hint: "Use get_global_section(global_section_id) for a compact element tree of one section.",
+        };
+    }));
+    server.tool("get_global_section", `Get one global section as a COMPACT tree (3-5x fewer tokens than raw JSON).
+Each line: ID [type] "text" .class [Nbind] [Nev] (children_count).
+Use this to learn how a real Header/Footer/block is composed before building your own.`, {
+        global_section_id: z.string().describe("Global section ID (from list_global_sections)"),
+        raw: z.boolean().default(false).describe("Return the FULL raw section JSON (large) instead of the compact tree — delivered via the large-result cache so you can split-read it with read_cached_result."),
+    }, ({ global_section_id, raw }) => handle(async () => {
+        const gs = await resolveSection(api, global_section_id);
+        if (!gs)
+            return { error: `Global section "${global_section_id}" not found. Call list_global_sections first.` };
+        const root = rootOf(gs);
+        if (raw) {
+            // Full fidelity — cache-then-split-read so even a >1MB tree is reachable.
+            return cacheLarge(`global_section:${gs.name || gs.id}`, root || {});
+        }
+        return {
+            id: gs.id,
+            name: gs.name,
+            slot: TYPE_LABEL[gs.type] || "block",
+            overview: root ? buildOverview(root) : null,
+            tree: root ? buildTreeText(root) : "(empty)",
+            hint: "Use get_global_section_element(global_section_id, element_id) for full style/config of one node. Pass raw=true for the full JSON via the cache.",
+        };
+    }));
+    server.tool("search_global_section_elements", `Search/filter elements within a global section (Header/Footer/block) without dumping the whole tree.
+Filter by type, id substring, custom_class, text, or has_bind / has_events / has_custom_class.`, {
+        global_section_id: z.string().describe("Global section ID"),
+        type: z.string().optional().describe("Filter by element type (e.g. 'menu', 'menu-item', 'container', 'image', 'text')"),
+        id: z.string().optional().describe("Filter by element ID substring"),
+        custom_class: z.string().optional().describe("Filter by custom class substring"),
+        text: z.string().optional().describe("Filter by text content substring"),
+        has_custom_class: z.boolean().optional().describe("Only elements with a custom class"),
+        has_bind: z.boolean().optional().describe("Only elements with data bindings"),
+        has_events: z.boolean().optional().describe("Only elements with events"),
+        limit: z.number().default(50).describe("Max results (default 50)"),
+    }, ({ global_section_id, ...filters }) => handle(async () => {
+        const gs = await resolveSection(api, global_section_id);
+        if (!gs)
+            return { error: `Global section "${global_section_id}" not found.` };
+        const root = rootOf(gs);
+        if (!root)
+            return { error: "Global section has no element tree." };
+        const results = searchElements(root, filters);
+        return { global_section_id, matched: results.length, elements: results };
+    }));
+    server.tool("get_global_section_element", "Get full detail (style, config, specials, events, bindings, responsive bp1..bp4, children IDs) of a single element inside a global section.", {
+        global_section_id: z.string().describe("Global section ID"),
+        element_id: z.string().describe("Element ID (e.g. 'MENU-1', 'TEXT-3')"),
+    }, ({ global_section_id, element_id }) => handle(async () => {
+        const gs = await resolveSection(api, global_section_id);
+        if (!gs)
+            return { error: `Global section "${global_section_id}" not found.` };
+        const root = rootOf(gs);
+        if (!root)
+            return { error: "Global section has no element tree." };
+        const node = findNodeById(root, element_id);
+        if (!node)
+            return { error: `Element "${element_id}" not found in global section.` };
+        const detail = nodeToDetail(node);
+        if (node.children && node.children.length) {
+            detail.children = node.children.map((c) => ({ id: c.id, type: c.type }));
+        }
+        return detail;
+    }));
+}

package/dist/tools/global-sources.js

@@ -13,7 +13,7 @@ import { getConfirmMode } from "./context.js";
  * - Safeguard on full source update (block if data shrinks >50%)
  */
 // ── Source tree helpers ──
-function parseSource(sourceJson) {
+export function parseSource(sourceJson) {
     try {
         return typeof sourceJson === "string" ? JSON.parse(sourceJson) : sourceJson;
     }
@@ -25,7 +25,7 @@ function parseSource(sourceJson) {
  *  - Page format: { sections: [...] } → returns sections array
  *  - Global source format: { id, type, children: [...] } → returns [rootNode]
  */
-function getRoots(source) {
+export function getRoots(source) {
     if (!source)
         return [];
     if (source.sections)
@@ -52,7 +52,7 @@ function walkSource(source, fn) {
             return;
     }
 }
-function buildOverview(source) {
+export function buildOverview(source) {
     const typeCounts = {};
     const customClasses = new Set();
     let total = 0;
@@ -72,7 +72,7 @@ function buildOverview(source) {
         classes: [...customClasses].sort(),
     };
 }
-function nodeToDetail(node) {
+export function nodeToDetail(node) {
     const entry = { id: node.id || "", type: node.type || "unknown" };
     if (node.style && Object.keys(node.style).length)
         entry.style = node.style;
@@ -95,7 +95,7 @@ function nodeToDetail(node) {
         entry.children_count = node.children.length;
     return entry;
 }
-function findNodeById(source, elementId) {
+export function findNodeById(source, elementId) {
     let found = null;
     walkSource(source, (node) => {
         if (node.id === elementId) {
@@ -165,7 +165,7 @@ function applyNodeUpdates(node, updates) {
         }
     }
 }
-function searchElements(source, filters) {
+export function searchElements(source, filters) {
     const results = [];
     const limit = filters.limit || 50;
     walkSource(source, (node) => {
@@ -206,7 +206,7 @@ function searchElements(source, filters) {
  *   │  └─ TEXT-2 [text] "Product name"
  *   └─ BUTTON-1 [button] "Thanh toán" .checkout-btn [2ev]
  */
-function buildTreeText(source) {
+export function buildTreeText(source) {
     const roots = getRoots(source);
     if (!roots.length)
         return "(empty)";

package/dist/tools/pages.js

@@ -434,7 +434,8 @@ IMPORTANT: Before calling, you MUST read existing content with list_page_content
         }
         return api.updatePageContent({ page_id, language_code, content, meta_tags });
     }));
-    server.tool("list_global_sections", "List reusable global sections", {}, () => handle(() => api.listGlobalSections()));
+    // list_global_sections (+ get/search/element drill-downs) live in tools/global-sections.ts
+    // — they return SLIM summaries instead of the raw multi-MB tree this endpoint produces.
     // ── Element interaction tools ──
     server.tool("get_page_element", "Get full detail of a single element by its ID (e.g. 'TEXT-3', 'BUTTON-1', 'SECTION-2'). Returns style, config, specials, events, bindings, responsive, and children IDs", {
         page_id: z.string().describe("Page ID"),

package/dist/tools/result-cache.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+const _cache = new Map();
+let _seq = 0;
+const TTL_MS = 10 * 60 * 1000;
+const DEFAULT_THRESHOLD = 20000; // chars — comfortably under the tool-result token budget
+const DEFAULT_CHUNK = 12000;
+function prune(now) {
+    for (const [k, v] of _cache)
+        if (now - v.created > TTL_MS)
+            _cache.delete(k);
+}
+/**
+ * Pass-through if small, otherwise cache and return a read handle.
+ * @returns `{ cached:false, data }` or `{ cached:true, cache_id, total_chars, ... }`
+ */
+export function cacheLarge(label, data, threshold = DEFAULT_THRESHOLD) {
+    const text = typeof data === "string" ? data : JSON.stringify(data);
+    if (text.length <= threshold)
+        return { cached: false, data };
+    const now = Date.now();
+    prune(now);
+    const id = `cache-${++_seq}`;
+    _cache.set(id, { text, label, created: now });
+    return {
+        cached: true,
+        cache_id: id,
+        label,
+        total_chars: text.length,
+        total_lines: text.split("\n").length,
+        preview: text.slice(0, 1500),
+        hint: `Large result cached (${text.length} chars). Read it in chunks with read_cached_result(cache_id="${id}", offset:0, length:${DEFAULT_CHUNK}). Expires in ${TTL_MS / 60000} min.`,
+    };
+}
+/** Direct accessor for other modules (e.g. to peek a cached entry). */
+export function getCached(id) {
+    return _cache.get(id);
+}
+export function registerResultCacheTools(server, _api, handle) {
+    server.tool("read_cached_result", `Read a slice of a large cached result produced by another tool (look for "cached":true + a cache_id in its output).
+Page through with offset/length; the response reports next_offset + remaining_chars until done.`, {
+        cache_id: z.string().describe('The cache_id returned by the producing tool (e.g. "cache-3")'),
+        offset: z.number().default(0).describe("Start character offset (default 0)"),
+        length: z.number().default(DEFAULT_CHUNK).describe(`Number of characters to return (default ${DEFAULT_CHUNK})`),
+    }, ({ cache_id, offset, length }) => handle(async () => {
+        const entry = _cache.get(cache_id);
+        if (!entry)
+            return { error: `Cache "${cache_id}" not found or expired. Re-run the producing tool.` };
+        const start = Math.max(0, offset);
+        const end = Math.min(entry.text.length, start + Math.max(1, length));
+        const slice = entry.text.slice(start, end);
+        const done = end >= entry.text.length;
+        return {
+            cache_id,
+            label: entry.label,
+            offset: start,
+            returned_chars: slice.length,
+            total_chars: entry.text.length,
+            next_offset: done ? null : end,
+            remaining_chars: entry.text.length - end,
+            done,
+            chunk: slice,
+        };
+    }));
+    server.tool("list_cached_results", "List the large results currently held in the session cache (id, label, size, age).", {}, () => handle(async () => {
+        const now = Date.now();
+        prune(now);
+        return {
+            count: _cache.size,
+            cached: [..._cache.entries()].map(([id, e]) => ({
+                cache_id: id,
+                label: e.label,
+                total_chars: e.text.length,
+                age_seconds: Math.round((now - e.created) / 1000),
+            })),
+        };
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.13.0",
+  "version": "1.15.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",