webcake-landing-mcp 1.0.84 → 1.2.0

package/README.md

@@ -172,7 +172,7 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 |-------|---------------|
 | **[Connect your IDE / claude.ai](docs/connect-mcp.md)** | Step-by-step connection for every client (npx & hosted URL), troubleshooting table. |
 | **[Configuration](docs/configuration.md)** | Env vars, `--env` presets, browser `login`, per-request headers, getting a JWT. |
-| **[Tools reference](docs/tools.md)** | All 22 tools in detail + the step-by-step workflow + model notes. |
+| **[Tools reference](docs/tools.md)** | All 23 tools in detail + the step-by-step workflow + model notes. |
 | **[Usage examples](docs/usage-examples.md)** | Three end-to-end walkthroughs: build from a brief, surgical edit, inspect a type. |
 | **[Manual / advanced install](docs/manual-install.md)** | Shell installers, cloned builds, hand-written per-IDE config. |
 | **[Page-element schema](docs/page-element-schema.md)** | The full element-model reference (+ [every special/event](docs/element-specials-reference.md)). |
@@ -181,12 +181,12 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 
 ## 🧰 The tools at a glance
 
-22 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
+23 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
 
 | Group | Tools | Needs |
 |-------|-------|-------|
 | **Reference** | `get_generation_guide` · `list_elements` · `get_element` · `get_page_schema` | nothing |
-| **Generation** | `new_element` · `new_page_skeleton` · `validate_page` | nothing |
+| **Generation** | `new_element` · `new_page_skeleton` · `validate_page` · `layout` (exact centering/row/grid/stack coordinates, both breakpoints) | nothing |
 | **Media** | `search_images` (real Pexels stock photos) · `get_icon_svg` (Material Symbols / Font Awesome icon names → inline SVG via Iconify) · `upload_images` (re-host external images, data: URIs, or local file paths from the user's machine) · `render_preview` (screenshot a page/URL so the model can see + compare it) | nothing |
 | **Ingest** | `ingest_html` · `ingest_url` (recreate an existing page) | nothing |
 | **Persistence** | `list_organizations` · `create_page` · `list_pages` · `find_pages` · `get_page` · `update_page` · `add_section` · `patch_page` · `publish_page` | `WEBCAKE_API_BASE` + `WEBCAKE_JWT` |

package/README.vi.md

@@ -174,12 +174,12 @@ flow `login` qua browser (+ contract backend), và cách lấy JWT bằng tay
 
 ## 🧰 Tool nhìn nhanh
 
-19 tool trong năm nhóm — mô tả đầy đủ ở **[docs/tools.vi.md](docs/tools.vi.md)**:
+20 tool trong năm nhóm — mô tả đầy đủ ở **[docs/tools.vi.md](docs/tools.vi.md)**:
 
 | Nhóm | Tools | Cần gì |
 |------|-------|--------|
 | **Tham chiếu** | `get_generation_guide` · `list_elements` · `get_element` · `get_page_schema` | không cần gì |
-| **Generation** | `new_element` · `new_page_skeleton` · `validate_page` | không cần gì |
+| **Generation** | `new_element` · `new_page_skeleton` · `validate_page` · `layout` | không cần gì |
 | **Media** | `search_images` (ảnh stock Pexels thật) | không cần gì (key riêng tuỳ chọn) |
 | **Ingest** | `ingest_html` · `ingest_url` (tái tạo trang có sẵn) | không cần gì |
 | **Lưu trữ** | `list_organizations` · `create_page` · `list_pages` · `find_pages` · `get_page` · `update_page` · `add_section` · `patch_page` · `publish_page` | `WEBCAKE_API_BASE` + `WEBCAKE_JWT` |

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.2.0",
+    "d": "21/06/2026",
+    "type": "Added",
+    "en": "New layout tool computes exact top/left/width/height coordinates for both breakpoints so the model never hand-calculates left/top (the number-one…",
+    "vi": "Tool mới layout tính toán chính xác tọa độ top/left/width/height cho cả hai breakpoint để model không cần tự tính left/top bằng tay (nguyên nhân…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "The Playwright screenshot engine that backs render_preview's GET /api/render/screenshot route now defaults to JPEG output instead of PNG, reducing…",
     "vi": "Engine chụp màn hình Playwright phục vụ route GET /api/render/screenshot của render_preview nay mặc định xuất ảnh JPEG thay vì PNG, giúp giảm kích…"
-  },
-  {
-    "v": "1.0.80",
-    "d": "16/06/2026",
-    "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,8 @@ 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 { computeLayout } from "./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 +271,18 @@ 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
+        }
+    },
+    // Exact centering/row/grid/stack coordinates for both breakpoints (the math
+    // the guide prescribes), so the model never hand-computes `left`/`top`.
+    computeLayout: (opts) => computeLayout(opts),
     canvasToSource: (canvas, meta) => canvasToPageSource(canvas, meta),
 };

