webcake-landing-mcp 1.0.61 → 1.0.62

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.62",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "validate_page now warns when a text-block's estimated rendered height overflows onto a sibling element placed directly below its declared box; the…",
+    "vi": "validate_page nay cảnh báo khi chiều cao render ước tính của text-block tràn xuống phần tử anh em đặt ngay phía dưới khung khai báo; cảnh báo nêu…"
+  },
   {
     "v": "1.0.61",
     "d": "11/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "New upload_images tool re-hosts up to 20 external image URLs or data: URIs as Webcake-hosted URLs (statics.pancake.vn) by downloading and uploading…",
     "vi": "Công cụ upload_images mới tải lại tối đa 20 URL ảnh ngoài hoặc data: URI thành URL do Webcake lưu trữ (statics.pancake.vn) bằng cách tải về và…"
-  },
-  {
-    "v": "1.0.56",
-    "d": "11/06/2026",
-    "type": "Added",
-    "en": "The expand pipeline now automatically derives styles.background from specials.src for every image-block node; the live published renderer reads only…",
-    "vi": "Pipeline expand nay tự động tính styles.background từ specials.src cho mọi node image-block; renderer trên trang published chỉ đọc…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -141,7 +141,7 @@ WORKFLOW (recommended)
 3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
 3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image (user-supplied or from the reference HTML/URL), upload_images it and use the returned Webcake URL; otherwise call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
 4. Assemble { page, popup, settings, options, cartConfigs }.
-5. Call validate_page and fix every error.
+5. Call validate_page and fix every error AND every warning — warnings are visible defects (text spilling onto the element below, off-canvas boxes, empty bands at a section's bottom, missing field_name, dead event targets), not advisory polish. Re-validate until the warning list is empty; only a demonstrably false positive may remain (tell the user which and why).
 6. To save: call list_organizations. If the account has EXACTLY ONE organization, create_page will auto-select it — no need to ask. If there are MULTIPLE organizations, show them to the user and ask which to use (highlight is_default as the suggested default); pass the chosen organization_id to create_page. If the user explicitly wants to save without any organization, pass organization_id:"personal". Then create_page (dry_run first, then dry_run:false). Note: create_page itself enforces this — it refuses to guess between multiple orgs and returns the org list asking you to pick.
 
 EDITING an existing page

package/dist/domains/landing/instructions.js

@@ -9,9 +9,9 @@ RULES (follow for every request):
 - INTAKE FIRST — do this EVERY time, even for a "quick"/"test" page. Do NOT jump straight to new_page_skeleton/create_page on the same turn as the request: ask the essentials, restate an outline, get a "yes", THEN build. Ask ONE short batch (3–6, with sensible defaults so the user answers fast) enough to understand the page's PURPOSE, name, look and layout: page purpose/goal, brand/page name, what they sell + price (sales/ads pages), primary color + logo/branding, sections & layout in order, primary CTA + destination, desktop+mobile or mobile-only, which organization. CONSULT, don't interrogate: SUGGEST so the user reacts to something concrete — propose a section flow (pick the archetype matching the page type) + a look (hero treatment + color/tone), and when the user is vague offer 2–3 directions to choose from; proactively suggest sections that fit their goal (social-proof, FAQ, countdown), but ask, don't silently add. Then restate the proposed design (section flow + CTA + color/tone) and WAIT for the user's confirmation, iterating until it matches their intent, before generating. Never assume or silently placeholder the page name, product, price, or colors — ask; only placeholder a core fact when the user explicitly declines to give it.
 - ASK for any real data the page will display — never invent it, and don't silently placeholder it. This includes: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, and exact stats/social-proof numbers. If a value the page needs is missing, ASK the user for it (in intake, or pause and ask before generating). Use a clearly-labelled placeholder ONLY when the user explicitly says to skip it — then tell them exactly what to fill in.
 - LANGUAGE: write ALL page copy in the SAME language the user is chatting in, with FULL, CORRECT diacritics/accents. For Vietnamese, every word MUST carry its proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025") — NEVER emit accent-stripped "không dấu" text. Never romanize or drop accent marks from any language.
-- ALWAYS call validate_page and fix every error before create_page / update_page.
+- ALWAYS call validate_page and fix every error before create_page / update_page. WARNINGS ARE A FIX LIST, NOT NOISE: each warning is a visible defect the customer will see (text spilling onto the element below, off-canvas boxes, empty bands, missing field_name, dead event targets). Fix every warning too — before the first save when building new, or via patch_page right after saving an edit — and re-validate until the list is empty. Only a warning you can demonstrate is a false positive may remain (name it to the user and say why). Never tell the user the page is done while warnings stand.
 - BUILD THE SOURCE IN ONE PASS — gather everything you need BEFORE assembling the source, then build the FULL tree once. BATCH the reads: when a section needs several element types (section + text-block + image-block + button + form + input), call get_element({types:[…]}) ONCE instead of one call per type — same for images, call search_images({queries:[…]}) ONCE with one query per image slot (it dedups + parallelizes and returns one best photo per query). Across MULTIPLE pages in one conversation: reusing skeletons you already fetched is correct, but call get_element for any type you have NOT already fetched in this conversation — NEVER author an unfamiliar type from memory; and if the earlier skeletons are no longer in your context (long conversation, compacted history), re-fetch before building. Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the request.
-- create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
+- create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors, warnings fixed), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
 - LARGE PAGES (4+ sections) — build INCREMENTALLY to avoid the giant single create_page payload that can drop the connection: create_page with a SMALL skeleton (empty/near-empty page) to get a page_id, then call add_section once per section (each call ships ONLY that section; the backend appends it server-side and rejects duplicate ids — no whole-source get+put). Small pages can still go in one create_page pass.
 - EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates. For a SMALL edit, PREFER patch_page over update_page: send only the changed elements by id (ops: update/replace/remove/add) instead of re-shipping the whole tree — the MCP fetches the live source, merges, validates and saves server-side. Use update_page only when you're rewriting most of the page. Never regenerate the whole tree for a small change.
 - FIX-AFTER-ERROR / RETRY-AFTER-TIMEOUT (don't rebuild — this is the #1 time-waster): every mutating tool (create_page, update_page, add_section, patch_page) writes the payload to a draft cache BEFORE the network call and returns a draft_id. On validation failure, timeout, or any network error, the draft is kept — retry or fix without re-sending the full JSON:

package/dist/domains/landing/validate.js

@@ -61,6 +61,25 @@ function num(v) {
     }
     return undefined;
 }
+/**
+ * Estimated rendered height (px) of a text-block's specials.text at a given
+ * fontSize/width — the guide's TEXT HEIGHT MATH (lines ≈ ceil(chars × fontSize
+ * × 0.55 / width), height ≈ lines × fontSize × 1.4; lines counted per explicit
+ * <br> segment). Returns undefined for empty text or template variables
+ * ({{…}}) whose rendered length is unknown.
+ */
+function estTextHeight(rawText, fs, w) {
+    if (rawText.includes("{{") || !(fs > 0) || !(w > 0))
+        return undefined;
+    const segments = rawText
+        .split(/<br\s*\/?>/i)
+        .map((s) => s.replace(/<[^>]*>/g, "").replace(/&nbsp;|&#160;/g, " ").trim())
+        .filter((s) => s !== "");
+    if (segments.length === 0)
+        return undefined;
+    const lines = segments.reduce((acc, seg) => acc + Math.max(1, Math.ceil((seg.length * fs * 0.55) / w)), 0);
+    return Math.round(lines * fs * 1.4);
+}
 /**
  * True when a CSS color string carries real hue — i.e. NOT white/black/grey/
  * transparent. Used to flag a page that ships with no color at all (every band
@@ -325,31 +344,22 @@ export function validatePage(input) {
                 // Wrapped-text overflow: live text height is AUTO — text that wraps to
                 // more lines than the declared box spills DOWN and overlaps the element
                 // below (the classic "2-line card title over the card body" defect).
-                // Rough estimate: avg glyph width ≈ fontSize × 0.55, line height ≈
-                // fontSize × 1.4; lines counted per explicit <br> segment. Warn only when
-                // the estimate exceeds the declared height by MORE than one full line
-                // (keeps the heuristic from flagging well-sized paragraphs). Skip text
-                // with template variables ({{…}}) — rendered length is unknown.
-                if (!rawText.includes("{{")) {
-                    const segments = rawText
-                        .split(/<br\s*\/?>/i)
-                        .map((s) => s.replace(/<[^>]*>/g, "").replace(/&nbsp;|&#160;/g, " ").trim())
-                        .filter((s) => s !== "");
-                    if (segments.length > 0) {
-                        for (const bp of ["desktop", "mobile"]) {
-                            const styles = node.responsive?.[bp]?.styles;
-                            const w = num(styles?.width);
-                            const h = num(styles?.height);
-                            const fs = num(styles?.fontSize) ?? 16;
-                            if (!w || !h || w <= 0 || fs <= 0)
-                                continue;
-                            const lines = segments.reduce((acc, seg) => acc + Math.max(1, Math.ceil((seg.length * fs * 0.55) / w)), 0);
-                            const lineH = fs * 1.4;
-                            const est = Math.round(lines * lineH);
-                            if (est > h + lineH) {
-                                warnings.push(`${path} (text-block) [${bp}]: text wraps to ~${lines} lines (~${est}px) but the box is only ${h}px tall — live text height is AUTO, so it will spill down and overlap the element below. Set height ≈ ${est}px and push the elements below down (estimate: lines ≈ ceil(chars × fontSize × 0.55 / width), height ≈ lines × fontSize × 1.4).`);
-                            }
-                        }
+                // Slack is capped at 24px: a full-line slack on a 40px heading (56px)
+                // is exactly what lets the most common defect — a 2-line H2 on a
+                // 1-line-tall box — slip through, while body text (16px → 22px line)
+                // keeps its old tolerance against the rough estimate.
+                for (const bp of ["desktop", "mobile"]) {
+                    const styles = node.responsive?.[bp]?.styles;
+                    const w = num(styles?.width);
+                    const h = num(styles?.height);
+                    const fs = num(styles?.fontSize) ?? 16;
+                    if (!w || !h)
+                        continue;
+                    const est = estTextHeight(rawText, fs, w);
+                    if (est == null)
+                        continue;
+                    if (est > h + Math.min(fs * 1.4, 24)) {
+                        warnings.push(`${path} (text-block) [${bp}]: text wraps to ~${est}px but the box is only ${h}px tall — live text height is AUTO, so it will spill down and overlap the element below. Set height ≈ ${est}px and push the elements below down (estimate: lines ≈ ceil(chars × fontSize × 0.55 / width), height ≈ lines × fontSize × 1.4).`);
                     }
                 }
             }
@@ -696,6 +706,95 @@ export function validatePage(input) {
         const ms = sec?.responsive?.mobile?.styles ?? {};
         checkBounds(sec, rootCanvasD, num(ds.height) ?? DEFAULT_SECTION_HEIGHT, rootCanvasM, num(ms.height) ?? DEFAULT_SECTION_HEIGHT, `page[${i}]`);
     });
+    // 3c) Wrapped-text collision — live text height is AUTO, so a text-block whose
+    //     content wraps past its declared box spills DOWN. When the declared layout
+    //     puts a sibling directly below (boxes NOT overlapping — overlapping boxes
+    //     are intentional layering), the spill lands ON that sibling: the classic
+    //     broken-looking page of a 2-line H2 over its subheading or a wrapped card
+    //     title over the card body. The own-box check (section 1) flags the text
+    //     block itself; this geometric pass names the VICTIM and the exact fix.
+    let overlapWarnings = 0;
+    const MAX_OVERLAP_WARNINGS = 12;
+    const checkTextOverlap = (container, path) => {
+        if (!container || !Array.isArray(container.children))
+            return;
+        const kids = container.children;
+        kids.forEach((child, idx) => {
+            if (!child || typeof child !== "object")
+                return;
+            const cpath = `${path}.children[${idx}]`;
+            const rawText = child.type === "text-block" ? child.specials?.text : undefined;
+            if (typeof rawText === "string") {
+                for (const bp of ["desktop", "mobile"]) {
+                    if (overlapWarnings >= MAX_OVERLAP_WARNINGS)
+                        break;
+                    const s = child.responsive?.[bp]?.styles;
+                    const top = num(s?.top);
+                    const left = num(s?.left) ?? 0;
+                    const w = num(s?.width);
+                    const h = num(s?.height);
+                    const fs = num(s?.fontSize) ?? 16;
+                    if (top == null || h == null || !w)
+                        continue;
+                    const est = estTextHeight(rawText, fs, w);
+                    if (est == null || est <= h)
+                        continue;
+                    const estBottom = top + est;
+                    // nearest sibling the declared layout places below this text block
+                    let hit;
+                    kids.forEach((sib, j) => {
+                        if (j === idx || !sib || typeof sib !== "object")
+                            return;
+                        const ss = sib.responsive?.[bp]?.styles;
+                        const st = num(ss?.top);
+                        const sl = num(ss?.left) ?? 0;
+                        const sw = num(ss?.width);
+                        if (st == null || sw == null)
+                            return;
+                        if (st < top + h)
+                            return; // declared boxes overlap or sibling is above → layering, skip
+                        if (sl + sw <= left || sl >= left + w)
+                            return; // no horizontal intersection
+                        if (estBottom > st + 4 && (!hit || st < hit.t))
+                            hit = { p: `${path}.children[${j}]`, t: st, type: sib.type ?? "?" };
+                    });
+                    if (hit) {
+                        warnings.push(`${cpath} (text-block) [${bp}]: wrapped text renders ~${est}px tall (declared ${h}px) and will spill onto ${hit.p} (${hit.type}, top=${hit.t}) below it. Set this block's height ≈ ${est} and move the elements below to top ≥ ${estBottom + 8}.`);
+                        overlapWarnings++;
+                    }
+                }
+            }
+            if (Array.isArray(child.children) && child.children.length > 0)
+                checkTextOverlap(child, cpath);
+        });
+    };
+    topList.forEach((sec, i) => checkTextOverlap(sec, `page[${i}]`));
+    // 3d) Trailing dead space — a section far taller than its lowest content
+    //     renders as a big empty band, which reads as a broken/unfinished page.
+    //     Threshold is generous (320px) since text auto-grow and bottom padding
+    //     are legitimate; advisory only.
+    topList.forEach((sec, i) => {
+        if (!sec || !Array.isArray(sec.children) || sec.children.length === 0)
+            return;
+        for (const bp of ["desktop", "mobile"]) {
+            const sh = num(sec.responsive?.[bp]?.styles?.height);
+            if (sh == null)
+                continue;
+            let maxBottom;
+            for (const child of sec.children) {
+                const s = child?.responsive?.[bp]?.styles;
+                const t = num(s?.top);
+                const h = num(s?.height);
+                if (t == null || h == null)
+                    continue;
+                if (maxBottom == null || t + h > maxBottom)
+                    maxBottom = t + h;
+            }
+            if (maxBottom != null && sh > maxBottom + 320) {
+                warnings.push(`page[${i}] (section) [${bp}]: height=${sh} but the lowest child ends at ${maxBottom} — ~${sh - maxBottom}px of empty band at the bottom of the section. Reduce the section height to ≈ ${maxBottom + 80} (or move content down into the band).`);
+            }
+        }
+    });
     // 3b) Page margin axis — every band (header included) should put its
     //     left-anchored content on ONE shared left margin. A header/section that
     //     starts on a different left than the rest is the #1 "looks misaligned"

package/dist/mcp/response.js

@@ -6,3 +6,15 @@ export function text(value) {
     const body = typeof value === "string" ? value : JSON.stringify(value, null, 2);
     return { content: [{ type: "text", text: body }] };
 }
+/**
+ * Directive shipped alongside every non-empty validation-warnings list.
+ * Warnings are design defects the customer WILL see (text overlapping the
+ * element below, off-canvas boxes, empty bands, dead event targets, missing
+ * field_name…) — without this, models treat them as advisory noise and save
+ * anyway.
+ */
+export const WARNINGS_NOTICE = "FIX THESE WARNINGS — each one is a visible defect the customer will see, not a suggestion. Apply the fix each warning prescribes (patch_page by element id is the cheap path), then re-validate until the list is empty. Only a warning you can demonstrate is a false positive may remain — name it to the user and say why. Do NOT report the page as done while warnings stand.";
+/** Spread helper: {} when there are no warnings, else { warnings, warnings_notice }. */
+export function warningsField(warnings) {
+    return warnings && warnings.length > 0 ? { warnings, warnings_notice: WARNINGS_NOTICE } : {};
+}

package/dist/smoke.js

@@ -8,6 +8,7 @@ import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { expandSource } from "./core/expand.js";
 import { compactSource, deepEq, sparseTemplate } from "./core/compact.js";
 import { parseHtml } from "./persistence/html-ingest.js";
+import { warningsField } from "./mcp/response.js";
 import { readConfig, resolveEnv, ENV_NAMES, configFromHeaders } from "./persistence/config.js";
 import { toEditorUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
 import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
@@ -964,5 +965,50 @@ console.log("== text-block styles.background warning (gradient-text-fill mode) =
     });
     check("text-block: no styles.background → no gradient-fill warning", !rNoBg2.warnings.some((w) => w.includes("gradient text-fill")), rNoBg2.warnings);
 }
+console.log("== warningsField: warnings ship with the fix-list directive ==");
+{
+    const withW = warningsField(["page[0]: something"]);
+    check("warningsField: non-empty warnings carry warnings_notice", Array.isArray(withW.warnings) && typeof withW.warnings_notice === "string" && withW.warnings_notice.includes("FIX THESE WARNINGS"), withW);
+    check("warningsField: empty list adds nothing", Object.keys(warningsField([])).length === 0 && Object.keys(warningsField(undefined)).length === 0);
+}
+console.log("== validator: wrapped-text collision + trailing dead space ==");
+{
+    const tb = (id, top, height, text, fontSize, extra = {}) => ({
+        id, type: "text-block",
+        responsive: {
+            desktop: { styles: { top, left: 80, width: 560, height, fontSize, ...extra } },
+            mobile: { styles: { top, left: 20, width: 380, height, fontSize: Math.round(fontSize * 0.7), ...extra } },
+        },
+        specials: { text, tag: "p" },
+    });
+    const sect = (children, height = 800) => ({
+        page: [{ id: "csec", type: "section", responsive: { desktop: { styles: { height } }, mobile: { styles: { height } } }, children }],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    const headline = "The challenges every hotel faces today"; // wraps to 2 lines at 40px/560w
+    // 2-line H2 on a 1-line box with the subheading right under the declared box → both checks fire
+    const rClash = validatePage(expandSource(sect([tb("h2", 120, 50, headline, 40), tb("sub", 180, 60, "Guests reach out from everywhere and teams are stretched thin.", 16)]), createElement));
+    check("collision: 2-line H2 over subheading warned (names the victim)", rClash.warnings.some((w) => w.includes("spill onto") && w.includes("children[1]")), rClash.warnings);
+    check("own-box: 2-line H2 on 1-line box no longer slips the one-line slack", rClash.warnings.some((w) => w.includes("children[0]") && w.includes("spill down")), rClash.warnings);
+    // properly sized heading + subheading pushed below the estimated bottom → silent
+    const rOk = validatePage(expandSource(sect([tb("h2", 120, 112, headline, 40), tb("sub", 260, 60, "Guests reach out from everywhere and teams are stretched thin.", 16)]), createElement));
+    check("collision: sized heading + pushed-down subheading → no overlap warning", !rOk.warnings.some((w) => w.includes("spill")), rOk.warnings);
+    // layered background rectangle (declared boxes overlap) must NOT count as a victim
+    const card = {
+        id: "card", type: "group",
+        responsive: { desktop: { styles: { top: 100, left: 80, width: 280, height: 300 } }, mobile: { styles: { top: 100, left: 20, width: 280, height: 300 } } },
+        children: [
+            { id: "bg", type: "rectangle", responsive: { desktop: { styles: { top: 0, left: 0, width: 280, height: 300 } }, mobile: { styles: { top: 0, left: 0, width: 280, height: 300 } } } },
+            tb("title", 24, 30, "Guests who book once and disappear forever", 22, { left: 24, width: 232 }),
+        ],
+    };
+    const rCard = validatePage(expandSource(sect([card]), createElement));
+    check("collision: layered card background is not a victim", !rCard.warnings.some((w) => w.includes("spill onto") && w.includes("rectangle")), rCard.warnings);
+    // trailing dead space: section 900 tall, content ends at 300
+    const rDead = validatePage(expandSource(sect([tb("h2", 200, 100, "Short", 40)], 900), createElement));
+    check("dead space: 600px empty band at section bottom warned", rDead.warnings.some((w) => w.includes("empty band")), rDead.warnings);
+    const rTight = validatePage(expandSource(sect([tb("h2", 200, 100, "Short", 40)], 500), createElement));
+    check("dead space: 200px bottom padding not flagged", !rTight.warnings.some((w) => w.includes("empty band")), rTight.warnings);
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/tools/generation.js

@@ -5,7 +5,7 @@
  */
 import { z } from "zod";
 import { sparseTemplate } from "../core/compact.js";
-import { text } from "../mcp/response.js";
+import { text, warningsField } from "../mcp/response.js";
 export function registerGenerationTools(server, domain) {
     // 5) New element ------------------------------------------------------------
     server.tool("new_element", "Returns a default element node for a type in the SPARSE authoring shape (fresh id, both breakpoints' seeded styles, seeded specials). Emit elements exactly like this — fill in specials + top/left coordinates; OMIT properties/runtime/empty events/config (the server hydrates them from factory defaults on validate/persist).", {
@@ -23,7 +23,7 @@ export function registerGenerationTools(server, domain) {
     // 6) New page skeleton ------------------------------------------------------
     server.tool("new_page_skeleton", "Returns an empty but complete top-level page source { page:[], popup:[], settings:{...defaults}, options:{...}, cartConfigs:{} } matching the real editor shape.", { mobileOnly: z.boolean().optional().describe("true if the page renders mobile-only.") }, { title: "New Page Skeleton", readOnlyHint: true, openWorldHint: false }, async ({ mobileOnly }) => text(domain.createPageSource({ mobileOnly: mobileOnly ?? false })));
     // 7) Validate page ----------------------------------------------------------
-    server.tool("validate_page", "Validates a 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 (blocking) and warnings (advisory).", {
+    server.tool("validate_page", "Validates a 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 (blocking — fix before persisting) and warnings (visible design defects — fix these too and re-validate to an empty list; only a demonstrably false positive may remain).", {
         page: z
             .any()
             .describe("The page source object { page:[...], settings:{} } OR a JSON string of it."),
@@ -31,6 +31,6 @@ export function registerGenerationTools(server, domain) {
         // Hydrate sparse nodes (the model may omit boilerplate) before validating,
         // so what we check is the same full tree that create_page/add_section persist.
         const result = domain.validate(domain.expand(page));
-        return text(result);
+        return text({ ...result, ...warningsField(result.warnings) });
     });
 }

package/dist/tools/persistence.js

@@ -10,7 +10,7 @@
  * hosted server is multi-user; in stdio/single-user mode they come from env.
  */
 import { z } from "zod";
-import { text } from "../mcp/response.js";
+import { text, warningsField } from "../mcp/response.js";
 import { readConfig, configFromHeaders } from "../persistence/config.js";
 import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, buildPublishRequestRedacted, buildPageApp, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, publishPage, toPreviewUrl, } from "../persistence/webcake-client.js";
 import { putDraft, getDraft, updateDraft, deleteDraft } from "../persistence/draft-cache.js";
@@ -102,7 +102,7 @@ export function registerPersistenceTools(server, domain) {
                 created: false,
                 reason: "validation_failed",
                 errors: result.errors,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 draft_id: existingDraftId,
                 hint: "Do NOT rebuild the whole source — it is cached as draft_id. Fix ONLY the listed elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged tree and creates the page. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements/get_element if unsure of the exact type name). The draft expires in ~30 min.",
             });
@@ -143,7 +143,7 @@ export function registerPersistenceTools(server, domain) {
             }
             return text({
                 dry_run: true,
-                validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                 ...(largePageAdvisory ? { large_page_advisory: largePageAdvisory } : {}),
                 env_ready: missing.length === 0,
                 missing_env: missing,
@@ -241,7 +241,7 @@ export function registerPersistenceTools(server, domain) {
             return text({
                 created: true,
                 ...outcome,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 ...(organizationAutoSelected ? { organization_auto_selected: true } : {}),
                 ...(organizationNote ? { note: organizationNote } : {}),
             });
@@ -251,7 +251,7 @@ export function registerPersistenceTools(server, domain) {
         return text({
             created: false,
             ...outcome,
-            warnings: result.warnings,
+            ...warningsField(result.warnings),
             draft_id: existingDraftId,
             hint: `Create failed — source is cached. Retry via create_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ draft_id: "${existingDraftId}", patches:[…], dry_run:false }). The draft expires in ~30 min.`,
         });
@@ -392,7 +392,7 @@ export function registerPersistenceTools(server, domain) {
                 updated: false,
                 reason: "validation_failed",
                 errors: result.errors,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 draft_id: existingDraftId,
                 hint: `Fix the errors, then retry update_page({ draft_id: "${existingDraftId}", dry_run:false }) — no need to re-send source. Or use patch_page({ page_id: "${resolvedPageId}", patches:[…] }) for surgical fixes.`,
             });
@@ -411,7 +411,7 @@ export function registerPersistenceTools(server, domain) {
             return text({
                 dry_run: true,
                 page_id: resolvedPageId,
-                validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                 env_ready: missing.length === 0,
                 missing_env: missing,
                 draft_id: existingDraftId,
@@ -433,13 +433,13 @@ export function registerPersistenceTools(server, domain) {
         const outcome = await updatePageSource(config, resolvedPageId, parsed);
         if (outcome.ok) {
             deleteDraft(existingDraftId);
-            return text({ updated: true, ...outcome, warnings: result.warnings });
+            return text({ updated: true, ...outcome, ...warningsField(result.warnings) });
         }
         updateDraft(existingDraftId, expanded);
         return text({
             updated: false,
             ...outcome,
-            warnings: result.warnings,
+            ...warningsField(result.warnings),
             draft_id: existingDraftId,
             hint: `Update failed — source is cached. Retry via update_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ page_id: "${resolvedPageId}", patches:[…] }). The draft expires in ~30 min.`,
         });
@@ -569,7 +569,7 @@ export function registerPersistenceTools(server, domain) {
                 added: false,
                 reason: "validation_failed",
                 errors: result.errors,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 draft_id: existingDraftId,
                 hint: "Do NOT rebuild the section batch — it is cached as draft_id. Fix ONLY the listed elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged shell and appends the sections. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' }. The draft expires in ~30 min.",
             });
@@ -597,7 +597,7 @@ export function registerPersistenceTools(server, domain) {
                 page_id,
                 sections_added: newSections.length,
                 section_labels: labels,
-                validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                 draft_id: existingDraftId,
                 request: buildAppendRequestRedacted(config, page_id, newSections),
                 note: "The backend appends these to the END of `page` and rejects duplicate element ids across the live tree.",
@@ -632,7 +632,7 @@ export function registerPersistenceTools(server, domain) {
                 preview_url: outcome.preview_url,
                 status: outcome.status,
                 error: outcome.error,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 ...(outcome.ok ? {} : {
                     draft_id: existingDraftId,
                     hint: "Append failed — the section batch is still cached. Fix the listed error (e.g. a duplicate id vs the live tree can be changed via patch_page({ draft_id, patches:[{op:'replace',id:'<old-id>',element:{…,id:'<new-id>'}}] })) then retry add_section({ page_id, draft_id, dry_run:false }).",
@@ -669,7 +669,7 @@ export function registerPersistenceTools(server, domain) {
                 added: false,
                 reason: "validation_failed",
                 errors: mergedResult.errors,
-                warnings: mergedResult.warnings,
+                ...warningsField(mergedResult.warnings),
                 page_section_count: counts,
                 hint: "Fix the section(s) — duplicate ids vs existing sections are a common cause — then retry.",
             });
@@ -689,7 +689,7 @@ export function registerPersistenceTools(server, domain) {
             preview_url: fbOutcome.preview_url,
             status: fbOutcome.status,
             error: fbOutcome.error,
-            warnings: mergedResult.warnings,
+            ...warningsField(mergedResult.warnings),
         });
     });
     // 14) Patch page (surgical element edit / fix-after-error) -------------------
@@ -928,7 +928,7 @@ export function registerPersistenceTools(server, domain) {
                     patched: false,
                     reason: "validation_failed",
                     errors: result.errors,
-                    warnings: result.warnings,
+                    ...warningsField(result.warnings),
                     patches_applied: applied,
                     draft_id,
                     hint: "Still invalid — fix the remaining errors with another patch_page({ draft_id, patches:[…] }). Your applied fixes are kept in the draft.",
@@ -954,7 +954,7 @@ export function registerPersistenceTools(server, domain) {
                         draft_id,
                         page_id: targetPageId,
                         patches_applied: applied,
-                        validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                        validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                         env_ready: missing.length === 0,
                         missing_env: missing,
                         request: config
@@ -985,7 +985,7 @@ export function registerPersistenceTools(server, domain) {
                     preview_url: outcome.preview_url,
                     status: outcome.status,
                     error: outcome.error,
-                    warnings: result.warnings,
+                    ...warningsField(result.warnings),
                     ...(outcome.ok ? {} : { draft_id, hint: `Append failed — fixes kept in draft. Retry patch_page({ draft_id: "${draft_id}", dry_run:false }) after resolving the error.` }),
                 });
             }
@@ -1008,7 +1008,7 @@ export function registerPersistenceTools(server, domain) {
                         draft_id,
                         page_id: targetPageId,
                         patches_applied: applied,
-                        validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                        validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                         env_ready: missing.length === 0,
                         missing_env: missing,
                         request: config
@@ -1038,7 +1038,7 @@ export function registerPersistenceTools(server, domain) {
                     preview_url: outcome.preview_url,
                     status: outcome.status,
                     error: outcome.error,
-                    warnings: result.warnings,
+                    ...warningsField(result.warnings),
                     ...(outcome.ok ? {} : { draft_id, hint: `Update failed — fixes kept in draft. Retry patch_page({ draft_id: "${draft_id}", dry_run:false }) after resolving the error.` }),
                 });
             }
@@ -1049,7 +1049,7 @@ export function registerPersistenceTools(server, domain) {
                     dry_run: true,
                     draft_id,
                     patches_applied: applied,
-                    validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                    validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                     env_ready: missing.length === 0,
                     missing_env: missing,
                     request: config
@@ -1081,7 +1081,7 @@ export function registerPersistenceTools(server, domain) {
                 preview_url: outcome.preview_url,
                 status: outcome.status,
                 error: outcome.error,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 ...(outcome.ok ? {} : { draft_id, hint: `Create failed — fixes kept in draft. Retry patch_page({ draft_id: "${draft_id}", dry_run:false }) or resolve the error first.` }),
             });
         }
@@ -1091,7 +1091,7 @@ export function registerPersistenceTools(server, domain) {
                 patched: false,
                 reason: "validation_failed",
                 errors: result.errors,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
                 patches_applied: applied,
                 hint: "The edit produced an invalid tree — fix the listed errors in your ops, then retry.",
             });
@@ -1105,7 +1105,7 @@ export function registerPersistenceTools(server, domain) {
                 dry_run: true,
                 page_id,
                 patches_applied: applied,
-                validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
                 draft_id: liveDraftId,
                 request: buildUpdateRequestRedacted(config, page_id, parsed),
                 hint: `Re-run patch_page({ draft_id: "${liveDraftId}", dry_run: false }) — no need to re-send patches. Or re-run with page_id + dry_run:false.`,
@@ -1121,7 +1121,7 @@ export function registerPersistenceTools(server, domain) {
                 editor_url: outcome.editor_url,
                 preview_url: outcome.preview_url,
                 status: outcome.status,
-                warnings: result.warnings,
+                ...warningsField(result.warnings),
             });
         }
         // Network failure / timeout: keep the update draft for retry.
@@ -1132,7 +1132,7 @@ export function registerPersistenceTools(server, domain) {
             page_id: outcome.page_id ?? page_id,
             status: outcome.status,
             error: outcome.error,
-            warnings: result.warnings,
+            ...warningsField(result.warnings),
             draft_id: liveDraftId,
             hint: `Save failed — the patched source is cached. Retry via patch_page({ draft_id: "${liveDraftId}", dry_run: false }) with no patches. The draft expires in ~30 min.`,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.61",
+  "version": "1.0.62",
   "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",