webcake-storefront-mcp 1.31.4 → 1.31.6

package/README.md

@@ -1,4 +1,8 @@
-# 🏪 WebCake Storefront MCP
+<p align="center">
+  <img src="./assets/logo.svg" alt="WebCake Storefront MCP" width="96" height="96">
+</p>
+
+<h1 align="center">WebCake Storefront MCP</h1>
 
 **English** · [Tiếng Việt](./README.vi.md)
 
@@ -78,7 +82,7 @@ An MCP (Model Context Protocol) server that teaches AI agents the **WebCake/Stor
 page source; `build_page` creates the page and saves it, and `publish_site` makes the whole site live.
 
 Beyond page authoring, it exposes your real store: pages & custom code, products, orders, collections,
-blog articles, promotions, combos, themes, customers, and automation — **~101 tools** in total.
+blog articles, promotions, combos, themes, customers, and automation — **~280 tools** in total.
 
 | Method | Best for | Auth |
 |--------|----------|------|
@@ -166,7 +170,7 @@ in chat via `update_auth` and `switch_site` — saved to a local config file at
 
 ## 🧰 The tools at a glance
 
-~101 tools. The headline group **builds pages**; the rest read and edit your live store.
+~280 tools. The headline group **builds pages**; the rest read and edit your live store.
 
 | Group | Tools | Needs |
 |-------|-------|-------|

package/README.vi.md

@@ -1,4 +1,8 @@
-# 🏪 WebCake Storefront MCP
+<p align="center">
+  <img src="./assets/logo.svg" alt="WebCake Storefront MCP" width="96" height="96">
+</p>
+
+<h1 align="center">WebCake Storefront MCP</h1>
 
 [English](./README.md) · **Tiếng Việt**
 
@@ -78,7 +82,7 @@ WebCake/StoreCake (BuilderX)** và kết nối tới backend. AI tạo nguồn t
 `build_page` tạo + lưu trang, `publish_site` đưa cả site lên live.
 
 Ngoài dựng trang, nó mở ra cả store thật: trang & custom code, sản phẩm, đơn hàng, collection,
-bài blog, khuyến mãi, combo, theme, khách hàng, automation — **~101 tool** tổng cộng.
+bài blog, khuyến mãi, combo, theme, khách hàng, automation — **~280 tool** tổng cộng.
 
 | Cách | Hợp cho | Auth |
 |--------|----------|------|
@@ -165,7 +169,7 @@ trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình
 
 ## 🧰 Bộ công cụ tổng quan
 
-~101 tool. Nhóm chủ lực **dựng trang**; phần còn lại đọc và sửa store thật của bạn.
+~280 tool. Nhóm chủ lực **dựng trang**; phần còn lại đọc và sửa store thật của bạn.
 
 | Nhóm | Tool | Cần |
 |-------|-------|-------|

package/dist/api.js

