webcake-landing-mcp 1.0.3 → 1.0.4

package/dist/index.js

@@ -18,7 +18,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { createElement, createPageSource } from "./factory.js";
-import { LIBRARY, GENERATION_GUIDE, CANVAS, CLICK_ACTIONS, HOVER_ACTIONS, EVENT_TRIGGERS, } from "./library.js";
+import { LIBRARY, GENERATION_GUIDE, CANVAS, CLICK_ACTIONS, HOVER_ACTIONS, SUCCESS_ACTIONS, ERROR_ACTIONS, DELAY_ACTIONS, EVENT_TRIGGERS, } from "./library.js";
 import { validatePage, coercePage, pageSchema } from "./validate.js";
 import { readConfig, buildRequestRedacted, createPage, listOrganizations, listPages, getPageSource, updatePageSource, buildUpdateRequestRedacted, } from "./webcake.js";
 const ALL_TYPES = Object.keys(LIBRARY);
@@ -52,6 +52,9 @@ server.tool("get_generation_guide", "Read this FIRST. Conventions for building a
     event_triggers: EVENT_TRIGGERS,
     click_actions: CLICK_ACTIONS,
     hover_actions: HOVER_ACTIONS,
+    success_actions: SUCCESS_ACTIONS,
+    error_actions: ERROR_ACTIONS,
+    delay_actions: DELAY_ACTIONS,
 }));
 // 2) List elements ------------------------------------------------------------
 server.tool("list_elements", "List every supported element type, grouped by category, with a one-line summary and whether it is a container (can hold children).", async () => {
@@ -100,7 +103,7 @@ server.tool("new_element", "Return a structurally-valid default element node for
 // 5) Page schema --------------------------------------------------------------
 server.tool("get_page_schema", "Return the full JSON Schema (Draft 2020-12) of a Webcake page source object { page: [...], settings: {...} }. Use it to understand the exact structure or for your own validation.", async () => text(pageSchema));
 // 6) Validate page ------------------------------------------------------------
-server.tool("validate_page", "Validate a generated page source against the schema + semantic rules (unique ids, dangling event targets, children only on containers, missing field_name, top-level types). Returns errors (must fix) and warnings. ALWAYS run before returning the final page.", {
+server.tool("validate_page", "Validate a generated page source against the schema + semantic rules (unique ids, dangling event targets, children only on containers, missing field_name, top-level types) plus form-data bindings (duplicate field_name within one form, dangling option-event promoId / connectedSurvey / connectedForm / set_field_value targets). Returns errors (must fix) and warnings. ALWAYS run before returning the final page.", {
     page: z
         .any()
         .describe("The page source object { page:[...], settings:{} } OR a JSON string of it."),

package/dist/library.js

@@ -6,42 +6,72 @@
  */
 export const CANVAS = { desktopWidth: 960, mobileWidth: 420, defaultSectionHeight: 800 };
 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).
 export const CLICK_ACTIONS = {
     none: "Do nothing.",
-    open_link: "Open a URL. target = URL (often with a `target`/`blank` flag for new tab).",
-    open_popup: "Open a popup. target = popup element id.",
-    close_popup: "Close a popup. target = popup element id.",
-    scroll_to: "Smooth-scroll to an element. target = element/section id.",
+    open_link: "Open a URL. target = URL. Extra: targetURL ('_blank'|'_self'), open_link_with_params (bool), send_to_thank_page (bool), delayTime (seconds).",
+    open_popup: "Open a popup. target = popup element id. Extra: animation, reverseAnimation.",
+    close_popup: "Close a popup. target = popup element id. Extra: animation.",
+    scroll_to: "Smooth-scroll to an element. target = element/section id. Extra: scrollMore (bonus px offset).",
     show_section: "Show a hidden section. target = section id.",
     hide_section: "Hide a section. target = section id.",
-    show_hide_element: "Toggle element visibility. target = element id.",
-    change_tab: "Switch tab. target = id.",
-    lightbox: "Open image in lightbox. target = image id/url.",
-    copy: "Copy to clipboard. target = the text; OR an element id when copyType='elementValue'.",
-    collapse: "Collapse/expand. target = id.",
-    set_field_value: "Set a form field value. target = field_name, plus set_value.",
+    show_hide_element: "Toggle element visibility. target = element id (comma-separated list allowed). Extra: onlyMode ('show'|'hide'), animation, animationOut.",
+    change_tab: "Switch tab/slide in a gallery/carousel. target = container id. Extra: moveTo ('prev'|'next'|'index'), tabIndex.",
+    lightbox: "Open in a lightbox. target = image/video/iframe URL. Extra: typeLightbox ('image'|'video'|'iframe'), alt.",
+    copy: "Copy to clipboard. target = the text; OR an element id when copyType='elementValue'. Extra: copyType.",
+    collapse: "Collapse/expand. target = element id.",
+    set_field_value: "Set a form field value. target = field_name (or w-<element id>). Extra: set_value (the value to set).",
     back_to: "Go back in browser history (history.back()). target = none.",
     share: "Share the current page URL. target = platform name: 'Facebook'|'Twitter'|'Custom'.",
     play_audio: "Play audio. target = audio file URL (NOT an element id).",
     stop_audio: "Stop audio. target = the same audio file URL (NOT an element id).",
-    open_sms: "Send SMS. target = phone number; optional smsBody for the message body.",
+    open_sms: "Send SMS. target = phone number. Extra: smsBody (message body).",
     send_email: "Open mail client. target = email address (mailto:).",
-    download_file: "Download a file. target = file URL; optional nameFile overrides filename.",
+    download_file: "Download a file. target = file URL. Extra: nameFile (overrides the saved filename).",
     close_webview: "Close a Facebook/Messenger in-app webview. target = none.",
-    open_cart: "Open cart.",
-    add_to_cart: "Add product to cart. target = product id.",
-    open_app: "Open chat/app. event.appTarget selects the provider (botcake|botcake_dynamic|whatsapp|mess_prefill|tiktok_prefill|line_prefill|others); target = destination URL/phone/ref.",
-    change_color: "Change color.",
-    custom_js: "Run custom JS.",
+    open_cart: "Open the cart drawer (WCart).",
+    add_to_cart: "Add a product to the cart. Uses specials.sprod/svariant/squantity (or event.sprod_id/svariant/squantity); target unused.",
+    open_app: "Open chat/app. event.appTarget selects the provider (botcake|botcake_dynamic|whatsapp|mess_prefill|tiktok_prefill|line_prefill|others); target = destination URL/phone/ref. Extra: wa_custom_text, line_custom_text, formIdLink (per provider).",
+    change_color: "Change a color. Acts on the trigger element, or target_element for a cross-element change. Extra: change_color_type, change_color, target_mode, target_element.",
+    custom_js: "Run custom JS. Extra: custom_js (the code string).",
 };
 export const HOVER_ACTIONS = {
-    change_color: "Change color on hover.",
-    change_background: "Change background on hover.",
-    change_text_color: "Change text color on hover.",
+    change_color: "Change color on hover. Extra: change_color, change_color_type, hoverText, hoverBorder, target_mode, target_element.",
+    change_background: "Change background on hover. Extra: hoverColor (applied via --hover-color).",
+    change_text_color: "Change text color on hover. Extra: hoverText.",
     change_underline: "Underline on hover.",
     change_overline: "Overline on hover.",
-    animation_hover: "Play a hover animation.",
-    show_hide_element: "Reveal/hide a target element on hover.",
+    animation_hover: "Play a hover animation. target = none.",
+    show_hide_element: "Reveal/hide a target element on hover. target = element id. Extra: animation, animationOut.",
+};
+// Actions on a FORM's own events array, fired AFTER a successful submit (type:"success").
+// target semantics match the click action of the same name.
+export const SUCCESS_ACTIONS = {
+    phone_call: "Call a number. target = phone number (tel:).",
+    open_sms: "Send SMS. target = phone number. Extra: smsBody.",
+    send_email: "Open mail client. target = email address.",
+    open_link: "Open a URL. target = URL. Extra: targetURL ('_blank'|'_self').",
+    scroll_to: "Scroll to an element. target = element id. Extra: scrollMore.",
+    open_popup: "Open a popup. target = popup id.",
+    close_popup: "Close a popup. target = popup id.",
+    download_file: "Download a file. target = file URL. Extra: nameFile.",
+    show_hide_element: "Toggle visibility. target = element id. Extra: onlyMode.",
+    show_section: "Show a section. target = section id.",
+    hide_section: "Hide a section. target = section id.",
+    close_webview: "Close a Facebook/Messenger webview. target = none.",
+    change_tab: "Switch tab/slide. target = container id. Extra: moveTo, tabIndex.",
+};
+// Actions on a FORM's events array, fired when validation FAILS (type:"error").
+export const ERROR_ACTIONS = {
+    open_popup: "Open a popup. target = popup id.",
+    close_popup: "Close a popup. target = popup id.",
+    show_hide_element: "Toggle visibility. target = element id. Extra: onlyMode.",
+};
+// Actions on ANY element's events array, fired when it scrolls into view (type:"delay").
+export const DELAY_ACTIONS = {
+    show_element: "Reveal this element after a delay. Extra: delay_multiplier (ms, default 1000).",
+    hide_element: "Hide this element after a delay. Extra: delay_multiplier (ms, default 1000).",
 };
 export const LIBRARY = {
     // ---------------- layout / containers ----------------
@@ -717,7 +747,7 @@ RULES
 - 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.
-- events item: { "id", "type":"click"|"hover"|"success"|"unset", "action", "target", "appTarget":"", "hoverColor":"" }. For element-targeting actions (open_popup, close_popup, scroll_to, show_section, hide_section, show_hide_element) target = the target element's id; for open_link target = URL; for copy target = the text; target may be null (e.g. animation_hover).
+- 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.
 - Do NOT invent prices, phone numbers, addresses, or statistics. Output text in the requested language.
 

package/dist/smoke.js

@@ -118,5 +118,62 @@ for (const [type, doc] of Object.entries(LIBRARY)) {
     const rr = validatePage(wrapped);
     check(`example ${type} valid`, rr.valid, rr.errors);
 }
+console.log("== validate: form-data binding checks ==");
+const mkBox = () => ({ desktop: { config: {}, styles: {} }, mobile: { config: {}, styles: {} } });
+const bindingsBad = {
+    page: [
+        {
+            id: "secf", type: "section",
+            properties: { name: "F", movable: false, sync: true },
+            responsive: { desktop: { config: {}, styles: { position: "relative", height: 800 } }, mobile: { config: {}, styles: { position: "relative", height: 800 } } },
+            specials: {}, runtime: {}, events: [],
+            children: [
+                {
+                    id: "frm1", type: "form",
+                    properties: { name: "Form", movable: true, sync: true },
+                    responsive: mkBox(), specials: {}, runtime: {}, events: [],
+                    children: [
+                        { id: "i1", type: "input", properties: {}, responsive: mkBox(), specials: { field_name: "phone_number" }, events: [] },
+                        { id: "i2", type: "input", properties: {}, responsive: mkBox(), specials: { field_name: "phone_number" }, events: [] },
+                        { id: "rad1", type: "radio", properties: {}, responsive: mkBox(),
+                            specials: { field_name: "opt", options: [{ id: "o1", events_option: [{ id: "e", type: "showhide", promoId: "ghost_target" }] }] },
+                            runtime: {}, events: [], children: [] },
+                        { id: "sv1", type: "survey", properties: {}, responsive: mkBox(), specials: { field_name: "sv", connectedForm: "missing_field" }, events: [] },
+                        { id: "b1", type: "button", properties: {}, responsive: mkBox(), specials: { text: "X" },
+                            events: [{ id: "ev", type: "click", action: "set_field_value", target: "w-nope" }] },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+const rbb = validatePage(bindingsBad);
+check("dup field_name in form warned", rbb.warnings.some((w) => w.includes('field_name "phone_number"') && w.includes("used 2")), rbb.warnings);
+check("dangling option promoId warned", rbb.warnings.some((w) => w.includes("promoId") && w.includes("ghost_target")), rbb.warnings);
+check("dangling connectedForm warned", rbb.warnings.some((w) => w.includes("connectedForm") && w.includes("missing_field")), rbb.warnings);
+check("dangling set_field_value element ref warned", rbb.warnings.some((w) => w.includes("set_field_value") && w.includes("w-nope")), rbb.warnings);
+const bindingsGood = {
+    page: [
+        {
+            id: "secg", type: "section",
+            properties: { name: "G", movable: false, sync: true },
+            responsive: { desktop: { config: {}, styles: { position: "relative", height: 800 } }, mobile: { config: {}, styles: { position: "relative", height: 800 } } },
+            specials: {}, runtime: {}, events: [],
+            children: [
+                {
+                    id: "frm2", type: "form",
+                    properties: { name: "Form", movable: true, sync: true },
+                    responsive: mkBox(), specials: {}, runtime: {}, events: [],
+                    children: [
+                        { id: "n1", type: "input", properties: {}, responsive: mkBox(), specials: { field_name: "full_name" }, events: [] },
+                        { id: "p1", type: "input", properties: {}, responsive: mkBox(), specials: { field_name: "phone_number" }, events: [] },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+const rbg = validatePage(bindingsGood);
+check("clean form has no binding warnings", rbg.warnings.length === 0, rbg.warnings);
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/validate.js

@@ -1,7 +1,10 @@
 /**
  * Page validation: JSON-Schema structural check (ajv, draft 2020-12) plus
  * semantic checks the schema can't express (unique ids, dangling event targets,
- * children only on containers, missing field_name, top-level types).
+ * children only on containers, missing field_name, top-level types). Also checks
+ * form-data bindings: duplicate field_name within a single form, and dangling
+ * option-level event targets (specials.options[].events_option promoId) and
+ * survey/field cross-wiring (connectedSurvey / connectedForm / set_field_value).
  */
 import { readFileSync } from "node:fs";
 import Ajv2020Module from "ajv/dist/2020.js";
@@ -66,6 +69,12 @@ export function validatePage(input) {
     // 2) Semantic
     const ids = new Map();
     const eventTargets = [];
+    // option-level events (specials.options[].events_option) targeting an element id
+    const optionTargets = [];
+    // survey/field cross-wiring (specials.connectedSurvey / connectedForm)
+    const connectRefs = [];
+    // form nodes — used to check field_name uniqueness within each form's scope
+    const forms = [];
     let elementCount = 0;
     const topList = Array.isArray(page?.page)
         ? page.page
@@ -113,6 +122,33 @@ export function validatePage(input) {
                 }
             }
         }
+        // collect form-data bindings: option-level events (showhide/collapse promoId)
+        // and survey/field cross-wiring; and remember form scopes for field_name checks.
+        const sp = node.specials;
+        if (sp && typeof sp === "object") {
+            if (Array.isArray(sp.options)) {
+                for (const opt of sp.options) {
+                    if (!opt || !Array.isArray(opt.events_option))
+                        continue;
+                    for (const ev of opt.events_option) {
+                        if (ev &&
+                            (ev.type === "showhide" || ev.type === "collapse") &&
+                            typeof ev.promoId === "string" &&
+                            ev.promoId.trim() !== "") {
+                            optionTargets.push({ from: node.id ?? path, kind: ev.type, target: ev.promoId });
+                        }
+                    }
+                }
+            }
+            for (const key of ["connectedSurvey", "connectedForm"]) {
+                const v = sp[key];
+                if (typeof v === "string" && v.trim() !== "") {
+                    connectRefs.push({ from: node.id ?? path, key, target: v });
+                }
+            }
+        }
+        if (type === "form")
+            forms.push(node);
         if (Array.isArray(node.children)) {
             node.children.forEach((c, idx) => walk(c, `${path}.children[${idx}]`));
         }
@@ -133,14 +169,64 @@ export function validatePage(input) {
         if (count > 1)
             errors.push(`Duplicate id "${id}" used ${count} times — ids must be unique.`);
     }
+    // Does `target` fail to resolve to any element id? (ids may be stored with or
+    // without the runtime `w-`/`#w-` prefix.)
+    const danglesId = (target) => {
+        const cleaned = target.replace(/^#?w-/, "");
+        return !ids.has(target) && !ids.has(cleaned);
+    };
     // dangling element-target events
     for (const t of eventTargets) {
         if (ELEMENT_TARGET_ACTIONS.has(t.action)) {
-            const cleaned = t.target.replace(/^#?w-/, "");
-            if (!ids.has(t.target) && !ids.has(cleaned)) {
+            if (danglesId(t.target)) {
                 warnings.push(`event on "${t.from}" action="${t.action}" target="${t.target}" does not match any element id.`);
             }
         }
+        else if (t.action === "set_field_value" && /^#?w-/.test(t.target) && danglesId(t.target)) {
+            // set_field_value target is a field_name OR an element id; only an explicit
+            // element ref (w- prefix) can dangle — a bare field_name is not an id.
+            warnings.push(`event on "${t.from}" action="set_field_value" target="${t.target}" looks like an element id but matches none.`);
+        }
+    }
+    // dangling option-level event targets (specials.options[].events_option promoId)
+    for (const t of optionTargets) {
+        if (danglesId(t.target)) {
+            warnings.push(`option event on "${t.from}" type="${t.kind}" promoId="${t.target}" does not match any element id.`);
+        }
+    }
+    // dangling survey/field cross-wiring
+    for (const r of connectRefs) {
+        if (danglesId(r.target)) {
+            warnings.push(`"${r.from}" specials.${r.key}="${r.target}" does not match any element id.`);
+        }
+    }
+    // field_name uniqueness WITHIN each form — duplicate names collide in the
+    // submitted data. (A nested form is its own data scope, so stop at one.)
+    const collectFieldNames = (n, acc) => {
+        if (!n || !Array.isArray(n.children))
+            return;
+        for (const c of n.children) {
+            if (!c || typeof c !== "object")
+                continue;
+            if (c.type === "form")
+                continue;
+            const fn = c.specials?.field_name;
+            if (typeof fn === "string" && fn.trim() !== "")
+                acc.push(fn.trim());
+            collectFieldNames(c, acc);
+        }
+    };
+    for (const form of forms) {
+        const names = [];
+        collectFieldNames(form, names);
+        const counts = new Map();
+        for (const fn of names)
+            counts.set(fn, (counts.get(fn) || 0) + 1);
+        for (const [fn, count] of counts) {
+            if (count > 1) {
+                warnings.push(`form "${form.id ?? "?"}": field_name "${fn}" used ${count} times — inputs in one form need a unique field_name (data collides on submit).`);
+            }
+        }
     }
     // 3) Layout bounds — flag children that fall off their container's canvas (a
     //    common cause of "off-center / misaligned" pages). Warnings only.

package/package.json

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