package/dist/domains/landing/instructions.js

@@ -32,7 +32,7 @@ MODEL (essentials):
 - Element: { id, type, properties, responsive:{desktop,mobile:{config,styles}}, specials, children, runtime, events }. Absolute canvas: children carry numeric top/left/width/height (px) per breakpoint (canvas width desktop=960, mobile=420); sections own a height.
 - ELEMENT CATALOG (the FULL menu — all ${ELEMENT_TYPES.length} types; PICK FROM HERE, never rebuild a dedicated type's behavior out of text-blocks/rectangles, and never invent a type; fetch specials + a skeleton via get_element({types:[…]}) for every type you'll use): ${CATALOG_SUMMARY}.
 - COMPACT AUTHORING (emit FEWER tokens — faster, cheaper): the server HYDRATES every element from its type's factory defaults, so OMIT the boilerplate. Send only: id, type, the meaningful responsive.desktop.styles + responsive.mobile.styles (positions/sizes/colors/font — provide BOTH breakpoints), specials (text/src/field_name…), and events ONLY when the element actually has them. You may DROP: properties, runtime, empty events/children, and each breakpoint's config (animation). A full node still works (it's just overlaid on the seed). Applies to create_page, update_page, add_section, patch_page, validate_page — ~halves the JSON you emit per element. The whole loop is sparse: get_element skeletons/examples and new_element already come in this shape (copy them as-is), and get_page returns sources COMPACTED the same way — edit the compacted tree and send it back without re-adding boilerplate.
-- CENTERING (the #1 layout defect — do the math, don't eyeball): to center a box compute left = round((canvas - width)/2) — 960 desktop, 420 mobile. textAlign:center only centers text inside the box, not the box itself. For a row of N items, center the whole row block (startLeft = round((canvas - (N*item + (N-1)*gap))/2)). Keep 0 ≤ left and left+width ≤ canvas on each breakpoint.
+- CENTERING (the #1 layout defect — do the math, don't eyeball): to center a box compute left = round((canvas - width)/2) — 960 desktop, 420 mobile. textAlign:center only centers text inside the box, not the box itself. For a row of N items, center the whole row block (startLeft = round((canvas - (N*item + (N-1)*gap))/2)). SHORTCUT — instead of computing this by hand (or with a script), call layout({ mode:'center'|'row'|'grid'|'stack', items|count+itemWidth+itemHeight, gap, top, … }): it returns the exact top/left/width/height for BOTH breakpoints (row/grid auto-stack into a single column on mobile), which you drop straight into each element's responsive.<bp>.styles. create_page also auto-fixes residual off-canvas/overlap, but layout gets the intended geometry right up front. Keep 0 ≤ left and left+width ≤ canvas on each breakpoint.
 - PAGE MARGIN (one shared axis — fixes the ragged/header-misaligned look): every section AND the header use the SAME column — left edge at 80 desktop / 20 mobile, right edge at 880 / 400 (content width 800 / 380). Header: logo at left=80, CTA right edge at 880 (its left = 880 − width). Never let one band start at left=80 and the next at left=140.
 - PREMIUM CRAFT (read "sang"): generous whitespace (don't cram; ~48–72px above each band's first element, ≥16–24px between elements); clear type scale (H1 40–56 / body 16–18, big jump); ONE accent used sparingly + neutrals; snap spacing to an 8px grid; reuse the same content width / margin / card+button radius across sections.
 - STICKY HEADER: a sticky/fixed header (config.sticky) OVERLAYS the page — it does NOT push sections below it down. Offset the first section's top content DOWN by the header height (~60–72px) so nothing hides behind it, and do NOT duplicate the shop name in both the header and the top of the hero. A non-sticky header stacks normally and needs no offset.
@@ -43,4 +43,4 @@ MODEL (essentials):
 - PREVIEW vs PUBLISH: for review share the EDITOR url (the builder renders the raw source). The editor_url SIGNS THE BROWSER IN automatically (it routes through the builder's /transport with the account token), so it works even when the user isn't logged in — but for the same reason it must go to the PAGE OWNER ONLY, never into anything public. create_page AUTO-PUBLISHES on success (builds the rendered app + publish_html), so a fresh page's preview_url renders right away — but the preview host (preview.localhost:5800 local / staging.webcake.me staging / www.webcake.me prod) only serves it for ~10 MINUTES after the last publish, then shows "Preview page is expired". The EDIT routes (update_page/add_section/patch_page) store source only — after finishing a round of edits, run publish_page({ page_id, dry_run:false }) to rebuild the rendered app (else the preview shows the STALE pre-edit build). ONLY a custom_domain (publish_page({ page_id, custom_domain, dry_run:false })) gives a permanent public URL; without one the page has just the ephemeral preview link — say so and suggest attaching a domain the user already points at Webcake.
 - VISUAL CHECK after saving (do it for every clone/reference build, and whenever the look matters): don't trust the build blind — LOOK at the rendered page and fix what's off. SCREENSHOT IT WITH YOUR OWN CAPABILITY FIRST — if you have a browser/screenshot MCP (e.g. chrome-devtools) or any tool that captures a URL, screenshot the returned preview_url yourself (fresh + unlimited); ONLY if you have none, call render_preview(page_id), which returns a PNG (on a quota/429 it returns ok:false → skip the check that round, never fail the build). Compare your shot to the reference (screenshot the reference URL too when you only have HTML) — section order, colors, spacing, image placement, sizing, text — then patch_page each mismatch by id, re-publish (publish_page), and screenshot again; loop 2–3 rounds. Rebuilding once from a glance lands ~60% similar — the look-and-patch loop is what closes the gap. The no-domain preview only renders ~10 min after the last publish, so shoot promptly and re-publish before re-checking.
 
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, get_icon_svg, upload_images, render_preview, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, layout, search_images, get_icon_svg, upload_images, render_preview, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;

package/dist/domains/landing/layout.js

@@ -0,0 +1,141 @@
+/**
+ * Layout coordinate math — the exact arithmetic the generation guide tells the
+ * model to do by hand ("do the math, don't eyeball `left`; off-center is the #1
+ * defect"), exposed as a deterministic helper so the model gets perfect
+ * coordinates for BOTH breakpoints instead of computing them in its head (or
+ * spinning up an ad-hoc script). Pure functions, no I/O.
+ *
+ * Four patterns cover the vast majority of landing layouts:
+ *  - center : center ONE box on the canvas.
+ *  - row    : N boxes in a horizontally-centered row (desktop) that STACK into a
+ *             single column on mobile (the feature-card / stats / logo-strip case).
+ *  - grid   : N uniform cells in `cols` columns, the block centered; stacks on mobile.
+ *  - stack  : a vertical list down the shared content column, both breakpoints.
+ *
+ * Every result honours the page-margin axis (content column 80..880 desktop /
+ * 20..400 mobile by default) and returns boxes the model drops straight into an
+ * element's responsive.<bp>.styles.
+ */
+import { CANVAS } from "./vocab.js";
+const r = Math.round;
+function resolveItems(opts) {
+    if (Array.isArray(opts.items) && opts.items.length) {
+        return opts.items.map((it) => ({ width: Math.max(0, it.width || 0), height: Math.max(0, it.height || 0) }));
+    }
+    const n = Math.max(1, opts.count ?? 1);
+    const w = Math.max(0, opts.itemWidth ?? 0);
+    const h = Math.max(0, opts.itemHeight ?? 0);
+    return Array.from({ length: n }, () => ({ width: w, height: h }));
+}
+/** Left edge of a `blockW`-wide block on a `canvas`-wide canvas for an alignment. */
+function blockLeft(align, canvas, margin, blockW) {
+    if (align === "left")
+        return margin;
+    if (align === "right")
+        return canvas - margin - blockW;
+    return r((canvas - blockW) / 2);
+}
+/** Stack a list of sizes into a single mobile column; returns boxes + the bottom y. */
+function stackMobile(items, startTop, itemW, left, rowGap) {
+    let y = startTop;
+    return items.map((it) => {
+        const box = { top: r(y), left: r(left), width: r(itemW), height: it.height };
+        y += it.height + rowGap;
+        return box;
+    });
+}
+export function computeLayout(opts) {
+    const notes = [];
+    const items = resolveItems(opts);
+    const gap = opts.gap ?? 24;
+    const rowGap = opts.rowGap ?? gap;
+    const top = opts.top ?? 0;
+    const mobileTop = opts.mobileTop ?? top;
+    const canvasD = opts.canvasDesktop ?? CANVAS.desktopWidth;
+    const canvasM = opts.canvasMobile ?? CANVAS.mobileWidth;
+    const marginD = opts.marginDesktop ?? 80;
+    const marginM = opts.marginMobile ?? 20;
+    const align = opts.align ?? "center";
+    const contentD = canvasD - 2 * marginD;
+    const contentM = canvasM - 2 * marginM;
+    const mobileItemW = Math.min(opts.mobileItemWidth ?? contentM, canvasM - 2 * marginM);
+    let desktop = [];
+    let mobile = [];
+    let summary = "";
+    if (opts.mode === "center") {
+        const it = items[0];
+        const wD = Math.min(it.width, canvasD);
+        desktop = [{ top, left: r((canvasD - wD) / 2), width: wD, height: it.height }];
+        const wM = Math.min(it.width, contentM);
+        mobile = [{ top: mobileTop, left: r((canvasM - wM) / 2), width: wM, height: it.height }];
+        if (wM !== it.width)
+            notes.push(`mobile: width ${it.width}→${wM} to fit the ${contentM}px content column.`);
+        summary = `center 1 box: desktop left ${desktop[0].left} (w ${wD}), mobile left ${mobile[0].left} (w ${wM}).`;
+    }
+    else if (opts.mode === "row") {
+        const blockW = items.reduce((s, it) => s + it.width, 0) + gap * (items.length - 1);
+        let x = blockLeft(align, canvasD, marginD, blockW);
+        desktop = items.map((it) => {
+            const box = { top, left: r(x), width: it.width, height: it.height };
+            x += it.width + gap;
+            return box;
+        });
+        const mLeft = blockLeft(align, canvasM, marginM, mobileItemW);
+        mobile = stackMobile(items, mobileTop, mobileItemW, mLeft, rowGap);
+        if (blockW > contentD)
+            notes.push(`desktop row width ${blockW} exceeds the ${contentD}px content column — shrink the items or gap, or split into fewer per row (use grid).`);
+        summary = `row of ${items.length}: desktop ${align}-aligned from left ${desktop[0].left} to ${desktop[desktop.length - 1].left + desktop[desktop.length - 1].width} at top ${top}; mobile stacked single-column (w ${mobileItemW}) from top ${mobileTop}.`;
+    }
+    else if (opts.mode === "grid") {
+        const n = items.length;
+        const cols = Math.max(1, opts.cols ?? Math.min(n, 3));
+        const cellW = Math.max(...items.map((it) => it.width));
+        const rows = [];
+        for (let i = 0; i < n; i += cols)
+            rows.push(items.slice(i, i + cols));
+        const blockW = cols * cellW + (cols - 1) * gap;
+        const startLeft = blockLeft(align, canvasD, marginD, blockW);
+        let y = top;
+        desktop = [];
+        for (const row of rows) {
+            const rowH = Math.max(...row.map((it) => it.height));
+            row.forEach((it, c) => {
+                desktop.push({ top: r(y), left: r(startLeft + c * (cellW + gap)), width: it.width, height: it.height });
+            });
+            y += rowH + rowGap;
+        }
+        const mLeft = blockLeft(align, canvasM, marginM, mobileItemW);
+        mobile = stackMobile(items, mobileTop, mobileItemW, mLeft, rowGap);
+        if (blockW > contentD)
+            notes.push(`desktop grid width ${blockW} exceeds the ${contentD}px content column — reduce cols, item width, or gap.`);
+        summary = `grid ${cols}×${rows.length} (${n} cells): desktop block from left ${startLeft}, top ${top}; mobile stacked single-column from top ${mobileTop}.`;
+    }
+    else {
+        // stack
+        let yD = top;
+        desktop = items.map((it) => {
+            const wD = Math.min(it.width, canvasD);
+            const left = blockLeft(align, canvasD, marginD, wD);
+            const box = { top: r(yD), left: r(left), width: wD, height: it.height };
+            yD += it.height + rowGap;
+            return box;
+        });
+        let yM = mobileTop;
+        mobile = items.map((it) => {
+            const wM = Math.min(it.width, contentM);
+            const left = blockLeft(align, canvasM, marginM, wM);
+            const box = { top: r(yM), left: r(left), width: wM, height: it.height };
+            yM += it.height + rowGap;
+            return box;
+        });
+        summary = `stack of ${items.length}: desktop ${align}-aligned from top ${top}; mobile from top ${mobileTop}.`;
+    }
+    // Guardrail: anything that lands off-canvas is a bad input — surface it (the
+    // model can adjust, and create_page's autofix will also pull it back).
+    const offEdge = (boxes, canvas) => boxes.some((b) => b.left < 0 || b.left + b.width > canvas);
+    if (offEdge(desktop, canvasD))
+        notes.push(`some desktop boxes fall outside 0..${canvasD} — reduce sizes/gap or change alignment.`);
+    if (offEdge(mobile, canvasM))
+        notes.push(`some mobile boxes fall outside 0..${canvasM}.`);
+    return { desktop, mobile, summary, notes };
+}

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/server.js

@@ -6,10 +6,29 @@
  * To add another domain later: import its `Domain` object and call
  * registerTools(server, otherDomain) — no changes to core or the tool layer.
  */
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { landingDomain } from "./domains/landing/index.js";
 import { registerTools } from "./tools/index.js";
 import { ICON_DATA_URI, ICON_MIME, BRAND } from "./branding.js";
+/**
+ * The published package version, read at runtime from package.json so the MCP
+ * serverInfo.version always matches what npm shipped (no hand-bumped constant to
+ * drift). package.json sits at the package root — one level above dist/ at
+ * runtime and above src/ in the tree — so the same relative URL resolves in both
+ * the compiled build and a checked-out source tree. Falls back to "0.0.0" if it
+ * can't be read (never block startup over a version string). Avoids a JSON import
+ * (the repo deliberately uses readFileSync for runtime JSON — see validate.ts).
+ */
+export function pkgVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 /**
  * Create the MCP server.
  * @param allowLocalFiles Set to false in remote HTTP (serve) mode to prevent
@@ -19,7 +38,7 @@ import { ICON_DATA_URI, ICON_MIME, BRAND } from "./branding.js";
 export function createServer({ allowLocalFiles = true } = {}) {
     const server = new McpServer({
         name: "webcake-landing",
-        version: "1.0.0",
+        version: pkgVersion(),
         // Shown by MCP clients (e.g. the claude.ai connector) instead of a generic
         // globe. icons is per the MCP spec; the data URI keeps it self-contained.
         title: BRAND.title,

package/dist/smoke.js

@@ -3,7 +3,10 @@
  * verify the server's building blocks without a client. Run: npm run smoke
  */
 import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, ELEMENTS, } from "./domains/landing/elements/index.js";
+import { readFileSync } from "node:fs";
 import { landingDomain } from "./domains/landing/index.js";
+import { computeLayout } from "./domains/landing/layout.js";
+import { pkgVersion } from "./server.js";
 import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { expandSource } from "./core/expand.js";
 import { compactSource, deepEq, sparseTemplate } from "./core/compact.js";
@@ -833,7 +836,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 +1639,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 +1839,116 @@ 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("== layout: exact centering/row/grid/stack coordinates (both breakpoints) ==");
+{
+    // center one box: left = round((canvas - w)/2) on each breakpoint.
+    const c = computeLayout({ mode: "center", itemWidth: 300, itemHeight: 80, count: 1 });
+    check("layout center: desktop left = (960-300)/2 = 330", c.desktop[0].left === 330 && c.desktop[0].width === 300, c.desktop[0]);
+    check("layout center: mobile left = (420-300)/2 = 60", c.mobile[0].left === 60 && c.mobile[0].width === 300, c.mobile[0]);
+    // row of 3 (200×150, gap 24, top 100): block 648 centered → startLeft 156.
+    const row = computeLayout({ mode: "row", count: 3, itemWidth: 200, itemHeight: 150, gap: 24, top: 100 });
+    check("layout row: 3 desktop boxes equally spaced from centered start", row.desktop.map((b) => b.left).join(",") === "156,380,604", row.desktop.map((b) => b.left));
+    check("layout row: all desktop tops = 100", row.desktop.every((b) => b.top === 100), row.desktop);
+    check("layout row: mobile stacks single-column (full content width, left 20)", row.mobile.every((b) => b.left === 20 && b.width === 380), row.mobile);
+    check("layout row: mobile tops accumulate height+gap (100, 274, 448)", row.mobile.map((b) => b.top).join(",") === "100,274,448", row.mobile.map((b) => b.top));
+    // grid 2×2 (250×200, gap 24, cols 2): block 524 centered → startLeft 218.
+    const grid = computeLayout({ mode: "grid", count: 4, itemWidth: 250, itemHeight: 200, gap: 24, cols: 2, top: 0 });
+    check("layout grid: row 0 at top 0 (left 218, 492)", grid.desktop[0].top === 0 && grid.desktop[0].left === 218 && grid.desktop[1].left === 492, grid.desktop.slice(0, 2));
+    check("layout grid: row 1 at top 224 (200 + 24 rowGap)", grid.desktop[2].top === 224 && grid.desktop[3].top === 224, grid.desktop.slice(2));
+    // stack (left-aligned at margin 80, cumulative tops with rowGap 24).
+    const stack = computeLayout({ mode: "stack", items: [{ width: 800, height: 60 }, { width: 800, height: 120 }], top: 40, align: "left" });
+    check("layout stack: first at margin 80 / top 40", stack.desktop[0].left === 80 && stack.desktop[0].top === 40, stack.desktop[0]);
+    check("layout stack: second top = 40 + 60 + 24 = 124", stack.desktop[1].top === 124, stack.desktop[1]);
+    // guardrails: an over-wide row is flagged (and would be off-canvas left).
+    const wide = computeLayout({ mode: "row", count: 5, itemWidth: 200, itemHeight: 100, gap: 24 });
+    check("layout: over-wide row produces a note", wide.notes.some((n) => /exceeds|outside/.test(n)), wide.notes);
+    // 1200-canvas + right alignment: block hugs the right margin.
+    const rightWide = computeLayout({ mode: "row", count: 2, itemWidth: 300, itemHeight: 120, gap: 40, canvasDesktop: 1200, align: "right", marginDesktop: 80 });
+    const lastRight = rightWide.desktop[1].left + rightWide.desktop[1].width;
+    check("layout: align right ends at canvas − margin (1200 − 80 = 1120)", lastRight === 1120, { lastRight, desktop: rightWide.desktop });
+}
+console.log("== server: MCP serverInfo.version follows package.json (no hardcoded constant) ==");
+{
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    check("server: pkgVersion() equals package.json version", pkgVersion() === pkg.version, { pkgVersion: pkgVersion(), pkg: pkg.version });
+    check("server: version is semver-shaped", /^\d+\.\d+\.\d+/.test(pkgVersion()), pkgVersion());
+}
 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,50 @@ 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) });