@@ -150,19 +150,19 @@ export class WebcakeCmsApi {
     /** Create a page. The backend creates the page AND its source in one call, so `source`
      *  is REQUIRED and must be a JSON string (stringified here if an object is passed).
      *  `slug`/`is_homepage` are NOT applied at create — set them afterwards via updatePage. */
-    createPage(params) {
+    createPage(params, opts) {
         const body = { ...params };
         if (body.source != null && typeof body.source !== "string")
             body.source = JSON.stringify(body.source);
         if (body.source == null)
             body.source = JSON.stringify({ sections: [] });
-        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body });
+        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body, timeout: opts?.timeout });
     }
     updatePage(pageId, params) {
         return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page`, { body: params });
     }
-    updatePageSource(pageId, params) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page_source`, { body: params });
+    updatePageSource(pageId, params, opts) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page_source`, { body: params, timeout: opts?.timeout });
     }
     deletePage(params) {
         return this.request("POST", `/api/v1/site/${this.siteId}/delete_page`, { body: params });
@@ -246,11 +246,20 @@ export class WebcakeCmsApi {
         });
         return { rebuilt: pages.length };
     }
-    /** Publish the site live. /publish runs the full "save" pipeline, which OVERWRITES
-     *  site.settings with the body's `settings` — so we send the CURRENT settings (else
-     *  they'd be nulled, disabling use_store/use_blog/etc.). Other collections default to [].
-     *  We ALSO rebuild every page's CSS first (rebuildSiteCss) because /publish alone does
-     *  not regenerate the storefront's dynamic CSS — without it the live site looks unstyled. */
+    /** Publish the site live. /publish snapshots the pages in the body into the LIVE version —
+     *  exactly like the builder's "Xuất bản" button (PagePublish.vue): it POSTs every page as
+     *  `{ source, id, type, slug, is_homepage, settings }` plus a `changes` map. Sending NO
+     *  pages (the old behaviour) made the backend publish nothing, so the storefront stayed on
+     *  "Trang chưa có giao diện hoặc chưa xuất bản" and every page kept is_build=false.
+     *  We also (a) keep the CURRENT site.settings so /publish doesn't null the theme + data-source
+     *  flags (use_store/use_blog/…), and (b) rebuild each page's compiled CSS first (rebuildSiteCss),
+     *  because /publish alone does not regenerate the storefront's dynamic CSS.
+     *  Global header/footer are already embedded inside each page's source, so they publish with
+     *  the page; the global_* arrays stay empty (empty = leave server-side globals untouched).
+     *  Pass `domain` (the site's live URL, e.g. https://<slug>.webcake.me) — builderx_spa sends
+     *  `domain: this.link` and without it the backend publishes to an EXPIRING preview. The
+     *  publish_site tool fills it from resolvePreviewUrl. Final body mirrors PagePublish.vue:
+     *  { pages, settings, changes, domain, global_sources:[], global_sections:[], page_contents:[] }. */
     async publishSite(params = {}) {
         let settings = params.settings;
         if (settings === undefined) {
@@ -259,11 +268,46 @@ export class WebcakeCmsApi {
         // The save pipeline stores site.settings as a JSON STRING — an object body is
         // rejected (422). Stringify unless the caller already passed a string.
         const settingsStr = typeof settings === "string" ? settings : JSON.stringify(settings || {});
+        // Collect every page WITH its saved source so the backend has something to publish.
+        let pages = params.pages;
+        let changes = params.changes;
+        if (!Array.isArray(pages)) {
+            const res = await this.listPages();
+            const list = (res && res.data) || res || [];
+            pages = (Array.isArray(list) ? list : [])
+                .map((p) => {
+                const src = p && p.source && p.source.source;
+                if (src == null || src === "")
+                    return null;
+                return {
+                    id: p.id,
+                    source: typeof src === "string" ? src : JSON.stringify(src),
+                    type: p.type,
+                    slug: p.slug,
+                    is_homepage: p.is_homepage === true,
+                    settings: JSON.stringify(p.settings || {}),
+                };
+            })
+                .filter(Boolean);
+        }
+        if (changes === undefined) {
+            changes = {};
+            for (const p of pages)
+                changes[p.id] = 1;
+        }
         // Regenerate compiled CSS for every page before publishing (no-op-safe on failure).
         await this.rebuildSiteCss(settingsStr).catch(() => { });
         return this.request("POST", `/api/v1/site/${this.siteId}/publish`, {
-            body: { global_sources: [], global_sections: [], page_contents: [], ...params, settings: settingsStr },
-            timeout: 60000,
+            body: {
+                pages,
+                changes,
+                global_sources: [],
+                global_sections: [],
+                page_contents: [],
+                ...params,
+                settings: settingsStr,
+            },
+            timeout: 120000,
         });
     }
     uploadImageBase64({ base64, content_type } = {}) {

package/dist/builder/catalog.js

@@ -163,6 +163,13 @@ export function buildElement(type, opts = {}) {
         node.bindings = opts.bindings;
     if (opts.events && !node.events)
         node.events = opts.events;
+    // Responsive CASCADE overrides: sparse per-breakpoint diffs ({ bp2|bp3|bp4: { style?, config? } }).
+    // Stashed on runtime.responsive; finalizeForRender cascades them bp1→bp4 (each smaller
+    // breakpoint inherits the resolved larger one, then applies its own diff).
+    if (opts.responsive && typeof opts.responsive === "object") {
+        node.runtime = node.runtime || {};
+        node.runtime.responsive = opts.responsive;
+    }
     if (Array.isArray(node.bindings) && node.bindings.length)
         node.bindings = normalizeBindings(node.bindings);
     if (Array.isArray(node.events) && node.events.length)

package/dist/builder/guide.js

@@ -2,6 +2,62 @@
 // page model well enough to author pages that actually render.
 export const BUILD_GUIDE = `# BuilderX page authoring guide
 
