webcake-storefront-mcp 1.31.6 → 1.31.7

package/dist/builder/page.js

@@ -89,20 +89,36 @@ export function stackChildren(container, children, opts = {}) {
     };
     children.forEach((child, i) => {
         child.runtime = child.runtime || {};
+        const cc = child.runtime.config || {};
         child.runtime.config = {
-            ...(child.runtime.config || {}),
+            ...cc,
             columnStart: colStart,
             columnEnd: colEnd,
             rowStart: i + 1,
             rowEnd: i + 2,
             constraintX: defaultConstraintX(child),
-            constraintY: (child.runtime.config && child.runtime.config.constraintY) || ["top"],
+            constraintY: cc.constraintY || ["top"],
+            // Width the template-native way: every element declares a width % of its cell
+            // (config.widthUnit + relWidth). Without these the renderer emits an invalid
+            // `width: %;` (the "width is 0" bug). Default to filling the cell; respect an
+            // element that opted into "auto" (content-sized, e.g. buttons) or "px".
+            ...sizeDefaults(cc),
             loaded: true,
         };
     });
     container.children = children;
     return container;
 }
+/** Template-native width defaults: fill the grid cell (widthUnit "%", relWidth 100) unless
+ *  the element already chose a unit. The storefront's build_position reads these (NOT
+ *  style.width, except when widthUnit==="px"). */
+function sizeDefaults(cfg) {
+    const widthUnit = cfg.widthUnit || "%";
+    const out = { widthUnit };
+    if (widthUnit !== "auto")
+        out.relWidth = cfg.relWidth != null ? cfg.relWidth : 100;
+    return out;
+}
 const ROW_PLACEHOLDER_ROW = () => ({ unit: "min/max", min: { unit: "px", absValue: 50 }, max: { unit: "max-c" } });
 /** Default responsive collapse for a multi-column row: full columns on desktop/laptop,
  *  2 columns on tablet, 1 column on mobile. `null` = keep the full column count. */
@@ -137,14 +153,16 @@ export function rowChildren(container, children, opts = {}) {
     };
     children.forEach((child, i) => {
         child.runtime = child.runtime || {};
+        const cc = child.runtime.config || {};
         child.runtime.config = {
-            ...(child.runtime.config || {}),
+            ...cc,
             columnStart: i + 1,
             columnEnd: i + 2,
             rowStart: 1,
             rowEnd: 2,
             constraintX: defaultConstraintX(child),
-            constraintY: (child.runtime.config && child.runtime.config.constraintY) || ["top"],
+            constraintY: cc.constraintY || ["top"],
+            ...sizeDefaults(cc),
             loaded: true,
             __cell: { index: i, ...meta },
         };
@@ -182,14 +200,27 @@ export function buildSection(childSpecs = [], sectionOpts = {}) {
         contentColEnd: SECTION_CONTENT_COL_END,
         rowGap: sectionOpts.rowGap,
     });
-    // Give sections vertical breathing room by default (a plain edge-to-edge stack looks
-    // unfinished). Caller can override via sectionOpts.style.
+    // Section vertical padding the TEMPLATE-NATIVE way: a fixed-height spacer GRID ROW at the
+    // top and bottom, content rows in between (real templates do exactly this — the storefront
+    // ignores CSS `padding` on a section, build_section only emits the grid). Default 64px;
+    // pass sectionOpts.padY (0 disables, e.g. a full-bleed hero).
+    const padY = sectionOpts.padY != null ? sectionOpts.padY : 64;
     section.runtime = section.runtime || {};
-    section.runtime.style = {
-        paddingTop: 56,
-        paddingBottom: 56,
-        ...(sectionOpts.style || {}),
-    };
+    const cfg = section.runtime.config || (section.runtime.config = {});
+    if (padY > 0 && Array.isArray(cfg.rows)) {
+        const spacer = () => ({ unit: "min/max", min: { unit: "px", absValue: padY }, max: { unit: "max-c" } });
+        cfg.rows = [spacer(), ...cfg.rows, spacer()];
+        cfg.grid = `3x${cfg.rows.length}`;
+        for (const c of children) {
+            const cc = c.runtime && c.runtime.config;
+            if (cc) {
+                cc.rowStart = (cc.rowStart || 1) + 1;
+                cc.rowEnd = (cc.rowEnd || 2) + 1;
+            }
+        }
+    }
+    // Section style carries background only (padding is done via the spacer rows above).
+    section.runtime.style = { ...(sectionOpts.style || {}) };
     return section;
 }
 export function buildFromSpec(spec) {

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.31.7",
+    "d": "26/06/2026",
+    "type": "Fixed",
+    "en": "build_page, create_page, update_page, and commit_page_draft now strip a leading / from slug before saving; a slug like /cart would previously 404 on…",
+    "vi": "build_page, create_page, update_page và commit_page_draft nay tự động loại bỏ dấu / đầu dòng khỏi slug trước khi lưu; các slug kiểu /cart trước đây…"
+  },
   {
     "v": "1.31.6",
     "d": "26/06/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "The HTTP_FUNCTION_GUIDE embedded in get_http_function and get_site_custom_code now includes a \"Common patterns\" section with battle-tested…",
     "vi": "HTTP_FUNCTION_GUIDE được nhúng trong get_http_function và get_site_custom_code nay bổ sung phần \"Common patterns\" với các recipe đã được kiểm chứng…"
-  },
-  {
-    "v": "1.31.1",
-    "d": "26/06/2026",
-    "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…"
   }
 ]

