webcake-landing-mcp 1.0.30 → 1.0.32

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.32",
+    "d": "08/06/2026",
+    "type": "Fixed",
+    "en": "get_element for select now marks specials.field_placeholder as required (the published renderer crashes without it), the element seed now emits a…",
+    "vi": "get_element cho select nay đánh dấu specials.field_placeholder là bắt buộc (renderer đã xuất bản sẽ crash nếu thiếu trường này), seed phần tử nay…"
+  },
+  {
+    "v": "1.0.31",
+    "d": "08/06/2026",
+    "type": "Fixed",
+    "en": "get_element for spin_wheel now correctly documents specials.code as a newline-delimited string (one line per segment in couponCode|Prize…",
+    "vi": "get_element cho spin_wheel nay ghi lại đúng specials.code là chuỗi phân cách bằng dấu xuống dòng (mỗi dòng một segment theo định dạng couponCode|Tên…"
+  },
   {
     "v": "1.0.30",
     "d": "08/06/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "The HTTP server's GET / route now serves the full HTML guide page to social and search crawlers (Facebook, Zalo, Twitter/X, LinkedIn, Slack,…",
     "vi": "Route GET / của HTTP server nay phục vụ trang hướng dẫn HTML đầy đủ cho các crawler mạng xã hội và công cụ tìm kiếm (Facebook, Zalo, Twitter/X,…"
-  },
-  {
-    "v": "1.0.26",
-    "d": "07/06/2026",
-    "type": "Added",
-    "en": "The HTTP server now serves a pre-rendered 1200×630 PNG social card at GET /og.png; the guide page's og:image and twitter:image meta tags now point…",
-    "vi": "HTTP server nay phục vụ ảnh social card PNG được render sẵn 1200×630 tại GET /og.png; các meta tag og:image và twitter:image của trang hướng dẫn nay…"
-  },
-  {
-    "v": "1.0.25",
-    "d": "07/06/2026",
-    "type": "Changed",
-    "en": "currency has moved from options.currency to settings.currency in the page source model; new_page_skeleton now emits it in the correct location,…",
-    "vi": "currency đã được chuyển từ options.currency sang settings.currency trong mô hình nguồn trang; new_page_skeleton giờ xuất đúng vị trí,…"
   }
 ]

package/dist/domains/landing/elements/content.js

