webcake-landing-mcp 1.0.84 → 1.1.0

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.1.0",
+    "d": "20/06/2026",
+    "type": "Added",
+    "en": "create_page, add_section, and validate_page now apply a deterministic layout auto-fix before validating or saving: off-canvas children are pulled…",
+    "vi": "create_page, add_section và validate_page nay tự động áp dụng một lần auto-fix layout xác định trước khi validate hoặc lưu: các phần tử con nằm…"
+  },
   {
     "v": "1.0.84",
     "d": "17/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "New render_preview tool screenshots a page's /preview/<id> or any public URL and returns a PNG the model can see, enabling a…",
     "vi": "Tool mới render_preview chụp màn hình /preview/<id> của một trang hoặc bất kỳ URL công khai nào và trả về ảnh PNG để model có thể NHÌN THẤY kết quả,…"
-  },
-  {
-    "v": "1.0.79",
-    "d": "15/06/2026",
-    "type": "Changed",
-    "en": "The Privacy Policy served at /privacy is updated with GDPR-style data-category headings, per-category purpose statements, documentation of…",
-    "vi": "Trang Privacy Policy tại /privacy được cập nhật với các tiêu đề phân loại dữ liệu theo chuẩn GDPR, ghi rõ mục đích xử lý từng loại dữ liệu, bổ sung…"
   }
 ]

package/dist/domains/landing/autofix-layout.js

