webcake-storefront-mcp 1.14.0 → 1.15.1

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

@@ -202,6 +202,8 @@ export function normalizeBindings(bindings) {
     if (!Array.isArray(bindings))
         return bindings;
     return bindings.map((b) => {
+        if (typeof b === "string")
+            return makeBinding(b); // bare "name::field" target
         if (!b || typeof b !== "object")
             return b;
         if (b.id && b.name)

package/dist/builder/catalog.js

@@ -166,7 +166,7 @@ export function buildElement(type, opts = {}) {
     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);
+        node.events = normalizeEvents(node.events, node.type);
     return node;
 }
 export function isKnownType(type) {

package/dist/builder/events.js

@@ -80,25 +80,45 @@ export function isKnownTrigger(name) {
 export function getEventAction(action) {
     return ACTION_BY_NAME[action];
 }
+// Element types whose events only fire on a specific trigger — mirrors builderx_spa
+// components/editor/traits/Events.vue `addEvent()`. For these the element-type trigger
+// is the right default (a click handler on a form never fires); for everything else the
+// action's usual trigger (or "click") wins.
+const SPECIAL_EVENT_TRIGGER = {
+    form: "success",
+    swiper: "tab",
+    popup: "hide",
+    "input-search": "onenter",
+    "submit-button": "hover",
+};
+/** The trigger the builder defaults to for a given element type, if it is a special one. */
+export function defaultTriggerForType(type) {
+    return type ? SPECIAL_EVENT_TRIGGER[type] : undefined;
+}
 /**
  * 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.
+ * eventName precedence (mirrors the editor): explicit > element-type default
+ * (form→success, swiper→tab, popup→hide, input-search→onenter, submit-button→hover) >
+ * the action's usual trigger > "click".
  *   makeEvent({ action: "scroll_to", scroll_to_id: "SECTION-x" })
- *   makeEvent({ action: "open_link", eventName: "click", link_target: "https://…" })
+ *   makeEvent({ action: "open_page", open_page_id: "…" }, "form") // eventName → "success"
  */
-export function makeEvent(spec) {
+export function makeEvent(spec, elementType) {
     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 = spec.eventName || defaultTriggerForType(elementType) || (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) {
+/** Ensure every event in an array has an id + an eventName (mint where missing).
+ *  Pass the owning element's type so special types get the right default trigger.
+ *  Round-trip safe: events that already carry id/eventName are preserved verbatim. */
+export function normalizeEvents(events, elementType) {
     if (!Array.isArray(events))
         return events;
-    return events.map((e) => (e && typeof e === "object" ? makeEvent(e) : e));
+    return events.map((e) => (e && typeof e === "object" ? makeEvent(e, elementType) : e));
 }
 /** Validate one element's events against the catalog + the set of ids present in the page. */
 export function validateEvents(node, allIds) {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.15.1",
+    "d": "24/06/2026",
+    "type": "Fixed",
+    "en": "update_page_element, update_page_elements, update_global_source_element, and update_global_source_elements now normalize events and bindings arrays…",
+    "vi": "update_page_element, update_page_elements, update_global_source_element và update_global_source_elements nay chuẩn hóa mảng events và bindings khi…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New update_product tool updates an existing product's name, description, images, category_ids, is_published flag, or variations (price/stock/SKU per…",
     "vi": "Tool mới update_product cập nhật name, description, images, category_ids, cờ is_published hoặc variations (giá/tồn kho/SKU theo từng biến thể) của…"
-  },
-  {
-    "v": "1.11.1",
-    "d": "24/06/2026",
-    "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…"
   }
 ]

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/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

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { getConfirmMode } from "./context.js";
+import { normalizeEvents } from "../builder/events.js";
+import { normalizeBindings } from "../builder/bindings.js";
 /**
  * Global Sources tools — manage site-wide components: cart, popup, overview, etc.
  *
@@ -13,7 +15,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 +27,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 +54,7 @@ function walkSource(source, fn) {
             return;
     }
 }
-function buildOverview(source) {
+export function buildOverview(source) {
     const typeCounts = {};
     const customClasses = new Set();
     let total = 0;
@@ -72,7 +74,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 +97,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) {
@@ -151,10 +153,11 @@ function applyNodeUpdates(node, updates) {
         node.config = { ...(node.config || {}), ...updates.config };
     if (updates.specials)
         node.specials = { ...(node.specials || {}), ...updates.specials };
+    // Normalize so updated events/bindings get a valid id + eventName (renderer needs it).
     if (updates.events !== undefined)
-        node.events = updates.events;
+        node.events = normalizeEvents(updates.events, node.type);
     if (updates.bindings !== undefined)
-        node.bindings = updates.bindings;
+        node.bindings = normalizeBindings(updates.bindings);
     if (updates.responsive) {
         for (const [bp, val] of Object.entries(updates.responsive)) {
             if (/^bp\d+$/.test(bp)) {
@@ -165,7 +168,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 +209,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)";
@@ -432,7 +435,8 @@ STEP 1: Call with dry_run=true (default) → returns diff of what will change.
 STEP 2: Show the diff to the user and ask for confirmation. NEVER proceed without explicit user approval.
 STEP 3: Only after user confirms, call again with dry_run=false to apply.
 IMPORTANT: You MUST show the diff to the user and get explicit "yes/ok/confirm" before calling with dry_run=false. Skipping confirmation risks data loss.
-Merge rules: style/config/specials = shallow merge, events/bindings = replace array, responsive = merge by bp key.`, {
+Merge rules: style/config/specials = shallow merge, responsive = merge by bp key.
+events/bindings = REPLACE the whole array — pass the COMPLETE list (read it first); entries are auto-normalized (id + eventName filled in).`, {
         global_source_id: z.string().describe("Global source ID"),
         element_id: z.string().describe("Element ID to update (e.g. 'TEXT-3', 'BUTTON-1')"),
         component: z.string().optional().describe('Component hint for faster lookup'),

package/dist/tools/pages.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { CUSTOM_CODE_GUIDE } from "../guides.js";
 import { getConfirmMode } from "./context.js";
+import { normalizeEvents } from "../builder/events.js";
+import { normalizeBindings } from "../builder/bindings.js";
 /**
  * Page source utilities.
  *
@@ -145,10 +147,13 @@ function applyNodeUpdates(node, updates) {
         node.config = { ...(node.config || {}), ...updates.config };
     if (updates.specials)
         node.specials = { ...(node.specials || {}), ...updates.specials };
+    // Normalize so updated events/bindings carry a valid id + eventName (and the right
+    // element-type default trigger) — the storefront renderer won't dispatch an event with
+    // no eventName. Round-trip safe: already-formed entries pass through unchanged.
     if (updates.events !== undefined)
-        node.events = updates.events;
+        node.events = normalizeEvents(updates.events, node.type);
     if (updates.bindings !== undefined)
-        node.bindings = updates.bindings;
+        node.bindings = normalizeBindings(updates.bindings);
     // Responsive breakpoints (bp1, bp2, ...)
     if (updates.responsive) {
         for (const [bp, val] of Object.entries(updates.responsive)) {
@@ -434,7 +439,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"),
@@ -459,7 +465,8 @@ STEP 1: Call with dry_run=true (default) → returns diff of what will change.
 STEP 2: Show the diff to the user and ask for confirmation. NEVER proceed without explicit user approval.
 STEP 3: Only after user confirms, call again with dry_run=false to apply.
 IMPORTANT: You MUST show the diff to the user and get explicit "yes/ok/confirm" before calling with dry_run=false. Skipping confirmation risks data loss.
-Merge rules: style/config/specials = shallow merge, events/bindings = replace array, responsive = merge by bp key.`, {
+Merge rules: style/config/specials = shallow merge, responsive = merge by bp key.
+events/bindings = REPLACE the whole array — pass the COMPLETE list (read it first with get_page_element so you don't drop the others); entries are auto-normalized (id + eventName filled in, so you can pass just { action, ...fields } / { target }).`, {
         page_id: z.string().describe("Page ID"),
         element_id: z.string().describe("Element ID to update (e.g. 'TEXT-3', 'BUTTON-1')"),
         dry_run: z.boolean().optional().describe("Preview only (true) or apply changes (false). Defaults to confirm_mode setting. Use toggle_confirm_mode to change default."),

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.14.0",
+  "version": "1.15.1",
   "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",