webcake-storefront-mcp 1.18.1 → 1.19.1

package/dist/builder/attributes.js

@@ -172,9 +172,9 @@ export const ELEMENT_ATTRS = {
             show_message: "Show a success message after submit (boolean).",
             show_message_time: "How long the success message stays (seconds).",
         },
-        config: { backgroundInput: "Input background.", labelColor: "Label colour.", placeholderColor: "Placeholder colour.", textPadding: "Input padding (px).", labelMarginBottom: "Gap below label (px)." },
-        events: "none",
-        notes: "Wrap input fields as children; put a submit-button inside. specials.type selects what the form does on submit.",
+        config: { backgroundInput: "Input background.", labelColor: "Label colour.", placeholderColor: "Placeholder colour.", textPadding: "Input padding (px).", labelMarginBottom: "Gap below label (px).", borderColor: "Input border colour (e.g. #dbe0e6).", borderRadius: "Input corner radius (e.g. 8px)." },
+        events: "success — fire follow-up actions after a successful submit (a form_order commonly does open_page→Thank-you page). eventName defaults to 'success' on a form.",
+        notes: "Wrap input fields as children; put a submit-button inside. specials.type selects what the form does on submit. Real order forms split fields across an inner form via specials.multiForms:[innerFormId] (inner form sets specials.formParent). A form_order uses dedicated field types: input(full_name), phone-number, email, detect-address, address (×3 province/district/ward), text-area(note).",
     },
     input: { specials: { ...FIELD, type: "Input type (default text)." }, config: { textPadding: "Padding.", backgroundInput: "Background." }, events: "none" },
     email: { specials: { ...FIELD, validate_email: "Email regex." }, events: "none", notes: "field_name usually 'email'." },