@@ -0,0 +1,231 @@
+/**
+ * Deterministic LAYOUT auto-fix — APPLIES the corrections the validator already
+ * computes, so the dominant build loop "validate → read warnings → patch_page →
+ * re-validate → re-publish" collapses to zero round-trips on the two most common
+ * layout defects:
+ *
+ *   1. Off-canvas boxes — a child whose box runs past the canvas edge is pulled
+ *      back on-canvas (left clamped to [0, canvasW − width]; negative top → 0).
+ *   2. Wrapped-text overlap — a text-block renders height:AUTO from `top` (the
+ *      renderer IGNORES the declared height), so text that wraps to more lines
+ *      than the author assumed spills DOWN onto the element below. The ONLY real
+ *      fix is to MOVE the elements below down — which is exactly what the reflow
+ *      does, measuring the real rendered height with the SAME font metrics
+ *      (estTextHeightPx) the validator warns with. A container is grown to
+ *      contain its reflowed content.
+ *
+ * Runs AFTER expand (on the full hydrated tree) and BEFORE validate/persist, in
+ * the build-a-new-page tools (create_page, add_section, validate_page). It
+ * MUTATES the tree in place and returns a human-readable list of every change so
+ * the correction is transparent — never a silent move. Conservative by design:
+ *  - only ever ADDS vertical whitespace / pulls boxes inward, never removes;
+ *  - skips intentional layering (declared-overlapping boxes — badges, card
+ *    backdrops, image-behind-text) using the validator's own gate;
+ *  - idempotent: a second pass over a fixed tree is a no-op.
+ *
+ * The validator still reports anything autofix can't safely resolve (e.g. a box
+ * wider than the canvas, cross-column card-height mismatches) as warnings.
+ */
+import { estTextHeightPx } from "./text-metrics.js";
+const CANVAS_DESKTOP = 960;
+const CANVAS_MOBILE = 420;
+const DEFAULT_SECTION_HEIGHT = 800;
+const MIN_GAP = 8; // px breathing room kept between a wrapped block and the one below
+const TOL = 1; // px rounding tolerance
+const MAX_FIXES = 40; // cap the reported list so a pathological page can't flood the response
+const BPS = ["desktop", "mobile"];
+/** Coerce a style value (number or "300px"/"300") to a finite number, else undefined. */
+function num(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : undefined;
+    if (typeof v === "string") {
+        const n = parseFloat(v);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+/** Material Symbols / Font Awesome single glyph — one glyph, not wrapping text (skip measuring). */
+function isIconGlyph(rawText) {
+    return (typeof rawText === "string" &&
+        (/\b(material-symbols|material-icons)\b/.test(rawText) || /<i\b[^>]*\bfa-/.test(rawText)));
+}
+function idOf(node) {
+    return typeof node?.id === "string" && node.id ? node.id : node?.type ?? "?";
+}
+/**
+ * Pull one child back on-canvas at a breakpoint (horizontal + negative-top only).
+ * A box WIDER than the canvas can't be clamped without resizing — left for the
+ * validator to warn about.
+ */
+function clampChild(child, bp, canvasW, fixes) {
+    const styles = child?.responsive?.[bp]?.styles;
+    if (!styles || typeof styles !== "object")
+        return;
+    const left = num(styles.left);
+    const width = num(styles.width);
+    const top = num(styles.top);
+    if (left != null && left < -TOL) {
+        styles.left = 0;
+        pushFix(fixes, `"${idOf(child)}" [${bp}]: off-canvas left=${left} → pulled to 0.`);
+    }
+    else if (left != null && width != null && width <= canvasW + TOL && left + width > canvasW + TOL) {
+        const fixed = Math.round(canvasW - width);
+        styles.left = fixed;
+        pushFix(fixes, `"${idOf(child)}" [${bp}]: ran off the right edge (left+width=${left + width} > ${canvasW}) → moved left to ${fixed}.`);
+    }
+    if (top != null && top < -TOL) {
+        styles.top = 0;
+        pushFix(fixes, `"${idOf(child)}" [${bp}]: negative top=${top} → pulled to 0.`);
+    }
+}
+/**
+ * Push siblings DOWN so no element sits inside the spill of a wrapped text-block
+ * above it. Uses ORIGINAL declared boxes to decide intentional layering (skip)
+ * and CURRENT positions + effective heights to decide clearance. Single
+ * top-to-bottom pass: each element's top is resolved once against finalized
+ * priors, so it converges and only moves elements down.
+ */
+function reflowChildren(kids, effH, origH, bp, fixes) {
+    const items = kids
+        .map((k) => {
+        const s = k?.responsive?.[bp]?.styles ?? {};
+        const top = num(s.top);
+        if (top == null)
+            return null;
+        return {
+            k,
+            origTop: top,
+            cur: top,
+            left: num(s.left) ?? 0,
+            w: num(s.width) ?? 0,
+            // The ORIGINAL declared height decides intentional layering — NOT the
+            // height a text-block leaf may have just been resized to (that would
+            // make a too-short box look like it "contains" the element below it).
+            declaredH: origH.get(k) ?? 0,
+            eff: effH.get(k) ?? num(s.height) ?? 0,
+        };
+    })
+        .filter((x) => x != null)
+        .sort((a, b) => a.origTop - b.origTop);
+    for (let i = 0; i < items.length; i++) {
+        const b = items[i];
+        let required = b.cur;
+        for (let j = 0; j < i; j++) {
+            const a = items[j];
+            // intentional layering (badge over rect, image behind text…): the author
+            // declared b inside a's declared box → leave it alone.
+            if (b.origTop < a.origTop + a.declaredH - TOL)
+                continue;
+            // only a sibling in the same horizontal column can be hit by the spill.
+            const intersects = a.left < b.left + b.w - TOL && b.left < a.left + a.w - TOL;
+            if (!intersects)
+                continue;
+            required = Math.max(required, a.cur + a.eff + MIN_GAP);
+        }
+        if (required > b.cur + TOL) {
+            const moved = Math.round(required - b.cur);
+            b.cur = Math.round(required);
+            b.k.responsive[bp].styles.top = b.cur;
+            pushFix(fixes, `"${idOf(b.k)}" [${bp}]: pushed down ${moved}px (top ${b.origTop}→${b.cur}) to clear wrapped text above it.`);
+        }
+    }
+}
+/**
+ * Settle one node's EFFECTIVE rendered height at a breakpoint (post-order):
+ * recurse so child boxes settle first, clamp + reflow this node's direct
+ * children, then grow this node's own height to contain them. Returns the
+ * effective height the PARENT should use for this node when it reflows.
+ */
+function processNode(node, bp, canvasW, pageFont, fixes) {
+    if (!node || typeof node !== "object")
+        return 0;
+    const styles = node?.responsive?.[bp]?.styles ?? {};
+    const ownW = num(styles.width) ?? canvasW;
+    const ownH = num(styles.height);
+    const kids = Array.isArray(node.children) ? node.children.filter((k) => k && typeof k === "object") : [];
+    if (kids.length === 0) {
+        // Leaf: a text-block renders at its measured height regardless of declared
+        // height. Resize the declared box to match (clears the own-box warning) and
+        // report it as the effective height the parent reflows against.
+        if (node.type === "text-block" && !isIconGlyph(node.specials?.text)) {
+            const est = estTextHeightPx(node.specials?.text, styles, pageFont);
+            if (est != null) {
+                const h = num(styles.height);
+                const fs = num(styles.fontSize) ?? 16;
+                if (h != null && est > h + Math.min(fs * 1.4, 24)) {
+                    styles.height = est;
+                    pushFix(fixes, `"${idOf(node)}" [${bp}]: resized height ${h}→${est} to fit wrapped text (real font metrics).`);
+                }
+                return est;
+            }
+        }
+        return ownH ?? 0;
+    }
+    // Capture ORIGINAL declared heights before recursion mutates any (text leaves
+    // get resized to their measured height) — the reflow's layering test needs the
+    // author's intended box, not the corrected one.
+    const origH = new Map();
+    for (const k of kids)
+        origH.set(k, num(k?.responsive?.[bp]?.styles?.height));
+    // 1) post-order: settle each child's effective height first.
+    const eff = new Map();
+    for (const k of kids) {
+        const childCanvasW = num(k?.responsive?.[bp]?.styles?.width) ?? ownW;
+        eff.set(k, processNode(k, bp, childCanvasW, pageFont, fixes));
+    }
+    // 2) pull each child on-canvas (horizontal), then 3) reflow them downward.
+    for (const k of kids)
+        clampChild(k, bp, ownW, fixes);
+    reflowChildren(kids, eff, origH, bp, fixes);
+    // 4) grow this container to contain its (reflowed) children.
+    let maxBottom = 0;
+    for (const k of kids) {
+        const t = num(k?.responsive?.[bp]?.styles?.top) ?? 0;
+        maxBottom = Math.max(maxBottom, t + (eff.get(k) ?? 0));
+    }
+    if (ownH != null && Math.ceil(maxBottom) > ownH + TOL) {
+        const grown = Math.ceil(maxBottom);
+        node.responsive[bp].styles.height = grown;
+        pushFix(fixes, `"${idOf(node)}" [${bp}]: grew height ${ownH}→${grown} to contain its content.`);
+        return grown;
+    }
+    return ownH != null ? ownH : Math.ceil(maxBottom);
+}
+function pushFix(fixes, msg) {
+    if (fixes.length < MAX_FIXES)
+        fixes.push(msg);
+    else if (fixes.length === MAX_FIXES)
+        fixes.push("…(more layout fixes applied — re-fetch with get_page to see the final coordinates).");
+}
+/**
+ * Apply the deterministic layout fixes to a (already-expanded) page source IN
+ * PLACE and return the list of changes. Tolerant — a non-object or a tree with
+ * no fixable defects returns an empty list. The canvas width comes from
+ * settings.width_section (defaults 960/420), the page font from
+ * settings.fontGeneral.
+ */
+export function autofixLayout(source) {
+    if (!source || typeof source !== "object")
+        return [];
+    const fixes = [];
+    const pageFont = source?.settings?.fontGeneral;
+    const ws = source?.settings?.width_section ?? {};
+    const canvasFor = {
+        desktop: num(ws.desktop) ?? CANVAS_DESKTOP,
+        mobile: num(ws.mobile) ?? CANVAS_MOBILE,
+    };
+    const roots = [];
+    for (const key of ["page", "popup"]) {
+        if (Array.isArray(source[key]))
+            roots.push(...source[key]);
+    }
+    for (const top of roots) {
+        if (!top || typeof top !== "object")
+            continue;
+        for (const bp of BPS) {
+            // A top-level section/popup has no top/left to clamp; process its subtree.
+            processNode(top, bp, canvasFor[bp], pageFont, fixes);
+        }
+    }
+    return fixes;
+}

package/dist/domains/landing/index.js

@@ -5,6 +5,7 @@ import { LIBRARY, ELEMENT_TYPES, CONTAINER_TYPES, FIELD_TYPES, createElement } f
 import { createPageSource } from "./page.js";
 import { canvasToPageSource } from "./canvas-to-source.js";
 import { validatePage, coercePage, pageSchema } from "./validate.js";
+import { autofixLayout } from "./autofix-layout.js";
 import { expandSource } from "../../core/expand.js";
 import { compactSource } from "../../core/compact.js";
 /** The payload returned by the get_generation_guide tool. */
@@ -269,5 +270,15 @@ export const landingDomain = {
         }
     },
     schema: pageSchema,
+    // Applies the deterministic layout fixes IN PLACE to an already-expanded tree
+    // (off-canvas clamp + wrapped-text downward reflow) and returns the change log.
+    autofixLayout: (input) => {
+        try {
+            return autofixLayout(input);
+        }
+        catch {
+            return []; // never let a layout-fix corner case block the build
+        }
+    },
     canvasToSource: (canvas, meta) => canvasToPageSource(canvas, meta),
 };

