webcake-landing-mcp 1.0.51 → 1.0.52

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.52",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "validate_page now errors when an element type that the renderer cannot animate (any type other than group, image-block, text-block, rectangle,…",
+    "vi": "validate_page nay báo lỗi khi một element có loại không được renderer hỗ trợ animation (chỉ group, image-block, text-block, rectangle, button,…"
+  },
   {
     "v": "1.0.51",
     "d": "10/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "New patch_page tool edits an existing page by element id without re-sending the whole source: the agent sends per-element ops (update, replace,…",
     "vi": "Công cụ patch_page mới cho phép chỉnh sửa trang hiện có theo element id mà không cần gửi lại toàn bộ source: agent gửi các op theo element (update,…"
-  },
-  {
-    "v": "1.0.46",
-    "d": "09/06/2026",
-    "type": "Changed",
-    "en": "validate_page now emits an advisory warning when no section, button, or text on the page carries a non-neutral color (white, black, or grey),…",
-    "vi": "validate_page nay phát cảnh báo tư vấn khi không có section, button hay text nào trên trang mang màu thực sự (không phải trắng, đen hoặc xám), giúp…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -101,7 +101,7 @@ RULES
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.
 - events item: { "id", "type", "action", "target", ...action-specific extra fields }. TRIGGER (type): click & hover on any element; success & error on a FORM (success = after a successful submit, error = on validation failure); delay on any element (when it scrolls into view); unset on init. Action vocab per trigger: click→CLICK_ACTIONS, hover→HOVER_ACTIONS, success→SUCCESS_ACTIONS, error→ERROR_ACTIONS, delay→DELAY_ACTIONS (all returned by get_generation_guide). For element-targeting actions (open_popup, close_popup, scroll_to, show_section, hide_section, show_hide_element, change_tab, collapse) target = the target element's id; open_link/download_file target = URL; open_sms/send_email/phone_call target = phone/email; copy target = text (or element id when copyType='elementValue'); set_field_value target = field_name; target may be null (e.g. animation_hover). Each action also reads extra fields (e.g. open_link→targetURL/delayTime, scroll_to→scrollMore, change_tab→moveTo/tabIndex, lightbox→typeLightbox/alt, show_hide_element→onlyMode, open_app→appTarget+provider fields, set_field_value→set_value) — see the action maps for the full list.
-- ANIMATION: each breakpoint's config has config.animation = { "name":"none", "delay":0, "duration":3, "repeat":null }. Keep "none" unless an entrance animation is wanted.
+- ANIMATION: each breakpoint's config has config.animation = { "name":"none", "delay":0, "duration":3, "repeat":null }. Animations only run on these 9 element types: group, image-block, text-block, rectangle, button, countdown, line, list-paragraph, notify (renderer contract: landing_page_build/render/build/animate.js). Any other type with a non-"none" name renders stuck/dim in its pre-animation state — keep "none" on all other types. The name must be from the editor's animate.css set; common entrance families: fadeIn* (fadeInUp, fadeInDown, fadeInLeft, fadeInRight…), slideIn* (slideInUp, slideInDown, slideInLeft, slideInRight), zoomIn* (zoomIn, zoomInUp, zoomInDown…), bounceIn* (bounceIn, bounceInUp…), backIn* (backInDown, backInLeft…), flipIn* (flipInX, flipInY), lightSpeedIn* (lightSpeedInLeft, lightSpeedInRight), rotateIn* (rotateIn, rotateInDownLeft…), rollIn, jackInTheBox; attention seekers: bounce, pulse, tada, headShake, wobble, jello, heartBeat, rubberBand, shakeX, shakeY. The full set is enforced by validate_page — use an invalid name and the element renders stuck. NEVER set styles.opacity < 1 for a "subtle" or "muted" look — opacity is permanent and renders the element and all its content faded forever; use rgba() alpha on the color or background property instead.
 - Real data the page DISPLAYS must come from the user — never invent it: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, exact stats/social-proof numbers. If a value the page needs is missing, ASK for it (in intake, or pause before generating); use a clearly-labelled placeholder ONLY when the user explicitly declines, and tell them exactly what to fill. Write ALL page copy in the SAME language the user is chatting in (mirror it), with FULL, CORRECT diacritics/accents — for Vietnamese this means proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025"), NEVER accent-stripped "không dấu" text. Do not romanize, transliterate, or drop accent marks from any language.
 
 INTAKE — act as a DESIGN CONSULTANT, not a form. Goal: understand what the customer actually wants, then design as close to their intent as possible. Ask BEFORE generating, EVERY time (even a "quick"/"test" page).

package/dist/domains/landing/validate.js

@@ -9,6 +9,7 @@
 import { readFileSync } from "node:fs";
 import Ajv2020Module from "ajv/dist/2020.js";
 import { CONTAINER_TYPES, FIELD_TYPES } from "./elements/index.js";
+import { ANIMATABLE_TYPES, ANIMATION_NAMES } from "./vocab.js";
 // ajv ships as CJS; under Node16 ESM the constructor is on `.default`.
 const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
 // Loaded at runtime (the build copies this JSON beside the compiled validator)
@@ -210,6 +211,48 @@ export function validatePage(input) {
                 });
             }
         }
