webcake-storefront-mcp 1.13.0 → 1.14.0

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,11 @@
 [
+  {
+    "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",
@@ -33,12 +40,5 @@
     "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/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/package.json

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