package/dist/smoke.js

@@ -50,8 +50,12 @@ console.log("== page: grid composition + validation ==");
         { type: "button", opts: { text: "Buy" } },
     ]);
     // A section uses the builder's centred 3-column grid; children sit in the centre column.
-    check("section grid is 3xN", hero.runtime.config.grid === "3x2", hero.runtime.config.grid);
+    // padY (default 64) adds a top + bottom SPACER ROW, so a 2-child section is 3x4 and the
+    // children start at row 2 (past the top spacer) — template-native section padding.
+    check("section grid is 3x(N+2) with spacer rows", hero.runtime.config.grid === "3x4", hero.runtime.config.grid);
+    check("top row is a padY spacer", hero.runtime.config.rows[0].min.absValue === 64, hero.runtime.config.rows[0]);
     check("children placed in centre column", hero.children.every((c) => c.runtime.config.columnStart === 2));
+    check("children shifted past top spacer", hero.children[0].runtime.config.rowStart === 2, hero.children[0].runtime.config.rowStart);
     const src = newPageSkeleton();
     src.sections.push(hero);
     const v = validatePage(src);
@@ -62,7 +66,7 @@ console.log("== page: grid composition + validation ==");
     const sec0 = src.sections[0];
     check("finalize removes runtime", !("runtime" in sec0), Object.keys(sec0));
     check("finalize adds bp1..bp4", ["bp1", "bp2", "bp3", "bp4"].every((bp) => sec0[bp]?.config), Object.keys(sec0));
-    check("section bp4 is mobile grid", sec0.bp4.config.grid === "3x2" && sec0.bp4.config.columns[0].absValue === 5, sec0.bp4.config.columns?.[0]);
+    check("section bp4 is mobile grid", sec0.bp4.config.grid === "3x4" && sec0.bp4.config.columns[0].absValue === 5, sec0.bp4.config.columns?.[0]);
     check("child bp1 keeps centre column", sec0.children[0].bp1.config.columnStart === 2, sec0.children[0].bp1?.config);
     check("finalize is idempotent", (finalizeForRender(src), !("runtime" in sec0)));
     // duplicate ids must fail validation

package/dist/tools/builder.js

@@ -61,6 +61,17 @@ export function buildPageSeo(seo = {}) {
         out.og_image = seo.thumbnail;
     return out;
 }