+        // animation contract — checked per breakpoint
+        // Source: landing_page_build/render/build/animate.js (animatable type list)
+        //         landing_page_backend/assets/editor/main/traits/TraitAnimation.vue (name set)
+        for (const bp of ["desktop", "mobile"]) {
+            const anim = node.responsive?.[bp]?.config?.animation;
+            if (!anim || typeof anim !== "object")
+                continue;
+            const animName = anim.name;
+            if (typeof animName !== "string" || animName === "none")
+                continue;
+            // name is present and not 'none' — check type animatability first
+            if (type && !ANIMATABLE_TYPES.has(type)) {
+                errors.push(`${path} (${type}) [${bp}]: the renderer cannot animate type "${type}" — ` +
+                    `the element will render stuck/dim in its pre-animation state. ` +
+                    `Fix: patch_page setting config:{${bp}:{animation:{name:'none',delay:0,duration:3,repeat:null}}} ` +
+                    `or move the animation onto an animatable wrapper (e.g. type "group").`);
+            }
+            // name must be in the known animate.css set
+            if (!ANIMATION_NAMES.has(animName)) {
+                errors.push(`${path} (${type ?? "?"}) [${bp}]: animation name "${animName}" is not in the editor's ` +
+                    `animate.css set — the keyframe is unknown and the animation never runs. ` +
+                    `Valid examples: fadeInUp, slideInLeft, zoomIn, bounceIn, backInDown, flipInX, lightSpeedInLeft, rotateIn, rollIn, jackInTheBox.`);
+            }
+        }
+        // styles.opacity < 1 renders the element permanently faded (exportCss.js emits opacity:<v>)
+        for (const bp of ["desktop", "mobile"]) {
+            const styles = node.responsive?.[bp]?.styles;
+            if (!styles || typeof styles !== "object")
+                continue;
+            const raw = styles.opacity;
+            if (raw === undefined || raw === null)
+                continue;
+            const v = typeof raw === "number" ? raw : typeof raw === "string" ? parseFloat(raw) : NaN;
+            if (!Number.isFinite(v))
+                continue; // non-numeric garbage → schema territory, skip
+            if (v < 1) {
+                warnings.push(`${path} (${type ?? "?"}) [${bp}]: styles.opacity=${v} — ` +
+                    `the element will render permanently faded. ` +
+                    `If unintended, fix via patch_page({op:'update',id:'${node.id ?? "?"}',styles:{${bp}:{opacity:1}}}); ` +
+                    `for a muted color use rgba() alpha on the color/background property instead.`);
+            }
+        }
         // countdown.language must be a key the renderer's lang table knows (or 'custom');
         // anything else (e.g. a locale code "vi"/"en") crashes the renderer with
         // "is not iterable" when it destructures lang[language].

package/dist/domains/landing/vocab.js

@@ -5,6 +5,47 @@
  * Derived from assets/render_v4/event/index.js.
  */
 export const CANVAS = { desktopWidth: 960, mobileWidth: 420, defaultSectionHeight: 800 };