+    });
+    // 7b) Layout coordinates -----------------------------------------------------
+    server.tool("layout", "Computes EXACT on-canvas coordinates (top/left/width/height) for a group of elements, for BOTH breakpoints, following the guide's layout math — so you NEVER hand-compute `left`/`top` (the #1 source of off-center defects) or write a script to do it. Drop the returned boxes straight into each element's responsive.<bp>.styles (results are in the same order you passed items). Four modes: 'center' (one box centered on the canvas); 'row' (N boxes in a horizontally-centered row on desktop that STACK into a single mobile column — feature cards / stats / logo strip); 'grid' (N uniform cells in `cols` columns, block centered; stacks on mobile); 'stack' (a vertical list down the shared content column on both breakpoints). Honours the page-margin axis (content column 80..880 desktop / 20..400 mobile by default). Pure math — no env, no network. `notes` flags off-canvas / over-wide inputs.", {
+        mode: z.enum(["center", "row", "grid", "stack"]).describe("Layout pattern. center=one box; row=horizontal row (stacks on mobile); grid=cols×rows (stacks on mobile); stack=vertical list."),
+        items: z
+            .array(z.object({ width: z.number(), height: z.number() }))
+            .optional()
+            .describe("Explicit per-item sizes in order (row/stack may vary sizes). Provide this OR count+itemWidth+itemHeight."),
+        count: z.number().int().positive().optional().describe("Uniform shortcut: number of identical boxes (use with itemWidth/itemHeight)."),
+        itemWidth: z.number().optional().describe("Uniform item width (with count)."),
+        itemHeight: z.number().optional().describe("Uniform item height (with count)."),
+        gap: z.number().optional().describe("Horizontal gap between row/grid items (px). Default 24."),
+        rowGap: z.number().optional().describe("Vertical gap between grid rows / stacked items (px). Default = gap."),
+        cols: z.number().int().positive().optional().describe("Grid columns. Default min(itemCount, 3)."),
+        top: z.number().optional().describe("Desktop start y inside the section (px). Default 0."),
+        mobileTop: z.number().optional().describe("Mobile start y (px). Default = top."),
+        canvasDesktop: z.number().optional().describe("Desktop canvas width. Default 960 (use 1200 for wide pages)."),
+        canvasMobile: z.number().optional().describe("Mobile canvas width. Default 420 (use 360 to match a narrow design)."),
+        marginDesktop: z.number().optional().describe("Desktop page margin / content inset. Default 80."),
+        marginMobile: z.number().optional().describe("Mobile page margin / content inset. Default 20."),
+        align: z.enum(["center", "left", "right"]).optional().describe("Horizontal alignment of the block within the canvas. Default center."),
+        mobileItemWidth: z.number().optional().describe("Stacked-mobile item width (row/grid). Default = mobile content width."),
+    }, { title: "Compute Layout Coordinates", readOnlyHint: true, openWorldHint: false }, async (opts) => {
+        if (!domain.computeLayout) {
+            return text({ error: "This domain does not provide layout coordinates." });
+        }
+        if (!opts.items?.length && !(opts.count && (opts.itemWidth != null || opts.itemHeight != null))) {
+            return text({
+                error: "Provide either `items` (an array of {width,height}) or `count` + `itemWidth` + `itemHeight`.",
+            });
+        }
+        return text(domain.computeLayout(opts));
     });
 }

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.2.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",