webcake-storefront-mcp 1.18.1 → 1.19.0

package/dist/builder/guide.js

@@ -161,9 +161,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,399 @@
+// 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 styled product grid card config that looks like a real shop, not a bare list. */
+const productGrid = (p, columns = 4) => ({
+    type: "grid-product",
+    opts: {
+        config: {
+            columns,
+            image_ratio: "1/1",
+            img_object_fit: "cover",
+            gap_column: 24,
+            gap_row: 32,
+            cardBorderRadius: 14,
+            cardBoxShadow: "0 6px 22px rgba(0,0,0,0.06)",
+            cardPadding: 12,
+            cardBackground: p.surface,
+            productNameColor: p.text,
+            productPriceColor: p.accent,
+            showAddToCart: true,
+        },
+    },
+});
+/** 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) {
+    const form = {
+        type: "form",
+        opts: { specials: { type: "form_order" }, 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 }, style: { borderColor: p.border, borderRadius: "8px" } } },
+            { type: "phone-number", opts: { specials: { field_name: "phone_number", label: "Số điện thoại", required: true, show_label: true }, style: { borderColor: p.border, borderRadius: "8px" } } },
+            { type: "address", opts: { specials: { field_name: "address", label: "Địa chỉ nhận hàng", show_label: true }, style: { borderColor: p.border, borderRadius: "8px" } } },
+            { type: "text-area", opts: { specials: { field_name: "note", label: "Ghi chú", show_label: true }, style: { borderColor: p.border, borderRadius: "8px" } } },
+            { 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: { config: { color: p.text }, style: { width: 26, height: 26 } } },
+            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,11 @@
 [
+  {
+    "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",
@@ -33,12 +40,5 @@
     "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/package.json

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