+/**
+ * Element types the runtime animator handles.
+ * Source: landing_page_build/render/build/animate.js — the switch statement
+ * that emits the animation CSS class only covers these 9 types. Any other type
+ * with config.animation.name != 'none' produces a broken CSS selector and the
+ * element stays in the pre-animation (dim/hidden) state permanently.
+ */
+export const ANIMATABLE_TYPES = new Set([
+    "group", "image-block", "text-block", "rectangle", "button",
+    "countdown", "line", "list-paragraph", "notify",
+]);
+/**
+ * Valid animation name values accepted by the editor and the renderer.
+ * Source: landing_page_backend/assets/editor/main/traits/TraitAnimation.vue
+ * (the animate.css-backed option list). Any name outside this set produces
+ * an unknown keyframe — the animation never runs and the element may render stuck.
+ */
+export const ANIMATION_NAMES = new Set([
+    "none",
+    "bounce", "flash", "pulse", "rubberBand", "shakeX", "shakeY", "headShake",
+    "swing", "swingCenter", "tada", "wobble", "jello", "heartBeat",
+    "backInDown", "backInLeft", "backInRight", "backInUp",
+    "backOutDown", "backOutLeft", "backOutRight", "backOutUp",
+    "bounceIn", "bounceInDown", "bounceInLeft", "bounceInRight", "bounceInUp",
+    "bounceOut", "bounceOutDown", "bounceOutLeft", "bounceOutRight", "bounceOutUp",
+    "fadeIn", "fadeInDown", "fadeInDownBig", "fadeInLeft", "fadeInLeftBig",
+    "fadeInRight", "fadeInRightBig", "fadeInUp", "fadeInUpBig",
+    "fadeInTopLeft", "fadeInTopRight", "fadeInBottomLeft", "fadeInBottomRight",
+    "fadeOut", "fadeOutDown", "fadeOutDownBig", "fadeOutLeft", "fadeOutLeftBig",
+    "fadeOutRight", "fadeOutRightBig", "fadeOutUp", "fadeOutUpBig",
+    "fadeOutTopLeft", "fadeOutTopRight", "fadeOutBottomRight", "fadeOutBottomLeft",
+    "flip", "flipInX", "flipInY", "flipOutX", "flipOutY",
+    "lightSpeedInRight", "lightSpeedInLeft", "lightSpeedOutRight", "lightSpeedOutLeft",
+    "rotateIn", "rotateInDownLeft", "rotateInDownRight", "rotateInUpLeft", "rotateInUpRight",
+    "rotateOut", "rotateOutDownLeft", "rotateOutDownRight", "rotateOutUpLeft", "rotateOutUpRight",
+    "hinge", "jackInTheBox", "rollIn", "rollOut",
+    "zoomIn", "zoomInDown", "zoomInLeft", "zoomInRight", "zoomInUp",
+    "zoomOut", "zoomOutDown", "zoomOutLeft", "zoomOutRight", "zoomOutUp",
+    "slideInDown", "slideInLeft", "slideInRight", "slideInUp",
+    "slideOutDown", "slideOutLeft", "slideOutRight", "slideOutUp",
+]);
 export const EVENT_TRIGGERS = ["click", "hover", "success", "error", "unset", "delay"];
 // Click-trigger actions. "Extra:" lists the action-specific event-object fields
 // the dispatcher reads beyond { id, type, action, target } (render_v4/event/index.js).

package/dist/smoke.js

@@ -494,5 +494,116 @@ console.log("== draft-cache: update draft round-trip (update_page / live-page pa
     deleteDraft(uid);
     check("update draft: deleteDraft removes entry", getDraft(uid) === null, getDraft(uid));
 }