+## DESIGN SYSTEM — lock this FIRST, every build (this is what makes free composition look DESIGNED)
+There are NO page templates here and NO seeded data — you COMPOSE every page from elements
+based on the user's actual goal. To make that composition look intentional (not a random pile
+of default elements), LOCK a small design system before you place anything, and reuse it on
+EVERY section and EVERY page:
+- PALETTE — from the site THEME matrix vars \`var(--color_RC)\` (see Colours below). Pick: page
+  background, body text, one accent (for CTAs/prices/highlights), one or two soft section tints.
+- TYPE SCALE — h1 40–56px / fontWeight 700, h2 28–34px / 600, body 16–18px with lineHeight "1.6",
+  small/muted 13–14px. Use the SAME sizes everywhere; don't invent a new size per section.
+- SPACING — everything on an 8px grid: 8 / 16 / 24 / 32 / 48 / 64. Section padding 64–96px,
+  rowGap 16–24 inside sections. Generous whitespace = premium; cramped = cheap.
+- ONE BUTTON SPEC — decide it once and reuse: e.g. \`{ background:"var(--color_24)",
+  color:"var(--color_00)", borderRadius:"8px", fontWeight:"600", height:48 }\`. Same button on
+  every page.
+- ONE CARD SPEC + ONE CONTENT WIDTH + ONE RADIUS — reuse the same card padding/radius/shadow and
+  the same centred content width across sections. Consistency = looks professionally designed.
+
+⚠️ CONTRAST is the #1 ugliness/bug — get it right:
+- The BRAND row \`var(--color_2C)\` goes LIGHT → DARK: \`var(--color_20)\` (lightest tint) …
+  \`var(--color_24)\` (darkest brand).
+- Button / CTA / price BACKGROUNDS must use \`var(--color_24)\` (dark brand) WITH a white label
+  \`var(--color_00)\`. This is readable on every theme.
+- NEVER put a white label on \`var(--color_20)\` — on many themes that's a pale tint (e.g. #f2decc)
+  and white text becomes INVISIBLE. Use \`var(--color_20)\`/\`var(--color_21)\` ONLY as soft section
+  tints / backgrounds, never as a button background under white text.
+- Body text = \`var(--color_04)\` (near-black). Page background = \`var(--color_00)\` (white).
+
+IMAGES (or the page looks broken/empty):
+- Every image needs a WebCake-CDN url (search_images → cdn_url, or upload_images), or it won't
+  render — the storefront whitelists image domains.
+- HERO must be a REAL full-width \`image\` element (width:"100%"), NOT a CSS \`background:url(...)\`
+  shorthand — the renderer ignores the shorthand and you get a blank band.
+- grid-product cards show the PRODUCT-LEVEL image, so create products WITH a product image or the
+  cards are blank.
+
+COLOR & SPACING DISCIPLINE:
+- ONE accent, used sparingly (CTAs, prices, a few highlights) — not on everything.
+- Alternate plain (\`var(--color_00)\`) and softly-tinted (\`var(--color_01)\`/\`var(--color_20)\`)
+  section backgrounds to give the page rhythm.
+- Reuse the SAME content width + radius + button across sections.
+
+COMPOSE, DON'T TEMPLATE — there are no templates and no seeded data, so for each page:
+1. Pick a SECTION ARCHETYPE for the page type (propose it, then confirm with the user via
+   get_intake_guide before building):
+   - home: hero · category tiles · featured products (grid-product) · story/USP · social proof · CTA
+   - category (type store): banner + breadcrumb + grid-product (+ optional filter sidebar)
+   - product detail (type store): 2-col [gallery | info: name/price/qty/add-to-cart/buy-now/trust]
+     + description band + related grid-product
+   - cart (type store): 2-col [cart-items | order summary card]
+   - checkout (type store): 2-col [form{form_order} | order summary]
+   - thank-you (type store): centred confirmation + order-items + continue-shopping
+2. Build each section from elements (new_section / new_row / new_element) using the locked
+   design system above.
+3. CREATE real product data + product images (create_product_category / create_product, images
+   from search_images/upload_images) so the dataset bindings (grid-product, product detail) resolve.
+
 ## Page shape
 A page's content is a single JSON object: \`{ "sections": [ <section>, ... ] }\`.
 - Save it via build_page (new page) or update_page_source (existing page).
@@ -70,10 +126,14 @@ already in this shape — see the \`responsive\` field on get_page_element/updat
   fontSize ("16px"), fontWeight, textAlign, border*, boxShadow, etc.
 - \`runtime.config.heightUnit\`: "auto" lets content set height (default for text/image).
 - Colours: use the site THEME matrix vars \`var(--color_RC)\` (R=row 0-4, C=col 0-4). Row 0 is
-  greyscale: \`var(--color_00)\`=WHITE … \`var(--color_04)\`=BLACK. Row 2 is the BRAND row:
-  \`var(--color_20)\` is the brand primary. So TEXT = \`var(--color_04)\` (NOT color_00, that's white →
-  invisible), ACCENT/buttons/prices = \`var(--color_20)\` (darker shade \`var(--color_24)\` if you need
-  white-on-accent contrast), page background = \`var(--color_00)\`. Plain hex/rgba() also work.
+  greyscale: \`var(--color_00)\`=WHITE … \`var(--color_04)\`=BLACK. Row 2 is the BRAND row, getting
+  DARKER left→right: \`var(--color_20)\` (lightest brand tint) … \`var(--color_24)\` (darkest brand).
+  So TEXT = \`var(--color_04)\` (NOT color_00 = white → invisible). PAGE BACKGROUND = \`var(--color_00)\`.
+  BUTTON / CTA BACKGROUND = \`var(--color_24)\` (the darkest brand shade) WITH a white label
+  (\`color:var(--color_00)\`) — this is readable on EVERY theme. ⚠️ Do NOT put a white label on
+  \`var(--color_20)\`: on many themes color_20 is a pale tint (e.g. #f2decc) and white text vanishes.
+  Use \`var(--color_20)\`/\`var(--color_21)\` only as a LIGHT section tint / soft background, never as a
+  button background under white text. PRICES / accents = \`var(--color_24)\` too. Plain hex/rgba() also work.
 
 ## Make it look DESIGNED (not plain) — do this, every page
 A bare stack of default elements looks unfinished. Apply real styling:
@@ -85,11 +145,14 @@ A bare stack of default elements looks unfinished. Apply real styling:
 - TYPOGRAPHY hierarchy: h1 40–56px / fontWeight 700, h2 28–34px / 600, body 16–18px with
   lineHeight "1.6", muted color for sub-text. Center hero text (textAlign:"center").
 - BUTTONS HAVE NO DEFAULT COLOUR — you MUST style them or they look like plain text:
-  \`{ type:"button", opts:{ text:"Mua ngay", style:{ background:"var(--color_20)", color:"var(--color_00)",
-  borderRadius:"8px", fontWeight:"600", height:48 } } }\` (brand background, white label).
-- HERO: prefer a section with a background image + an overlay heading/sub/button on top
-  (set section_opts.style.background or a full-width image, then text centered), rather than a
-  small image stacked above text.
+  \`{ type:"button", opts:{ text:"Mua ngay", style:{ background:"var(--color_24)", color:"var(--color_00)",
+  borderRadius:"8px", fontWeight:"600", height:48 } } }\` (DARK brand background, white label — always readable).
+- HERO: build it as a section whose FIRST child is a full-width \`image\` element (the background photo,
+  width:"100%", height ~480), then overlay the heading/sub/button on top. ⚠️ Do NOT rely on a CSS
+  \`background:"linear-gradient(...), url(...)"\` SHORTHAND on the section — the storefront renderer
+  ignores the shorthand and the photo won't show (you get a blank/flat band). A real \`image\` element
+  (src = a WebCake-CDN url) always renders; for a text overlay put a semi-transparent \`rectangle\`
+  over it and the text above that.
 - PRODUCT GRID: grid-product SELF-RENDERS the image+name+price card. Its look is
   INDUSTRY-DEPENDENT (surveyed fashion/kids/cosmetics/food/electronics) — only \`bold price\`,
   \`responsive\` collapse and \`show_original_price/show_discount_on_price\` are near-universal;
@@ -99,19 +162,31 @@ A bare stack of default elements looks unfinished. Apply real styling:
   and \`opts.specials\`: { products_per_load:8-36, on_hover:"zoom"|"swap", show_rating, show_ribbon }.
   (There are NO cardBorderRadius/cardBoxShadow keys.) For variations use \`attr\` elements
   (attrName:"auto"); steppers are \`quantity-input\` (defaults spinner:"hide-spin").
-- BRAND COLOURS: text = var(--color_04) (black), accent = var(--color_20) (brand) for buttons,
-  prices, highlights — consistent accent = looks intentional. (var(--color_00) is WHITE — only
-  for backgrounds / labels on the accent, never for text on a white surface.)
+- BRAND COLOURS: text = var(--color_04) (black); accent = var(--color_24) (DARK brand) for button
+  backgrounds, prices, highlights — consistent accent = looks intentional. (var(--color_00) is WHITE
+  — only for page backgrounds / labels ON the dark accent, never for text on a white surface; and a
+  white label on the pale var(--color_20) tint is the #1 invisible-text bug.)
 - IMAGES: must be WebCake-CDN urls (search_images cdn_url / upload_images), else they won't show.
+  A product card (grid-product) shows the PRODUCT-LEVEL thumbnail — if a product only has variation
+  images and no product image, its card is blank, so set product images when you create products.
 
 ## Responsive breakpoints
 The four breakpoints (largest → smallest), keyed bp1..bp4, are:
 - \`bp1\` ≥1320px (desktop, the base) · \`bp2\` 993–1319 (laptop) · \`bp3\` 641–992 (tablet) · \`bp4\` 320–640 (mobile).
-For NEW pages you author once in \`runtime\` (desktop) and build_page copies it to all four
-breakpoints automatically — the page renders identically across devices. To make a node
-look DIFFERENT on a smaller screen, set that breakpoint's key explicitly, e.g.
-\`node.bp4 = { style: { fontSize: "20px" }, config: {...} }\`. (There is no \`tablet\`/\`laptop\`
-key — only bp1..bp4.)
+For NEW pages you author once in \`runtime\` (the bp1/desktop base); on save the build expands
+it into bp1..bp4. By default all four are the same (renders identically across devices), PLUS
+sections re-centre their grid per breakpoint and multi-column rows auto-collapse (4→2→1 cols).
+
+RESPONSIVE CASCADE (reason about each breakpoint, don't hand-copy): to make a node look
+different on smaller screens, pass \`opts.responsive\` = SPARSE per-breakpoint diffs and the
+build cascades them bp1→bp4 (each smaller breakpoint inherits the resolved larger one, then
+applies only the keys you give). You only write what CHANGES:
+\`new_element("text", { text:"...", style:{ fontSize:"52px" },
+   responsive:{ bp3:{ style:{ fontSize:"38px" } }, bp4:{ style:{ fontSize:"28px", textAlign:"center" } } } })\`
+→ bp1/bp2 = 52px; bp3 = 38px; bp4 = 28px centred. Works on new_element/new_section/new_row and
+build_page children (in each child's \`opts.responsive\`). Use it for hero headline sizes, padding,
+columnGap, hiding/realigning per device. (There is no \`tablet\`/\`laptop\` key — only bp1..bp4.)
+You can still hand-set a final \`node.bpN\` when editing an already-saved page.
 
 ## Content & data
 - Text: \`specials.text\` (HTML allowed), \`specials.tag\` ("h1".."p").
@@ -203,13 +278,15 @@ set \`type\` accordingly so the binding source is turned on. A binding target li
 ## Build the WHOLE storefront — every page to the SAME standard (NOT just the home page)
 A shop is multi-page. Build EACH page to a real e-commerce standard with the same palette,
 spacing and header/footer — never leave the home page rich and the rest as bare stubs.
-\`scaffold_store_pages\` now builds FULLY-DESIGNED, palette-aware store pages by DEFAULT
-(style:"rich") — banner+breadcrumb+styled grid (Category), 2-col gallery|info with price/
-quantity/add-to-cart+trust badges+related (Product), 2-col cart|summary, 2-col checkout
-form|summary, centred thank-you — and auto-wires navigation between them. Then add chrome with
-\`scaffold_global_sections({ brand, contact })\` for a designed Header+Footer in one call. Pass
-style:"minimal" only if you want bare stubs to hand-build. The per-page recipe each rich page
-follows (so you can match it when editing or building extra pages):
+There are NO page templates and NO scaffold shortcuts: you COMPOSE each store page from elements
+(new_section / new_row / new_element → build_page) using the locked design system, then add a
+GLOBAL header/footer via create_global_section. Create the store pages whose slugs the storefront
+expects so navigation resolves (clicking a product/category/cart lands on a real page, not a 404):
+Category (slug "collections"), Product (slug "products"), Cart (slug "cart"), Checkout (slug
+"checkout"), Thank-you (slug "complete") — all build_page type:'store' (auto-enables use_store);
+plus optional member (login/register/profile, type 'member') and blog (blog/post, type 'blog')
+pages. Wire navigation between them yourself with open_page events (add-to-cart → cart, cart →
+checkout, order success → thank-you, thank-you → home). The per-page archetype to compose:
 - Category (collections, type store): banner + heading + grid-product (+ optional intro/CTA).
 - Product detail (products, type store): 2-col [product-gallery | info: text-dataset
   product::product_name + product_price/original_price + short_description, quantity-input,
@@ -237,9 +314,8 @@ create the globals — they embed into each page's source. If you later overwrit
 later with update_global_section_element(s) and it updates on every page at once.
 
 ## Popups (newsletter / promo / age-gate)
-A popup is a GLOBAL SOURCE, not a page section. FAST PATH: \`scaffold_popup({ brand, headline, offer })\`
-builds + saves a designed newsletter popup (heading + text + email form + close button, centred)
-and returns its id. To build one by hand:
+A popup is a GLOBAL SOURCE, not a page section. Compose it from elements (there is no scaffold
+shortcut), then save it as a "popup" global source:
 1. Build the popup node: new_element("popup", { children:[…heading,text,form,close button…], style:{ width:480, background:"#fff", borderRadius:"12px" }, config:{ popupHorizontalPosition:"center", popupVerticalPosition:"center" }, specials:{ effect:"fade-in", timeAnim:0.5 } }).
    - SIZE + POSITION live in the popup's runtime style/config (width/height/background + popupHorizontalPosition/popupVerticalPosition), NOT in specials. createPopup seeds a centred-modal default.
    - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. (There is no exit-intent/only-once flag in the node — those are app settings.)
@@ -252,9 +328,25 @@ List existing popups with list_global_sources({component:"popup"}); edit via upd
 
 ## Workflow (do this every time)
 1. Intake: confirm goal, brand, colours, sections wanted (ask 3-5 questions if unclear).
-2. list_elements / get_element to pick the right component types.
+2. list_elements / get_element to pick the right component types; get_page_schema for the exact
+   node contract ({ sections:[ { id,type,specials,runtime:{style,config},children,events,bindings } ] }).
 3. Build sections with new_section (or new_element for one node), fill content.
 4. validate_page — fix every error and review warnings.
 5. build_page with dry_run:true first → review → dry_run:false to persist.
 6. For existing pages, prefer surgical edits (update_page_element) over full rewrites.
+
+## LARGE PAGES — avoid timeout (use the DRAFT flow)
+A multi-section page sent in one build_page can be a huge request and hit the 15s timeout.
+For anything beyond a small/simple page, build it incrementally with the durable DRAFT flow:
+1. start_page_draft({ name, slug, type?, is_homepage?, seo? }) → draft_id (LOCAL, no network).
+2. add_draft_section({ draft_id, section }) ONCE per section — each is cached locally (safe,
+   can't time out) and quick-validated. Build the section with new_section first.
+3. commit_page_draft({ draft_id, dry_run:true }) to validate the whole page, then dry_run:false
+   to persist. It creates the page then appends sections ONE AT A TIME (small requests), saving
+   progress after each — and RESUMES from where it stopped if a request is interrupted (just call
+   commit_page_draft again). clear_page_draft discards a draft.
+The draft cache is DISPOSABLE — Redis on the remote server when REDIS_URL is set, in-memory
+otherwise, with a sliding ~2h TTL. A lost draft (expiry / cache restart) just means re-sending
+the sections via start_page_draft + add_draft_section (or build_page directly) — never a failure.
+Keep build_page for small/simple pages.
 Always keep Vietnamese text with full diacritics; reply in the user's language.`;