package/dist/mcp/response.js

@@ -42,3 +42,14 @@ export const WARNINGS_NOTICE = "FIX THESE WARNINGS — each one is a visible def
 export function warningsField(warnings) {
     return warnings && warnings.length > 0 ? { warnings, warnings_notice: WARNINGS_NOTICE } : {};
 }
+/**
+ * Directive shipped alongside an auto-fix change list. Unlike warnings, these
+ * defects were ALREADY corrected deterministically on this call (positions /
+ * heights changed in the saved tree), so the model needs no action — just
+ * awareness that coordinates moved.
+ */
+export const AUTO_FIXED_NOTICE = "These layout defects were auto-corrected on this call (off-canvas boxes pulled on-canvas; elements below wrapped text pushed down to clear the spill; containers grown to fit). The new coordinates/heights are what got validated and saved — no action needed. If you re-emit this source later, keep these positions (or re-fetch with get_page) rather than reverting to the originals.";
+/** Spread helper: {} when nothing was auto-fixed, else { auto_fixed, auto_fixed_notice }. */
+export function autoFixedField(autoFixed) {
+    return autoFixed && autoFixed.length > 0 ? { auto_fixed: autoFixed, auto_fixed_notice: AUTO_FIXED_NOTICE } : {};
+}

package/dist/smoke.js

