webcake-storefront-mcp 1.31.7 → 1.31.9

package/dist/api.js

@@ -1,4 +1,7 @@
 const DEFAULT_TIMEOUT = 15000;
+/** Stamped on every page this MCP server creates (backend column `pages.by_ai`),
+ *  so the builder can flag AI-authored pages. Mirrors the landing-page convention. */
+export const BY_AI_MARKER = "mcp";
 export class WebcakeCmsApi {
     baseUrl;
     token;
@@ -149,13 +152,17 @@ 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. */
+     *  `slug`/`is_homepage` are NOT applied at create — set them afterwards via updatePage.
+     *  Every page born here is AI-authored, so we stamp `by_ai` (persisted to `pages.by_ai`)
+     *  and the builder shows an "AI" tag next to the page name. */
     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: [] });
+        if (body.by_ai == null)
+            body.by_ai = BY_AI_MARKER;
         return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body, timeout: opts?.timeout });
     }
     updatePage(pageId, params) {

package/dist/builder/catalog.js

@@ -157,6 +157,41 @@ export function buildElement(type, opts = {}) {
     }
     // Guarantee children-using factories never throw on a missing children array.
     const node = fn({ children: [], ...opts });
+    // Some factories (container, menu, menu-droppable, …) IGNORE opts.config / opts.style — they
+    // only wire children/specials. That silently dropped base layout keys like config.isHidden
+    // (e.g. a "hidden on desktop" mobile bar stayed visible). Backfill them into runtime so EVERY
+    // element honours opts.config/opts.style. Existing values from factories that DO handle them are
+    // kept (opts wins only where the factory left it unset) — idempotent for those.
+    if (opts.config && typeof opts.config === "object") {
+        node.runtime = node.runtime || {};
+        node.runtime.config = { ...opts.config, ...(node.runtime.config || {}) };
+    }
+    if (opts.style && typeof opts.style === "object") {
+        node.runtime = node.runtime || {};
+        node.runtime.style = { ...opts.style, ...(node.runtime.style || {}) };
+    }
+    // Generic horizontal ALIGNMENT control: opts.align maps to the renderer's constraintX so
+    // ANY element (button, text, image, container…) can be placed left / centre / right, or
+    // told to FILL its grid cell. Without this a content-sized element (e.g. a button) lands
+    // wherever the default constraint puts it; authors had no clean knob to centre or pin it.
+    // 'fill' also forces a 100%-width cell so the element truly spans the column.
+    if (opts.align) {
+        const ALIGN = {
+            left: ["left"], center: ["centerLeft"], centre: ["centerLeft"],
+            right: ["right"], fill: ["left", "right"], stretch: ["left", "right"],
+        };
+        const cx = ALIGN[String(opts.align).toLowerCase()];
+        if (cx) {
+            node.runtime = node.runtime || {};
+            const rc = (node.runtime.config = node.runtime.config || {});
+            rc.constraintX = cx;
+            if (cx.length === 2) {
+                rc.widthUnit = "%";
+                if (rc.relWidth == null)
+                    rc.relWidth = 100;
+            }
+        }
+    }
     // Some factories ignore opts.bindings/events — attach them so any element the AI passes
     // them to gets them — then normalize so each binding/event has a valid id (+ name/eventName).
     if (opts.bindings && !node.bindings)

package/dist/builder/factory.js

@@ -135,12 +135,26 @@ export const createButton = (opts = {}) => {
     button.id = 'BUTTON-' + randomString(8);
     button.type = 'button';
     button.runtime.style = {
-        width: 142,
-        height: 46,
+        height: 48,
         fontSize: '16px',
+        // Generous horizontal padding so the label never sits edge-to-edge — the #1 "ugly
+        // button" complaint when a button stretched full width. Centred text keeps it tidy
+        // whatever the width. Override any of these via opts.style.
+        paddingTop: '0px',
+        paddingBottom: '0px',
+        paddingLeft: '28px',
+        paddingRight: '28px',
+        textAlign: 'center',
         ...(opts.style || {}),
     };
     button.runtime.config = {
+        // A button sizes to its CONTENT (label + padding), NOT the full grid cell. Without
+        // this, stackChildren's sizeDefaults stretches it to widthUnit:'%'/relWidth:100 — i.e.
+        // an edge-to-edge bar with cramped text. Content-width + the default centred
+        // constraintX means a standalone CTA sits centred with breathing room instead of being
+        // slammed flush-left. To make a button FILL its container, pass opts.align:'fill' (or
+        // opts.config.widthUnit:'%').
+        widthUnit: 'auto',
         ...(opts.config || {})
     };
     button.specials.text = opts.text || 'Button';
@@ -725,9 +739,19 @@ export const createSubmitButton = (opts = {}) => {
     const button = cloneDeep(SKELETON);
     button.id = 'SUBMIT-BUTTON-' + randomString(8);
     button.type = 'submit-button';
-    button.runtime.style = opts.style || {};
-    button.runtime.config = opts.config || {};
+    // A form submit button stays full-width (the norm inside a form column) but gets a real
+    // height + side padding + centred label so it never renders as a cramped sliver.
+    button.runtime.style = {
+        height: 48,
+        fontSize: '16px',
+        paddingLeft: '24px',
+        paddingRight: '24px',
+        textAlign: 'center',
+        ...(opts.style || {}),
+    };
+    button.runtime.config = { ...(opts.config || {}) };
     button.specials = {
+        ...(opts.specials || {}),
         text: opts.specials?.text || 'Submit'
     };
     return button;

package/dist/builder/guide.js

@@ -94,6 +94,20 @@ children with a grid:
 new_section does ALL of this for you: pass children and they are stacked one row each in
 the centre column.
 
+### ALIGNMENT inside a cell — how children line up (avoid the "snapped to a corner" look)
+\`constraintX\`/\`constraintY\` decide where a child sits in its grid cell. The renderer maps:
+- \`["left","right"]\` → justify-self: STRETCH — the element FILLS the cell width (this is what makes
+  columns, cards, and images line up edge-to-edge). This is the DEFAULT new_section/new_row give to
+  every width-filling element (text, image, container, repeaters), so siblings stay in straight rows.
+- \`["centerLeft"]\` → justify-self: CENTER (shrinks a content-width element to its content and centres it),
+  \`["left"]\` → left, \`["right"]\` → right. \`constraintY\`: \`["top"]\` (default) / \`["bottom"]\` / \`["centerTop"]\` (middle).
+DON'T hand-set \`["centerLeft"]\` on a full-width element (text/container/card) — that snaps it to its
+content width and floats it, so it no longer lines up with its neighbours (the classic "cắn/lệch" bug).
+Instead: leave the default stretch and control the LOOK with \`textAlign\` (for text) or, for a
+content-width element like a button, with \`opts.align\` ('left'|'center'|'right'|'fill'). A button is
+content-width + centred by DEFAULT; pass \`align:"left"\` so it lines up with left-aligned text above it,
+or \`align:"fill"\` to span the column.
+
 ## Multi-column rows (cards side by side) — USE THIS, real pages are full of them
 A plain vertical stack looks like a blog post, not a designed page. Feature cards,
 category tiles, footer columns, a text+image hero — all are HORIZONTAL rows. Two ways:
@@ -147,6 +161,13 @@ A bare stack of default elements looks unfinished. Apply real styling:
 - 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_24)", color:"var(--color_00)",
   borderRadius:"8px", fontWeight:"600", height:48 } } }\` (DARK brand background, white label — always readable).
+- BUTTON WIDTH & ALIGNMENT (don't fight it): a \`button\` is CONTENT-SIZED by default (label + built-in
+  28px side padding) and CENTRED in its cell — so a standalone CTA looks like a real button, never a
+  full-width bar with cramped text or one slammed flush-left. To place/size it, pass \`opts.align\`:
+  \`"left"\` | \`"center"\` (default) | \`"right"\` | \`"fill"\` (span the whole column, e.g. two side-by-side
+  Add-to-cart / Buy-now buttons, or a button inside a narrow summary card). \`align\` works on ANY element
+  (text/image/container too). A form \`submit-button\` stays full-width by design. Do NOT try to force a
+  button's width via \`style.width\` — the renderer ignores it (use \`align:"fill"\` instead).
 - 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
@@ -176,6 +197,11 @@ The four breakpoints (largest → smallest), keyed bp1..bp4, are:
 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).
+AUTO-RESPONSIVE DEFAULTS (you get these for free, no diffs needed): on tablet/mobile the build
+also shrinks oversized TYPOGRAPHY (any fontSize ≥22px scales ~0.86× on tablet / ~0.72× on mobile,
+floored at 15px) and TALL images (height >320px shrinks on mobile) so hero headlines and big media
+don't blow out small screens. Body text (<22px) is left alone. Pass \`opts.responsive\` only to
+OVERRIDE this default for a specific node/breakpoint (your explicit diff always wins).
 
 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
@@ -275,6 +301,14 @@ Rule of thumb: if the page shows products, a cart, customer/order data, or blog
 set \`type\` accordingly so the binding source is turned on. A binding target like
 \`product::product_price\` REQUIRES its page to be the matching type.
 
+### ONE page per singleton type — only \`custom\` is unlimited
+A site has exactly ONE homepage (\`main\`), ONE \`error\` page and ONE \`maintain\` page; a second
+one only shadows the first, so \`create_page\` / \`build_page\` / \`start_page_draft\` REFUSE it and
+hand you the existing \`page_id\` — edit that page (replace_page_source / add_section /
+update_page) instead of creating another. \`store\`/\`member\`/\`blog\` may have several pages
+(cart + checkout + collections…, login + register…) but each SLUG is unique per site, so those
+are refused on a duplicate slug. \`custom\` pages are unlimited as long as their slugs differ.
+
 ## 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.
@@ -313,6 +347,27 @@ create the globals — they embed into each page's source. If you later overwrit
 (delete_global_section by the section NODE id, then create once) to re-embed cleanly. Edit a global
 later with update_global_section_element(s) and it updates on every page at once.
 
+### HEADER must be RESPONSIVE — add a MOBILE MENUBAR, don't just let nav stack
+A header built as one horizontal row of nav links looks fine on desktop but on a phone the links
+squash or collapse into an ugly vertical pile. Build a header that carries TWO navs and swap them
+per breakpoint with the \`isHidden\` config (it cascades bp1→bp4 like any config key):
+- DESKTOP nav — the inline row of links in the top bar. Keep it on desktop+laptop, hide from tablet
+  down: \`responsive:{ bp3:{ config:{ isHidden:true } } }\` (base visible).
+- MOBILE MENUBAR — a SEPARATE container, a centred horizontal row of the same links placed as a
+  second row of the header section (below the logo/cart bar). Hide it on desktop+laptop, show from
+  tablet down: base \`config:{ isHidden:true }\` + \`responsive:{ bp3:{ config:{ isHidden:false } } }\`.
+RELIABILITY NOTE (storefront-verified): this two-nav \`isHidden\`-SWAP is the dependable mobile
+menubar. AVOID these — they do NOT render dependably from raw MCP data: the native \`menu\`
+\`type:"hamburger"\` (its ☰ trigger paints as a 0-width empty box; an inline-SVG \`mask\` is ignored);
+a \`toggle\`-revealed panel (the storefront only makes a toggle target's hidden state reactive when
+it's wired in the builder UI, so a click can't show an \`isHidden\` element); and \`open_popup\` drawers
+(popups are global_sources and the publish pipeline doesn't always emit them, so the popup isn't on
+the page). A plain visible mobile nav row, shown via \`isHidden\` swap, always works.
+Lay the bar as a 2-column row [logo | (desktop-nav + cart, aligned right)] and add the mobile nav row
+as the section's 2nd child. Keep the logo + cart-icon visible on every breakpoint.
+(If you do want a real collapsible hamburger, finish it in the WebCake builder UI, which wires the
+toggle/menu reactively — the MCP can't reproduce that wiring from data alone.)
+
 ## Popups (newsletter / promo / age-gate)
 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:

package/dist/builder/page.js

@@ -10,6 +10,42 @@ import { validateEvents } from "./events.js";
 import { validateBindings } from "./bindings.js";
 import { BREAKPOINTS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
 const clone = (o) => structuredClone(o);
+/** Parse a CSS px length ("52px") or a bare number (52) → number, else null. */
+function pxToNum(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : null;
+    const m = /^(-?\d+(?:\.\d+)?)px$/.exec(String(v ?? "").trim());
+    return m ? parseFloat(m[1]) : null;
+}
+/** AUTO-RESPONSIVE down-scaling per breakpoint. Headings/large text and very tall media
+ *  keep their desktop size on phones unless the author hand-writes a responsive diff —
+ *  which makes generated pages look broken on mobile. These factors shrink oversized
+ *  typography (and tall images) on tablet/mobile by DEFAULT. Applied only when the author
+ *  did NOT already override the property at this breakpoint (resolved value === base). */
+const AUTO_FONT_FACTOR = { bp1: 1, bp2: 1, bp3: 0.86, bp4: 0.72 };
+const AUTO_IMG_HEIGHT_FACTOR = { bp1: 1, bp2: 1, bp3: 0.82, bp4: 0.58 };
+/** Mutate a resolved per-breakpoint `style` in place: shrink big fonts (≥22px) and tall
+ *  images (>320px) for smaller breakpoints. `baseStyle` is the bp1/authored style — we only
+ *  auto-scale a property the author left untouched at this bp (resolved === base). */
+function applyAutoResponsive(node, bp, baseStyle, style) {
+    const ff = AUTO_FONT_FACTOR[bp];
+    if (ff != null && ff < 1) {
+        const baseF = pxToNum(baseStyle.fontSize);
+        const curF = pxToNum(style.fontSize);
+        if (baseF != null && curF != null && curF === baseF && baseF >= 22) {
+            style.fontSize = Math.max(15, Math.round(baseF * ff)) + "px";
+        }
+    }
+    const hf = AUTO_IMG_HEIGHT_FACTOR[bp];
+    if (hf != null && hf < 1 && (node.type === "image" || node.type === "image-dataset")) {
+        const baseH = pxToNum(baseStyle.height);
+        const curH = pxToNum(style.height);
+        if (baseH != null && curH != null && curH === baseH && baseH > 320) {
+            const nh = Math.round(baseH * hf);
+            style.height = typeof baseStyle.height === "number" ? nh : nh + "px";
+        }
+    }
+}
 /** Walk every node in a source tree (depth-first). Return false from fn to stop. */
 export function walk(source, fn) {
     const sections = source && Array.isArray(source.sections) ? source.sections : [];
@@ -64,11 +100,28 @@ const FILL_WIDTH_TYPES = new Set([
     "grid-category", "grid-blog", "product-gallery", "product-image-carousel",
     "custom-layout", "layout-dataset", "form",
 ]);
-/** Default horizontal constraint for a child: stretch for fill-width components,
- *  else the builder's usual centred placement. Respects an explicit constraintX. */
+/**
+ * Default horizontal constraint for a child in its grid cell. THE ALIGNMENT RULE:
+ * an element that FILLS its cell width (widthUnit "%", relWidth 100 — the default for
+ * text/image/container/repeaters) must STRETCH (`["left","right"]` → justify-self:stretch),
+ * NOT centre. The old default `["centerLeft"]` (justify-self:center) snapped such elements
+ * to their content width and floated them — so sibling columns/cards/images did NOT line up
+ * (the "cắn left-top / không thẳng hàng" bug). Stretch makes every full-width child span its
+ * cell edge-to-edge, so its OWN textAlign / inner stacking controls layout and rows align.
+ * Only a genuinely CONTENT-WIDTH element (widthUnit "auto", e.g. a button) gets a point
+ * constraint, defaulting to centre. An explicit constraintX (e.g. set by opts.align) always wins.
+ */
 function defaultConstraintX(child) {
-    return ((child.runtime && child.runtime.config && child.runtime.config.constraintX) ||
-        (FILL_WIDTH_TYPES.has(child.type) ? ["left", "right"] : ["centerLeft"]));
+    const cfg = (child.runtime && child.runtime.config) || {};
+    if (cfg.constraintX)
+        return cfg.constraintX; // explicit / from opts.align
+    if (FILL_WIDTH_TYPES.has(child.type))
+        return ["left", "right"];
+    // Content-sized elements (a button opts into widthUnit:"auto") centre by default; everything
+    // else fills its cell, so it must stretch to line up with its neighbours.
+    if (cfg.widthUnit === "auto")
+        return ["centerLeft"];
+    return ["left", "right"];
 }
 export function stackChildren(container, children, opts = {}) {
     const gridCols = opts.gridCols || 1;
@@ -340,6 +393,8 @@ function expandNodeToBreakpoints(node) {
             delete config.__row;
             delete config.__cell;
             delete config.responsive;
+            // Shrink oversized fonts / tall images on tablet & mobile by default (author diffs win).
+            applyAutoResponsive(node, bp, rt.style || {}, style);
             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.9",
+    "d": "07/09/2026",
+    "type": "Added",
+    "en": "Pages created by create_page, build_page, and commit_page_draft are now stamped with by_ai: \"mcp\" (persisted to the backend pages.by_ai column) so…",
+    "vi": "Các trang được tạo bởi create_page, build_page và commit_page_draft nay được đánh dấu by_ai: \"mcp\" (lưu vào cột pages.by_ai ở backend) để builder có…"
+  },
+  {
+    "v": "1.31.8",
+    "d": "29/06/2026",
+    "type": "Fixed",
+    "en": "Elements placed by new_section, new_row, and build_page that fill their grid cell (text, image, container, columns, repeaters) now receive…",
+    "vi": "Các phần tử được đặt bởi new_section, new_row và build_page mà lấp đầy ô lưới (text, image, container, columns, repeaters) nay nhận constraintX:…"
+  },
   {
     "v": "1.31.7",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "The guide returned by get_http_function and get_site_custom_code now includes a verified end-to-end \"Custom data TABLES (collections)\" section…",
     "vi": "Hướng dẫn trả về bởi get_http_function và get_site_custom_code nay bổ sung phần \"Custom data TABLES (collections)\" đã được xác minh thực tế, ghi lại…"
-  },
-  {
-    "v": "1.31.3",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New update_collection_columns tool reads the current collection schema and PATCHes it with the system columns plus the provided custom columns,…",
-    "vi": "Tool mới update_collection_columns đọc schema hiện tại của collection rồi PATCH lại với các cột hệ thống cộng các cột tùy chỉnh được cung cấp, cho…"
-  },
-  {
-    "v": "1.31.2",
-    "d": "26/06/2026",
-    "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…"
   }
 ]

package/dist/tools/builder.js

@@ -38,6 +38,59 @@ export const PAGE_TYPE_FLAG = {
     error: "use_error", maintain: "use_maintain",
 };
 export const PAGE_KINDS = ["main", "store", "member", "blog", "custom", "error", "maintain"];
+/** Page kinds a site only ever has ONE of. The homepage is `main`, and the storefront
+ *  resolves exactly one `error` / `maintain` page — a second one just shadows the first,
+ *  so creating it is always a mistake. `store` / `member` / `blog` are NOT here: a site
+ *  legitimately has several of each (cart + checkout + collections…, login + register…),
+ *  they are kept unique by SLUG instead. `custom` is unlimited. */
+export const SINGLETON_PAGE_KINDS = ["main", "error", "maintain"];
+function briefPage(p) {
+    return { id: p.id, name: p.name, slug: p.slug ?? null, type: p.type ?? null, is_homepage: !!p.is_homepage };
+}
+/** Guard run before CREATING a page, so the agent edits the existing page instead of
+ *  piling up duplicates the storefront will never route to. Two rules:
+ *    1. singleton kinds (main/error/maintain, incl. `is_homepage`) — one per site;
+ *    2. every other kind — the slug must be free (the backend has a (site_id, slug)
+ *       unique index, so a duplicate slug fails there anyway, just with a vaguer error).
+ *  `custom` pages stay unlimited as long as their slugs differ.
+ *  Returns null when the page may be created. A failed lookup never blocks the create. */
+export async function checkPageCreateConflict(api, { kind, slug, is_homepage }) {
+    let pages;
+    try {
+        const res = await api.listPages();
+        pages = (res && res.data) || res || [];
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(pages))
+        return null;
+    const singleton = is_homepage ? "main" : kind;
+    if (singleton && SINGLETON_PAGE_KINDS.includes(singleton)) {
+        const typeNum = PAGE_TYPE_NUM[singleton];
+        const found = pages.find((p) => (singleton === "main" ? !!p.is_homepage || p.type === typeNum : p.type === typeNum));
+        if (found) {
+            return {
+                error: `This site already has a '${singleton}' page ("${found.name}"), and only one is allowed — ` +
+                    `only 'custom' pages can be created repeatedly. Edit page ${found.id} instead ` +
+                    `(replace_page_source / add_section / update_page), or create a 'custom' page.`,
+                existing_page: briefPage(found),
+            };
+        }
+    }
+    const cleanSlug = normalizeSlug(slug ?? undefined);
+    if (cleanSlug) {
+        const found = pages.find((p) => p.slug === cleanSlug);
+        if (found) {
+            return {
+                error: `This site already has a page at slug "${cleanSlug}" ("${found.name}"). Slugs are unique per site — ` +
+                    `edit page ${found.id} instead (replace_page_source / add_section / update_page), or pick another slug.`,
+                existing_page: briefPage(found),
+            };
+        }
+    }
+    return null;
+}
 /** Build the page.settings.seo block from simple inputs (the real shape; tokens like
  *  {{name_page}} / {{name_site}} are resolved by the storefront). */
 export function buildPageSeo(seo = {}) {
@@ -83,7 +136,7 @@ export function registerBuilderTools(server, api, handle) {
     server.tool("list_bindings", "List every dynamic-data BINDING target: the datasets (product, cart_item, order, order_item, post, category, customer, customer_address, …) and their exact field names ('product::product_price', …), which page type each needs (store/member/blog), and how repeater children (grid-product, cart-items, post-list) bind per-item. Attach via new_element opts.bindings (ids auto-minted, e.g. opts.bindings=[{ target:'product::product_price' }]).", {}, () => handle(async () => describeBindingsCatalog()));
     server.tool("new_element", "Build a single structurally-valid element node from the real builder factory. Returns the node — edit its specials/style, then place it in a section's children.", {
         type: z.string().describe("Element type (see list_elements)"),
-        opts: z.record(z.any()).optional().describe("Factory opts: { text, src, width, height, style, config, specials, events }"),
+        opts: z.record(z.any()).optional().describe("Factory opts: { text, src, width, height, style, config, specials, events, bindings, responsive, align }. align = horizontal placement in the grid cell: 'left'|'center'|'right'|'fill' (works on any element; buttons are content-width+centred by default — use align:'fill' to span the column)."),
     }, ({ type, opts }) => handle(async () => buildElement(type, opts || {})));
     server.tool("new_section", `Build a complete section node with children laid out in the builder's vertical grid.
 Pass an array of element specs; each child is stacked top-to-bottom. Nest containers via the child's own 'children'.
@@ -118,7 +171,8 @@ Example children: [{ "type":"container", "children":[{"type":"image","opts":{...
     }));
     server.tool("build_page", `Create a brand-new page AND set its full content source in one step.
 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.`, {
+The source must be { sections: [...] } — build sections with new_section. Validation errors block the real save.
+ONE page per site for type main (homepage) / error / maintain, and slugs are unique per site: a duplicate is refused (dry_run reports blocked:true) and you get the existing page_id to edit instead. Only 'custom' pages can be created over and over.`, {
         name: z.string().describe("Page name"),
         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)"),
@@ -148,18 +202,27 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         // 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);
+        // Only 'custom' pages may be created over and over; singleton kinds and taken
+        // slugs must be edited in place instead of duplicated.
+        const conflict = await checkPageCreateConflict(api, { kind, slug: cleanSlug, is_homepage });
         if (dry_run) {
             return {
                 dry_run: true,
+                ...(conflict ? { blocked: true, conflict } : {}),
                 validation,
                 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
-                    ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
-                    : "Fix the errors above before saving.",
+                hint: conflict
+                    ? conflict.error
+                    : validation.valid
+                        ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
+                        : "Fix the errors above before saving.",
             };
         }
+        if (conflict) {
+            return { error: conflict.error, existing_page: conflict.existing_page };
+        }
         if (!validation.valid) {
             return { error: "Validation failed — not saving.", validation };
         }

package/dist/tools/page-draft.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo, normalizeSlug } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo, normalizeSlug, checkPageCreateConflict } 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).
@@ -25,7 +25,8 @@ function newPageId(res) {
  * commit, so re-running commit_page_draft continues from where it stopped.
  */
 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.`, {
+    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.
+ONE page per site for type main (homepage) / error / maintain, and slugs are unique per site: the draft is refused up-front with the existing page_id to edit instead. Only 'custom' pages can be created over and over.`, {
         name: z.string().describe("Page name"),
         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
@@ -44,6 +45,11 @@ export function registerPageDraftTools(server, api, handle) {
             .optional()
             .describe("SEO for this page → settings.seo (applied on commit)."),
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
+        // Fail before the agent builds any sections: only 'custom' pages may be created
+        // repeatedly — singleton kinds and taken slugs must be edited in place.
+        const conflict = await checkPageCreateConflict(api, { kind: type, slug, is_homepage });
+        if (conflict)
+            return { error: conflict.error, existing_page: conflict.existing_page };
         const draft = await createDraft(api.siteId, { name, slug, type, is_homepage, seo });
         return {
             draft_id: draft.draft_id,
@@ -101,8 +107,16 @@ RESUMABLE: if a request fails mid-commit, the draft keeps its page_id + committe
         const full = { sections: draft.sections };
         const validation = validatePage(full);
         const total = draft.sections.length;
+        // Re-check on commit — a draft can sit for hours, and the page may have been
+        // created meanwhile. Skipped when resuming: the page already exists.
+        const conflict = draft.page_id
+            ? null
+            : await checkPageCreateConflict(api, { kind: draft.meta.type, slug: draft.meta.slug, is_homepage: draft.meta.is_homepage });
         if (dry_run) {
-            return { dry_run: true, draft_id, total_sections: total, validation, stats: validation.stats };
+            return { dry_run: true, draft_id, total_sections: total, ...(conflict ? { blocked: true, conflict } : {}), validation, stats: validation.stats };
+        }
+        if (conflict) {
+            return { error: conflict.error, existing_page: conflict.existing_page };
         }
         if (!validation.valid) {
             return { error: "Validation failed — not committing.", validation };

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, normalizeSlug } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_KINDS, buildPageSeo, normalizeSlug, checkPageCreateConflict } from "./builder.js";
 /**
  * Page source utilities.
  *
@@ -294,10 +294,10 @@ Examples:
         const results = searchElements(source, filters);
         return { page_id, matched: results.length, elements: results };
     }));
-    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.", {
+    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. ONE page per site for main (homepage) / error / maintain, and slugs are unique per site — a duplicate is refused with the existing page_id to edit instead; only 'custom' pages can be created over and over.", {
         name: z.string().describe("Page name"),
         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."),
+        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. main/error/maintain are one-per-site; use 'custom' for extra pages."),
         is_homepage: z.boolean().default(false).describe("Set as homepage"),
         seo: z
             .object({ title: z.string().optional(), description: z.string().optional(), keyword: z.string().optional(), favicon: z.string().optional(), thumbnail: z.string().optional() })
@@ -306,6 +306,11 @@ Examples:
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
         const cleanSlug = normalizeSlug(slug);
         const typeNum = type ? PAGE_TYPE_NUM[type] : undefined;
+        // Only 'custom' pages may be created repeatedly — singleton kinds (homepage/error/
+        // maintain) and taken slugs must be edited in place instead of duplicated.
+        const conflict = await checkPageCreateConflict(api, { kind: type, slug: cleanSlug, is_homepage });
+        if (conflict)
+            return { error: conflict.error, existing_page: conflict.existing_page };
         const created = await api.createPage({ name, ...(typeNum != null ? { type: typeNum } : {}) });
         invalidatePageCache();
         const pageId = (created && (created.id || created.data?.id || created.page?.id)) || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.31.7",
+  "version": "1.31.9",
   "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",
@@ -32,7 +32,7 @@
     "smoke": "node dist/smoke.js",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run smoke",
-    "test": "node --test test/"
+    "test": "node --test \"test/*.test.mjs\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",