webcake-storefront-mcp 1.27.0 → 1.29.0

package/dist/builder/guide.js

@@ -237,10 +237,13 @@ create the globals — they embed into each page's source. If you later overwrit
 later with update_global_section_element(s) and it updates on every page at once.
 
 ## Popups (newsletter / promo / age-gate)
-A popup is a GLOBAL SOURCE, not a page section. Build it, store it, then trigger it:
-1. Build the popup body (new_section: heading + text + form/input + a close button), then wrap it:
-   new_element("popup", { children:[<that section>], specials:{ /* trigger + overlay */ } }).
-   Trigger/behaviour (auto-open after a delay, exit-intent, only-once, overlay) lives in specials.
+A popup is a GLOBAL SOURCE, not a page section. FAST PATH: \`scaffold_popup({ brand, headline, offer })\`
+builds + saves a designed newsletter popup (heading + text + email form + close button, centred)
+and returns its id. To build one by hand:
+1. Build the popup node: new_element("popup", { children:[…heading,text,form,close button…], style:{ width:480, background:"#fff", borderRadius:"12px" }, config:{ popupHorizontalPosition:"center", popupVerticalPosition:"center" }, specials:{ effect:"fade-in", timeAnim:0.5 } }).
+   - SIZE + POSITION live in the popup's runtime style/config (width/height/background + popupHorizontalPosition/popupVerticalPosition), NOT in specials. createPopup seeds a centred-modal default.
+   - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. (There is no exit-intent/only-once flag in the node — those are app settings.)
+   - OVERLAY is NOT on the popup node — it's a field on the open_popup EVENT (popup_overlay:true).
 2. Save it: create_global_source({ component:"popup", source:{ sections:[<popupNode>] } }) -> returns its id.
 3. Open/close from any element via events: a button { action:"open_popup", popup_id:"<id>", popup_overlay:true };
    a close button inside { action:"close_popup", popup_id:"<id>" }; a form can auto-close on its

package/dist/builder/page.js

@@ -192,7 +192,7 @@ export function buildSection(childSpecs = [], sectionOpts = {}) {
     };
     return section;
 }
-function buildFromSpec(spec) {
+export function buildFromSpec(spec) {
     if (!spec || !spec.type) {
         throw new Error("Each element spec must have a 'type'.");
     }

package/dist/builder/templates.js

@@ -13,9 +13,10 @@
 // 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 { buildSection, buildFromSpec, stackChildren, walk } from "./page.js";
 import { buildElement } from "./catalog.js";
 import { normalizeEvents } from "./events.js";
+const X_ICON_SVG = "<svg xmlns='http://www.w3.org/2000/svg' fill='currentColor' width='100%' height='100%' viewBox='0 0 24 24'><path d='M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z'></path></svg>";
 // Slots map onto the site theme's 5×5 colour matrix, surfaced as CSS vars var(--color_RC)
 // (R=row, C=col). Row 0 is greyscale (00=white … 04=black); row 2 is the BRAND row. Using
 // var(--color_00) for text was a bug — that's WHITE (invisible on the white surface).
@@ -310,7 +311,9 @@ export function headerSection(opts = {}) {
         { 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 logo = opts.logo
+        ? { type: "image", opts: { config: { src: opts.logo }, style: { height: 40, width: 140 } } }
+        : { type: "text", opts: { text: opts.brand || "Shop", specials: { tag: "h2" }, style: { fontSize: "24px", fontWeight: "800", color: p.text } } };
     // Real designer templates use a `menu` of `menu-item`s, NOT text links — and a menu-item's
     // navigation lives in its SPECIALS (linkType/linkPage/pageId), not events. We build the
     // items directly (via buildElement, so buildFromSpec doesn't grid-stack the menu) and leave
@@ -326,16 +329,32 @@ export function headerSection(opts = {}) {
             children: menuItems,
         },
     };
+    // Right-hand actions: optional search / account / language, then cart + CTA — like real headers.
+    const actionChildren = [];
+    const actionWidths = [];
+    if (opts.search !== false) {
+        actionChildren.push({ type: "input-search", opts: { specials: { field_name: "search", placeholder: "Tìm kiếm sản phẩm...", showIcon: true }, config: { inputBackground: p.surfaceAlt, inputBorderColor: p.border, inputBorderRadius: "8px", iconColor: p.muted, placeholderColor: p.muted, iconAlign: "left" }, style: { height: 40 } } });
+        actionWidths.push({ unit: "px", absValue: 200 });
+    }
+    if (opts.account) {
+        actionChildren.push({ type: "member-bar", opts: { specials: { showView: "not_logged", layoutShow: "text", textLogin: "Đăng nhập", textSignup: "Đăng ký" }, config: { colorIcon: p.text }, style: { color: p.text } } });
+        actionWidths.push({ unit: "max-c" });
+    }
+    if (opts.language) {
+        actionChildren.push({ type: "language-menu", opts: { specials: { show_flag: true, type: "dropdown" }, config: { color: p.text, display: "abbreviated" } } });
+        actionWidths.push({ unit: "max-c" });
+    }
+    actionChildren.push({ type: "cart-icon", opts: { style: { width: 26, height: 26, color: p.text } } });
+    actionWidths.push({ unit: "px", absValue: 32 });
+    actionChildren.push(cta(opts.cta || "Đặt mua ngay", p, { navTo: "collections", height: 44 }));
+    actionWidths.push({ unit: "max-c" });
     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 }),
-        ],
+        colWidths: actionWidths,
+        collapse: { bp4: Math.min(2, actionChildren.length) },
+        children: actionChildren,
     };
     return buildSection([
         {
@@ -392,6 +411,48 @@ export function footerSection(opts = {}) {
     });
 }
 // ---------------------------------------------------------------------------
+// POPUP (newsletter / promo) — a global SOURCE, not a page section
+// ---------------------------------------------------------------------------
+/**
+ * A designed newsletter/promo popup, returned as a ready-to-save global-source source
+ * `{ sections: [ <popup node> ] }`. The popup carries an auto-open-after-delay trigger in
+ * specials and a centred-modal geometry (seeded by createPopup); the close button references
+ * the popup's own id. Save with create_global_source({ component:"popup", source }).
+ * Run finalizeForRender(source) BEFORE saving (the tool does this).
+ */
+export function newsletterPopupSource(opts = {}) {
+    const p = resolvePalette(opts.palette);
+    const heading = {
+        type: "text",
+        opts: { text: opts.headline || "Nhận ưu đãi 10%", specials: { tag: "h2" }, style: { fontSize: "26px", fontWeight: "800", color: p.text, textAlign: "center", lineHeight: "1.3" } },
+    };
+    const sub = {
+        type: "text",
+        opts: { text: opts.subtext || "Đăng ký nhận tin để không bỏ lỡ khuyến mãi mới nhất.", style: { fontSize: "15px", color: p.muted, textAlign: "center", lineHeight: "1.6" } },
+    };
+    const form = {
+        type: "form",
+        opts: { specials: { type: "subscribe" }, config: { backgroundInput: p.surface, placeholderColor: p.muted, labelColor: p.text, textPadding: 14, rowGap: 12 } },
+        children: [
+            { type: "email", opts: { specials: { field_name: "email", placeholder: "Email của bạn", show_label: false }, config: { backgroundInput: p.surface, textPadding: 14 }, style: { borderColor: p.border, borderRadius: "8px", height: 46 } } },
+            { type: "submit-button", opts: { text: opts.ctaLabel || "Đăng ký ngay", style: { background: p.accent, color: p.onAccent, borderRadius: "8px", height: 46, fontWeight: "600", width: "100%", textAlign: "center" } } },
+        ],
+    };
+    // Close button: a small X in the top-right that closes this popup (wired to the popup id below).
+    const close = { type: "rectangle", opts: { config: { mask: X_ICON_SVG }, style: { width: 22, height: 22, background: p.muted } } };
+    const content = [heading, sub, form, close].map((s) => buildFromSpec(s));
+    const popup = buildElement("popup", {
+        specials: { effect: "fade-in", timeAnim: 0.5, openPopupAction: "openPopupWithTime", timeOpenPopup: opts.delaySeconds ?? 6 },
+        style: { width: 460, background: p.surface, borderRadius: "14px", paddingTop: 40, paddingBottom: 40, paddingLeft: 32, paddingRight: 32 },
+        config: { popupHorizontalPosition: "center", popupVerticalPosition: "center" },
+    });
+    stackChildren(popup, content, { rowGap: 18 });
+    // Wire the close button to dismiss THIS popup now that we know its id.
+    const closeNode = content[content.length - 1];
+    closeNode.events = normalizeEvents([{ action: "close_popup", popup_id: popup.id }], "rectangle");
+    return { sections: [popup] };
+}
+// ---------------------------------------------------------------------------
 // registry the scaffolder iterates
 // ---------------------------------------------------------------------------
 /**

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.29.0",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "scaffold_global_sections now accepts a logo parameter (hosted image URL) that renders an image element in the header instead of the brand-name text…",
+    "vi": "scaffold_global_sections nay nhận thêm tham số logo (URL hình ảnh được host) để hiển thị phần tử image trong header thay vì node text tên thương hiệu."
+  },
+  {
+    "v": "1.28.0",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "New scaffold_popup tool builds and saves a designed newsletter/promo popup (heading + subtext + email subscribe form + close button, centred modal)…",
+    "vi": "Tool mới scaffold_popup xây dựng và lưu một popup newsletter/promo được thiết kế sẵn (tiêu đề + phụ đề + form đăng ký email + nút đóng, dạng modal…"
+  },
   {
     "v": "1.27.0",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "list_elements now documents 16 previously-uncovered element types, completing curated attribute coverage across all 132 factory types: popup…",
     "vi": "list_elements nay tài liệu hóa 16 kiểu phần tử trước đây chưa được ghi lại, hoàn thiện độ phủ thuộc tính curated cho toàn bộ 132 kiểu factory: popup…"
-  },
-  {
-    "v": "1.24.0",
-    "d": "26/06/2026",
-    "type": "Changed",
-    "en": "list_elements now documents tabIndex and text_animation_type as shared specials present on every element, covering tab-panel visibility binding and…",
-    "vi": "list_elements nay tài liệu hóa tabIndex và text_animation_type là các specials dùng chung có trên mọi phần tử, bao gồm gắn kết hiển thị/ẩn cho…"
-  },
-  {
-    "v": "1.23.0",
-    "d": "25/06/2026",
-    "type": "Added",
-    "en": "get_build_guide now includes a category-page filter recipe explaining how sidebar filter widgets (checkbox-group, color-group, tags,…",
-    "vi": "get_build_guide nay bổ sung công thức filter trang danh mục, giải thích cách các widget lọc trong sidebar (checkbox-group, color-group, tags,…"
   }
 ]

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

@@ -135,11 +135,15 @@ force=true. Two-step safety: dry_run=true (default) previews; dry_run=false perf
         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')."),
+        logo: z.string().optional().describe("Logo image URL (hosted) — renders an image instead of the brand text."),
+        search: z.boolean().default(true).describe("Add a storefront search box to the header (most real templates have one)."),
+        account: z.boolean().default(false).describe("Add a login/account bar (member sites)."),
+        language: z.boolean().default(false).describe("Add a language switcher (multilingual sites)."),
         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 () => {
+    }, ({ brand, links, contact, cta, logo, search, account, language, 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)) || [];
@@ -174,7 +178,7 @@ force=true. Two-step safety: dry_run=true (default) previews; dry_run=false perf
             if (!force && slotTaken("header"))
                 skipped.push("header");
             else
-                toCreate.push({ type: "header", name: "Header", node: buildNode("header", headerSection({ brand, links: links, cta, palette })) });
+                toCreate.push({ type: "header", name: "Header", node: buildNode("header", headerSection({ brand, links: links, cta, logo, search, account, language, palette })) });
         }
         if (wantFooter) {
             if (!force && slotTaken("footer"))

package/dist/tools/global-sources.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { getConfirmMode } from "./context.js";
 import { normalizeEvents } from "../builder/events.js";
 import { normalizeBindings } from "../builder/bindings.js";
+import { newsletterPopupSource, contrastSafePalette } from "../builder/templates.js";
+import { finalizeForRender, validatePage } from "../builder/page.js";
 /**
  * Global Sources tools — manage site-wide components: cart, popup, overview, etc.
  *
@@ -575,6 +577,35 @@ Same merge rules: style/config/specials = shallow merge, events/bindings = repla
         invalidateGsCache();
         return res;
     }));
+    server.tool("scaffold_popup", `Build AND save a designed newsletter/promo popup in one call (a 'popup' global source).
+Returns the popup id — open it from any element with an open_popup event { popup_id, popup_overlay:true },
+or set it to auto-open after a delay (built in). Centred modal: heading + subtext + email subscribe
+form + close button, palette-aware (accent derived from the site theme). Use dry_run to preview.`, {
+        headline: z.string().optional().describe("Popup heading (default: 'Nhận ưu đãi 10%')"),
+        subtext: z.string().optional().describe("Supporting line under the heading"),
+        cta_label: z.string().optional().describe("Submit button label (default: 'Đăng ký ngay')"),
+        delay_seconds: z.number().optional().describe("Auto-open after N seconds (default 6)"),
+        palette: z.record(z.any()).optional().describe("Colour overrides { accent, text, surface, ... }; defaults to the site theme."),
+        dry_run: z.boolean().default(true).describe("Preview the popup source (true) or create+save it (false)"),
+    }, ({ headline, subtext, cta_label, delay_seconds, palette, dry_run }) => handle(async () => {
+        const themePal = await contrastSafePalette(api);
+        const source = newsletterPopupSource({
+            headline, subtext, ctaLabel: cta_label, delaySeconds: delay_seconds,
+            palette: { ...themePal, ...(palette || {}) },
+        });
+        const validation = validatePage(source);
+        finalizeForRender(source);
+        const popupId = source.sections[0]?.id || null;
+        if (dry_run) {
+            return { dry_run: true, valid: validation.valid, popup_id: popupId, ...(validation.errors ? { errors: validation.errors } : {}), hint: "Centred newsletter popup. Call again with dry_run=false to save it, then open it via an open_popup event (popup_id above)." };
+        }
+        if (!validation.valid)
+            return { error: "Popup failed validation — not saving.", validation };
+        const res = await api.createGlobalSource({ component: "popup", source, type: "default", site_id: api.siteId });
+        invalidateGsCache();
+        const id = res?.data?.id || res?.id || popupId;
+        return { success: true, global_source_id: id, popup_id: popupId, next_step: "Open it from a button/header with events:[{ action:'open_popup', popup_id, popup_overlay:true }] (or it auto-opens after the delay). publish_site to take it live." };
+    }));
     server.tool("update_global_source", `Replace full source of a global source.
 IMPORTANT: Before calling this tool, you MUST:
 1. Read existing source with get_global_source_detail first

package/package.json

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