webcake-landing-mcp 1.0.60 → 1.0.62

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.62",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "validate_page now warns when a text-block's estimated rendered height overflows onto a sibling element placed directly below its declared box; the…",
+    "vi": "validate_page nay cảnh báo khi chiều cao render ước tính của text-block tràn xuống phần tử anh em đặt ngay phía dưới khung khai báo; cảnh báo nêu…"
+  },
+  {
+    "v": "1.0.61",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "ingest_html and ingest_url now return a size_hint field ({ height, basis, css? }) on every AST section, providing the desktop section height in px…",
+    "vi": "ingest_html và ingest_url nay trả về trường size_hint ({ height, basis, css? }) trên mỗi section trong AST, cung cấp chiều cao desktop của section…"
+  },
   {
     "v": "1.0.60",
     "d": "11/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New upload_images tool re-hosts up to 20 external image URLs or data: URIs as Webcake-hosted URLs (statics.pancake.vn) by downloading and uploading…",
     "vi": "Công cụ upload_images mới tải lại tối đa 20 URL ảnh ngoài hoặc data: URI thành URL do Webcake lưu trữ (statics.pancake.vn) bằng cách tải về và…"
-  },
-  {
-    "v": "1.0.56",
-    "d": "11/06/2026",
-    "type": "Added",
-    "en": "The expand pipeline now automatically derives styles.background from specials.src for every image-block node; the live published renderer reads only…",
-    "vi": "Pipeline expand nay tự động tính styles.background từ specials.src cho mọi node image-block; renderer trên trang published chỉ đọc…"
-  },
-  {
-    "v": "1.0.55",
-    "d": "10/06/2026",
-    "type": "Fixed",
-    "en": "The install command now correctly locates claude_desktop_config.json on Windows when Claude Desktop was installed from the Microsoft Store: the…",
-    "vi": "Lệnh install nay xác định đúng đường dẫn claude_desktop_config.json trên Windows khi Claude Desktop được cài từ Microsoft Store: bản Store bị…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -141,7 +141,7 @@ WORKFLOW (recommended)
 3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
 3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image (user-supplied or from the reference HTML/URL), upload_images it and use the returned Webcake URL; otherwise call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
 4. Assemble { page, popup, settings, options, cartConfigs }.
-5. Call validate_page and fix every error.
+5. Call validate_page and fix every error AND every warning — warnings are visible defects (text spilling onto the element below, off-canvas boxes, empty bands at a section's bottom, missing field_name, dead event targets), not advisory polish. Re-validate until the warning list is empty; only a demonstrably false positive may remain (tell the user which and why).
 6. To save: call list_organizations. If the account has EXACTLY ONE organization, create_page will auto-select it — no need to ask. If there are MULTIPLE organizations, show them to the user and ask which to use (highlight is_default as the suggested default); pass the chosen organization_id to create_page. If the user explicitly wants to save without any organization, pass organization_id:"personal". Then create_page (dry_run first, then dry_run:false). Note: create_page itself enforces this — it refuses to guess between multiple orgs and returns the org list asking you to pick.
 
 EDITING an existing page
@@ -154,5 +154,6 @@ EDITING an existing page
 
 REFERENCE INPUT (HTML page to clone or adapt)
 - ingest_html(html, detail:'full') / ingest_url(url, detail:'full') returns a richer AST for clone-quality rebuilds: CSS custom-property palette (design tokens by name), background_images from stylesheets (hero/CTA bg images invisible to a plain img scan), per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, gradients, and images as { src, alt } objects. Use detail:'compact' (default) for a quick layout-only reference.
-- Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links. When the ingested page contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), NOT as element soup.
+- SECTION HEIGHTS: every AST section carries size_hint = { height, basis, css? } — the section's desktop height on the 960px canvas (basis:'css' = an explicit height/min-height found in the source, css holds the raw value e.g. "100vh"; basis:'estimate' = content-volume math). Set each rebuilt section's desktop height FROM its size_hint (±15% to fit your actual element placement) instead of the 800px default, so the page's vertical rhythm tracks the source: a 72px header stays a slim bar, a 1200px pricing band stays tall. Mobile is NOT hinted — redo the height per the mobile text math (stacked content is taller).
+- Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links. When the ingested page contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box, NOT as element soup. The full AST hands you the SOURCE for this: section.widgets = [{ hint, html, css? }] — the widget's cleaned outerHTML plus the stylesheet rules that style it. Build the html-box FROM that html verbatim: inline each css rule into the matching elements' style="" attributes (an html-box has no <style> scope), wrap in a root div with width:100%;height:100%;box-sizing:border-box;overflow:hidden, and size the html-box to the widget's box — do NOT re-imagine the widget's markup from the summary fields.
 - Reference images are the user's assets — for BOTH intents (adapt AND clone), re-host every real image URL found in the AST (images, background_images, og_image) via upload_images and reuse it in the matching slot; never hotlink and never replace it with a search_images stock photo. intent='adapt' rewrites TEXT for the user's brand, not the imagery; search_images only fills slots that have no source image.`;

package/dist/domains/landing/instructions.js

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

package/dist/domains/landing/validate.js

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

package/dist/mcp/response.js

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

package/dist/persistence/html-ingest.js

@@ -165,7 +165,16 @@ export function parseHtml(html, detail = "compact") {
         };
     }
     const sectionEls = findSections(body);
-    const sections = sectionEls.map((el) => classifySection(el, detail));
+    const sections = sectionEls.map((el) => {
+        const sec = classifySection(el, detail);
+        sec.size_hint = computeSizeHint(el, sec, styleBlocks);
+        if (detail === "full") {
+            const widgets = detectWidgets(el, styleBlocks);
+            if (widgets.length)
+                sec.widgets = widgets;
+        }
+        return sec;
+    });
     // Brand hints from inline styles (both modes).
     const styleAttrs = [];
     body.querySelectorAll("[style]").forEach((el) => {
@@ -204,25 +213,33 @@ export function parseHtml(html, detail = "compact") {
         ...base,
         gradients: gradients.length ? gradients : undefined,
     };
-    // Size-cap: drop blocks[].body first, then truncate lists.
-    const serialized = JSON.stringify(result);
-    if (serialized.length > FULL_SIZE_CAP) {
-        // Strip block bodies.
+    // Size-cap shedding order: blocks[].body → widgets[].css → lists → widgets
+    // (widget html goes last — it's the clone-fidelity payload of full mode).
+    if (JSON.stringify(result).length > FULL_SIZE_CAP) {
         for (const sec of result.sections) {
-            if (sec.blocks) {
+            if (sec.blocks)
                 for (const blk of sec.blocks)
                     delete blk.body;
+        }
+        if (JSON.stringify(result).length > FULL_SIZE_CAP) {
+            for (const sec of result.sections) {
+                if (sec.widgets)
+                    for (const w of sec.widgets)
+                        delete w.css;
             }
         }
-        const s2 = JSON.stringify(result);
-        if (s2.length > FULL_SIZE_CAP) {
-            // Truncate lists.
+        if (JSON.stringify(result).length > FULL_SIZE_CAP) {
             for (const sec of result.sections) {
                 if (sec.lists && sec.lists.length > 5)
                     sec.lists = sec.lists.slice(0, 5);
             }
             result.truncated = true;
         }
+        if (JSON.stringify(result).length > FULL_SIZE_CAP) {
+            for (const sec of result.sections)
+                delete sec.widgets;
+            result.truncated = true;
+        }
     }
     return result;
 }
@@ -616,6 +633,202 @@ function pickLists(el, _blocks) {
         .filter((t) => t.length > 3 && t.length < 200)
         .slice(0, 15);
 }
+// ─── size hint (desktop section height) ──────────────────────────────────────
+const SIZE_DECL_RE = /(?:^|[;{\s])(min-height|height)\s*:\s*([\d.]+)(px|vh|rem|em)\b/gi;
+const VH_PX = 8; // 1vh ≈ 8px (~800px viewport), so a 100vh hero lands near the editor's 800px default band
+function clamp(v, lo, hi) {
+    return Math.min(hi, Math.max(lo, v));
+}
+/** lines ≈ ceil(chars × fontSize × glyphFactor / width) — same model as the generation guide's text math. */
+function textLines(chars, fontSize, width, factor = 0.55) {
+    if (chars <= 0)
+        return 0;
+    return Math.max(1, Math.ceil((chars * fontSize * factor) / width));
+}
+/** Parse height/min-height declarations out of a CSS declaration string. */
+function sizeDecls(decl) {
+    const out = [];
+    SIZE_DECL_RE.lastIndex = 0;
+    let m;
+    while ((m = SIZE_DECL_RE.exec(decl)) !== null) {
+        const kind = m[1].toLowerCase();
+        const v = parseFloat(m[2]);
+        const unit = m[3].toLowerCase();
+        const px = unit === "px" ? v : unit === "vh" ? v * VH_PX : v * 16; // rem/em ≈ 16px
+        if (px >= 40 && px <= 2400)
+            out.push({ kind, px: Math.round(px), raw: `${m[2]}${unit}` });
+    }
+    return out;
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Explicit height/min-height for a section element: its inline style, plus any
+ * stylesheet rule whose selector mentions the element's #id or one of its
+ * classes (whole-token match — `.hero` doesn't match `.hero-card`). Regex-level
+ * on purpose; full selector matching needs a renderer.
+ */
+function cssSizeDecls(el, styleBlocks) {
+    const out = [];
+    const inline = el.getAttribute("style");
+    if (inline)
+        out.push(...sizeDecls(inline));
+    const id = el.getAttribute("id");
+    const classes = (el.getAttribute("class") ?? "").trim().split(/\s+/).filter(Boolean).slice(0, 4);
+    const tokens = [...(id ? ["#" + id] : []), ...classes.map((c) => "." + c)];
+    if (tokens.length) {
+        const matchers = tokens.map((t) => new RegExp(escapeRe(t) + "(?![\\w-])"));
+        const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+        for (const css of styleBlocks) {
+            ruleRe.lastIndex = 0;
+            let m;
+            while ((m = ruleRe.exec(css)) !== null) {
+                if (matchers.some((re) => re.test(m[1])))
+                    out.push(...sizeDecls(m[2]));
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Content-volume estimate of the section's desktop height (960px canvas,
+ * ~800px content column) so the rebuilt band is proportional to the source
+ * instead of a flat 800px default.
+ */
+function estimateSectionHeight(el, sec) {
+    const role = sec.role;
+    if (role === "header")
+        return 72;
+    if (role === "footer") {
+        const linkRows = Math.ceil((sec.links?.length ?? 0) / 4);
+        return clamp(120 + linkRows * 32 + (sec.paragraphs?.length ?? 0) * 24, 140, 480);
+    }
+    let h = 140; // band padding (top + bottom)
+    if (sec.heading) {
+        const fs = role === "hero" ? 48 : 36;
+        h += textLines(sec.heading.length, fs, 800, 0.6) * Math.round(fs * 1.2) + 20;
+    }
+    if (sec.subheading)
+        h += textLines(sec.subheading.length, 18, 640) * 27 + 16;
+    for (const p of sec.paragraphs ?? [])
+        h += textLines(p.length, 16, 640) * 24 + 12;
+    if (sec.ctas?.length)
+        h += 76;
+    if (sec.form_fields?.length)
+        h += sec.form_fields.length * 64 + 24;
+    // Card/tile rows: full mode carries blocks; compact recounts from the DOM.
+    let cards = sec.blocks?.length ?? 0;
+    if (!cards && (role === "features" || role === "pricing" || role === "testimonials")) {
+        cards = Math.min(countFeatureBlocks(el), 12);
+    }
+    if (cards)
+        h += Math.ceil(cards / 3) * (role === "pricing" ? 420 : 260) + 24;
+    else if (sec.lists?.length)
+        h += sec.lists.length * 30;
+    const imgCount = sec.images?.length ?? 0;
+    if (role === "gallery")
+        h += Math.ceil(imgCount / 3) * 260;
+    else if (role === "hero")
+        h = Math.max(h, imgCount ? 560 : 480);
+    else if (imgCount)
+        h += 320; // a content image alongside/below the text
+    return clamp(Math.round(h / 10) * 10, 160, 1600);
+}
+function computeSizeHint(el, sec, styleBlocks) {
+    const estimate = estimateSectionHeight(el, sec);
+    const decls = cssSizeDecls(el, styleBlocks);
+    const fixed = decls.filter((d) => d.kind === "height").sort((a, b) => b.px - a.px)[0];
+    // An explicit height pins the band; min-height grows with content, so take the larger.
+    if (fixed)
+        return { height: fixed.px, basis: "css", css: fixed.raw };
+    const min = decls.filter((d) => d.kind === "min-height").sort((a, b) => b.px - a.px)[0];
+    if (min)
+        return { height: Math.max(min.px, estimate), basis: "css", css: min.raw };
+    return { height: estimate, basis: "estimate" };
+}
+// ─── full-mode: composite-widget extraction (html-box source) ────────────────
+// Class/id keywords that mark a composite visual the guide rebuilds as ONE
+// html-box. Conservative on purpose — generic words (card, window, slider)
+// over-match ordinary content.
+const WIDGET_HINT_RE = /\b(mockup|phone|device|browser|terminal|console|dashboard|chat|inbox|player)\b/i;
+const WIDGET_HTML_CAP = 8000;
+const WIDGET_CSS_CAP = 4000;
+const MAX_WIDGETS_PER_SECTION = 2;
+/** outerHTML cleaned for html-box reuse: scripts/styles stripped, whitespace collapsed. */
+function cleanWidgetHtml(el) {
+    // Re-parse a copy so removals don't mutate the tree other pickers read.
+    const frag = parse(el.toString(), { lowerCaseTagName: true });
+    frag.querySelectorAll("script, style, noscript").forEach((n) => n.remove());
+    return frag
+        .toString()
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/>\s+</g, "><")
+        .replace(/\s{2,}/g, " ")
+        .trim();
+}
+/** Stylesheet rules whose selector mentions a class/id used inside the widget HTML. */
+function widgetCss(html, styleBlocks) {
+    const tokens = new Set();
+    for (const m of html.matchAll(/class="([^"]+)"/g)) {
+        for (const c of m[1].trim().split(/\s+/))
+            if (c)
+                tokens.add("." + c);
+    }
+    for (const m of html.matchAll(/id="([^"]+)"/g)) {
+        if (m[1].trim())
+            tokens.add("#" + m[1].trim());
+    }
+    if (!tokens.size)
+        return undefined;
+    const matchers = [...tokens].map((t) => new RegExp(escapeRe(t) + "(?![\\w-])"));
+    const parts = [];
+    let total = 0;
+    const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+    for (const css of styleBlocks) {
+        ruleRe.lastIndex = 0;
+        let m;
+        while ((m = ruleRe.exec(css)) !== null) {
+            const sel = m[1].trim();
+            if (!matchers.some((re) => re.test(sel)))
+                continue;
+            const rule = `${sel.replace(/\s+/g, " ")}{${m[2].trim().replace(/\s+/g, " ")}}`;
+            if (total + rule.length > WIDGET_CSS_CAP)
+                return parts.join("");
+            parts.push(rule);
+            total += rule.length;
+        }
+    }
+    return parts.length ? parts.join("") : undefined;
+}
+/**
+ * Find composite-widget candidates inside a section: OUTERMOST descendants
+ * whose class/id matches WIDGET_HINT_RE and that have real internal structure
+ * (≥3 descendant elements). Emits the cleaned HTML + matching CSS so the
+ * model's html-box reproduces the source instead of approximating it.
+ */
+function detectWidgets(el, styleBlocks) {
+    const out = [];
+    const walk = (node) => {
+        for (const k of elementChildren(node)) {
+            if (out.length >= MAX_WIDGETS_PER_SECTION)
+                return;
+            const idCls = (k.getAttribute("id") ?? "") + " " + (k.getAttribute("class") ?? "");
+            const m = idCls.match(WIDGET_HINT_RE);
+            if (m && k.querySelectorAll("*").length >= 3) {
+                const html = cleanWidgetHtml(k);
+                if (html && html.length <= WIDGET_HTML_CAP) {
+                    const css = widgetCss(html, styleBlocks);
+                    out.push(css ? { hint: m[1].toLowerCase(), html, css } : { hint: m[1].toLowerCase(), html });
+                    continue; // outermost only — don't descend into an emitted widget
+                }
+            }
+            walk(k);
+        }
+    };
+    walk(el);
+    return out;
+}
 // ─── color / font helpers ────────────────────────────────────────────────────
 function elText(el) {
     const t = el?.text?.trim();

package/dist/smoke.js

@@ -8,6 +8,7 @@ import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { expandSource } from "./core/expand.js";
 import { compactSource, deepEq, sparseTemplate } from "./core/compact.js";
 import { parseHtml } from "./persistence/html-ingest.js";
+import { warningsField } from "./mcp/response.js";
 import { readConfig, resolveEnv, ENV_NAMES, configFromHeaders } from "./persistence/config.js";
 import { toEditorUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
 import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
@@ -236,6 +237,28 @@ check("ingest: hero image captured", (hero?.images?.length ?? 0) > 0, hero?.imag
 const form = ast.sections.find((s) => s.role === "form");
 check("ingest: form fields captured", (form?.form_fields?.length ?? 0) >= 2, form?.form_fields);
 check("ingest: form submit CTA captured", !!form?.ctas?.[0]?.text?.includes("Place"), form?.ctas);
+console.log("== ingest: size_hint (desktop section heights) ==");
+check("ingest: every section has a size_hint", ast.sections.every((s) => (s.size_hint?.height ?? 0) > 0), ast.sections.map((s) => s.size_hint));
+const headerHint = ast.sections.find((s) => s.role === "header")?.size_hint;
+check("ingest: header size_hint is a slim bar", !!headerHint && headerHint.height <= 120, headerHint);
+const heroHint = ast.sections.find((s) => s.role === "hero")?.size_hint;
+check("ingest: hero size_hint is a tall band", !!heroHint && heroHint.height >= 400, heroHint);
+const footerHint = ast.sections.find((s) => s.role === "footer")?.size_hint;
+check("ingest: footer size_hint shorter than hero", !!footerHint && !!heroHint && footerHint.height < heroHint.height, { footerHint, heroHint });
+const cssHintHtml = `<!DOCTYPE html><html><head><style>
+  .hero { min-height: 100vh; }
+  #promo { height: 560px; }
+</style></head><body>
+  <section class="hero"><h1>Big hero</h1><p>Tagline goes here for the hero band.</p><button>Go</button></section>
+  <section id="promo"><h2>Promo</h2><p>Limited time offer on all plans this week.</p><button>Claim</button></section>
+  <section style="min-height: 75vh"><h2>Inline</h2><p>Inline-styled band with its own height.</p></section>
+</body></html>`;
+const cssAst = parseHtml(cssHintHtml);
+const cssHints = cssAst.sections.map((s) => s.size_hint);
+check("ingest: 100vh class rule → css basis ~800px", cssHints[0]?.basis === "css" && cssHints[0]?.height === 800 && cssHints[0]?.css === "100vh", cssHints[0]);
+check("ingest: explicit px height by #id → css basis exact", cssHints[1]?.basis === "css" && cssHints[1]?.height === 560, cssHints[1]);
+check("ingest: inline min-height vh → css basis", cssHints[2]?.basis === "css" && cssHints[2]?.height === 600, cssHints[2]);
+check("ingest: .hero rule does not leak into #promo", cssHints[1]?.css !== "100vh", cssHints[1]);
 console.log("== ingest: tolerates empty/CSR-shell HTML ==");
 const empty = parseHtml("");
 check("ingest: empty input → warning", (empty.warnings?.length ?? 0) > 0, empty.warnings);
@@ -296,6 +319,27 @@ check("ingest: compact has no blocks", compactAst.sections.every((s) => s.blocks
 check("ingest: compact has no gradients", compactAst.gradients === undefined, compactAst.gradients);
 check("ingest: compact images are plain strings", compactAst.sections.every((s) => !s.images || s.images.every((i) => typeof i === "string")), compactAst.sections.map((s) => s.images));
 check("ingest: default (no detail arg) is compact-compatible", parseHtml(sampleHtml).sections.every((s) => s.blocks === undefined));
+console.log("== ingest: full mode — composite widget extraction (html-box source) ==");
+const widgetHtml = `<!DOCTYPE html><html><head><style>
+  .phone-mockup { width: 320px; border-radius: 24px; background: #111; }
+  .chat-bubble { padding: 8px 12px; border-radius: 12px; background: #f1f1f1; }
+  .chat-bubble.right { background: #0A7C6E; color: #fff; }
+</style></head><body>
+  <section><h1>Talk to us</h1><p>Our assistant answers around the clock for you.</p><button>Start chat</button>
+    <div class="phone-mockup"><div class="screen"><div class="chat-bubble left">Xin chào!</div><div class="chat-bubble right">Chào bạn</div><div class="chat-input">Type a message…</div></div><script>track()</script></div>
+  </section>
+  <section><h2>About</h2><p>Plain prose section with no composite widget at all.</p></section>
+</body></html>`;
+const widgetAst = parseHtml(widgetHtml, "full");
+const wSec = widgetAst.sections[0];
+check("widgets: detected on the mockup section", (wSec?.widgets?.length ?? 0) === 1, wSec?.widgets?.map((w) => w.hint));
+const w0 = wSec?.widgets?.[0];
+check("widgets: hint from class keyword", w0?.hint === "phone" || w0?.hint === "mockup", w0?.hint);
+check("widgets: html keeps inner structure", !!w0?.html.includes("chat-bubble"), w0?.html);
+check("widgets: scripts stripped from html", !(w0?.html ?? "").includes("<script"), w0?.html);
+check("widgets: matching css rules attached", !!w0?.css?.includes(".phone-mockup") && !!w0?.css?.includes(".chat-bubble"), w0?.css);
+check("widgets: none on plain sections", widgetAst.sections[1]?.widgets === undefined, widgetAst.sections[1]);
+check("widgets: compact mode emits none", parseHtml(widgetHtml, "compact").sections.every((s) => s.widgets === undefined));
 console.log("== ingest: nested-grid block detection (depth > 1) ==");
 // section > .grid-wrapper > .card  — blocks must be found even though cards are not direct children
 const nestedGridHtml = `<!DOCTYPE html><html lang="en"><head><title>T</title></head><body>
@@ -921,5 +965,50 @@ console.log("== text-block styles.background warning (gradient-text-fill mode) =
     });
     check("text-block: no styles.background → no gradient-fill warning", !rNoBg2.warnings.some((w) => w.includes("gradient text-fill")), rNoBg2.warnings);
 }
+console.log("== warningsField: warnings ship with the fix-list directive ==");
+{
+    const withW = warningsField(["page[0]: something"]);
+    check("warningsField: non-empty warnings carry warnings_notice", Array.isArray(withW.warnings) && typeof withW.warnings_notice === "string" && withW.warnings_notice.includes("FIX THESE WARNINGS"), withW);
+    check("warningsField: empty list adds nothing", Object.keys(warningsField([])).length === 0 && Object.keys(warningsField(undefined)).length === 0);
+}
+console.log("== validator: wrapped-text collision + trailing dead space ==");
+{
+    const tb = (id, top, height, text, fontSize, extra = {}) => ({
+        id, type: "text-block",
+        responsive: {
+            desktop: { styles: { top, left: 80, width: 560, height, fontSize, ...extra } },
+            mobile: { styles: { top, left: 20, width: 380, height, fontSize: Math.round(fontSize * 0.7), ...extra } },
+        },
+        specials: { text, tag: "p" },
+    });
+    const sect = (children, height = 800) => ({
+        page: [{ id: "csec", type: "section", responsive: { desktop: { styles: { height } }, mobile: { styles: { height } } }, children }],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    const headline = "The challenges every hotel faces today"; // wraps to 2 lines at 40px/560w
+    // 2-line H2 on a 1-line box with the subheading right under the declared box → both checks fire
+    const rClash = validatePage(expandSource(sect([tb("h2", 120, 50, headline, 40), tb("sub", 180, 60, "Guests reach out from everywhere and teams are stretched thin.", 16)]), createElement));
+    check("collision: 2-line H2 over subheading warned (names the victim)", rClash.warnings.some((w) => w.includes("spill onto") && w.includes("children[1]")), rClash.warnings);
+    check("own-box: 2-line H2 on 1-line box no longer slips the one-line slack", rClash.warnings.some((w) => w.includes("children[0]") && w.includes("spill down")), rClash.warnings);
+    // properly sized heading + subheading pushed below the estimated bottom → silent
+    const rOk = validatePage(expandSource(sect([tb("h2", 120, 112, headline, 40), tb("sub", 260, 60, "Guests reach out from everywhere and teams are stretched thin.", 16)]), createElement));
+    check("collision: sized heading + pushed-down subheading → no overlap warning", !rOk.warnings.some((w) => w.includes("spill")), rOk.warnings);
+    // layered background rectangle (declared boxes overlap) must NOT count as a victim
+    const card = {
+        id: "card", type: "group",
+        responsive: { desktop: { styles: { top: 100, left: 80, width: 280, height: 300 } }, mobile: { styles: { top: 100, left: 20, width: 280, height: 300 } } },
+        children: [
+            { id: "bg", type: "rectangle", responsive: { desktop: { styles: { top: 0, left: 0, width: 280, height: 300 } }, mobile: { styles: { top: 0, left: 0, width: 280, height: 300 } } } },
+            tb("title", 24, 30, "Guests who book once and disappear forever", 22, { left: 24, width: 232 }),
+        ],
+    };
+    const rCard = validatePage(expandSource(sect([card]), createElement));
+    check("collision: layered card background is not a victim", !rCard.warnings.some((w) => w.includes("spill onto") && w.includes("rectangle")), rCard.warnings);
+    // trailing dead space: section 900 tall, content ends at 300
+    const rDead = validatePage(expandSource(sect([tb("h2", 200, 100, "Short", 40)], 900), createElement));
+    check("dead space: 600px empty band at section bottom warned", rDead.warnings.some((w) => w.includes("empty band")), rDead.warnings);
+    const rTight = validatePage(expandSource(sect([tb("h2", 200, 100, "Short", 40)], 500), createElement));
+    check("dead space: 200px bottom padding not flagged", !rTight.warnings.some((w) => w.includes("empty band")), rTight.warnings);
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/tools/generation.js

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

package/dist/tools/ingest.js

@@ -24,9 +24,9 @@ import { parseHtml, fetchHtml } from "../persistence/html-ingest.js";
 const detailParam = z
     .enum(["compact", "full"])
     .optional()
-    .describe("Level of detail in the returned AST. 'compact' (default) — backward-compatible ~2-5 KB shape with top colors/fonts from inline styles. 'full' — richer AST: CSS custom-property palette (design tokens by name), background_images from stylesheets, gradients, per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, extended paragraphs, and images as { src, alt } objects. Use 'full' for clone-faithful rebuilds. Image URLs found in the result (images, background_images, og_image) are the user's assets: re-host them via upload_images and reuse them in the generated page for BOTH intents (never hotlink, never replace them with search_images stock photos).");
+    .describe("Level of detail in the returned AST. 'compact' (default) — backward-compatible ~2-5 KB shape with top colors/fonts from inline styles. 'full' — richer AST: CSS custom-property palette (design tokens by name), background_images from stylesheets, gradients, per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, extended paragraphs, images as { src, alt } objects, and per-section widgets = { hint, html, css? } — the cleaned source HTML + matching CSS of composite visuals (phone/device mockup, chat thread, dashboard, browser frame) to rebuild VERBATIM as ONE html-box (inline the css; don't re-imagine the markup). Use 'full' for clone-faithful rebuilds. Image URLs found in the result (images, background_images, og_image) are the user's assets: re-host them via upload_images and reuse them in the generated page for BOTH intents (never hotlink, never replace them with search_images stock photos).");
 export function registerIngestTools(server) {
-    server.tool("ingest_html", "Parses an HTML string into a reference AST: title, description, og_image, language, and sections classified by role (header, hero, features, about, form, cta, gallery, testimonials, pricing, faq, footer, unknown) with headings, subheadings, paragraphs, images, ctas, links, form fields — plus top colors, fonts, CSS custom-property palette, and background_images pulled from both inline styles and <style> blocks. Returns ~2-5KB (compact) or up to ~25KB (full). Use detail:'full' for clone-faithful rebuilds — it adds per-section blocks (cards/tiles/steps), li lists, gradients, and images as { src, alt } objects. Image URLs in the result (images, background_images, og_image) are the user's assets — re-host them via upload_images and reuse them for BOTH intents; use search_images only for slots with no source image.", {
+    server.tool("ingest_html", "Parses an HTML string into a reference AST: title, description, og_image, language, and sections classified by role (header, hero, features, about, form, cta, gallery, testimonials, pricing, faq, footer, unknown) with headings, subheadings, paragraphs, images, ctas, links, form fields, and a size_hint (desktop section height in px — from the source CSS when explicit, else a content-volume estimate; set the rebuilt section's desktop height from it) — plus top colors, fonts, CSS custom-property palette, and background_images pulled from both inline styles and <style> blocks. Returns ~2-5KB (compact) or up to ~25KB (full). Use detail:'full' for clone-faithful rebuilds — it adds per-section blocks (cards/tiles/steps), li lists, gradients, images as { src, alt } objects, and widgets (the source HTML + CSS of composite mockups, to paste into ONE html-box). Image URLs in the result (images, background_images, og_image) are the user's assets — re-host them via upload_images and reuse them for BOTH intents; use search_images only for slots with no source image.", {
         html: z.string().describe("Raw HTML of a page or a section."),
         intent: z
             .enum(["adapt", "clone"])
@@ -34,7 +34,7 @@ export function registerIngestTools(server) {
             .describe("How the caller intends to use the result. 'adapt' (default) — use as a layout reference and rewrite the TEXT for the user's brand (images from the reference are still re-hosted via upload_images and reused). 'clone' — keep text and images close to the original."),
         detail: detailParam,
     }, { title: "Ingest HTML Reference", readOnlyHint: true, openWorldHint: false }, async ({ html, intent, detail }) => text({ intent: intent ?? "adapt", ...parseHtml(html, detail ?? "compact") }));
-    server.tool("ingest_url", "Fetches a public webpage (GET, 10s timeout, 2MB cap) and parses it into the same reference AST as ingest_html. Returns a warning when the page appears client-rendered (empty <body>) so the caller can fall back to a screenshot — Claude can analyze a screenshot natively without this tool. Does not execute JavaScript; sites built with React/Vue/Next.js may return little content. Use detail:'full' for clone-faithful rebuilds — adds CSS palette, background_images, per-section blocks, lists, and images as { src, alt } objects. Image URLs in the result are the user's assets — re-host them via upload_images and reuse them for BOTH intents; use search_images only for slots with no source image.", {
+    server.tool("ingest_url", "Fetches a public webpage (GET, 10s timeout, 2MB cap) and parses it into the same reference AST as ingest_html (including per-section size_hint desktop heights). Returns a warning when the page appears client-rendered (empty <body>) so the caller can fall back to a screenshot — Claude can analyze a screenshot natively without this tool. Does not execute JavaScript; sites built with React/Vue/Next.js may return little content. Use detail:'full' for clone-faithful rebuilds — adds CSS palette, background_images, per-section blocks, lists, images as { src, alt } objects, and widgets (source HTML + CSS of composite mockups for html-box rebuilds). Image URLs in the result are the user's assets — re-host them via upload_images and reuse them for BOTH intents; use search_images only for slots with no source image.", {
         url: z.string().describe("Public HTTP(S) URL of the page to fetch."),
         intent: z
             .enum(["adapt", "clone"])

package/dist/tools/persistence.js

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

package/package.json

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