+/** Normalize a page slug to what the storefront matches on. The storefront routes by the
+ *  RAW path segment (e.g. "/cart" → path ["cart"]) and looks up `page.slug == "cart"`, so a
+ *  stored slug WITH a leading "/" (e.g. "/cart") never matches and the page 404s. The homepage
+ *  is matched by `is_nil(slug)`, so an empty/"/" slug must become "no slug" (undefined) — never
+ *  stored as "". Strips leading/trailing slashes; returns undefined for the homepage/blank case. */
+export function normalizeSlug(slug) {
+    if (!slug)
+        return undefined;
+    const s = String(slug).trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    return s.length ? s : undefined;
+}
 export function registerBuilderTools(server, api, handle) {
     server.tool("get_build_guide", "Get the BuilderX page authoring guide: page shape, the grid layout model, styling, breakpoints, forms/data, and the build workflow. Read this before building or heavily editing a page.", {}, () => handle(async () => ({ guide: BUILD_GUIDE })));
     server.tool("get_page_schema", "Get the authoritative JSON Schema (Draft 2020-12) for a page source `{ sections: [...] }` — the structural contract for every node (id/type/specials/runtime{style,config}/children/events/bindings) in the CSS-grid model. Use it as the shape to emit; validate_page enforces the semantic rules.", {}, () => handle(async () => PAGE_SCHEMA));
@@ -109,7 +120,7 @@ Example children: [{ "type":"container", "children":[{"type":"image","opts":{...
 Two-step safety: call with dry_run=true (default) to validate and preview, then dry_run=false to actually create + save.
 The source must be { sections: [...] } — build sections with new_section. Validation errors block the real save.`, {
         name: z.string().describe("Page name"),
-        slug: z.string().describe("URL slug, e.g. '/landing' or '/about'"),
+        slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Store pages MUST use the conventional slugs: category='collections', product detail='products', cart='cart', checkout='checkout', thank-you='complete'. The homepage needs no slug (pass is_homepage:true)."),
         source: z.any().describe("Full page source { sections: [...] } (object or JSON string)"),
         type: z
             .enum(PAGE_KINDS)
@@ -134,11 +145,14 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         const kind = type || (is_homepage ? "main" : undefined);
         const typeNum = kind ? PAGE_TYPE_NUM[kind] : undefined;
         const requiredFlag = kind ? PAGE_TYPE_FLAG[kind] : undefined;
+        // Strip a leading "/" — the storefront matches `page.slug == "<segment>"` (no slash),
+        // so "/cart" would 404. Homepage (blank/"/") → undefined (matched by is_nil(slug)).
+        const cleanSlug = normalizeSlug(slug);
         if (dry_run) {
             return {
                 dry_run: true,
                 validation,
-                request: { name, slug, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
+                request: { name, slug: cleanSlug ?? null, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
                 will_enable_feature: requiredFlag ?? null,
                 renders_at_breakpoints: ["bp1", "bp2", "bp3", "bp4"],
                 hint: validation.valid
@@ -170,10 +184,10 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         }
         // slug / homepage / SEO are not applied at create — set them via update_page.
         const seoBlock = seo ? buildPageSeo(seo) : null;
-        if (slug || is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
+        if (cleanSlug || is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
             await api
                 .updatePage(pageId, {
-                ...(slug ? { slug } : {}),
+                ...(cleanSlug ? { slug: cleanSlug } : {}),
                 ...(is_homepage ? { is_homepage: true } : {}),
                 ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
             })
@@ -183,7 +197,7 @@ The source must be { sections: [...] } — build sections with new_section. Vali
             success: true,
             page_id: pageId,
             name,
-            slug,
+            slug: cleanSlug ?? null,
             page_type: kind ?? null,
             ...(feature ? { data_source: { flag: feature.flag, newly_enabled: feature.changed } } : {}),
             stats: validation.stats,

package/dist/tools/catalog-write.js

@@ -18,6 +18,18 @@ const variationSpec = z.object({
         .optional()
         .describe("Attribute values for this variation, e.g. [{name:'Color',value:'Đen'},{name:'Size',value:'M'}]"),
 });
+/** Normalize an attribute value to its keyword key (DEN for "Đen", TRANG for "Trắng", S for "S") —
+ *  the form the storefront variation selector uses. Strips Vietnamese diacritics + uppercases. */
+function attrKeyValue(v) {
+    return String(v)
+        .normalize("NFD").replace(/[̀-ͯ]/g, "")
+        .replace(/đ/g, "d").replace(/Đ/g, "D")
+        .toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+/** Cartesian product of N lists — used to expand attribute axes into one variation per combo. */
+function cartesian(lists) {
+    return lists.reduce((acc, cur) => acc.flatMap((a) => cur.map((b) => [...a, b])), [[]]);
+}
 export function registerCatalogWriteTools(server, api, handle) {
     server.tool("create_product", `Create a product so the storefront has real merchandise (grid-product / slider-product bindings need this).
 Simple use: pass name + price (+ images, category_ids). One default variation with the price/stock is created for you.
@@ -39,23 +51,49 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
         variations: z.array(variationSpec).optional().describe("Explicit per-SKU variations. Omit to auto-build one from price/stock/sku."),
     }, ({ name, price, original_price, stock, sku, images, description, short_description, category_ids, attributes, variations }) => handle(async () => {
         let vars = variations;
+        // Enrich attribute axes with the id + keyword shape the storefront variation selector
+        // needs (a raw {name,values} declares the axis but attaches it to no variation).
+        const attrDefs = (attributes || []).map((a) => ({
+            id: randomUUID(),
+            name: a.name,
+            values: a.values,
+            keyword: (a.values || []).map((v) => ({ keyValue: attrKeyValue(v), value: v })),
+        }));
         if (!vars || !vars.length) {
             if (price == null)
                 throw new Error("Provide `price` (or explicit `variations`) to create a product.");
-            vars = [
-                {
-                    custom_id: sku || `SKU-${randomUUID().slice(0, 8)}`,
+            if (attrDefs.length) {
+                // Expand the attribute axes into ONE variation per value-combination, each carrying
+                // `fields` — otherwise the axis is declared but bound to nothing (not selectable).
+                const axisLists = attrDefs.map((a) => a.values.map((v) => ({ name: a.name, value: v })));
+                const combos = cartesian(axisLists);
+                vars = combos.map((combo) => ({
+                    custom_id: `SKU-${randomUUID().slice(0, 8)}`,
                     retail_price: price,
                     original_price: original_price ?? price,
                     remain_quantity: stock ?? 100,
                     images: images || [],
                     weight: 0,
-                    fields: [],
-                },
-            ];
+                    fields: combo.map((c) => ({ id: randomUUID(), name: c.name, value: c.value })),
+                    is_hidden: false,
+                }));
+            }
+            else {
+                vars = [
+                    {
+                        custom_id: sku || `SKU-${randomUUID().slice(0, 8)}`,
+                        retail_price: price,
+                        original_price: original_price ?? price,
+                        remain_quantity: stock ?? 100,
+                        images: images || [],
+                        weight: 0,
+                        fields: [],
+                    },
+                ];
+            }
         }
         else {
-            // Normalise: fill SKU / original_price / stock defaults per variation.
+            // Normalise: fill SKU / original_price / stock defaults per variation; mint field ids.
             vars = vars.map((v) => ({
                 custom_id: v.custom_id || `SKU-${randomUUID().slice(0, 8)}`,
                 retail_price: v.retail_price,
@@ -63,7 +101,7 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
                 remain_quantity: v.remain_quantity ?? 100,
                 images: v.images || [],
                 weight: v.weight ?? 0,
-                fields: v.fields || [],
+                fields: (v.fields || []).map((f) => ({ id: f.id || randomUUID(), name: f.name, value: f.value })),
                 is_hidden: false,
             }));
         }
@@ -75,7 +113,7 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
             //  endpoint, so it must be [] — never omitted — even for a no-variation product.)
             categories: category_ids || [],
             ribbons: [],
-            product_attributes: attributes || [],
+            product_attributes: attrDefs,
             ...(description ? { description } : {}),
             // short_description is an ARRAY of {description} blocks on the real product shape.
             ...(short_description ? { short_description: [{ description: short_description }] } : {}),

package/dist/tools/page-draft.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo, normalizeSlug } from "./builder.js";
 import { validatePage, finalizeForRender, reassignIds } from "../builder/page.js";
 import { createDraft, getDraft, setDraft, appendDraftSection, listDrafts, delDraft, } from "../persistence/draft-cache.js";
 // Friendly result when a draft is gone (disposable cache: expired ~2h or restart).
@@ -27,7 +27,7 @@ function newPageId(res) {
 export function registerPageDraftTools(server, api, handle) {
     server.tool("start_page_draft", `Start a page draft (no network). Build a multi-section page safely: cache each section with add_draft_section, then commit_page_draft persists it to the backend INCREMENTALLY (resumable on timeout). Use this instead of build_page for large/multi-section pages. The draft cache is DISPOSABLE (Redis on the remote server when REDIS_URL is set, in-memory otherwise; sliding ~2h TTL) — if a draft is ever lost, just re-send the sections, never a failure.`, {
         name: z.string().describe("Page name"),
-        slug: z.string().describe("URL slug, e.g. '/landing' or '/about'"),
+        slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Store pages MUST use: category='collections', product='products', cart='cart', checkout='checkout', thank-you='complete'. Homepage needs no slug (is_homepage:true)."),
         type: z
             .enum(PAGE_KINDS)
             .optional()
@@ -140,11 +140,13 @@ RESUMABLE: if a request fails mid-commit, the draft keeps its page_id + committe
                 await setDraft(draft);
             }
             // All sections committed → apply slug / homepage / SEO, then drop the draft.
+            // Strip a leading "/" so the storefront's bare-segment match resolves (else 404).
+            const cleanSlug = normalizeSlug(draft.meta.slug);
             const seoBlock = draft.meta.seo ? buildPageSeo(draft.meta.seo) : null;
-            if (draft.meta.slug || draft.meta.is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
+            if (cleanSlug || draft.meta.is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
                 await api
                     .updatePage(draft.page_id, {
-                    ...(draft.meta.slug ? { slug: draft.meta.slug } : {}),
+                    ...(cleanSlug ? { slug: cleanSlug } : {}),
                     ...(draft.meta.is_homepage ? { is_homepage: true } : {}),
                     ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
                 })

package/dist/tools/pages.js

@@ -3,7 +3,7 @@ import { CUSTOM_CODE_GUIDE } from "../guides.js";
 import { getConfirmMode } from "./context.js";
 import { normalizeEvents } from "../builder/events.js";
 import { normalizeBindings } from "../builder/bindings.js";
-import { PAGE_TYPE_NUM, PAGE_KINDS, buildPageSeo } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_KINDS, buildPageSeo, normalizeSlug } from "./builder.js";
 /**
  * Page source utilities.
  *
@@ -296,7 +296,7 @@ Examples:
     }));
     server.tool("create_page", "Create a new (empty) page. For a page with content use build_page instead. type is a KIND (main/store/member/blog/custom/error/maintain) mapped to the numeric backend type; pass seo so it doesn't publish with an empty title.", {
         name: z.string().describe("Page name"),
-        slug: z.string().describe("URL slug (e.g. '/about')"),
+        slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Homepage needs no slug (pass is_homepage:true)."),
         type: z.enum(PAGE_KINDS).optional().describe("Page kind (main/store/member/blog/custom/error/maintain). store/member/blog need their data-source flag enabled — prefer build_page which auto-enables it."),
         is_homepage: z.boolean().default(false).describe("Set as homepage"),
         seo: z
@@ -304,30 +304,39 @@ Examples:
             .optional()
             .describe("SEO → settings.seo (title/description/keyword/favicon/thumbnail). Tokens {{name_page}}/{{name_site}} allowed."),
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
+        const cleanSlug = normalizeSlug(slug);
         const typeNum = type ? PAGE_TYPE_NUM[type] : undefined;
         const created = await api.createPage({ name, ...(typeNum != null ? { type: typeNum } : {}) });
         invalidatePageCache();
         const pageId = (created && (created.id || created.data?.id || created.page?.id)) || null;
         const seoBlock = seo ? buildPageSeo(seo) : null;
-        if (pageId && (slug || is_homepage || (seoBlock && Object.keys(seoBlock).length))) {
+        if (pageId && (cleanSlug || is_homepage || (seoBlock && Object.keys(seoBlock).length))) {
             await api
                 .updatePage(pageId, {
-                ...(slug ? { slug } : {}),
+                ...(cleanSlug ? { slug: cleanSlug } : {}),
                 ...(is_homepage ? { is_homepage: true } : {}),
                 ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
             })
                 .catch(() => { });
             invalidatePageCache();
         }
-        return { success: true, page_id: pageId, name, slug, type: type ?? null, raw: pageId ? undefined : created };
+        return { success: true, page_id: pageId, name, slug: cleanSlug ?? null, type: type ?? null, raw: pageId ? undefined : created };
     }));
     server.tool("update_page", "Update page properties (name, slug, settings, custom code)", {
         page_id: z.string().describe("Page ID"),
         name: z.string().optional().describe("New name"),
-        slug: z.string().optional().describe("New slug"),
+        slug: z.string().optional().describe("New slug WITHOUT a leading slash (e.g. 'about', 'cart'). A leading '/' is stripped automatically — '/cart' would 404 on the storefront."),
         is_homepage: z.boolean().optional().describe("Set as homepage"),
         settings: z.record(z.any()).optional().describe("Page settings"),
     }, ({ page_id, ...params }) => handle(async () => {
+        // Normalize slug (strip leading "/") so the storefront's bare-segment match resolves.
+        if (params.slug !== undefined) {
+            const clean = normalizeSlug(params.slug);
+            if (clean)
+                params.slug = clean;
+            else
+                delete params.slug;
+        }
         const res = await api.updatePage(page_id, params);
         invalidatePageCache();
         return res;

package/package.json

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