@@ -152,9 +152,9 @@ export const CONTENT = [
     {
         type: "gallery", category: "content", container: false, defaultName: "Gallery",
         summary: "Multi-image/video gallery with thumbnail strip. Content comes entirely from specials.media — this is NOT a container and has no children.",
-        useWhen: "Photo grids/galleries with several images or videos. No image API — fill specials.media with placeholder URLs (https://placehold.co/600x400).",
+        useWhen: "Photo grids/galleries with several images or videos. No image API — fill specials.media with placeholder image objects (see media). NEVER use plain URL strings — the gallery reads item.link and renders blank for a string.",
         keySpecials: {
-            media: "array of image URLs or video objects {type:'video', linkVideo:'<url>', typeVideo:'youtube'|'upload'} — use placeholder URLs if no real images.",
+            media: "array of media OBJECTS (NOT plain URLs — the gallery reads item.link). Image item: {type:'image', link:'<url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} — use a https://placehold.co/WxH URL for link if no real image. Video item: {type:'image', link:'<poster-url>', linkVideo:'<video-url>', typeVideo:'youtube'|'upload', imageCompression:true}.",
             allowZoom: "'off' | 'carousel' | 'lightbox' — (config) zoom/lightbox mode when clicking an image.",
             showNavigation: "boolean — (config) show prev/next navigation arrows.",
             thumbnailAutoplay: "number (ms) | 'off' — (config) auto-advance thumbnails every N ms, or 'off' to disable.",
@@ -167,7 +167,15 @@ export const CONTENT = [
         seed: (el) => {
             seedPosition(el);
             setBox(el, 350, 400);
-            el.specials.media = [imgPlaceholder(600, 400, "1"), imgPlaceholder(600, 400, "2"), imgPlaceholder(600, 400, "3")];
+            // gallery media items are OBJECTS, not strings — the renderer reads item.link
+            // (a plain URL string renders blank). Shape mirrors the editor's seed.
+            el.specials.media = [1, 2, 3].map((n) => ({
+                type: "image",
+                link: imgPlaceholder(600, 400, String(n)),
+                linkVideo: "",
+                typeVideo: "youtube",
+                imageCompression: true,
+            }));
             // gallery has NO children — content comes entirely from specials.media (gallery.js never reads vm.children)
         },
     },

package/dist/domains/landing/elements/form.js

@@ -109,19 +109,40 @@ export const FORM = [
         useWhen: "Pick one from a list.",
         keySpecials: {
             field_name: "REQUIRED unique data key.",
-            field_placeholder: "placeholder/label.",
+            field_placeholder: "REQUIRED — the disabled first-option label (the placeholder/prompt). The key is `field_placeholder`, NOT `placeholder`. The select renderer crashes if this is missing.",
             default_value: "string (option id) to pre-select; 'default-none' = no pre-selection.",
             defaultVariationId: "string — default product variation id registered on the parent form regardless of selection.",
             defaultVariationQuantity: "number — quantity registered with defaultVariationId.",
             ignoreOnHidden: "boolean — when CSS-hidden, remove this element's variations from the form total.",
             isConnectSurvey: "boolean — link to a survey for conditional show/hide.",
             connectedSurvey: "string — id of the connected survey.",
-            options: "array of rich option objects {id, name, value, variations:[{id,quantity,price}], attrOnly/prodId/attrName/attrVal/attrs (attribute mode), quantityOnly/quantityProd/quantityValue (quantity mode), tags:[], toggleEvent, events_option:[]} — events_option items drive show/hide, collapse, and price/discount/shipping adjustments. See docs/element-specials-reference.md for the full option schema.",
+            options: "array of option objects. The renderer builds each <option> from `id` and `name` ONLY — MINIMUM shape is {id, name} where name is BOTH the visible text and the submitted value. Do NOT use the HTML-style {label, value} — those keys are ignored and the option renders blank. Rich commerce options may also carry value, variations:[{id,quantity,price}], attrOnly/prodId/attrName/attrVal/attrs, quantityOnly/quantityProd/quantityValue, tags:[], toggleEvent, events_option:[] (show/hide, collapse, price/discount/shipping). See docs/element-specials-reference.md for the full option schema.",
         },
         seed: (el) => {
             seedPosition(el);
             setBox(el, 150, 36);
             el.specials.field_name = `select_${el.id}`;
+            el.specials.field_placeholder = "Chọn...";
+            el.specials.default_value = "default-none";
+        },
+        example: {
+            id: "sel_attend", type: "select",
+            properties: { name: "Select", movable: true, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { top: 0, left: 0, width: 300, height: 44 } },
+                mobile: { config: {}, styles: { top: 0, left: 0, width: 280, height: 44 } },
+            },
+            // options use {id, name} — NOT {label, value}. field_placeholder is required.
+            specials: {
+                field_name: "attendance",
+                field_placeholder: "Bạn có tham dự không?",
+                default_value: "default-none",
+                options: [
+                    { id: "opt_yes", name: "Tôi sẽ tham dự" },
+                    { id: "opt_no", name: "Rất tiếc, tôi không thể đến" },
+                ],
+            },
+            runtime: {}, events: [],
         },
     },
     {
@@ -147,7 +168,7 @@ export const FORM = [
             ignoreOnHidden: "boolean — when CSS-hidden, exclude this element's variations from the form total.",
             isConnectSurvey: "boolean — link to a survey for conditional show/hide.",
             connectedSurvey: "string — id of the connected survey.",
-            options: "array of rich option objects (same shape as select) — additionally supports the tcb_auto_banking event type in events_option (sets the storecake_tcb payment gateway). See docs/element-specials-reference.md for the full option schema.",
+            options: "array of option objects, MINIMUM shape {id, name} (name = visible text; the renderer crashes on options that lack a string `name`). Do NOT use {label, value}. Same rich shape as select — additionally supports the tcb_auto_banking event type in events_option (sets the storecake_tcb payment gateway). See docs/element-specials-reference.md for the full option schema.",
         },
         seed: (el) => {
             seedPosition(el);
@@ -169,7 +190,7 @@ export const FORM = [
             ignoreOnHidden: "boolean — when hidden, exclude this element's variations from the form total.",
             isConnectSurvey: "boolean — link to a survey for conditional show/hide.",
             connectedSurvey: "string — id of the connected survey.",
-            options: "array of rich option objects (same shape as select) — events_option additionally supports 9 payment-gateway event types (tcb_auto_banking, xendit_banking, onepay_banking, mercadopago_banking, vnpay_banking, paymongo_banking, stripe_banking, paypal_banking, momopay_banking) that set the form's payment provider. See docs/element-specials-reference.md for the full option schema.",
+            options: "array of option objects, MINIMUM shape {id, name} (name = visible text; the renderer crashes on options that lack a string `name`). Do NOT use {label, value}. Same rich shape as select — events_option additionally supports 9 payment-gateway event types (tcb_auto_banking, xendit_banking, onepay_banking, mercadopago_banking, vnpay_banking, paymongo_banking, stripe_banking, paypal_banking, momopay_banking) that set the form's payment provider. See docs/element-specials-reference.md for the full option schema.",
         },
         seed: (el) => {
             seedPosition(el);

package/dist/domains/landing/elements/marketing.js

@@ -105,9 +105,9 @@ export const MARKETING = [
         summary: "Lucky-spin wheel with configurable prize segments and coupon codes. Can open a result popup after spinning and supports dataset-driven coupon lists.",
         useWhen: "Gamified lead capture / promos. Users spin to win a coupon or prize.",
         keySpecials: {
-            message: "array of strings — prize label for each wheel segment.",
+            message: "string — result-popup message template shown after a spin (NOT segment labels). Supports placeholders {{coupon_text}}, {{coupon_code}}, {{spin_turn_left}}, {{coupon_codes}}.",
             spin: "object — spin configuration (segment colors, angles, etc.).",
-            code: "array of strings — coupon codes corresponding to each segment.",
+            code: "string (NOT an array) — the segments. ONE LINE PER SEGMENT, each line `couponCode|Prize Name|percent`, lines joined by \\n. The visible label on each wheel slice is the middle field (Prize Name); percent is the win weight. e.g. 'SALE10|Giảm 10%|40\\nSALE50|Giảm 50%|10\\nMISS|Chúc may mắn|50'.",
             dataType: "0 | 1 — 0=static codes, 1=dataset-driven codes.",
             datasetId: "string — webcake dataset ID for coupon codes.",
             codeDataset: "string — dataset column key for the coupon code.",
@@ -123,6 +123,16 @@ export const MARKETING = [
             seedPosition(el);
             setBox(el, 400, 400);
             setStyle(el, "color", "rgba(255, 255, 255, 1)");
+            // `code` is a newline-delimited string, ONE segment per line `couponCode|Prize Name|percent`
+            // (the editor preview does code.split("\n") and crashes/renders blank if it is missing).
+            el.specials.code = [
+                "PRIZE1|Giải 1|20",
+                "PRIZE2|Giải 2|20",
+                "PRIZE3|Giải 3|20",
+                "MISS|Chúc may mắn|40",
+            ].join("\n");
+            // `message` is the result-popup template (a string), NOT segment labels.
+            el.specials.message = "Chúc mừng! Bạn nhận được {{coupon_text}} (mã: {{coupon_code}}).";
         },
     },
     {

package/dist/domains/landing/guide.js

@@ -78,7 +78,7 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 RULES
 - Visible content goes in "specials" (text-block.specials.text, image-block.specials.src…), NEVER in "styles".
 - Colors as rgba(r,g,b,a). fontSize/borderWidth/top/left/width/height are NUMBERS (px).
-- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). There is NO image API yet, so set image-block specials.src to a PLACEHOLDER URL sized to the box: "https://placehold.co/<width>x<height>". NEVER leave src empty — it renders blank and the page looks broken. gallery.media = array of such URLs; video.specials.img = a poster placeholder. The user replaces these later.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). There is NO image API yet, so set image-block specials.src to a PLACEHOLDER URL sized to the box: "https://placehold.co/<width>x<height>". NEVER leave src empty — it renders blank and the page looks broken. gallery.media = array of OBJECTS {type:'image', link:'<placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster placeholder. The user replaces these later.
 - CONTRAST: text must contrast with the section background (dark text on light sections, light text on dark sections). Don't put light-gray text on white or faint text on a dark background.
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.

package/dist/domains/landing/instructions.js

@@ -20,6 +20,6 @@ MODEL (essentials):
 - CENTERING (the #1 layout defect — do the math, don't eyeball): to center a box compute left = round((canvas - width)/2) — 960 desktop, 420 mobile. textAlign:center only centers text inside the box, not the box itself. For a row of N items, center the whole row block (startLeft = round((canvas - (N*item + (N-1)*gap))/2)). Keep 0 ≤ left and left+width ≤ canvas on each breakpoint.
 - STICKY HEADER: a sticky/fixed header (config.sticky) OVERLAYS the page — it does NOT push sections below it down. Offset the first section's top content DOWN by the header height (~60–72px) so nothing hides behind it, and do NOT duplicate the shop name in both the header and the top of the hero. A non-sticky header stacks normally and needs no offset.
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
-- IMAGES: include them (hero/product, feature icons, about photo). No image API yet → set image-block specials.src to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height> (gallery.media = array of these; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
+- IMAGES: include them (hero/product, feature icons, about photo). No image API yet → set image-block specials.src to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height> (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
 
 Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, list_organizations, create_page, list_pages, get_page, update_page.`;

package/dist/domains/landing/validate.js

@@ -26,6 +26,11 @@ const ELEMENT_TARGET_ACTIONS = new Set([
     "show_hide_element", "change_tab", "collapse",
 ]);
 const TOP_LEVEL_TYPES = new Set(["section", "dynamic_page", "popup"]);
+// Fields whose renderer builds each <option> from `option.name`. A missing name
+// crashes the published renderer (radio/checkbox-group call .replace/.normalize on
+// it; select shows a blank option). The correct option shape is {id, name} — NOT
+// the HTML-style {label, value}.
+const OPTION_NAME_FIELDS = new Set(["select", "radio", "checkbox-group"]);
 // Fixed canvas reference (matches vocab CANVAS) used for the layout/bounds check.
 const CANVAS_DESKTOP = 960;
 const CANVAS_MOBILE = 420;
@@ -108,10 +113,36 @@ export function validatePage(input) {
         }
         // form fields need field_name
         if (type && FIELD_TYPES.has(type)) {
-            const fn = node.specials?.field_name;
+            const specials = node.specials;
+            const fn = specials?.field_name;
             if (!fn || typeof fn !== "string" || fn.trim() === "") {
                 warnings.push(`${path} (${type}): form input should have a unique specials.field_name.`);
             }
+            // `field_placeholder` is the ONLY placeholder key the renderer reads. A stray
+            // `placeholder` renders blank; a select with no field_placeholder crashes the
+            // published renderer (unescapeHTML(undefined)).
+            if (specials && typeof specials === "object") {
+                const hasFieldPlaceholder = typeof specials.field_placeholder === "string";
+                if (typeof specials.placeholder === "string" && !hasFieldPlaceholder) {
+                    warnings.push(`${path} (${type}): uses specials.placeholder — the renderer reads specials.field_placeholder. Rename "placeholder" → "field_placeholder".`);
+                }
+                if (type === "select" && !hasFieldPlaceholder) {
+                    errors.push(`${path} (select): needs a string specials.field_placeholder (the select renderer crashes without it).`);
+                }
+            }
+            // select/radio/checkbox-group render each option from option.name; a missing
+            // name crashes the renderer (radio/checkbox-group) or renders blank (select).
+            if (OPTION_NAME_FIELDS.has(type) && Array.isArray(specials?.options)) {
+                specials.options.forEach((opt, oi) => {
+                    if (typeof opt?.name !== "string" || opt.name.trim() === "") {
+                        const keys = opt && typeof opt === "object" ? Object.keys(opt) : [];
+                        const hint = keys.includes("label") || keys.includes("value")
+                            ? ` Use {id, name} — not {label, value} (found keys: ${keys.join(", ")}).`
+                            : "";
+                        errors.push(`${path} (${type}): specials.options[${oi}] needs a non-empty string "name" (the visible option text).${hint}`);
+                    }
+                });
+            }
         }
         // collect events
         if (Array.isArray(node.events)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "license": "MIT",