@@ -833,7 +833,7 @@ check("clone: html-box passthrough renames builder classes (ladi-html-code → w
 console.log("== expand: image-block published background derives from specials.src (placeholder seed must not win) ==");
 {
     const mk = (src) => ({
-        page: [{ id: "s", type: "section", responsive: { desktop: { styles: { height: 300 } }, mobile: { styles: { height: 300 } } }, children: [
+        page: [{ id: "lsec1", type: "section", responsive: { desktop: { styles: { height: 300 } }, mobile: { styles: { height: 300 } } }, children: [
                     { id: "im", type: "image-block", responsive: { desktop: { styles: { top: 0, left: 0, width: 100, height: 80 } }, mobile: { styles: { top: 0, left: 0, width: 100, height: 80 } } }, specials: { src } },
                 ] }], popup: [], settings: {}, options: {}, cartConfigs: {},
     });
@@ -1636,14 +1636,14 @@ console.log("== validator: pill/badge label alignment ==");
                 responsive: { desktop: { styles: { height: 400 } }, mobile: { styles: { height: 400 } } },
                 children: [
                     {
-                        id: "pill", type: "rectangle",
+                        id: "pill1", type: "rectangle",
                         responsive: {
                             desktop: { styles: { top: 100, left: 330, width: 300, height: 36, borderRadius: "999px", background: "rgba(59,130,246,0.15)", ...pillOpts } },
                             mobile: { styles: { top: 100, left: 60, width: 300, height: 36, borderRadius: "999px", background: "rgba(59,130,246,0.15)", ...pillOpts } },
                         },
                     },
                     {
-                        id: "label", type: "text-block",
+                        id: "label1", type: "text-block",
                         responsive: {
                             desktop: { styles: { top: textTop, left: textLeft, width: textW, height: 20, fontSize: 14, fontWeight: 600, textAlign: "center", ...textOpts } },
                             mobile: { styles: { top: textTop, left: textLeft - 270, width: textW, height: 20, fontSize: 14, fontWeight: 600, textAlign: "center", ...textOpts } },
@@ -1836,5 +1836,82 @@ console.log("== upload_images: localContentType (ext + magic, pure offline) ==")
     check("isAllowedScreenshotUrl: localhost rejected", !isAllowedScreenshotUrl("http://localhost:5800/preview/1").ok);
     check("isAllowedScreenshotUrl: garbage rejected", !isAllowedScreenshotUrl("not a url").ok);
 }
+console.log("== autofix-layout: clamps off-canvas + reflows wrapped-text overlap (reported, idempotent) ==");
+{
+    // Hero with: a too-short H1 box whose long text WRAPS (renderer height:auto, so
+    // it spills onto the subheading right below), plus an off-canvas CTA. autofix
+    // should push the subheading down and pull the CTA back on-canvas — clearing
+    // the very warnings the validator would otherwise emit.
+    const page = {
+        page: [
+            {
+                id: "heroSec", type: "section",
+                responsive: { desktop: { styles: { height: 400, background: "rgba(17,24,39,1)" } }, mobile: { styles: { height: 400, background: "rgba(17,24,39,1)" } } },
+                children: [
+                    {
+                        id: "head1", type: "text-block",
+                        responsive: {
+                            desktop: { styles: { top: 40, left: 80, width: 300, height: 40, fontSize: 40, fontWeight: "bold", color: "rgba(255,255,255,1)" } },
+                            mobile: { styles: { top: 40, left: 20, width: 380, height: 40, fontSize: 30, fontWeight: "bold", color: "rgba(255,255,255,1)" } },
+                        },
+                        specials: { text: "This headline is intentionally long enough to wrap onto several lines inside a narrow box", tag: "h1" },
+                    },
+                    {
+                        id: "subh1", type: "text-block",
+                        responsive: {
+                            desktop: { styles: { top: 92, left: 80, width: 300, height: 24, fontSize: 16, color: "rgba(255,255,255,1)" } },
+                            mobile: { styles: { top: 92, left: 20, width: 380, height: 24, fontSize: 16, color: "rgba(255,255,255,1)" } },
+                        },
+                        specials: { text: "Short subheading", tag: "p" },
+                    },
+                    {
+                        id: "cta1", type: "button",
+                        responsive: {
+                            desktop: { styles: { top: 320, left: 900, width: 160, height: 44, background: "rgba(246,4,87,1)" } },
+                            mobile: { styles: { top: 320, left: 40, width: 160, height: 44, background: "rgba(246,4,87,1)" } },
+                        },
+                        specials: { text: "Go" },
+                    },
+                ],
+            },
+        ],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi", fontGeneral: "Roboto" },
+    };
+    const expanded = landingDomain.expand(page);
+    const subTopBefore = expanded.page[0].children[1].responsive.desktop.styles.top;
+    const fixes = landingDomain.autofixLayout(expanded);
+    check("autofix: returns a non-empty change list", fixes.length > 0, fixes);
+    const subTopAfter = expanded.page[0].children[1].responsive.desktop.styles.top;
+    check("autofix: pushed the subheading below the wrapped headline", subTopAfter > subTopBefore, { subTopBefore, subTopAfter });
+    const ctaLeftAfter = expanded.page[0].children[2].responsive.desktop.styles.left;
+    check("autofix: pulled the off-canvas CTA on-canvas (left+width ≤ 960)", ctaLeftAfter + 160 <= 960, ctaLeftAfter);
+    const post = validatePage(expanded);
+    check("autofix: result still validates", post.valid, post.errors);
+    check("autofix: cleared the wrapped-text spill + off-canvas warnings", !post.warnings.some((w) => /spill onto|exceeds canvas/.test(w)), post.warnings);
+    // Idempotent: a second pass over the fixed tree changes nothing.
+    const fixes2 = landingDomain.autofixLayout(expanded);
+    check("autofix: idempotent (second pass is a no-op)", fixes2.length === 0, fixes2);
+    // No-op on an already-correct page (the canonical `good` fixture).
+    const cleanFixes = landingDomain.autofixLayout(landingDomain.expand(good));
+    check("autofix: no changes on an already-valid page", cleanFixes.length === 0, cleanFixes);
+    // Intentional layering (a label declared INSIDE a pill rectangle's box) is NOT
+    // treated as an overlap to reflow.
+    const layered = {
+        page: [
+            {
+                id: "lsec1", type: "section",
+                responsive: { desktop: { styles: { height: 300, background: "rgba(255,255,255,1)" } }, mobile: { styles: { height: 300, background: "rgba(255,255,255,1)" } } },
+                children: [
+                    { id: "pill1", type: "rectangle", responsive: { desktop: { styles: { top: 40, left: 80, width: 160, height: 36, background: "rgba(0,88,188,1)", borderRadius: "18px" } }, mobile: { styles: { top: 40, left: 20, width: 160, height: 36, background: "rgba(0,88,188,1)", borderRadius: "18px" } } }, specials: {} },
+                    { id: "label1", type: "text-block", responsive: { desktop: { styles: { top: 48, left: 96, width: 130, height: 20, fontSize: 14, color: "rgba(255,255,255,1)", textAlign: "center" } }, mobile: { styles: { top: 48, left: 36, width: 130, height: 20, fontSize: 14, color: "rgba(255,255,255,1)", textAlign: "center" } } }, specials: { text: "NEW", tag: "span" } },
+                ],
+            },
+        ],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi", fontGeneral: "Roboto" },
+    };
+    const layExp = landingDomain.expand(layered);
+    landingDomain.autofixLayout(layExp);
+    check("autofix: leaves intentional layering (label over pill) in place", layExp.page[0].children[1].responsive.desktop.styles.top === 48, layExp.page[0].children[1].responsive.desktop.styles);
+}
 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, warningsField } from "../mcp/response.js";
+import { text, warningsField, autoFixedField } 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).", {
@@ -32,14 +32,18 @@ export function registerGenerationTools(server, domain) {
             : undefined,
     })));
     // 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 — 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).", {
+    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). FIRST auto-fixes the layout defects that can be resolved deterministically (off-canvas boxes pulled on-canvas; elements below wrapped text pushed down to clear the spill — the same corrections create_page/add_section apply on save) and reports them in auto_fixed. Then 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."),
     }, { title: "Validate Page Source", readOnlyHint: true, openWorldHint: false }, async ({ page }) => {
         // 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, ...warningsField(result.warnings) });
+        const expanded = domain.expand(page);
+        // Apply the same deterministic layout auto-fix create_page/add_section run,
+        // so validate reflects (and reports) the tree that would actually be saved.
+        const autoFixed = domain.autofixLayout?.(expanded) ?? [];
+        const result = domain.validate(expanded);
+        return text({ ...result, ...autoFixedField(autoFixed), ...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, warningsField } from "../mcp/response.js";
+import { text, warningsField, autoFixedField } 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";
@@ -71,7 +71,7 @@ export function registerPersistenceTools(server, domain) {
         return text(await listOrganizations(config));
     });
     // 9) Create page (persist) --------------------------------------------------
-    server.tool("create_page", "Persists a page source to the configured Webcake backend: creates a NEW page, saves the source, then AUTO-PUBLISHES it (builds the rendered app on the build host + publishes via the editor's publish_html route) so the preview renders immediately — set publish:false to skip, and note the no-domain preview link still expires ~10 minutes after each publish (publish_page with custom_domain gives a permanent URL). A failed auto-publish never fails the create (result.publish says how to retry). Validates first. DEFAULTS to dry_run=true (validates, caches the source as draft_id, returns the HTTP request it WOULD send, token masked); dry_run=false to actually create. Accepts draft_id from a previous call (validation failure, dry_run, or a timed-out create) — re-runs from the cached source without re-sending the full JSON. Organization resolution on the real run (dry_run=false): (1) explicit organization_id wins; pass the string 'personal' to save without any org. (2) WEBCAKE_ORG_ID env / x-webcake-org-id header wins. (3) Otherwise list_organizations is called: 0 orgs or lookup fails → personal (no org); exactly 1 org → used automatically (result includes organization_auto_selected:true); 2+ orgs → returns ok:false with the org list and asks the caller to re-call with organization_id. Real writes need WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+    server.tool("create_page", "Persists a page source to the configured Webcake backend: creates a NEW page, saves the source, then AUTO-PUBLISHES it (builds the rendered app on the build host + publishes via the editor's publish_html route) so the preview renders immediately — set publish:false to skip, and note the no-domain preview link still expires ~10 minutes after each publish (publish_page with custom_domain gives a permanent URL). A failed auto-publish never fails the create (result.publish says how to retry). Auto-fixes the deterministically-resolvable layout defects first (off-canvas boxes pulled on-canvas; elements below wrapped text pushed down to clear the spill; containers grown to fit) and reports them in auto_fixed — so the saved tree is corrected without a patch round-trip. Then validates. DEFAULTS to dry_run=true (validates, caches the source as draft_id, returns the HTTP request it WOULD send, token masked); dry_run=false to actually create. Accepts draft_id from a previous call (validation failure, dry_run, or a timed-out create) — re-runs from the cached source without re-sending the full JSON. Organization resolution on the real run (dry_run=false): (1) explicit organization_id wins; pass the string 'personal' to save without any org. (2) WEBCAKE_ORG_ID env / x-webcake-org-id header wins. (3) Otherwise list_organizations is called: 0 orgs or lookup fails → personal (no org); exactly 1 org → used automatically (result includes organization_auto_selected:true); 2+ orgs → returns ok:false with the org list and asks the caller to re-call with organization_id. Real writes need WEBCAKE_API_BASE + WEBCAKE_JWT.", {
         source: z
             .any()
             .optional()
@@ -131,6 +131,11 @@ export function registerPersistenceTools(server, domain) {
         // On dry_run, use the explicit arg or the draft's stored org (if any).
         const draftOrgId = cachedDraft?.organization_id;
         const orgId = explicitOrgId ?? draftOrgId;
+        // Deterministic layout auto-fix (off-canvas clamp + wrapped-text reflow)
+        // BEFORE validate/persist, so the saved tree is the corrected one and the
+        // dominant validate→patch→re-validate loop is skipped for those defects.
+        // Mutates `expanded` in place — the draft cached below is the fixed tree.
+        const autoFixed = domain.autofixLayout?.(expanded) ?? [];
         const result = domain.validate(expanded);
         if (!result.valid) {
             // Cache the failed source so the model can fix ONLY the broken elements via
@@ -146,6 +151,7 @@ export function registerPersistenceTools(server, domain) {
                 created: false,
                 reason: "validation_failed",
                 errors: result.errors,
+                ...autoFixedField(autoFixed),
                 ...warningsField(result.warnings),
                 draft_id: existingDraftId,
                 hint: "Do NOT rebuild the whole source — it is cached as draft_id. Each error names the offending element id — fix ONLY those 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). A stray/extra key ('must NOT have additional properties') → { op:'replace', id, element:<clean node> } — op:'update' MERGES and cannot delete a key. The draft expires in ~2 h.",
@@ -188,6 +194,7 @@ export function registerPersistenceTools(server, domain) {
             return text({
                 dry_run: true,
                 validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
+                ...autoFixedField(autoFixed),
                 ...(largePageAdvisory ? { large_page_advisory: largePageAdvisory } : {}),
                 env_ready: missing.length === 0,
                 missing_env: missing,
@@ -296,6 +303,7 @@ export function registerPersistenceTools(server, domain) {
                 created: true,
                 ...outcome,
                 publish: publishOutcome,
+                ...autoFixedField(autoFixed),
                 ...warningsField(result.warnings),
                 ...(organizationAutoSelected ? { organization_auto_selected: true } : {}),
                 ...(organizationNote ? { note: organizationNote } : {}),
@@ -610,6 +618,9 @@ export function registerPersistenceTools(server, domain) {
             };
             expandedShell = domain.expand(shell);
         }
+        // Same deterministic layout auto-fix as create_page, on the section shell
+        // (off-canvas clamp + wrapped-text reflow) before validate/append.
+        const autoFixed = domain.autofixLayout?.(expandedShell) ?? [];
         const newSections = Array.isArray(expandedShell?.page) ? expandedShell.page : [];
         const labels = newSections.map(sectionLabel);
         // Light validation: the append path does NOT fetch the live tree, so validate
@@ -633,6 +644,7 @@ export function registerPersistenceTools(server, domain) {
                 added: false,
                 reason: "validation_failed",
                 errors: result.errors,
+                ...autoFixedField(autoFixed),
                 ...warningsField(result.warnings),
                 draft_id: existingDraftId,
                 hint: "Do NOT rebuild the section batch — it is cached as draft_id. Each error names the offending element id — fix ONLY those 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>' }. A stray/extra key ('must NOT have additional properties') → { op:'replace', id, element:<clean node> } — op:'update' MERGES and cannot delete a key. The draft expires in ~2 h.",
@@ -662,6 +674,7 @@ export function registerPersistenceTools(server, domain) {
                 sections_added: newSections.length,
                 section_labels: labels,
                 validation: { valid: true, ...warningsField(result.warnings), stats: result.stats },
+                ...autoFixedField(autoFixed),
                 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.",
@@ -697,6 +710,7 @@ export function registerPersistenceTools(server, domain) {
                 status: outcome.status,
                 error: outcome.error,
                 ...(outcome.rehost ? { rehost: outcome.rehost } : {}),
+                ...autoFixedField(autoFixed),
                 ...warningsField(result.warnings),
                 ...(outcome.ok ? {} : {
                     draft_id: existingDraftId,

package/package.json

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