package/dist/builder/page-schema.js

@@ -0,0 +1,156 @@
+// Authoritative JSON Schema (Draft 2020-12) for the BuilderX storefront page SOURCE — the
+// `{ sections: [...] }` object that build_page / update_page_source persist. Mirrors what
+// webcake-landing-mcp exposes via get_page_schema, but for THIS product's CSS-GRID model
+// (not absolute top/left). It documents the AUTHORING shape an AI emits via new_section /
+// new_element (nodes carry a staging `runtime:{style,config}`; build_page expands that into
+// the per-breakpoint bp1..bp4 keys the storefront actually renders). Use it as the structural
+// contract; validate_page enforces the semantic rules (unique ids, valid grids, form fields).
+export const PAGE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://webcake.io/schemas/storefront-page.json",
+    title: "BuilderX storefront page source",
+    description: "A page's content: a vertical stack of section nodes. Build nodes with new_section/new_element (the factory fills correct defaults) — never hand-write a node from scratch.",
+    type: "object",
+    required: ["sections"],
+    additionalProperties: true,
+    properties: {
+        sections: {
+            type: "array",
+            description: "Top-level bands, rendered top→bottom. Only `section` nodes are valid here.",
+            items: { $ref: "#/$defs/node" },
+        },
+    },
+    $defs: {
+        node: {
+            type: "object",
+            required: ["id", "type"],
+            additionalProperties: true,
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Unique per page. Prefix = TYPE- (e.g. 'TEXT-ab12cd34', 'SECTION-...'). Minted by the factory; never reuse.",
+                },
+                type: {
+                    type: "string",
+                    description: "Element type from list_elements (e.g. section, container, text, image, button, grid-product, form, input, cart-items, menu).",
+                },
+                name: { type: "string", description: "Optional editor label." },
+                specials: {
+                    type: "object",
+                    description: "CONTENT + behaviour. Per-type keys (see get_element): text/tag (text), src (image, also in config), field_name (form input), type (form: form_order|form_login|…), products_per_load (grid-product), linkType/linkPage (menu-item nav), …",
+                    additionalProperties: true,
+                },
+                runtime: {
+                    type: "object",
+                    description: "STAGING shape emitted by new_section/new_element. The storefront does NOT read `runtime` — build_page/add_section (the SPA's buildElementWithBreakpoint) expand it into bp1..bp4 {style,config} on save and DELETE runtime; runtime.specials, if present, is merged into the top-level specials. Author here; don't hand-write bp1..bp4 for new pages.",
+                    additionalProperties: true,
+                    properties: {
+                        style: { $ref: "#/$defs/style" },
+                        config: { $ref: "#/$defs/config" },
+                        specials: { type: "object", description: "Optional per-breakpoint specials override; merged into top-level specials on expand.", additionalProperties: true },
+                        responsive: { $ref: "#/$defs/responsive" },
+                    },
+                },
+                children: {
+                    type: "array",
+                    description: "Child nodes — ONLY for container types (section, container, form, and repeaters like grid-product/cart-items whose children are the per-item template).",
+                    items: { $ref: "#/$defs/node" },
+                },
+                events: { type: "array", items: { $ref: "#/$defs/event" } },
+                bindings: { type: "array", items: { $ref: "#/$defs/binding" } },
+                bp1: { $ref: "#/$defs/breakpoint" },
+                bp2: { $ref: "#/$defs/breakpoint" },
+                bp3: { $ref: "#/$defs/breakpoint" },
+                bp4: { $ref: "#/$defs/breakpoint" },
+            },
+        },
+        responsive: {
+            type: "object",
+            description: "CASCADE overrides — sparse per-breakpoint diffs you (the AI) supply to make the page responsive by reasoning, not a flat copy. bp1 is the base (runtime.style/config). Each smaller breakpoint INHERITS the resolved larger one, then applies only the keys here. Example: { bp4: { style: { fontSize: '28px', textAlign: 'center' } }, bp3: { style: { fontSize: '36px' } } } → bp1/bp2 keep the base h1; bp3 shrinks it; bp4 shrinks + centres. Pass via opts.responsive on new_element/new_section/new_row/build_page children.",
+            additionalProperties: false,
+            properties: {
+                bp2: { $ref: "#/$defs/bpOverride" },
+                bp3: { $ref: "#/$defs/bpOverride" },
+                bp4: { $ref: "#/$defs/bpOverride" },
+            },
+        },
+        bpOverride: {
+            type: "object",
+            description: "Only the style/config keys that CHANGE at this breakpoint (everything else cascades from the larger breakpoint).",
+            additionalProperties: false,
+            properties: {
+                style: { $ref: "#/$defs/style" },
+                config: { $ref: "#/$defs/config" },
+            },
+        },
+        breakpoint: {
+            type: "object",
+            description: "Per-breakpoint render data (bp1 ≥1320 desktop · bp2 993–1319 · bp3 641–992 tablet · bp4 320–640 mobile). Written by build_page; set explicitly only to override a smaller screen.",
+            additionalProperties: false,
+            properties: {
+                style: { $ref: "#/$defs/style" },
+                config: { $ref: "#/$defs/config" },
+            },
+        },
+        style: {
+            type: "object",
+            description: "CSS-ish props. Numbers (width/height) are px. Colours: theme vars var(--color_RC) or hex/rgba. borderRadius is a STRING with units ('8px'). Common: width,height,color,background,fontSize,fontWeight,textAlign,lineHeight,border,boxShadow,padding*,borderRadius,overflow,justifyContent.",
+            additionalProperties: true,
+        },
+        config: {
+            type: "object",
+            description: "LAYOUT (CSS grid placement) + a few render flags. Not absolute top/left.",
+            additionalProperties: true,
+            properties: {
+                grid: { type: "string", description: "Grid template id, e.g. '3xN' (section: margin·content·margin) or '1xN' (container)." },
+                columns: { type: "array", description: "Column unit objects, e.g. [{unit:'fr',value:1},{unit:'px',absValue:1300,value:1},{unit:'fr',value:1}].", items: { type: "object" } },
+                rows: { type: "array", description: "Row unit objects — one per child.", items: { type: "object" } },
+                rowGap: { type: "number", description: "Vertical gap (px) between stacked children." },
+                columnGap: { type: "number", description: "Horizontal gap (px) between columns." },
+                heightUnit: { type: "string", description: "'auto' lets content set height (the common value); a fixed px height is used otherwise." },
+                loaded: { type: "boolean", description: "Internal flag set on expand (bp config). You don't set it." },
+                columnStart: { type: "number" },
+                columnEnd: { type: "number" },
+                rowStart: { type: "number" },
+                rowEnd: { type: "number" },
+                constraintX: { type: "array", items: { type: "string", enum: ["left", "right", "centerLeft"] } },
+                constraintY: { type: "array", items: { type: "string", enum: ["top", "bottom", "centerTop"] } },
+                src: { type: "string", description: "Image source URL (image elements). MUST be a WebCake-CDN url or it won't render." },
+            },
+        },
+        event: {
+            type: "object",
+            description: "Interaction. Set `action` (+ its fields); the factory mints id and a sensible eventName. See list_events.",
+            required: ["action"],
+            additionalProperties: true,
+            properties: {
+                action: {
+                    type: "string",
+                    description: "open_page | open_link | open_category | scroll_to | toggle | open_popup | close_popup | add_to_cart | buy_now | apply_promotion | phone_call | open_email | scale | …",
+                },
+                eventName: { type: "string", description: "Trigger: click (default) | hover | success | submit | mouseenter | mouseleave." },
+                open_page_id: { type: "string" },
+                open_category_id: { type: "string" },
+                link_target: { type: "string" },
+                link_target_url: { type: "string" },
+                scroll_to_id: { type: "string" },
+                toggle_id: { type: "string" },
+                popup_id: { type: "string" },
+                popup_overlay: { type: "boolean" },
+                open_page: { type: "string", description: "Commerce shortcut, e.g. add_to_cart with open_page:'cart'." },
+                phone_call_number: { type: "string" },
+                open_email: { type: "string" },
+            },
+        },
+        binding: {
+            type: "object",
+            description: "Dataset binding for dataset elements / repeater children. Set `target`; the builder mints id. Target only resolves on a page whose `type` enables that dataset (store/member/blog). See list_bindings.",
+            required: ["target"],
+            additionalProperties: true,
+            properties: {
+                target: { type: "string", description: "'<dataset>::<field>', e.g. product::product_price, cart_item::cart_item_name, order_item::product_name." },
+                name: { type: "string", description: "Dataset name (product, cart_item, order_item, post, category, customer_address, …)." },
+            },
+        },
+    },
+};