@@ -205,22 +205,22 @@ export const ELEMENT_ATTRS = {
     switch: { events: "none", notes: "Toggle; style width/height." },
     // ── commerce ──
     "grid-product": {
-        specials: { displayStyle: "default | only_image | border.", original_price_position: "left | right." },
-        config: { columns: "Products per row.", responsive: "autofit | fixed.", item_show: "How many products to show.", image_ratio: "16/9|3/2|4/3|1/1|9/16|2/3|3/4.", img_object_fit: "cover|contain|fill|stretch.", gap_column: "Column gap.", gap_row: "Row gap.", product_info_alignment: "left|center|right." },
+        specials: { displayStyle: "default | only_image | border.", original_price_position: "left | right.", products_per_load: "Products fetched per page/scroll (real default 36).", show_original_price: "Show the compare-at price (boolean).", show_discount_on_price: "Show a discount badge on the price (boolean).", show_quick_view: "Show a quick-view button on hover (boolean)." },
+        config: { columns: "Products per row.", responsive: "autofit | fixed | custom.", item_show: "How many products to show.", image_ratio: "16/9|3/2|4/3|1/1|4/5|9/16|2/3|3/4 (designer templates use 4/5).", img_object_fit: "cover|contain|fill|stretch.", gap_column: "Column gap (real default 30).", gap_row: "Row gap (real default 15).", product_info_padding_y: "Vertical padding of the name/price block (px).", price_padding_y: "Vertical padding around the price (px).", product_info_alignment: "left|center|right.", productNameFont: "Product-name font family.", productNameFontSize: "Product-name font size (px).", productPriceFont: "Price font family.", productPriceFontSize: "Price font size (px).", productPriceFontWeight: "Price font weight (e.g. bold).", productOriginalPriceFontSize: "Compare-at price font size (px).", sizeThumbnail: "{ width, height } of the card image." },
         events: "none",
         bindings: ["product::product_image", "product::product_name", "product::product_price"],
-        notes: "Lists store products. Requires a 'store' page / use_store. Configure columns + image_ratio.",
+        notes: "Lists store products (self-renders image+name+price card). Requires a 'store' page / use_store. Configure columns + image_ratio (4/5 reads as a fashion card); the price/name fonts + show_* flags style the card.",
     },
     "slider-product": { specials: { displayStyle: "default|only_image|border.", original_price_position: "left|right." }, config: { slideItems: "Visible products.", slideWidth: "Card width.", image_ratio: "Aspect ratio." }, events: "none", bindings: ["product::product_image", "product::product_name", "product::product_price"] },
     "product-gallery": { events: "none", notes: "Product detail image gallery (product page)." },
     "product-image-carousel": { events: "none", notes: "Product image carousel (product page)." },
-    "cart-items": { events: "none", bindings: ["cart_item::cart_item_image", "cart_item::cart_item_name", "cart_item::cart_item_price", "cart_item::cart_item_total_price", "cart_item::cart_item_prod_attr"], notes: "Cart line items (cart page)." },
-    "cart-icon": { specials: { svg: "Icon SVG.", itemCount: "Badge count." }, events: "click — opens cart." },
+    "cart-items": { events: "none", bindings: ["cart_item::cart_item_image", "cart_item::cart_item_name", "cart_item::cart_item_price", "cart_item::cart_item_total_price", "cart_item::cart_item_prod_attr"], notes: "Cart line items (cart page). A repeater whose config.columns defines the per-row column template — real templates use [70px image, 1fr name, ~240px price, ~116px qty, ~240px total, 34px remove]." },
+    "cart-icon": { specials: { svg: "Icon SVG (defaults to a bag icon; fill='currentColor' so it inherits style.color).", itemCount: "Badge count (0 placeholder)." }, config: { itemCountFontFamily: "Badge font family.", itemCountFontSize: "Badge font size (e.g. 11px).", itemCountColor: "Badge text colour.", itemCountBorderRadius: "Badge corner radius (50% = circle)." }, events: "click — opens cart. Real templates wrap it in a container with open_popup(mouseenter)/close_popup(mouseleave) for a mini-cart, plus a container with open_page→cart page." },
     "quantity-input": { events: "none", notes: "Quantity stepper (product/cart)." },
     attr: { events: "none", notes: "Product attribute selector (variations)." },
     payment: { events: "none", notes: "Payment methods block (checkout)." },
     "delivery-method": { specials: { options: "[{type: delivery|store_pickup, name, active}]." }, events: "none" },
-    "order-items": { events: "none", bindings: ["order_item::product_image", "order_item::product_name", "order_item::product_quantity", "order_item::product_attrs", "order_item::items_sum_up_price"], notes: "Order summary lines." },
+    "order-items": { events: "none", bindings: ["order_item::product_image", "order_item::product_name", "order_item::product_quantity", "order_item::product_attrs", "order_item::items_sum_up_price"], notes: "Order summary lines (checkout/thank-you). Repeater whose config.columns is the per-row template — real templates use [75px image, 1fr name, 95px price]." },
     "order-history": { events: "none", notes: "Member order history (member page)." },
     coupon: { events: "none", notes: "Coupon / discount code input." },
     "product-overlay": { specials: { type: "discount | custom." }, events: "none", notes: "Badge overlaid on a product card." },
@@ -253,8 +253,8 @@ export const ELEMENT_ATTRS = {
     "favorite-icon": { events: "click — toggle favourite." },
     "bonus-items": { specials: { typeBonus: "combo_product | other." }, events: "none" },
     // ── navigation ──
-    menu: { specials: { type: "horizontal | vertical | hamburger | anchor.", sync: "Auto-sync items with site pages (boolean)." }, events: "none", notes: "Holds menu-item children." },
-    "menu-item": { specials: { name: "Link label.", isCustom: "Custom link (boolean).", linkType: "page | category | blog_category | brand | product_tag | custom.", linkCategory: "Linked category id.", categoryId: "Category id.", syncSubmenu: "Auto-build submenu (boolean)." }, events: "click — navigates.", notes: "Set linkType + the matching id (or a custom href) to point the link." },
+    menu: { specials: { type: "horizontal | vertical | hamburger | anchor.", sync: "Auto-sync items with site pages (boolean).", fullField: "Stretch items to fill the menu width (boolean)." }, config: { showArrow: "Show the dropdown caret on items with a submenu (boolean).", textColor: "Item text colour (often a theme var like var(--color_20)).", colorHover: "Item hover colour.", "--padX": "Horizontal padding inside each item (CSS var, e.g. 15px)." }, events: "none", notes: "Holds menu-item children. Real templates colour items via theme vars (var(--color_20))." },
+    "menu-item": { specials: { name: "Link label.", isCustom: "Custom link (boolean).", linkType: "page | category | blog_category | brand | product_tag | custom.", linkPage: "Target page id (linkType=page).", pageId: "Target page id (mirror of linkPage, set both).", linkCategory: "Linked category id.", categoryId: "Category id.", syncSubmenu: "Auto-build submenu (boolean)." }, events: "navigation lives in SPECIALS here, NOT events — set linkType + the matching id.", notes: "For a page link set linkType='page' + linkPage + pageId + name. (Generic text/container/button elements navigate via events:[{action:'open_page',open_page_id}] instead.)" },
     "menu-anchor-item": { specials: { name: "Label.", isCustom: "Custom.", linkType: "Link kind.", categoryId: "Category id." }, events: "click — scrolls to an anchor." },
     submenu: { events: "none", notes: "Dropdown under a menu-item." },
     "menu-droppable": { events: "none" },

package/dist/builder/factory.js

@@ -363,15 +363,42 @@ export const buildElementWithBreakpoint = (el, breakpoint) => {
     el.specials = Object.assign({}, el.specials || {}, customSpecials);
     delete el.runtime;
 };
+// Real designer-template grid-product defaults (mined from prod theme "Mode Féminine"):
+// the card self-renders image + name + price; these keys control its look. Callers may
+// override any of them via opts.config / opts.specials.
 export const createGridProduct = (opts = {}) => {
     const product = cloneDeep(SKELETON);
     product.id = 'GRID-PRODUCT-' + randomString(8);
     product.type = 'grid-product';
     product.runtime.style = {
         width: opts.width,
-        height: 354
+        height: 354,
+        ...(opts.style || {})
+    };
+    product.runtime.config = {
+        columns: 4,
+        image_ratio: '4/5',
+        img_object_fit: 'cover',
+        gap_column: 30,
+        gap_row: 15,
+        product_info_padding_y: 15,
+        price_padding_y: 5,
+        productNameFontSize: 18,
+        productPriceFontSize: 18,
+        productPriceFontWeight: 'bold',
+        productOriginalPriceFontSize: 18,
+        responsive: 'custom',
+        heightUnit: 'auto',
+        ...(opts.config || {})
+    };
+    product.specials = {
+        element_async: true,
+        products_per_load: 36,
+        show_original_price: true,
+        show_discount_on_price: true,
+        show_quick_view: false,
+        ...(opts.specials || {})
     };
-    product.runtime.config = { heightUnit: 'auto' };
     return product;
 };
 export const createSliderProduct = (opts = {}) => {
@@ -441,17 +468,28 @@ export const createMemberBar = (opts = {}) => {
     menuBar.specials = { ...opts.specials };
     return menuBar;
 };
-export const createCartIcon = ({ svg, itemCount, config, children } = {}) => {
+// Default shopping-bag icon (real prod template svg, 28×28, fill=currentColor so it
+// inherits the element's colour). Used when a caller doesn't supply its own svg, so a
+// header cart-icon is never blank.
+const DEFAULT_CART_SVG = '<svg width="100%" height="100%" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M14.0166 3.76758C10.2864 3.76758 7.38924 7.04233 7.38924 10.9179C7.38924 10.9179 7.38924 10.9179 7.38924 10.918H4.94829C4.21457 10.918 3.66298 11.5872 3.8031 12.3074L5.89025 23.0355C6.10354 24.1318 7.06378 24.9232 8.18064 24.9232H19.8444C20.9613 24.9232 21.9215 24.1318 22.1348 23.0355L24.2219 12.3074C24.3621 11.5872 23.8105 10.918 23.0767 10.918H20.644C20.644 10.9179 20.644 10.9179 20.644 10.9179C20.644 7.04233 17.7468 3.76758 14.0166 3.76758ZM18.894 10.918C18.894 10.9179 18.894 10.9179 18.894 10.9179C18.894 7.86235 16.6401 5.51758 14.0166 5.51758C11.3931 5.51758 9.13924 7.86235 9.13924 10.9179C9.13924 10.9179 9.13924 10.9179 9.13924 10.918H18.894ZM7.60804 22.7013L5.65605 12.668H22.369L20.417 22.7013C20.3637 22.9754 20.1236 23.1732 19.8444 23.1732H8.18064C7.90143 23.1732 7.66137 22.9754 7.60804 22.7013Z" fill="currentColor"></path></svg>';
+export const createCartIcon = ({ svg, itemCount, config, style, children } = {}) => {
     const cart = cloneDeep(SKELETON);
     cart.id = 'CART-ICON-' + randomString(8);
     cart.type = 'cart-icon';
-    cart.runtime.config = { ...config };
+    cart.runtime.config = {
+        itemCountFontFamily: 'Roboto',
+        itemCountFontSize: '11px',
+        itemCountColor: 'white',
+        itemCountBorderRadius: '50%',
+        ...config
+    };
     cart.runtime.style = {
         width: 24,
-        height: 24
+        height: 24,
+        ...(style || {})
     };
-    cart.specials.svg = svg;
-    cart.specials.itemCount = itemCount;
+    cart.specials.svg = svg || DEFAULT_CART_SVG;
+    cart.specials.itemCount = itemCount ?? 0;
     if (children)
         cart.children = children || [];
     return cart;
@@ -558,7 +596,11 @@ export const createProductGallery = (opts = {}) => {
     gallery.id = 'PRODUCT-GALLERY-' + randomString(8);
     gallery.type = 'product-gallery';
     gallery.runtime.style = opts.style || {};
-    gallery.runtime.config = opts.config || {};
+    gallery.runtime.config = {
+        sizeThumbnail: { width: 580, height: 580 },
+        heightUnit: 'auto',
+        ...(opts.config || {})
+    };
     return gallery;
 };
 export const createProductImagesCarousel = (opts = {}) => {

package/dist/builder/guide.js

@@ -87,9 +87,13 @@ A bare stack of default elements looks unfinished. Apply real styling:
 - 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.
-- PRODUCT GRID: style the cards — \`grid-product opts.config\`: { columns:3-4, image_ratio:"1/1",
-  img_object_fit:"cover", gap_column:20, gap_row:28, cardBorderRadius:12, cardBoxShadow:"0 6px 24px rgba(0,0,0,.08)",
-  productNameColor:"var(--color_00)", productPriceColor:"var(--color_02)" }.
+- PRODUCT GRID: grid-product SELF-RENDERS the image+name+price card; you mostly set
+  \`opts.config\`: { columns:3-4, image_ratio:"4/5" (a tall fashion card; "1/1" for square),
+  img_object_fit:"cover", gap_column:30, gap_row:15, product_info_padding_y:15,
+  productNameFontSize:18, productPriceFontSize:18, productPriceFontWeight:"bold" } and
+  \`opts.specials\`: { products_per_load:36, show_original_price:true, show_discount_on_price:true }.
+  (These are the real designer-template defaults — the factory now ships them, so a bare
+  grid-product already looks right; there are NO cardBorderRadius/cardBoxShadow keys.)
 - BRAND COLOURS: reuse var(--color_00) (text), and an accent (var(--color_02)/var(--color_03))
   for buttons, prices, highlights — consistent accent = looks intentional.
 - IMAGES: must be WebCake-CDN urls (search_images cdn_url / upload_images), else they won't show.
@@ -137,7 +141,12 @@ fields); the builder mints the id and picks a sensible \`eventName\` (trigger).
 - Commerce: \`{ action:"add_to_cart", open_page:"cart" }\`, \`{ action:"buy_now" }\`, \`{ action:"apply_promotion" }\`.
 - Contact: \`{ action:"phone_call", phone_call_number:"+84…" }\`, \`{ action:"open_email", open_email:"hi@shop.vn" }\`.
 - Hover style (set eventName:"hover"): \`{ eventName:"hover", action:"scale" }\`.
+- Form follow-up (eventName defaults to "success" on a form): a form_order commonly carries
+  \`{ action:"open_page", open_page_id:"<thank-you page>" }\` so a successful order redirects.
 Example: \`new_element("button", { text:"Mua ngay", style:{…}, events:[{ action:"add_to_cart", open_page:"cart" }] })\`.
+NAV EXCEPTION — \`menu\`/\`menu-item\`: a menu-item's navigation lives in its SPECIALS, not events.
+For a page link set \`menu-item specials\`: { linkType:"page", linkPage:"<page id>", pageId:"<page id>", name:"Trang chủ" }.
+(Only generic elements — text/container/button/image/rectangle — navigate via the events array above.)
 validate_page warns on unknown actions, missing required fields, and events whose
 in-page target (toggle_id/scroll_to_id/…) doesn't exist on the page.
 
@@ -161,9 +170,13 @@ 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\` creates FUNCTIONAL but MINIMAL pages (a heading + the binding element);
-treat them as STARTERS to enrich, not the finished page. After scaffolding, rebuild each page's
-source so it looks designed:
+\`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):
 - 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,

package/dist/builder/templates.js

@@ -0,0 +1,411 @@
+// High-level, palette-aware PAGE & CHROME templates.
+//
+// The low-level builders (new_section/new_element/new_row -> buildSection/buildRow/
+// buildElement) are flexible but leave the AI to hand-compose every node, so generated
+// store pages end up bare. These templates encode the per-page recipes from the BUILD_GUIDE
+// as ready-to-save `{ sections: [...] }` sources that already look like a real shop:
+// styled headings, breadcrumbs, 2-column product detail, styled product-grid cards, trust
+// badges, an order summary, and a designed header/footer.
+//
+// Everything is built through buildSection/buildRow so the output is the same runtime shape
+// the builder emits; finalizeForRender() (called by the tools) expands it to bp1..bp4.
+//
+// Colours use the site theme CSS vars by default (var(--color_02) accent, var(--color_00)
+// text) so a generated site matches whatever palette the theme already defines; callers can
+// override any slot via a Palette object.
+import { buildSection, walk } from "./page.js";
+import { normalizeEvents } from "./events.js";
+const DEFAULT_PALETTE = {
+    accent: "var(--color_02)",
+    onAccent: "#ffffff",
+    text: "var(--color_00)",
+    muted: "#6b7280",
+    surface: "#ffffff",
+    surfaceAlt: "#f7f5f2",
+    border: "#e8e3dc",
+};
+export function resolvePalette(p = {}) {
+    return { ...DEFAULT_PALETTE, ...Object.fromEntries(Object.entries(p).filter(([, v]) => v != null)) };
+}
+// ---------------------------------------------------------------------------
+// small spec helpers (return element specs for buildSection/buildRow children)
+// ---------------------------------------------------------------------------
+const heading = (text, opts = {}) => ({
+    type: "text",
+    opts: {
+        text,
+        specials: { tag: opts.tag || "h2" },
+        style: {
+            fontSize: `${opts.size ?? 30}px`,
+            fontWeight: String(opts.weight ?? 700),
+            color: opts.color,
+            textAlign: opts.align,
+            lineHeight: "1.25",
+        },
+    },
+});
+const paragraph = (text, p, opts = {}) => ({
+    type: "text",
+    opts: {
+        text,
+        style: {
+            fontSize: `${opts.size ?? 16}px`,
+            fontWeight: "400",
+            color: opts.color || p.muted,
+            textAlign: opts.align,
+            lineHeight: "1.6",
+        },
+    },
+});
+/** Accent CTA button. `navTo` is a slug sentinel the scaffolder resolves to a real
+ *  open_page event once all pages exist (see wireNavigation). The sentinel rides INSIDE an
+ *  events entry because the button factory keeps opts.events but drops arbitrary specials. */
+const cta = (text, p, opts = {}) => ({
+    type: "button",
+    opts: {
+        text,
+        ...(opts.events || opts.navTo ? { events: [...(opts.events || []), ...(opts.navTo ? [{ action: "open_page", _navTo: opts.navTo }] : [])] } : {}),
+        style: {
+            background: p.accent,
+            color: p.onAccent,
+            borderRadius: "10px",
+            height: opts.height ?? 50,
+            fontWeight: "600",
+            fontSize: "16px",
+            paddingLeft: "28px",
+            paddingRight: "28px",
+            ...(opts.full ? { width: "100%" } : {}),
+            textAlign: "center",
+        },
+    },
+});
+const outlineBtn = (text, p, opts = {}) => ({
+    type: "button",
+    opts: {
+        text,
+        ...(opts.navTo ? { events: [{ action: "open_page", _navTo: opts.navTo }] } : {}),
+        style: {
+            background: "transparent",
+            color: p.accent,
+            border: `1px solid ${p.accent}`,
+            borderRadius: "10px",
+            height: opts.height ?? 48,
+            fontWeight: "600",
+            fontSize: "15px",
+            paddingLeft: "24px",
+            paddingRight: "24px",
+            textAlign: "center",
+        },
+    },
+});
+/** A small "icon + label" trust badge (free shipping, authentic, support…). */
+const trustBadge = (icon, label, p) => ({
+    type: "container",
+    layout: "row",
+    columnGap: 10,
+    colWidths: [{ unit: "px", absValue: 30 }, { unit: "fr", value: 1 }],
+    collapse: { bp4: 2 },
+    children: [
+        { type: "text", opts: { text: icon, style: { fontSize: "22px", lineHeight: "1.2" } } },
+        { type: "text", opts: { text: label, style: { fontSize: "13px", fontWeight: "600", color: p.text, lineHeight: "1.3" } } },
+    ],
+});
+/** A product-grid card config matching real designer templates. grid-product self-renders
+ *  image + name + price; the factory now ships the real designer defaults (image_ratio 4/5,
+ *  products_per_load 36, gap_column 30/gap_row 15, bold price, show original/discount price),
+ *  so here we only set the column count + the price accent colour from the palette. */
+const productGrid = (p, columns = 4) => ({
+    type: "grid-product",
+    opts: {
+        config: {
+            columns,
+            productPriceColor: p.accent,
+        },
+    },
+});
+/** Dataset text bound to a product field (name/price/description). */
+const productField = (field, style) => ({
+    type: "text-dataset",
+    opts: {
+        bindings: [{ id: "BINDING" + Math.random().toString(36).slice(2, 8), name: "product", target: `product::${field}` }],
+        style,
+    },
+});
+const sectionStyle = (p, bg, padY = 64) => ({
+    style: { background: bg, paddingTop: padY, paddingBottom: padY, paddingLeft: 20, paddingRight: 20 },
+});
+// ---------------------------------------------------------------------------
+// STORE PAGE templates -> { sections: [...] }
+// ---------------------------------------------------------------------------
+export function categoryPageSource(p, opts = {}) {
+    const banner = buildSection([
+        { type: "breadcrumb", opts: { style: { fontSize: "13px", color: p.muted } } },
+        heading(opts.title || "Tất cả sản phẩm", { tag: "h1", size: 40, color: p.text, align: "center" }),
+        paragraph(opts.subtitle || "Khám phá bộ sưu tập của chúng tôi", p, { align: "center", size: 17 }),
+    ], { ...sectionStyle(p, p.surfaceAlt, 56), rowGap: 12 });
+    const grid = buildSection([productGrid(p, 4)], sectionStyle(p, p.surface, 56));
+    return { sections: [banner, grid] };
+}
+export function productPageSource(p) {
+    const breadcrumbRow = buildSection([{ type: "breadcrumb", opts: { style: { fontSize: "13px", color: p.muted } } }], { ...sectionStyle(p, p.surface, 24) });
+    const infoColumn = {
+        type: "container",
+        children: [
+            productField("product_name", { fontSize: "30px", fontWeight: "700", color: p.text, lineHeight: "1.25" }),
+            productField("product_price", { fontSize: "26px", fontWeight: "700", color: p.accent }),
+            productField("product_description", { fontSize: "15px", fontWeight: "400", color: p.muted, lineHeight: "1.6" }),
+            { type: "quantity-input", opts: { style: { borderColor: p.border, borderRadius: "8px" } } },
+            cta("Thêm vào giỏ", p, { full: true, height: 52, events: [{ action: "add_to_cart", open_page: "cart" }] }),
+            {
+                type: "container",
+                layout: "row",
+                columnGap: 16,
+                collapse: { bp4: 1 },
+                children: [
+                    trustBadge("🚚", "Miễn phí giao hàng", p),
+                    trustBadge("✅", "Hàng chính hãng", p),
+                    trustBadge("↩️", "Đổi trả 7 ngày", p),
+                ],
+            },
+        ],
+    };
+    const detail = buildSection([
+        {
+            type: "container",
+            layout: "row",
+            columnGap: 48,
+            colWidths: [{ unit: "fr", value: 1 }, { unit: "fr", value: 1 }],
+            collapse: { bp3: 1, bp4: 1 },
+            children: [{ type: "product-gallery", opts: { style: { borderRadius: "14px" } } }, infoColumn],
+        },
+    ], sectionStyle(p, p.surface, 32));
+    const related = buildSection([heading("Sản phẩm liên quan", { tag: "h2", size: 26, color: p.text, align: "center" }), productGrid(p, 4)], { ...sectionStyle(p, p.surfaceAlt, 56), rowGap: 24 });
+    return { sections: [breadcrumbRow, detail, related] };
+}
+export function cartPageSource(p) {
+    const summary = {
+        type: "container",
+        opts: { style: { background: p.surfaceAlt, borderRadius: "14px", padding: "24px", border: `1px solid ${p.border}` } },
+        children: [
+            heading("Tóm tắt đơn hàng", { tag: "h3", size: 20, color: p.text }),
+            paragraph("Phí vận chuyển và mã giảm giá sẽ được tính ở bước thanh toán.", p, { size: 14 }),
+            cta("Tiến hành thanh toán", p, { full: true, height: 52, navTo: "checkout" }),
+            outlineBtn("Tiếp tục mua sắm", p, { navTo: "home" }),
+        ],
+    };
+    const body = buildSection([
+        heading("Giỏ hàng của bạn", { tag: "h1", size: 34, color: p.text }),
+        {
+            type: "container",
+            layout: "row",
+            columnGap: 40,
+            colWidths: [{ unit: "fr", value: 2 }, { unit: "fr", value: 1 }],
+            collapse: { bp3: 1, bp4: 1 },
+            children: [{ type: "cart-items", opts: {} }, summary],
+        },
+    ], { ...sectionStyle(p, p.surface, 48), rowGap: 24 });
+    return { sections: [body] };
+}
+export function checkoutPageSource(p) {
+    // form_order config keys mirror real designer templates: input background, placeholder
+    // colour, label colour/gap, input padding. The success event (eventName defaults to
+    // "success" for a form) redirects to the Thank-you page once it exists (navTo sentinel).
+    const fieldStyle = { borderColor: p.border, borderRadius: "8px" };
+    const formConfig = {
+        backgroundInput: "#ffffff",
+        placeholderColor: p.muted,
+        labelColor: p.text,
+        labelMarginBottom: 8,
+        textPadding: 15,
+        columnGap: 15,
+        rowGap: 15,
+    };
+    const form = {
+        type: "form",
+        opts: {
+            specials: { type: "form_order" },
+            config: formConfig,
+            events: [{ action: "open_page", _navTo: "complete" }],
+            style: { background: p.surface },
+        },
+        children: [
+            { type: "input", opts: { specials: { field_name: "full_name", label: "Họ và tên", placeholder: "Nguyễn Văn A", required: true, show_label: true }, config: formConfig, style: fieldStyle } },
+            { type: "phone-number", opts: { specials: { field_name: "phone_number", label: "Số điện thoại", placeholder: "09xx xxx xxx", required: true, show_label: true }, config: formConfig, style: fieldStyle } },
+            { type: "email", opts: { specials: { field_name: "email", label: "Email", placeholder: "email@example.com", show_label: true }, config: formConfig, style: fieldStyle } },
+            { type: "address", opts: { specials: { field_name: "address", label: "Địa chỉ nhận hàng", show_label: true }, config: formConfig, style: fieldStyle } },
+            { type: "text-area", opts: { specials: { field_name: "note", label: "Ghi chú", placeholder: "Ghi chú cho đơn hàng (tuỳ chọn)", show_label: true }, config: formConfig, style: fieldStyle } },
+            { type: "submit-button", opts: { text: "Đặt hàng", style: { background: p.accent, color: p.onAccent, borderRadius: "10px", height: 52, fontWeight: "600", width: "100%", textAlign: "center" } } },
+        ],
+    };
+    const summary = {
+        type: "container",
+        opts: { style: { background: p.surfaceAlt, borderRadius: "14px", padding: "24px", border: `1px solid ${p.border}` } },
+        children: [heading("Đơn hàng của bạn", { tag: "h3", size: 20, color: p.text }), { type: "cart-items", opts: {} }],
+    };
+    const body = buildSection([
+        heading("Thanh toán", { tag: "h1", size: 34, color: p.text }),
+        {
+            type: "container",
+            layout: "row",
+            columnGap: 40,
+            colWidths: [{ unit: "fr", value: 3 }, { unit: "fr", value: 2 }],
+            collapse: { bp3: 1, bp4: 1 },
+            children: [form, summary],
+        },
+    ], { ...sectionStyle(p, p.surface, 48), rowGap: 24 });
+    return { sections: [body] };
+}
+export function thankYouPageSource(p) {
+    const body = buildSection([
+        heading("🎉", { tag: "h2", size: 56, align: "center" }),
+        heading("Cảm ơn bạn đã đặt hàng!", { tag: "h1", size: 34, color: p.text, align: "center" }),
+        paragraph("Chúng tôi đã nhận được đơn hàng của bạn và sẽ liên hệ xác nhận trong thời gian sớm nhất.", p, { align: "center", size: 17 }),
+        { type: "order-items", opts: {} },
+        cta("Tiếp tục mua sắm", p, { navTo: "home" }),
+    ], { ...sectionStyle(p, p.surface, 64), rowGap: 18 });
+    return { sections: [body] };
+}
+export function headerSection(opts = {}) {
+    const p = resolvePalette(opts.palette);
+    const links = opts.links && opts.links.length ? opts.links : [
+        { label: "Trang chủ", navTo: "home" },
+        { label: "Sản phẩm", navTo: "collections" },
+        { label: "Giỏ hàng", navTo: "cart" },
+    ];
+    const logo = { type: "text", opts: { text: opts.brand || "Shop", specials: { tag: "h2" }, style: { fontSize: "24px", fontWeight: "800", color: p.text } } };
+    const nav = {
+        type: "container",
+        layout: "row",
+        columnGap: 28,
+        collapse: { bp4: 3 },
+        children: links.map((l) => ({
+            type: "text",
+            opts: {
+                text: l.label,
+                ...(l.navTo || l.url ? { specials: { ...(l.navTo ? { _navTo: l.navTo } : {}), ...(l.url ? { _navUrl: l.url } : {}) } } : {}),
+                style: { fontSize: "15px", fontWeight: "600", color: p.text, cursor: "pointer" },
+            },
+        })),
+    };
+    const actions = {
+        type: "container",
+        layout: "row",
+        columnGap: 16,
+        colWidths: [{ unit: "px", absValue: 32 }, { unit: "max-c" }],
+        collapse: { bp4: 2 },
+        children: [
+            { type: "cart-icon", opts: { style: { width: 26, height: 26, color: p.text } } },
+            cta(opts.cta || "Đặt mua ngay", p, { navTo: "collections", height: 44 }),
+        ],
+    };
+    return buildSection([
+        {
+            type: "container",
+            layout: "row",
+            columnGap: 24,
+            colWidths: [{ unit: "max-c" }, { unit: "fr", value: 1 }, { unit: "max-c" }],
+            collapse: { bp4: 1 },
+            children: [logo, nav, actions],
+        },
+    ], { style: { background: p.surface, paddingTop: 16, paddingBottom: 16, paddingLeft: 20, paddingRight: 20, borderBottom: `1px solid ${p.border}` } });
+}
+export function footerSection(opts = {}) {
+    const p = resolvePalette(opts.palette);
+    const brandCol = {
+        type: "container",
+        children: [
+            { type: "text", opts: { text: opts.brand || "Shop", specials: { tag: "h3" }, style: { fontSize: "20px", fontWeight: "800", color: "#fff" } } },
+            { type: "text", opts: { text: opts.tagline || "Cảm ơn bạn đã ghé thăm cửa hàng.", style: { fontSize: "14px", color: "rgba(255,255,255,0.7)", lineHeight: "1.6" } } },
+        ],
+    };
+    const linkCols = (opts.columns && opts.columns.length ? opts.columns : [
+        { title: "Cửa hàng", links: ["Trang chủ", "Sản phẩm", "Giỏ hàng"] },
+        { title: "Hỗ trợ", links: ["Chính sách đổi trả", "Giao hàng", "Liên hệ"] },
+    ]).map((col) => ({
+        type: "container",
+        children: [
+            { type: "text", opts: { text: col.title, style: { fontSize: "15px", fontWeight: "700", color: "#fff" } } },
+            ...col.links.map((t) => ({ type: "text", opts: { text: t, style: { fontSize: "14px", color: "rgba(255,255,255,0.7)", lineHeight: "2" } } })),
+        ],
+    }));
+    const c = opts.contact || {};
+    const contactCol = {
+        type: "container",
+        children: [
+            { type: "text", opts: { text: "Liên hệ", style: { fontSize: "15px", fontWeight: "700", color: "#fff" } } },
+            ...(c.phone ? [{ type: "text", opts: { text: `📞 ${c.phone}`, style: { fontSize: "14px", color: "rgba(255,255,255,0.7)", lineHeight: "2" } } }] : []),
+            ...(c.email ? [{ type: "text", opts: { text: `✉️ ${c.email}`, style: { fontSize: "14px", color: "rgba(255,255,255,0.7)", lineHeight: "2" } } }] : []),
+            ...(c.address ? [{ type: "text", opts: { text: `📍 ${c.address}`, style: { fontSize: "14px", color: "rgba(255,255,255,0.7)", lineHeight: "1.6" } } }] : []),
+        ],
+    };
+    const topRow = {
+        type: "container",
+        layout: "row",
+        columnGap: 40,
+        colWidths: [{ unit: "fr", value: 2 }, { unit: "fr", value: 1 }, { unit: "fr", value: 1 }, { unit: "fr", value: 1 }],
+        collapse: { bp3: 2, bp4: 1 },
+        children: [brandCol, ...linkCols, contactCol],
+    };
+    const copyright = { type: "text", opts: { text: `© ${opts.brand || "Shop"}. All rights reserved.`, style: { fontSize: "13px", color: "rgba(255,255,255,0.5)", textAlign: "center" } } };
+    return buildSection([topRow, copyright], {
+        style: { background: "#1c1917", paddingTop: 56, paddingBottom: 32, paddingLeft: 20, paddingRight: 20 },
+        rowGap: 32,
+    });
+}
+// ---------------------------------------------------------------------------
+// registry the scaffolder iterates
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the `_navTo` / `_navUrl` sentinels the templates leave on buttons/links into real
+ * open_page / open_link events, now that every page exists and we know its id. `slugToId`
+ * maps a page slug (e.g. "checkout", "cart", "collections") to its page id; the special
+ * slug "home" maps to the homepage id. Returns the number of nodes wired so the caller can
+ * skip re-saving an unchanged page. Run on the raw source BEFORE finalizeForRender.
+ */
+export function wireNavigation(source, slugToId) {
+    let wired = 0;
+    const resolve = (slug) => slugToId[slug] || slugToId[slug.replace(/^\//, "")];
+    walk(source, (node) => {
+        // (a) text links carry the sentinel in specials (the text factory keeps it).
+        const sp = node && node.specials;
+        if (sp && sp._navTo) {
+            const id = resolve(sp._navTo);
+            if (id) {
+                node.events = normalizeEvents([{ action: "open_page", open_page_id: id }], node.type);
+                wired++;
+            }
+            delete sp._navTo;
+        }
+        if (sp && sp._navUrl) {
+            node.events = normalizeEvents([{ action: "open_link", link_target: sp._navUrl, link_target_url: sp._navUrl }], node.type);
+            delete sp._navUrl;
+            wired++;
+        }
+        // (b) buttons carry the sentinel inside an events entry (the button factory keeps events
+        //     but drops arbitrary specials). Resolve _navTo -> open_page_id in place; drop the
+        //     event entirely if its target page doesn't exist so we never emit a dead open_page.
+        if (Array.isArray(node && node.events) && node.events.length) {
+            node.events = node.events
+                .map((e) => {
+                if (e && e._navTo) {
+                    const id = resolve(e._navTo);
+                    const { _navTo, ...rest } = e;
+                    if (!id)
+                        return null;
+                    wired++;
+                    return { ...rest, open_page_id: id };
+                }
+                return e;
+            })
+                .filter(Boolean);
+        }
+    });
+    return wired;
+}
+export const STORE_PAGE_TEMPLATES = [
+    { name: "Category Page", slug: "collections", build: categoryPageSource },
+    { name: "Product Page", slug: "products", build: productPageSource },
+    { name: "Cart Page", slug: "cart", build: cartPageSource },
+    { name: "Checkout Page", slug: "checkout", build: checkoutPageSource },
+    { name: "Thank You Page", slug: "complete", build: thankYouPageSource },
+];

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.19.1",
+    "d": "25/06/2026",
+    "type": "Fixed",
+    "en": "create_site_from_template now auto-generates a URL-safe slug from the site name when none is supplied, fixing the 400 error returned by the backend…",
+    "vi": "create_site_from_template nay tự động tạo slug an toàn cho URL từ tên site khi không có slug nào được cung cấp, khắc phục lỗi 400 mà backend trả về…"
+  },
+  {
+    "v": "1.19.0",
+    "d": "25/06/2026",
+    "type": "Added",
+    "en": "New scaffold_global_sections tool generates a fully-designed global Header and Footer in one call — logo, nav links, cart icon, CTA button, and a…",
+    "vi": "Tool mới scaffold_global_sections tạo Header và Footer toàn cục đã thiết kế sẵn trong một lần gọi — logo, liên kết điều hướng, icon giỏ hàng, nút…"
+  },
   {
     "v": "1.18.1",
     "d": "25/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New new_row tool builds a multi-column responsive row container where child elements are placed side by side (left to right); the row auto-collapses…",
     "vi": "Tool mới new_row tạo một container đa cột responsive với các phần tử con được đặt nằm ngang cạnh nhau (từ trái sang phải); hàng tự động thu gọn…"
-  },
-  {
-    "v": "1.16.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New uninstall_app, update_app, and update_app_review tools complete the app lifecycle: uninstall an installed app by subscription id, patch an app's…",
-    "vi": "Tool mới uninstall_app, update_app và update_app_review hoàn thiện vòng đời ứng dụng: gỡ cài đặt theo subscription id, cập nhật config/status của…"
-  },
-  {
-    "v": "1.15.1",
-    "d": "24/06/2026",
-    "type": "Fixed",
-    "en": "update_page_element, update_page_elements, update_global_source_element, and update_global_source_elements now normalize events and bindings arrays…",
-    "vi": "update_page_element, update_page_elements, update_global_source_element và update_global_source_elements nay chuẩn hóa mảng events và bindings khi…"
   }
 ]

package/dist/tools/builder.js

@@ -4,6 +4,7 @@ import { listElements, getElement, buildElement } from "../builder/catalog.js";
 import { describeEventsCatalog } from "../builder/events.js";
 import { describeBindingsCatalog } from "../builder/bindings.js";
 import { buildSection, buildRow, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
+import { STORE_PAGE_TEMPLATES, resolvePalette, wireNavigation } from "../builder/templates.js";
 // Recursive spec for new_section / build_page children.
 const elementSpec = z.object({
     type: z.string().describe("Element type (see list_elements)"),
@@ -198,13 +199,19 @@ Creates only the ones MISSING (matched by slug): Category (collections), Product
 Cart (cart), Checkout (checkout), Thank-you (complete) — all type 'store' (enables use_store),
 plus optional member (login/register/profile) and blog (blog/post) pages.
 Run this right after you create products/categories. dry_run=true (default) previews.
-NOTE: these are MINIMAL STARTER pages (a heading + the binding element) — you MUST then
-enrich EACH one to the same standard as the home page (see get_build_guide "Build the WHOLE
-storefront"), and add a GLOBAL header/footer (create_global_section). Don't leave them bare.`, {
+By default (style:"rich") each store page is a FULLY-DESIGNED, palette-aware page — banner +
+breadcrumb + styled product-grid cards (Category), 2-column gallery|info with price/quantity/
+add-to-cart + trust badges + related products (Product), 2-col cart|summary, 2-col checkout
+form|summary, and a centred thank-you — and navigation between them (cart→checkout, add-to-cart
+→cart, thank-you→home) is auto-wired. Colours follow the site theme vars unless you pass a palette.
+Still add a GLOBAL header/footer with scaffold_global_sections (or create_global_section).
+Pass style:"minimal" for the old bare stubs (heading + binding element only).`, {
+        style: z.enum(["rich", "minimal"]).default("rich").describe("'rich' = fully-designed, palette-aware store pages (default). 'minimal' = bare starter stubs you must enrich yourself."),
+        palette: z.record(z.any()).optional().describe("Optional colour overrides for rich pages: { accent, onAccent, text, muted, surface, surfaceAlt, border }. Defaults to the site theme CSS vars (var(--color_02) accent, var(--color_00) text)."),
         include_member: z.boolean().default(false).describe("Also create login/register/profile (type member, use_member)"),
         include_blog: z.boolean().default(false).describe("Also create blog list + post pages (type blog, use_blog)"),
         dry_run: z.boolean().default(true).describe("Preview (true) or actually create the missing pages (false)"),
-    }, ({ include_member, include_blog, dry_run }) => handle(async () => {
+    }, ({ style, palette, include_member, include_blog, dry_run }) => handle(async () => {
         const bind = (name, field) => ({
             id: "BINDING" + Math.random().toString(36).slice(2, 8),
             name,
@@ -212,38 +219,38 @@ storefront"), and add a GLOBAL header/footer (create_global_section). Don't leav
         });
         const h1 = (text) => ({ type: "text", opts: { text, specials: { tag: "h1" }, style: { fontSize: "32px", fontWeight: "700" } } });
         const accentBtn = (text, type = "button") => ({ type, opts: { text, style: { background: "var(--color_02)", color: "#fff", borderRadius: "8px", height: 48, fontWeight: "600" } } });
+        // Rich (default) store pages come from the designed, palette-aware templates;
+        // 'minimal' falls back to the original bare stubs.
+        const pal = resolvePalette(palette || {});
+        const minimalStore = {
+            collections: () => ({ sections: [buildSection([h1("Danh mục sản phẩm"), { type: "grid-product", opts: { config: { columns: 3, image_ratio: "1/1", gap_column: 24, gap_row: 32 } } }])] }),
+            products: () => ({ sections: [buildSection([
+                        { type: "product-gallery", opts: {} },
+                        { type: "text-dataset", opts: { bindings: [bind("product", "product_name")], style: { fontSize: "28px", fontWeight: "700" } } },
+                        { type: "text-dataset", opts: { bindings: [bind("product", "product_price")], style: { fontSize: "22px", fontWeight: "700", color: "var(--color_02)" } } },
+                        { type: "quantity-input", opts: {} },
+                        accentBtn("Thêm vào giỏ"),
+                    ])] }),
+            cart: () => ({ sections: [buildSection([h1("Giỏ hàng"), { type: "cart-items", opts: {} }, accentBtn("Tiến hành thanh toán")])] }),
+            checkout: () => ({ sections: [buildSection([
+                        h1("Thanh toán"),
+                        { type: "form", opts: { specials: { type: "form_order" } }, children: [
+                                { type: "input", opts: { specials: { field_name: "full_name", label: "Họ tên", placeholder: "Họ tên", required: true, show_label: true } } },
+                                { type: "phone-number", opts: { specials: { field_name: "phone_number", label: "Số điện thoại", required: true, show_label: true } } },
+                                { type: "address", opts: { specials: { field_name: "address", label: "Địa chỉ", show_label: true } } },
+                                accentBtn("Đặt hàng", "submit-button"),
+                            ] },
+                    ])] }),
+            complete: () => ({ sections: [buildSection([h1("Cảm ơn bạn đã đặt hàng!"), { type: "order-items", opts: {} }])] }),
+        };
         // Each spec: { name, slug, kind, build() -> { sections } }
-        const SPECS = [
-            { name: "Category Page", slug: "collections", kind: "store", flag: "use_store", build: () => ({ sections: [
-                        buildSection([h1("Danh mục sản phẩm"), { type: "grid-product", opts: { config: { columns: 3, image_ratio: "1/1", gap_column: 24, gap_row: 32 } } }]),
-                    ] }) },
-            { name: "Product Page", slug: "products", kind: "store", flag: "use_store", build: () => ({ sections: [
-                        buildSection([
-                            { type: "product-gallery", opts: {} },
-                            { type: "text-dataset", opts: { bindings: [bind("product", "product_name")], style: { fontSize: "28px", fontWeight: "700" } } },
-                            { type: "text-dataset", opts: { bindings: [bind("product", "product_price")], style: { fontSize: "22px", fontWeight: "700", color: "var(--color_02)" } } },
-                            { type: "quantity-input", opts: {} },
-                            accentBtn("Thêm vào giỏ"),
-                        ]),
-                    ] }) },
-            { name: "Cart Page", slug: "cart", kind: "store", flag: "use_store", build: () => ({ sections: [
-                        buildSection([h1("Giỏ hàng"), { type: "cart-items", opts: {} }, accentBtn("Tiến hành thanh toán")]),
-                    ] }) },
-            { name: "Checkout Page", slug: "checkout", kind: "store", flag: "use_store", build: () => ({ sections: [
-                        buildSection([
-                            h1("Thanh toán"),
-                            { type: "form", opts: { specials: { type: "form_order" } }, children: [
-                                    { type: "input", opts: { specials: { field_name: "full_name", label: "Họ tên", placeholder: "Họ tên", required: true, show_label: true } } },
-                                    { type: "phone-number", opts: { specials: { field_name: "phone_number", label: "Số điện thoại", required: true, show_label: true } } },
-                                    { type: "address", opts: { specials: { field_name: "address", label: "Địa chỉ", show_label: true } } },
-                                    accentBtn("Đặt hàng", "submit-button"),
-                                ] },
-                        ]),
-                    ] }) },
-            { name: "Thank You Page", slug: "complete", kind: "store", flag: "use_store", build: () => ({ sections: [
-                        buildSection([h1("Cảm ơn bạn đã đặt hàng!"), { type: "order-items", opts: {} }]),
-                    ] }) },
-        ];
+        const SPECS = STORE_PAGE_TEMPLATES.map((t) => ({
+            name: t.name,
+            slug: t.slug,
+            kind: "store",
+            flag: "use_store",
+            build: () => (style === "minimal" ? minimalStore[t.slug]() : t.build(pal)),
+        }));
         if (include_member) {
             SPECS.push({ name: "Login Page", slug: "login", kind: "member", flag: "use_member", build: () => ({ sections: [
                         buildSection([h1("Đăng nhập"), { type: "form", opts: { specials: { type: "form_login" } }, children: [
@@ -282,6 +289,18 @@ storefront"), and add a GLOBAL header/footer (create_global_section). Don't leav
         const created = [];
         const errors = [];
         const flagsEnabled = new Set();
+        // slug -> page id, seeded with the pages that already exist (so cross-page nav
+        // resolves even when only some store pages are newly created).
+        const slugToId = {};
+        for (const pg of Array.isArray(pages) ? pages : []) {
+            const sl = (pg.slug || "").replace(/^\//, "");
+            if (sl)
+                slugToId[sl] = pg.id;
+            if (pg.is_homepage)
+                slugToId["home"] = pg.id;
+        }
+        // Keep each newly-built source so we can wire navigation once every id is known.
+        const built = [];
         for (const spec of missing) {
             try {
                 if (!flagsEnabled.has(spec.flag)) {
@@ -297,21 +316,40 @@ storefront"), and add a GLOBAL header/footer (create_global_section). Don't leav
                 finalizeForRender(source);
                 const res = await api.createPage({ name: spec.name, source, type: PAGE_TYPE_NUM[spec.kind] });
                 const pid = newPageId(res);
-                if (pid)
+                if (pid) {
                     await api.updatePage(pid, { slug: spec.slug }).catch(() => { });
+                    slugToId[spec.slug] = pid;
+                    built.push({ spec, pid, source });
+                }
                 created.push({ name: spec.name, slug: spec.slug, type: spec.kind, page_id: pid });
             }
             catch (e) {
                 errors.push({ slug: spec.slug, error: e?.message ?? String(e) });
             }
         }
+        // Second pass: resolve the _navTo sentinels the templates left on buttons/links into
+        // real open_page events (cart→checkout, thank-you→home, …), now that every page id is
+        // known. Only re-save the pages that actually changed.
+        let nav_wired = 0;
+        for (const { pid, source } of built) {
+            try {
+                const n = wireNavigation(source, slugToId);
+                if (n > 0) {
+                    nav_wired += n;
+                    await api.updatePageSource(pid, { source }).catch(() => { });
+                }
+            }
+            catch { /* nav wiring is best-effort */ }
+        }
         return {
             success: true,
+            style,
             created,
             already_exist: skipped,
             ...(errors.length ? { errors } : {}),
             data_sources_enabled: [...flagsEnabled],
-            note: "Publish the site (publish_site) to take the new pages live.",
+            nav_links_wired: nav_wired,
+            note: "Add a header/footer with scaffold_global_sections, then publish_site to take the new pages live.",
         };
     }));
 }

package/dist/tools/context.js

@@ -34,8 +34,8 @@ export function registerContextTools(server, api, handle) {
             "create_site (tên + slug) → tự chuyển sang site mới",
             "create_product_category + create_product cho từng sản phẩm (ảnh từ search_images/upload_images trước)",
             "build_page trang chủ (type:'main', is_homepage:true) với hero, lưới sản phẩm, câu chuyện, CTA, …",
-            "scaffold_store_pages để tạo trang danh mục/chi tiết/giỏ/thanh toán/cảm ơn",
-            "Tách Header/Footer thành global section (create_global_section) để dùng chung mọi trang",
+            "scaffold_store_pages (style:'rich' mặc định) → trang danh mục/chi tiết/giỏ/thanh toán/cảm ơn ĐÃ thiết kế sẵn, tự nối điều hướng",
+            "scaffold_global_sections({ brand, contact }) → Header + Footer thiết kế sẵn, dùng chung mọi trang (tự bỏ qua slot đã có)",
             "publish_site (cũng rebuild CSS storefront)",
         ],
         notes: "Sau khi build xong, QA trên builder editor (app_base/editor/:site_id) hoặc storefront đã publish; publish_site sẽ rebuild CSS để hết tình trạng trang thiếu style.",

package/dist/tools/global-section-write.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { validatePage, finalizeForRender } from "../builder/page.js";
+import { headerSection, footerSection, wireNavigation } from "../builder/templates.js";
 /**
  * Write tools for global SECTIONS (Header / Footer / reusable blocks).
  *
@@ -124,6 +125,96 @@ Two-step safety: dry_run=true (default) previews which pages change; dry_run=fal
             raw: ok ? undefined : res,
         };
     }));
+    server.tool("scaffold_global_sections", `Generate a DESIGNED global Header and Footer in one call and embed them on every page —
+the fast path to consistent site chrome. The header has logo + nav links + cart icon + CTA;
+the footer has brand blurb + link columns + contact + copyright. Navigation is auto-wired to
+real pages (Home/Products/Cart). Colours follow the site theme vars unless you pass a palette.
+SKIPS a slot that already has a global section (won't create a second header/footer) unless
+force=true. Two-step safety: dry_run=true (default) previews; dry_run=false performs the atomic save.`, {
+        brand: z.string().describe("Shop / brand name shown as the logo and in the footer."),
+        links: z.array(z.object({ label: z.string(), navTo: z.string().optional(), url: z.string().optional() })).optional().describe("Header nav links. navTo = a page slug ('home','collections','cart') auto-wired to open_page; url = external link. Defaults to Home/Products/Cart."),
+        contact: z.object({ phone: z.string().optional(), email: z.string().optional(), address: z.string().optional() }).optional().describe("Real contact info for the footer (don't invent — omit what you don't have)."),
+        cta: z.string().optional().describe("Header call-to-action button label (default 'Đặt mua ngay')."),
+        palette: z.record(z.any()).optional().describe("Optional colour overrides { accent, onAccent, text, muted, surface, surfaceAlt, border }."),
+        include: z.enum(["both", "header", "footer"]).default("both").describe("Which chrome to generate."),
+        force: z.boolean().default(false).describe("Create even if a header/footer global already exists (otherwise that slot is skipped)."),
+        dry_run: z.boolean().default(true).describe("Preview (true) or perform the atomic save (false)."),
+    }, ({ brand, links, contact, cta, palette, include, force, dry_run }) => handle(async () => {
+        // Which slots already have a global section? (dedupe by type unless force)
+        const existingRes = await api.listGlobalSections().catch(() => null);
+        const existing = (existingRes && (existingRes.data || existingRes.global_sections || existingRes)) || [];
+        const slotTaken = (slot) => Array.isArray(existing) && existing.some((g) => (g.slot || "").toLowerCase() === slot || TYPE_NUM[slot] === g.type);
+        const wantHeader = include !== "footer";
+        const wantFooter = include !== "header";
+        const skipped = [];
+        // Resolve slug -> page id for nav wiring + page embedding.
+        const allPages = await loadPages(api);
+        const slugToId = {};
+        const pagesRes = await api.listPages();
+        for (const pg of (pagesRes && pagesRes.data) || pagesRes || []) {
+            const sl = (pg.slug || "").replace(/^\//, "");
+            if (sl)
+                slugToId[sl] = pg.id;
+            if (pg.is_homepage)
+                slugToId["home"] = pg.id;
+        }
+        // Build the finalized, nav-wired global nodes for each requested slot.
+        const toCreate = [];
+        const buildNode = (type, raw) => {
+            raw.specials = { ...(raw.specials || {}), global: type };
+            const wrap = { sections: [raw] };
+            const validation = validatePage(wrap);
+            if (!validation.valid)
+                throw new Error(`${type} failed validation: ${JSON.stringify(validation.errors)}`);
+            finalizeForRender(wrap);
+            wireNavigation(wrap, slugToId); // resolve _navTo on header links/CTA
+            return wrap.sections[0];
+        };
+        if (wantHeader) {
+            if (!force && slotTaken("header"))
+                skipped.push("header");
+            else
+                toCreate.push({ type: "header", name: "Header", node: buildNode("header", headerSection({ brand, links: links, cta, palette })) });
+        }
+        if (wantFooter) {
+            if (!force && slotTaken("footer"))
+                skipped.push("footer");
+            else
+                toCreate.push({ type: "footer", name: "Footer", node: buildNode("footer", footerSection({ brand, contact, palette })) });
+        }
+        if (!toCreate.length) {
+            return { success: true, created: [], skipped, note: skipped.length ? "Those slots already have a global section (pass force=true to add anyway)." : "Nothing to create." };
+        }
+        if (dry_run) {
+            return {
+                dry_run: true,
+                will_create: toCreate.map((t) => ({ type: t.type, section_id: t.node.id })),
+                skipped,
+                embeds_into_pages: allPages.length,
+                hint: "Call again with dry_run=false to create + embed the header/footer, then publish_site.",
+            };
+        }
+        // Inject every node into every page, then one atomic /save with all globals + pages.
+        for (const t of toCreate)
+            for (const p of allPages)
+                injectNode(p.source, t.node, t.type);
+        const changedPages = allPages.map((p) => ({ id: p.id, source: JSON.stringify(p.source) }));
+        const changes = allPages.reduce((o, p) => { o[p.id] = 1; return o; }, {});
+        const global_sections = toCreate.map((t) => ({
+            section_id: t.node.id, name: t.name, type: TYPE_NUM[t.type],
+            pages: allPages.map((p) => p.id), section: t.node, status: "new", contents: [],
+        }));
+        const res = await api.saveGlobalSections({ global_sections, pages: changedPages, changes });
+        const ok = !!(res && (res.success || res.data));
+        return {
+            success: ok,
+            created: toCreate.map((t) => ({ type: t.type, section_id: t.node.id })),
+            skipped,
+            embedded_pages: changedPages.length,
+            note: "Publish the site (publish_site) to take the header/footer live.",
+            raw: ok ? undefined : res,
+        };
+    }));
     server.tool("delete_global_section", `Delete a global section (Header/Footer/block) and remove its node from every page source.
 Two-step safety: dry_run=true (default) shows which pages would change; dry_run=false performs the atomic save.`, {
         section_id: z.string().describe("The global section's section_id (the section node id) — from list_global_sections."),

package/dist/tools/products.js

@@ -5,7 +5,12 @@ export function registerProductTools(server, api, handle) {
         limit: z.number().optional().describe("Items per page"),
         term: z.string().optional().describe("Search by product name"),
     }, ({ page, limit, term }) => handle(async () => {
-        const res = await api.listProducts({ page, limit, term });
+        // Build a clean query — the /products/all endpoint 400s on undefined/blank keys,
+        // so default page/limit and drop term unless it's a real search string.
+        const query = { page: page ?? 1, limit: limit ?? 50 };
+        if (term && term.trim())
+            query.term = term.trim();
+        const res = await api.listProducts(query);
         const products = (res && res.data) || res || [];
         if (!Array.isArray(products))
             return res;

package/dist/tools/site-style.js

@@ -172,8 +172,19 @@ update_page_element(s), colours/fonts via the site-style tools, then publish_sit
         switch_to: z.boolean().default(true).describe("Switch the session to the new site after creating it (saved for next session)"),
     }, ({ name, theme_id, slug, switch_to }) => handle(async () => {
         let res;
+        // The import_store_to_theme endpoint REQUIRES a slug — omitting it 400s ("Bad
+        // Request"). Auto-generate a URL-safe one from the name when the caller didn't pass it.
+        const safeSlug = (slug && slug.trim()) ||
+            (name || "site")
+                .toLowerCase()
+                .normalize("NFD")
+                .replace(/[̀-ͯ]/g, "")
+                .replace(/đ/g, "d")
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-+|-+$/g, "")
+                .slice(0, 48) || `site-${Date.now().toString(36)}`;
         try {
-            res = await api.importStoreToTheme({ id: theme_id, name, ...(slug ? { slug } : {}) });
+            res = await api.importStoreToTheme({ id: theme_id, name, slug: safeSlug });
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.18.1",
+  "version": "1.19.1",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",