+console.log("== validate: animation contract checks ==");
+{
+    const mkSec = (children) => ({
+        id: "anim_sec",
+        type: "section",
+        properties: { name: "S", movable: false, sync: true },
+        responsive: {
+            desktop: { config: {}, styles: { position: "relative", height: 800, background: "rgba(255,255,255,1)" } },
+            mobile: { config: {}, styles: { position: "relative", height: 800, background: "rgba(255,255,255,1)" } },
+        },
+        specials: {}, runtime: {}, events: [],
+        children,
+    });
+    const mkEl = (id, type, animName, bp = "both") => ({
+        id,
+        type,
+        properties: { name: "el", movable: true, sync: true },
+        responsive: {
+            desktop: {
+                config: bp === "mobile" ? {} : { animation: { name: animName, delay: 0, duration: 3, repeat: null } },
+                styles: { top: 10, left: 10, width: 100, height: 40 },
+            },
+            mobile: {
+                config: bp === "desktop" ? {} : { animation: { name: animName, delay: 0, duration: 3, repeat: null } },
+                styles: { top: 10, left: 10, width: 100, height: 40 },
+            },
+        },
+        specials: type === "button" ? { text: "X" } : type === "text-block" ? { text: "X" } : {},
+        runtime: {}, events: [],
+    });
+    // 1) non-animatable type (form) with a real animation name → ERROR
+    const rForm = validatePage({
+        page: [mkSec([mkEl("f1", "form", "fadeInUp")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: non-animatable type (form) fadeInUp → error", rForm.errors.some((e) => e.includes("cannot animate") && e.includes("form")), rForm.errors);
+    // 2) bogus animation name on a text-block → ERROR
+    const rBogus = validatePage({
+        page: [mkSec([mkEl("t1", "text-block", "fade-in-up")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: bogus name 'fade-in-up' on text-block → error", rBogus.errors.some((e) => e.includes('"fade-in-up"') && e.includes("not in the editor")), rBogus.errors);
+    // 3) non-animatable type (html-box) with bogus name → BOTH errors
+    const rHtmlBad = validatePage({
+        page: [mkSec([mkEl("h1", "html-box", "fade-in-up")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: html-box + bogus name → type error present", rHtmlBad.errors.some((e) => e.includes("cannot animate") && e.includes("html-box")), rHtmlBad.errors);
+    check("anim: html-box + bogus name → name error present", rHtmlBad.errors.some((e) => e.includes('"fade-in-up"')), rHtmlBad.errors);
+    // 4) valid name on animatable type → NO animation error
+    const rGood = validatePage({
+        page: [mkSec([mkEl("t2", "text-block", "fadeInUp")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: valid 'fadeInUp' on text-block → no animation error", !rGood.errors.some((e) => e.includes("animate") || e.includes("keyframe")), rGood.errors);
+    // 5) name 'none' on any type → no error at all
+    const rNone = validatePage({
+        page: [mkSec([mkEl("f2", "form", "none")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: name='none' on form → no animation error", !rNone.errors.some((e) => e.includes("animate")), rNone.errors);
+    // 6) absent animation object → no error
+    const rNoAnim = validatePage({
+        page: [mkSec([{
+                    id: "f3", type: "form",
+                    properties: { name: "el", movable: true, sync: true },
+                    responsive: {
+                        desktop: { config: {}, styles: { top: 10, left: 10, width: 100, height: 40 } },
+                        mobile: { config: {}, styles: { top: 10, left: 10, width: 100, height: 40 } },
+                    },
+                    specials: {}, runtime: {}, events: [], children: [],
+                }])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("anim: absent animation config on form → no animation error", !rNoAnim.errors.some((e) => e.includes("animate")), rNoAnim.errors);
+    // 7) styles.opacity 0.4 (number) → WARNING
+    const mkOpacity = (id, type, opacity) => ({
+        id,
+        type,
+        properties: { name: "el", movable: true, sync: true },
+        responsive: {
+            desktop: { config: {}, styles: { top: 10, left: 10, width: 100, height: 40, opacity } },
+            mobile: { config: {}, styles: { top: 10, left: 10, width: 100, height: 40 } },
+        },
+        specials: type === "button" ? { text: "X" } : {},
+        runtime: {}, events: [],
+    });
+    const rOp04 = validatePage({
+        page: [mkSec([mkOpacity("b1", "button", 0.4)])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("opacity: 0.4 number → warning present", rOp04.warnings.some((w) => w.includes("opacity=0.4") && w.includes("permanently faded")), rOp04.warnings);
+    // 8) styles.opacity "0.4" (numeric string) → WARNING
+    const rOpStr = validatePage({
+        page: [mkSec([mkOpacity("b2", "button", "0.4")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("opacity: '0.4' string → warning present", rOpStr.warnings.some((w) => w.includes("opacity=0.4") && w.includes("permanently faded")), rOpStr.warnings);
+    // 9) styles.opacity 1 → NO warning
+    const rOp1 = validatePage({
+        page: [mkSec([mkOpacity("b3", "button", 1)])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("opacity: 1 → no opacity warning", !rOp1.warnings.some((w) => w.includes("permanently faded")), rOp1.warnings);
+    // 10) non-numeric opacity (e.g. "inherit") → NO warning (schema territory)
+    const rOpStr2 = validatePage({
+        page: [mkSec([mkOpacity("b4", "button", "inherit")])],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    check("opacity: 'inherit' string → no opacity warning", !rOpStr2.warnings.some((w) => w.includes("permanently faded")), rOpStr2.warnings);
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.51",
+  "version": "1.0.52",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "mcpName": "io.github.vuluu2k/webcake-landing-mcp",
   "type": "module",