package/dist/builder/page.js

@@ -282,18 +282,33 @@ export function validatePage(source) {
  */
 function expandNodeToBreakpoints(node) {
     const rt = node && node.runtime;
-    if (rt && (rt.style || rt.config)) {
-        const baseStyle = rt.style || {};
+    if (rt && (rt.style || rt.config || rt.responsive)) {
         const baseConfig = { ...(rt.config || {}), loaded: true };
         const isSection = node.type === "section";
         const rowMeta = baseConfig.__row; // this node is a multi-column row container
         const cellMeta = baseConfig.__cell; // this node is a cell inside a row
+        // Per-breakpoint sparse overrides the AI supplied (opts.responsive → runtime.responsive):
+        // { bp2?:{style?,config?}, bp3?:{...}, bp4?:{...} }. bp1 is the base (runtime.style/config).
+        const overrides = rt.responsive && typeof rt.responsive === "object" ? rt.responsive : {};
+        // CASCADE (waterfall) bp1→bp4: each breakpoint starts from the RESOLVED larger one, then
+        // applies its own diff. So the AI only writes what CHANGES at each breakpoint and the rest
+        // inherits downward — proper AI-reasoned responsive instead of a flat copy.
+        let accStyle = rt.style || {};
+        let accConfig = baseConfig;
         for (const [bp, [minW]] of Object.entries(BREAKPOINTS)) {
-            const style = clone(baseStyle);
-            const config = clone(baseConfig);
+            const ov = overrides[bp];
+            if (ov && typeof ov === "object") {
+                if (ov.style)
+                    accStyle = { ...accStyle, ...ov.style };
+                if (ov.config)
+                    accConfig = { ...accConfig, ...ov.config };
+            }
+            const style = clone(accStyle);
+            const config = clone(accConfig);
             // Internal build-time markers never get persisted.
             delete config.__row;
             delete config.__cell;
+            delete config.responsive;
             if (isSection) {
                 const g = genGridByBp(minW);
                 const sectionRows = baseConfig.rows && baseConfig.rows.length ? clone(baseConfig.rows) : clone(g.rows);

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.6",
+    "d": "26/06/2026",
+    "type": "Removed",
+    "en": "scaffold_store_pages, scaffold_global_sections, and scaffold_popup tools are removed; pages are now composed free-form from elements using…",
+    "vi": "Các tool scaffold_store_pages, scaffold_global_sections và scaffold_popup đã bị xóa; các trang nay được tổ hợp tự do từ các phần tử bằng…"
+  },
+  {
+    "v": "1.31.5",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "Column definitions accepted by create_collection and update_collection_columns now support five new optional fields: note (help text for the…",
+    "vi": "Định nghĩa cột được chấp nhận bởi create_collection và update_collection_columns nay hỗ trợ thêm năm trường tùy chọn mới: note (ghi chú/mô tả cho…"
+  },
   {
     "v": "1.31.4",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "The webcake-data SDK reference embedded in get_http_function and get_site_custom_code now documents the correct Mongoose-document API: filters are…",
     "vi": "Tài liệu tham chiếu SDK webcake-data được nhúng trong get_http_function và get_site_custom_code nay ghi lại đúng API kiểu Mongoose-document: bộ lọc…"
-  },
-  {
-    "v": "1.31.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New create_collection tool creates a custom data table by accepting a name and a schema array of field definitions (with types such as string,…",
-    "vi": "Tool mới create_collection tạo bảng dữ liệu tùy chỉnh bằng cách nhận tham số name và mảng schema chứa định nghĩa các trường (với các kiểu dữ liệu…"
-  },
-  {
-    "v": "1.30.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New list_customers tool browses or searches the site's customer list; accepts page, limit, and term (name/phone/email keyword) and returns a compact…",
-    "vi": "Tool mới list_customers duyệt hoặc tìm kiếm danh sách khách hàng của site; nhận các tham số page, limit và term (từ khóa tên/điện thoại/email) và…"
   }
 ]

package/dist/db.js

@@ -58,3 +58,5 @@ export function setCachedUpload(siteId, source, cdnUrl) {
     imageCache[`${siteId}::${source}`] = cdnUrl;
     writeJson(IMAGE_CACHE_FILE, imageCache);
 }
+// Page-draft cache moved to src/persistence/draft-cache.ts (Redis-or-memory,
+// disposable + sliding TTL) — no longer a shared on-disk file.