webcake-landing-mcp 1.0.47 → 1.0.49

package/README.md

@@ -443,13 +443,13 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 |------|-------------|
 | `get_generation_guide` | **Read FIRST.** Output shape, coordinate system, event vocabulary, workflow. |
 | `list_elements` | All element types by category (summary + when-to-use + container?). |
-| `get_element` | One type: hints, key `specials`, default skeleton, filled example. |
+| `get_element` | One type (or many at once): hints, key `specials`, a SPARSE skeleton (the exact shape to emit — the server hydrates omitted boilerplate), filled example. |
 | `get_page_schema` | Full JSON Schema (Draft 2020-12) of a page source. |
 
 ### Generation
 | Tool | Description |
 |------|-------------|
-| `new_element` | A structurally-valid default node for a type (fresh id). |
+| `new_element` | A default node for a type (fresh id) in the SPARSE authoring shape — copy it as-is; omitted boilerplate is hydrated server-side. |
 | `new_page_skeleton` | An empty but complete top-level source `{ page, popup, settings, options, cartConfigs }`. |
 | `validate_page` | Structural + semantic validation (ids, event targets, containers, `field_name`). |
 
@@ -465,7 +465,7 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 | `create_page` | Persist a generated source as a new page (source-only). **Defaults to `dry_run=true`.** |
 | `list_pages` | List the account's pages (id, name, organization_id, updated_at) to pick one to edit. |
 | `find_pages` | Search the account's pages by name, domain, and/or page id (AND-combined) to locate one to edit; returns id, name, org, custom/default domain, updated_at. |
-| `get_page` | Fetch an existing page's decoded source tree so you can edit it. |
+| `get_page` | Fetch an existing page's decoded source tree, COMPACTED to the sparse authoring shape (factory-default boilerplate stripped — far fewer tokens; `compact:false` for the raw tree). Edit and send back as-is. |
 | `update_page` | Overwrite an existing page's source with an edited tree. **Defaults to `dry_run=true`.** |
 
 ---

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.49",
+    "d": "10/06/2026",
+    "type": "Changed",
+    "en": "get_page now returns a compacted source by default: factory-default boilerplate (properties, runtime, empty events/children, per-breakpoint config,…",
+    "vi": "get_page nay trả về source đã compacted theo mặc định: các boilerplate theo factory-default (properties, runtime, events/children rỗng, config theo…"
+  },
+  {
+    "v": "1.0.48",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "create_page now caches the expanded source in an in-memory draft store when validation fails and returns a draft_id alongside the validation errors,…",
+    "vi": "create_page nay lưu source đã expand vào bộ nhớ draft khi xác thực thất bại và trả về draft_id kèm theo danh sách lỗi, cho phép agent chỉ sửa các…"
+  },
   {
     "v": "1.0.47",
     "d": "10/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New find_pages tool searches the account's pages by name, domain (matches custom_domain or default_domain), and/or page id (filters are…",
     "vi": "Công cụ find_pages mới tìm kiếm các trang trong tài khoản theo tên, domain (khớp với custom_domain hoặc default_domain), và/hoặc page id (các bộ lọc…"
-  },
-  {
-    "v": "1.0.43",
-    "d": "09/06/2026",
-    "type": "Changed",
-    "en": "The GET / web guide page has refreshed copy throughout: updated page title and meta description, simplified FAQ answers in both English and…",
-    "vi": "Trang hướng dẫn GET / được làm mới toàn bộ nội dung: cập nhật tiêu đề trang và meta description, đơn giản hóa câu trả lời FAQ bằng cả tiếng Anh và…"
-  },
-  {
-    "v": "1.0.42",
-    "d": "09/06/2026",
-    "type": "Fixed",
-    "en": "validate_page now raises an error when a countdown element's specials.language is set to a value outside the eight supported word-values (vietnam,…",
-    "vi": "validate_page nay phát lỗi khi element countdown có specials.language là giá trị nằm ngoài tám word-value được hỗ trợ (vietnam, english, filipino,…"
   }
 ]

package/dist/core/compact.js

@@ -0,0 +1,158 @@
+/**
+ * Full-node compaction (the inverse of ./expand.ts).
+ *
+ * `compactNode` strips from a FULL element node everything that `expandNode`
+ * would re-create identically from the type's factory default: `properties`
+ * keys equal to the seed (movable/sync/default name), `runtime` when it equals
+ * the seed's, empty `events`, empty seed-equal `children`, and each
+ * breakpoint's `config`/`styles` keys whose values match the seed (notloaded +
+ * the default animation block). What remains is the SPARSE authoring shape the
+ * model is asked to emit — so `get_page` can return a compacted tree and the
+ * model sees (and learns to write) sparse nodes instead of boilerplate.
+ *
+ * Invariant (smoke-tested): expand(compact(x)) persists the SAME tree as
+ * expand(x). Compaction only removes data the expansion seed restores.
+ * Unknown types and non-element values pass through untouched.
+ */
+import { base } from "./element.js";
+const STD_KEYS = ["id", "type", "properties", "specials", "runtime", "events", "responsive", "children"];
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+/** JSON-ish deep equality (objects, arrays, primitives — no cycles). */
+export function deepEq(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEq(v, b[i]));
+    }
+    if (isObj(a) && isObj(b)) {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        return ka.length === kb.length && ka.every((k) => deepEq(a[k], b[k]));
+    }
+    return false;
+}
+/** Keys of `input` whose values differ from `seed`'s; undefined when nothing differs. */
+function diffShallow(input, seed) {
+    if (!isObj(input))
+        return undefined;
+    const out = {};
+    const seedObj = isObj(seed) ? seed : {};
+    for (const k of Object.keys(input)) {
+        if (!deepEq(input[k], seedObj[k]))
+            out[k] = input[k];
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Strip from ONE (full) element node everything its factory seed re-creates. */
+export function compactNode(input, createElement) {
+    if (!isObj(input))
+        return input;
+    const type = input.type;
+    if (typeof type !== "string" || type === "")
+        return input;
+    // Seed with the DEFAULT name (no override): a custom properties.name must
+    // survive the diff, because expandNode re-seeds from input.properties.name.
+    let seed;
+    try {
+        seed = createElement(type);
+    }
+    catch {
+        return input;
+    }
+    const out = {};
+    if (typeof input.id === "string")
+        out.id = input.id;
+    out.type = type;
+    const props = diffShallow(input.properties, seed.properties);
+    if (props)
+        out.properties = props;
+    const specials = diffShallow(input.specials, seed.specials);
+    if (specials)
+        out.specials = specials;
+    // runtime/events are replaced WHOLESALE by expandNode when provided, so they
+    // can only be dropped when they equal the seed's (typically {} / []).
+    if (isObj(input.runtime) && !deepEq(input.runtime, seed.runtime))
+        out.runtime = input.runtime;
+    if (Array.isArray(input.events) && !deepEq(input.events, seed.events))
+        out.events = input.events;
+    const responsive = {};
+    for (const bp of ["desktop", "mobile"]) {
+        const inBp = isObj(input.responsive) ? input.responsive[bp] : undefined;
+        if (!isObj(inBp))
+            continue; // absent → expand restores the seed breakpoint
+        const seedBp = seed.responsive[bp];
+        const bpOut = {};
+        const cfg = diffShallow(inBp.config, seedBp.config);
+        if (cfg)
+            bpOut.config = cfg;
+        const sty = diffShallow(inBp.styles, seedBp.styles);
+        if (sty)
+            bpOut.styles = sty;
+        for (const k of Object.keys(inBp)) {
+            if (k === "config" || k === "styles")
+                continue;
+            if (!deepEq(inBp[k], seedBp[k]))
+                bpOut[k] = inBp[k];
+        }
+        if (Object.keys(bpOut).length)
+            responsive[bp] = bpOut;
+    }
+    if (Object.keys(responsive).length)
+        out.responsive = responsive;
+    // children: expandNode falls back to seed.children when omitted, so a
+    // seed-equal children array (e.g. an empty []) can be dropped entirely.
+    if (Array.isArray(input.children) && !deepEq(input.children, seed.children)) {
+        out.children = input.children.map((c) => compactNode(c, createElement));
+    }
+    // carry over any non-standard keys (expandNode round-trips them too).
+    for (const k of Object.keys(input)) {
+        if (!STD_KEYS.includes(k))
+            out[k] = input[k];
+    }
+    return out;
+}
+/**
+ * The sparse AUTHORING TEMPLATE of a factory node — what get_element/new_element
+ * hand the model to copy. Unlike `compactNode` (which diffs against the type's
+ * own seed and so reduces a fresh factory node to nothing), this KEEPS the
+ * seeded meaningful values — styles, specials, non-default config, children —
+ * and drops only the boilerplate the server hydrates on persist: `properties`,
+ * `runtime`, empty `events`, and each breakpoint's base config (notloaded +
+ * the default animation block). Both breakpoints stay visible: the model must
+ * always provide desktop AND mobile styles.
+ */
+export function sparseTemplate(node) {
+    const blank = base();
+    const out = { id: node.id, type: node.type };
+    if (isObj(node.specials) && Object.keys(node.specials).length)
+        out.specials = node.specials;
+    const responsive = {};
+    for (const bp of ["desktop", "mobile"]) {
+        const nBp = node.responsive[bp];
+        const bpOut = {};
+        const cfg = diffShallow(nBp?.config, blank.responsive[bp].config);
+        if (cfg)
+            bpOut.config = cfg;
+        bpOut.styles = isObj(nBp?.styles) ? nBp.styles : {};
+        responsive[bp] = bpOut;
+    }
+    out.responsive = responsive;
+    if (Array.isArray(node.events) && node.events.length)
+        out.events = node.events;
+    if (Array.isArray(node.children))
+        out.children = node.children.map(sparseTemplate);
+    return out;
+}
+/** Compact every node in a page source ({ page, popup, dynamic_pages }). */
+export function compactSource(source, createElement) {
+    if (!isObj(source))
+        return source;
+    const out = { ...source };
+    if (Array.isArray(source.page))
+        out.page = source.page.map((s) => compactNode(s, createElement));
+    if (Array.isArray(source.popup))
+        out.popup = source.popup.map((p) => compactNode(p, createElement));
+    if (Array.isArray(source.dynamic_pages))
+        out.dynamic_pages = source.dynamic_pages.map((p) => compactNode(p, createElement));
+    return out;
+}

package/dist/domains/landing/elements/content.js

@@ -22,15 +22,15 @@ export const CONTENT = [
             el.specials.text = "hello world";
             el.specials.tag = "p";
         },
+        // Examples are in the SPARSE authoring shape — the server hydrates
+        // properties/runtime/events/config from factory defaults on validate/persist.
         example: {
             id: "headline1", type: "text-block",
-            properties: { name: "Headline", movable: true, sync: true },
             responsive: {
-                desktop: { config: {}, styles: { top: 80, left: 180, width: 600, fontSize: 44, fontWeight: "bold", color: "rgba(26,32,44,1)", textAlign: "center" } },
-                mobile: { config: {}, styles: { top: 60, left: 20, width: 380, fontSize: 28, fontWeight: "bold", color: "rgba(26,32,44,1)", textAlign: "center" } },
+                desktop: { styles: { top: 80, left: 180, width: 600, fontSize: 44, fontWeight: "bold", color: "rgba(26,32,44,1)", textAlign: "center" } },
+                mobile: { styles: { top: 60, left: 20, width: 380, fontSize: 28, fontWeight: "bold", color: "rgba(26,32,44,1)", textAlign: "center" } },
             },
             specials: { text: "Bán hàng dễ hơn với Webcake", tag: "h1" },
-            runtime: {}, events: [],
         },
     },
     {
@@ -67,13 +67,11 @@ export const CONTENT = [
         },
         example: {
             id: "hero_img", type: "image-block",
-            properties: { name: "Image Block", movable: true, sync: true },
             responsive: {
-                desktop: { config: {}, styles: { top: 40, left: 540, width: 360, height: 300, position: "absolute" } },
-                mobile: { config: {}, styles: { top: 260, left: 60, width: 300, height: 240, position: "absolute" } },
+                desktop: { styles: { top: 40, left: 540, width: 360, height: 300, position: "absolute" } },
+                mobile: { styles: { top: 260, left: 60, width: 300, height: 240, position: "absolute" } },
             },
             specials: { src: "https://placehold.co/360x300?text=Product", imageCompression: true },
-            runtime: {}, events: [],
         },
     },
     {
@@ -117,12 +115,11 @@ export const CONTENT = [
         },
         example: {
             id: "cta_main", type: "button",
-            properties: { name: "CTA", movable: true, sync: true },
             responsive: {
-                desktop: { config: {}, styles: { top: 300, left: 405, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
-                mobile: { config: {}, styles: { top: 200, left: 135, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
+                desktop: { styles: { top: 300, left: 405, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
+                mobile: { styles: { top: 200, left: 135, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
             },
-            specials: { text: "Đăng ký ngay" }, runtime: {},
+            specials: { text: "Đăng ký ngay" },
             events: [{ id: "ev_cta", type: "click", action: "scroll_to", target: "form_section" }],
         },
     },

package/dist/domains/landing/elements/form.js

@@ -77,15 +77,15 @@ export const FORM = [
             setBox(el, 150, 36);
             el.specials.field_name = `input_${el.id}`;
         },
+        // Examples are in the SPARSE authoring shape — the server hydrates
+        // properties/runtime/events/config from factory defaults on validate/persist.
         example: {
             id: "in_phone", type: "input",
-            properties: { name: "Input", movable: true, sync: true },
             responsive: {
-                desktop: { config: {}, styles: { top: 60, left: 20, width: 360, height: 40 } },
-                mobile: { config: {}, styles: { top: 60, left: 20, width: 360, height: 40 } },
+                desktop: { styles: { top: 60, left: 20, width: 360, height: 40 } },
+                mobile: { styles: { top: 60, left: 20, width: 360, height: 40 } },
             },
             specials: { field_name: "phone", field_placeholder: "Số điện thoại", field_type: "phone", required: true },
-            runtime: {}, events: [],
         },
     },
     {
@@ -127,10 +127,9 @@ export const FORM = [
         },
         example: {
             id: "sel_attend", type: "select",
-            properties: { name: "Select", movable: true, sync: true },
             responsive: {
-                desktop: { config: {}, styles: { top: 0, left: 0, width: 300, height: 44 } },
-                mobile: { config: {}, styles: { top: 0, left: 0, width: 280, height: 44 } },
+                desktop: { styles: { top: 0, left: 0, width: 300, height: 44 } },
+                mobile: { styles: { top: 0, left: 0, width: 280, height: 44 } },
             },
             // options use {id, name} — NOT {label, value}. field_placeholder is required.
             specials: {
@@ -142,7 +141,6 @@ export const FORM = [
                     { id: "opt_no", name: "Rất tiếc, tôi không thể đến" },
                 ],
             },
-            runtime: {}, events: [],
         },
     },
     {

package/dist/domains/landing/elements/layout.js

@@ -133,22 +133,22 @@ export const LAYOUT = [
             el.properties.movable = false;
             setBox(el, 400, 250);
         },
+        // Example is in the SPARSE authoring shape — the server hydrates
+        // properties/runtime/events/config from factory defaults on validate/persist.
         example: {
             id: "popthanks", type: "popup",
-            properties: { name: "Thank you", movable: false, sync: true },
+            properties: { name: "Thank you" },
             responsive: {
-                desktop: { config: {}, styles: { width: 420, height: 220, background: "rgba(255,255,255,1)", borderRadius: "12px" } },
-                mobile: { config: {}, styles: { width: 360, height: 220, background: "rgba(255,255,255,1)", borderRadius: "12px" } },
+                desktop: { styles: { width: 420, height: 220, background: "rgba(255,255,255,1)", borderRadius: "12px" } },
+                mobile: { styles: { width: 360, height: 220, background: "rgba(255,255,255,1)", borderRadius: "12px" } },
             },
-            specials: {}, runtime: {}, events: [],
             children: [
                 { id: "popclose", type: "button",
-                    properties: { name: "Close", movable: true, sync: true },
                     responsive: {
-                        desktop: { config: {}, styles: { top: 150, left: 160, width: 100, height: 40, background: "rgba(76,175,80,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center" } },
-                        mobile: { config: {}, styles: { top: 150, left: 130, width: 100, height: 40, background: "rgba(76,175,80,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center" } },
+                        desktop: { styles: { top: 150, left: 160, width: 100, height: 40, background: "rgba(76,175,80,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center" } },
+                        mobile: { styles: { top: 150, left: 130, width: 100, height: 40, background: "rgba(76,175,80,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center" } },
                     },
-                    specials: { text: "Đóng" }, runtime: {},
+                    specials: { text: "Đóng" },
                     events: [{ id: "ev1", type: "click", action: "close_popup", target: "popthanks" }] },
             ],
         },

package/dist/domains/landing/guide.js

@@ -23,7 +23,7 @@ ELEMENT NODE (every element)
   "specials": { ...type-specific CONTENT... }, "runtime": {}, "events": [],
   "children": [ ... ] }  // children ONLY on container types
 - Cross-cutting config keys apply to EVERY element via the per-breakpoint config (responsive.<bp>.config): sticky/stickyPosition/stickyTop/stickyBottom/stickyLeft/stickyRight/stickyWidth/stickyHeight/stickyUnpinAtSections…, animation, hide, lock. The full per-element specials reference (every renderer-read key, including the rich select/checkbox-group/radio/survey option-object schema) lives in docs/element-specials-reference.md.
-- COMPACT AUTHORING (emit FEWER tokens): the server hydrates each element from its type's factory defaults, so you may OMIT boilerplate — \`properties\`, \`runtime\`, empty \`events\`/\`children\`, and each breakpoint's \`config\` (the default animation). Emit only id, type, the meaningful responsive.<bp>.styles for BOTH breakpoints, specials, and events when present. e.g. { "type":"text-block","id":"h1","responsive":{"desktop":{"styles":{"top":120,"left":80,"width":500,"height":70,"fontSize":48,"color":"rgba(20,30,25,1)"}},"mobile":{"styles":{"top":100,"left":20,"width":380,"height":60,"fontSize":32}}},"specials":{"text":"…"} } hydrates into the full node. A complete node still works.
+- COMPACT AUTHORING (emit FEWER tokens): the server hydrates each element from its type's factory defaults, so you may OMIT boilerplate — \`properties\`, \`runtime\`, empty \`events\`/\`children\`, and each breakpoint's \`config\` (the default animation). Emit only id, type, the meaningful responsive.<bp>.styles for BOTH breakpoints, specials, and events when present. e.g. { "type":"text-block","id":"h1","responsive":{"desktop":{"styles":{"top":120,"left":80,"width":500,"height":70,"fontSize":48,"color":"rgba(20,30,25,1)"}},"mobile":{"styles":{"top":100,"left":20,"width":380,"height":60,"fontSize":32}}},"specials":{"text":"…"} } hydrates into the full node. A complete node still works. The whole loop is sparse: get_element skeletons/examples + new_element already come in this shape (copy them as-is), and get_page returns sources COMPACTED the same way — edit and send back without re-adding boilerplate.
 
 COORDINATE SYSTEM (critical)
 - Absolute-positioning canvas (NOT flexbox). Children carry top/left/width/height in px (numbers).
@@ -138,5 +138,5 @@ EDITING an existing page
 - get_page(page_id) → you get the live { page, popup, settings, ... }. Edit it surgically: change only the elements the user asked for (text/styles/specials/events); keep every other element, its id, and coordinates intact. Never regenerate the whole tree for a small change.
 - SMALL edit → PREFER patch_page(page_id, patches): send ONLY the changed elements by id, not the whole source. Ops — {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merge; op defaults to 'update'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. The MCP fetches the live source, applies the ops, validates the whole tree, and saves. Reserve update_page(page_id, full source) for when you're rewriting most of the page.
 - To add an element: give it a unique id + top/left/width/height, then patch_page({op:'add', parent_id:<section id>, element:<node>}).
-- FIX-AFTER-ERROR: when create_page/update_page/add_section reports validation errors, fix ONLY the offending element ids with patch_page — do not rebuild and re-send the whole source. (If a create failed before any save, create_page a small valid skeleton first to get a page_id, then patch_page/add_section.)
+- FIX-AFTER-ERROR (never rebuild the whole source): when create_page/update_page/add_section reports validation errors, fix ONLY the offending element ids with patch_page. If create_page failed, its error returns a draft_id (source cached) → patch_page({ draft_id, patches, dry_run:false }) fixes + creates the page (a wrong type → { op:'update', id, type:'<allowed type>' }). If update_page/add_section failed, the page has a page_id → patch_page({ page_id, patches }).
 - patch_page/update_page default to dry_run=true (preview); pass dry_run:false to save.`;

package/dist/domains/landing/index.js

@@ -5,6 +5,7 @@ import { LIBRARY, ELEMENT_TYPES, CONTAINER_TYPES, FIELD_TYPES, createElement } f
 import { createPageSource } from "./page.js";
 import { validatePage, coercePage, pageSchema } from "./validate.js";
 import { expandSource } from "../../core/expand.js";
+import { compactSource } from "../../core/compact.js";
 /** The payload returned by the get_generation_guide tool. */
 export const guidePayload = {
     guide: GENERATION_GUIDE,
@@ -36,5 +37,13 @@ export const landingDomain = {
             return input; // bad JSON — let validate report it
         }
     },
+    compact: (input) => {
+        try {
+            return compactSource(coercePage(input), createElement);
+        }
+        catch {
+            return input; // bad JSON — return as-is
+        }
+    },
     schema: pageSchema,
 };

package/dist/domains/landing/instructions.js

@@ -14,14 +14,17 @@ RULES (follow for every 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.
 - 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 (don't rebuild): when create_page / update_page / add_section returns validation errors, the page already saved by then has a page_id — correct ONLY the offending element ids with patch_page (send just those ops), do NOT re-emit the whole source. That avoids re-shipping the large payload that drops the connection. (For a create that failed before any save: create_page a SMALL valid skeleton first to get a page_id, then patch_page / add_section to fill it in.)
+- FIX-AFTER-ERROR (don't rebuild — this is the #1 time-waster): when create_page / update_page / add_section returns validation errors, DO NOT regenerate and re-send the whole source. Send only the fix via patch_page:
+  · create_page failed → its error returns a draft_id (the source is cached server-side). Call patch_page({ draft_id, patches:[…], dry_run:false }) with ops fixing ONLY the listed elements; it re-validates the merged tree and CREATES the page. A wrong element type is the most common error → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements if unsure). The draft keeps your fixes across rounds and expires in ~30 min.
+  · update_page / add_section failed → the page already has a page_id → patch_page({ page_id, patches:[…] }) the offending ids.
+  Either way you ship a tiny diff, not the large payload that drops the connection.
 - Organizations: call list_organizations and ask which to use; default to the is_default org. Endpoints are owner-scoped (only the account's own pages).
 - REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements. (2) HTML string → call ingest_html(html) to get a compact AST. (3) URL → call ingest_url(url) for the same AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts) — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
 
 MODEL (essentials):
 - Top-level: { page:[sections], popup:[popups], dynamic_pages:[], settings:{}, options:{mobileOnly,versionID}, cartConfigs:{isActive:false}, svariations:[] }. Popups are a SEPARATE top-level array, NOT inside page; currency lives in settings.currency (not options). Leave dynamic_pages/svariations as [] for a static page, but keep them on edit round-trips.
 - 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.
-- 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, validate_page — ~halves the JSON you emit per element.
+- 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.
 - 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.

package/dist/persistence/draft-cache.js

@@ -0,0 +1,58 @@
+/**
+ * Tiny in-memory store for page sources that FAILED create_page validation, so the
+ * model can fix ONLY the broken elements (patch_page with a draft_id) instead of
+ * re-emitting the whole source. The create-before-save gap: a failed create has no
+ * page_id to patch against, so we hold the source here keyed by a random draft_id.
+ *
+ * Bounded + TTL'd; a lost draft (process restart, eviction, expiry) just means the
+ * model falls back to re-sending the full source via create_page — never a failure.
+ * Process-global, but draft_ids are random/unguessable AND persisting still uses the
+ * CALLER's own creds, so a draft only ever yields a page in the caller's account.
+ */
+import { randomUUID } from "node:crypto";
+const TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_ENTRIES = 50;
+const store = new Map();
+function sweep(now) {
+    for (const [id, d] of store)
+        if (now - d.created > TTL_MS)
+            store.delete(id);
+    while (store.size > MAX_ENTRIES) {
+        let oldestId;
+        let oldestTs = Infinity;
+        for (const [id, d] of store) {
+            if (d.created < oldestTs) {
+                oldestTs = d.created;
+                oldestId = id;
+            }
+        }
+        if (oldestId)
+            store.delete(oldestId);
+        else
+            break;
+    }
+}
+/** Cache a failed source. Returns the draft_id to hand back to the model. */
+export function putDraft(draft) {
+    const now = Date.now();
+    sweep(now);
+    const id = `draft_${randomUUID().replace(/-/g, "").slice(0, 20)}`;
+    store.set(id, { ...draft, created: now });
+    return id;
+}
+/** Replace a draft's source after applying patches (refreshes its TTL). */
+export function updateDraft(id, source) {
+    const d = store.get(id);
+    if (d) {
+        d.source = source;
+        d.created = Date.now();
+    }
+}
+/** Fetch a live (non-expired) draft, or null if missing/expired. */
+export function getDraft(id) {
+    sweep(Date.now());
+    return store.get(id) ?? null;
+}
+export function deleteDraft(id) {
+    store.delete(id);
+}

package/dist/smoke.js

@@ -5,6 +5,7 @@
 import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, ELEMENTS, } from "./domains/landing/elements/index.js";
 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 { readConfig, resolveEnv, ENV_NAMES } from "./persistence/config.js";
 import { toEditorUrl } from "./persistence/webcake-client.js";
@@ -162,6 +163,35 @@ check("expand preserves provided styles", eTxt.responsive.desktop.styles.fontSiz
 check("expand keeps id/type/specials", eTxt.id === "t_h1" && eTxt.type === "text-block" && eTxt.specials.text === "Sparse hero", eTxt);
 check("expanded sparse page validates", validatePage(exp).valid, validatePage(exp).errors);
 check("expand(full good page) still valid", validatePage(expandSource(good, createElement)).valid);
+console.log("== compact: the inverse of expand (round-trip persists the same tree) ==");
+{
+    const cGood = compactSource(good, createElement);
+    const cBtn = cGood.page[0].children[0];
+    check("compact strips runtime + breakpoint config boilerplate", cBtn.runtime === undefined && cBtn.responsive.desktop.config === undefined, cBtn);
+    check("compact keeps real events", Array.isArray(cBtn.events) && cBtn.events.length === 1, cBtn.events);
+    check("compact keeps only non-default properties (custom name)", deepEq(cBtn.properties, { name: "CTA" }), cBtn.properties);
+    check("compact drops empty popup events/children/specials", cGood.page[1].events === undefined && cGood.page[1].children === undefined && cGood.page[1].specials === undefined, cGood.page[1]);
+    check("round-trip: expand(compact(x)) deep-equals expand(x)", deepEq(expandSource(cGood, createElement), expandSource(good, createElement)));
+    const cmpSparse = compactSource(exp, createElement); // compact(expand(sparse))
+    check("round-trip from sparse: expand(compact(expand(s))) == expand(s)", deepEq(expandSource(cmpSparse, createElement), expandSource(sparse, createElement)));
+    check("compact tolerates unknown types (pass-through)", compactSource({ page: [{ id: "x", type: "nope" }] }, createElement).page[0].id === "x");
+}
+console.log("== sparseTemplate: the authoring shape get_element/new_element hand out ==");
+{
+    const tplText = sparseTemplate(createElement("text-block"));
+    check("template strips properties/runtime/empty events", tplText.properties === undefined && tplText.runtime === undefined && tplText.events === undefined, tplText);
+    check("template keeps seeded styles + specials on BOTH breakpoints", tplText.responsive.desktop.styles.width === 200 && tplText.responsive.mobile.styles.width === 200 && tplText.specials.text === "hello world", tplText);
+    check("template drops base config (notloaded/animation)", tplText.responsive.desktop.config === undefined, tplText.responsive.desktop);
+    const tplList = sparseTemplate(createElement("list-paragraph"));
+    check("template keeps non-default seeded config (list icons)", tplList.responsive.desktop.config?.iconSize === 12, tplList.responsive.desktop.config);
+    check("template keeps container children", Array.isArray(sparseTemplate(createElement("form")).children));
+    const wrapped = {
+        page: [{ id: "tsec", type: "section", responsive: { desktop: { styles: { height: 800 } }, mobile: { styles: { height: 800 } } }, children: [{ ...tplText, id: "ttext" }] }],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    };
+    const tr = validatePage(expandSource(wrapped, createElement));
+    check("template node expands to a valid page", tr.valid, tr.errors);
+}
 console.log("== ingest: parseHtml extracts a compact AST ==");
 const sampleHtml = `<!DOCTYPE html><html lang="en"><head>
   <title>Brew Coffee</title>
@@ -209,10 +239,12 @@ check("ingest: empty input → warning", (empty.warnings?.length ?? 0) > 0, empt
 const csr = parseHtml(`<html><head><title>SPA</title></head><body><div id="root"></div></body></html>`);
 check("ingest: CSR shell → warning", (csr.warnings?.[0] ?? "").includes("client-rendered"), csr.warnings);
 check("ingest: CSR shell → title still extracted", csr.title === "SPA", csr.title);
-console.log("== library: each example validates as a single element subtree ==");
+console.log("== library: each (sparse) example expands to a valid element subtree ==");
 for (const [type, doc] of Object.entries(LIBRARY)) {
     if (!doc.example)
         continue;
+    // Examples are authored SPARSE (the shape the model should emit), so they go
+    // through expand first — the same path validate_page/create_page take.
     const wrapped = {
         page: [
             {
@@ -227,7 +259,7 @@ for (const [type, doc] of Object.entries(LIBRARY)) {
             },
         ],
     };
-    const rr = validatePage(wrapped);
+    const rr = validatePage(expandSource(wrapped, createElement));
     check(`example ${type} valid`, rr.valid, rr.errors);
 }
 console.log("== schema enum stays in sync with LIBRARY (single source of truth) ==");

package/dist/tools/generation.js

@@ -4,17 +4,21 @@
  * the injected Domain.
  */
 import { z } from "zod";
+import { sparseTemplate } from "../core/compact.js";
 import { text } from "../mcp/response.js";
 export function registerGenerationTools(server, domain) {
     // 5) New element ------------------------------------------------------------
-    server.tool("new_element", "Returns a structurally-valid default element node for a type (correct properties/responsive/specials/sizes), with a fresh id. The caller fills in specials + top/left coordinates.", {
+    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).", {
         type: z.string().describe("Element type to create."),
         name: z.string().optional().describe("Optional properties.name override (layer label)."),
     }, { title: "New Element Node", readOnlyHint: true, openWorldHint: false }, async ({ type, name }) => {
         if (!domain.catalog[type]) {
             return text({ error: `Unknown element type "${type}".`, valid_types: domain.elementTypes });
         }
-        return text(domain.createElement(type, name ? { name } : {}));
+        const el = sparseTemplate(domain.createElement(type));
+        if (name)
+            el.properties = { name };
+        return text(el);
     });
     // 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 })));

package/dist/tools/persistence.js

@@ -13,6 +13,7 @@ import { z } from "zod";
 import { text } from "../mcp/response.js";
 import { readConfig, configFromHeaders } from "../persistence/config.js";
 import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, } from "../persistence/webcake-client.js";
+import { putDraft, getDraft, updateDraft, deleteDraft } from "../persistence/draft-cache.js";
 export function registerPersistenceTools(server, domain) {
     // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
     const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
@@ -33,7 +34,7 @@ export function registerPersistenceTools(server, domain) {
     server.tool("create_page", "Persists a page source to the configured Webcake backend: creates a NEW page and saves the source (source-only — opens in the editor where re-saving renders it). Validates first. DEFAULTS to dry_run=true (returns the HTTP request it WOULD send, token masked); dry_run=false to actually create. The page lands in `organization_id` if given; without an org the page is personal (org=null). Real writes need WEBCAKE_API_BASE + WEBCAKE_JWT.", {
         source: z
             .any()
-            .describe("Full page source { page, popup, settings, options, cartConfigs } (object or JSON string)."),
+            .describe("Page source { page, popup, settings, options, cartConfigs } (object or JSON string). Author elements SPARSE — only id, type, responsive.<bp>.styles for BOTH breakpoints, specials, and real events; OMIT properties/runtime/empty events+children/per-breakpoint config — the server hydrates them from factory defaults (a full node also works)."),
         name: z.string().optional().describe("Page name (default 'AI Page')."),
         organization_id: z
             .union([z.string(), z.number()])
@@ -52,12 +53,17 @@ export function registerPersistenceTools(server, domain) {
         const expanded = domain.expand(source);
         const result = domain.validate(expanded);
         if (!result.valid) {
+            // Cache the failed source so the model can fix ONLY the broken elements via
+            // patch_page({ draft_id }) instead of regenerating + re-shipping the whole
+            // source (there is no page_id yet, so patch_page can't target a live page).
+            const draft_id = putDraft({ source: expanded, name: pageName, organization_id: orgId });
             return text({
                 created: false,
                 reason: "validation_failed",
                 errors: result.errors,
                 warnings: result.warnings,
-                hint: "Fix the errors (run validate_page) before creating.",
+                draft_id,
+                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.",
             });
         }
         const parsed = domain.coerce(expanded);
@@ -154,18 +160,32 @@ export function registerPersistenceTools(server, domain) {
         });
     });
     // 11) Get page (read source) ------------------------------------------------
-    server.tool("get_page", "Fetches an existing page's decoded source tree { page, popup, settings, options, cartConfigs } plus name and organization_id. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", { page_id: z.string().describe("The page id (from list_pages or a URL).") }, { title: "Get Webcake Page Source", readOnlyHint: true, openWorldHint: true }, async ({ page_id }, extra) => {
+    server.tool("get_page", "Fetches an existing page's decoded source tree { page, popup, settings, options, cartConfigs } plus name and organization_id. By DEFAULT the source is COMPACTED: boilerplate every element shares (properties/runtime/empty events+children/per-breakpoint config + factory-default style keys) is stripped, leaving the sparse authoring shape — edit it and send it back as-is; update_page/patch_page re-hydrate from factory defaults. Pass compact:false for the raw stored tree. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+        page_id: z.string().describe("The page id (from list_pages or a URL)."),
+        compact: z
+            .boolean()
+            .optional()
+            .describe("Default TRUE — strip factory-default boilerplate from every element (sparse shape, far fewer tokens). false returns the raw stored tree."),
+    }, { title: "Get Webcake Page Source", readOnlyHint: true, openWorldHint: true }, async ({ page_id, compact }, extra) => {
         const { config, missing } = cfgFor(extra);
         if (!config)
             return text({ ok: false, reason: "missing_env", missing_env: missing });
-        return text(await getPageSource(config, page_id));
+        const res = await getPageSource(config, page_id);
+        if (!res.ok || compact === false || res.source == null)
+            return text(res);
+        return text({
+            ...res,
+            source: domain.compact(res.source),
+            compacted: true,
+            note: "Source is COMPACTED (factory-default boilerplate stripped). Edit elements in this same sparse shape — keep ids — and send the edited tree back to update_page (or use patch_page for small edits); the server re-hydrates omitted boilerplate.",
+        });
     });
     // 12) Update page (edit existing) -------------------------------------------
     server.tool("update_page", "Overwrites an EXISTING page's source with an edited tree (source-only; re-render in the editor for preview/publish). Validates first. DEFAULTS to dry_run=true (preview the request, token masked); dry_run=false to actually save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
         page_id: z.string().describe("The page id to update (must be owned by the account)."),
         source: z
             .any()
-            .describe("The full edited page source { page, popup, settings, options, cartConfigs } (object or JSON string)."),
+            .describe("The edited page source { page, popup, settings, options, cartConfigs } (object or JSON string). The compacted tree from get_page can be edited and sent back AS-IS — sparse nodes are re-hydrated from factory defaults (a full tree also works)."),
         dry_run: z.boolean().optional().describe("Default TRUE — preview without sending. Set false to actually save."),
     }, { title: "Update Webcake Page (Overwrite)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, source, dry_run }, extra) => {
         const isDry = dry_run !== false;
@@ -237,7 +257,7 @@ export function registerPersistenceTools(server, domain) {
         page_id: z.string().describe("The page id to append to (from create_page or list_pages; must be owned by the account)."),
         sections: z
             .any()
-            .describe("One section node, or an array of section nodes, to append to the END of `page` (object/array or JSON string). Each is a normal section element { id, type:'section', responsive, children, … } with a UNIQUE id; they stack vertically after the existing sections."),
+            .describe("One section node, or an array of section nodes, to append to the END of `page` (object/array or JSON string). Each is a normal section element { id, type:'section', responsive, children, … } with a UNIQUE id; they stack vertically after the existing sections. Author SPARSE nodes — omit properties/runtime/empty events+children/per-breakpoint config; the server hydrates them from factory defaults."),
         dry_run: z
             .boolean()
             .optional()
@@ -430,48 +450,66 @@ export function registerPersistenceTools(server, domain) {
         }
         return touched;
     };
-    server.tool("patch_page", "Edits an EXISTING page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Send only a list of per-element ops; the MCP fetches the live source, applies them, validates the WHOLE merged tree (blocks on errors), and saves. Ops: {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. Use this to fix the elements a failed create_page/update_page/add_section reported, or to change one element's text/color/position — instead of rebuilding the page. DEFAULTS to dry_run=true (reads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (it reads the live page, so creds are required even on dry_run).", {
-        page_id: z.string().describe("The page id to edit (from create_page, list_pages, or find_pages; must be owned by the account)."),
+    server.tool("patch_page", "Edits a page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Targets EITHER a live page (page_id) OR a cached failed-create source (draft_id, returned by a create_page that failed validation). Send only a list of per-element ops; the MCP loads the source, applies them, validates the WHOLE merged tree (blocks on errors), and saves (update for page_id; create for draft_id). Ops: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'; `type` fixes a wrong element type), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. Use this to fix the elements a failed create_page/update_page/add_section reported (e.g. a bad type → {op:'update',id,type:'button'}) instead of rebuilding the page. DEFAULTS to dry_run=true (loads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (a draft_id patch only needs creds to actually create; a page_id patch reads the live page so needs creds even on dry_run).", {
+        page_id: z.string().optional().describe("Edit a LIVE page by id (from create_page, list_pages, or find_pages; must be owned by the account). Provide page_id OR draft_id."),
+        draft_id: z.string().optional().describe("Fix a CACHED source from a create_page that failed validation (the create_page error returns draft_id). The patched tree is created as a new page once valid. Provide page_id OR draft_id."),
         patches: z
             .any()
-            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container."),
+            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted; set `type` to fix a wrong element type); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container. `element` may be a SPARSE node (id/type/styles/specials/events only) — the server hydrates omitted boilerplate from factory defaults."),
         dry_run: z
             .boolean()
             .optional()
-            .describe("Default TRUE — read, merge, validate and preview the resulting save WITHOUT writing. Set false to actually save."),
-    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, patches, dry_run }, extra) => {
+            .describe("Default TRUE — load, merge, validate and preview the resulting save WITHOUT writing. Set false to actually save."),
+    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, draft_id, patches, dry_run }, extra) => {
         const isDry = dry_run !== false; // default true (safe)
         const ops = asArray(patches).filter((p) => p != null && typeof p === "object");
         if (ops.length === 0) {
             return text({ patched: false, reason: "no_patches", hint: "Pass an op object or a non-empty array of { op, id, … } ops." });
         }
-        // patch_page always reads the live tree (even on dry_run) — needs creds.
-        const { config, missing } = cfgFor(extra);
-        if (!config) {
-            return text({
-                patched: false,
-                reason: "missing_env",
-                missing_env: missing,
-                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
-            });
+        if (!page_id && !draft_id) {
+            return text({ patched: false, reason: "no_target", hint: "Pass page_id (a live page) or draft_id (the cached source from a failed create_page)." });
         }
-        const current = await getPageSource(config, page_id);
-        if (!current.ok || current.source == null) {
-            return text({
-                patched: false,
-                reason: "fetch_failed",
-                status: current.status,
-                error: current.error ?? "Page source not found.",
-                hint: "Check the page_id (find_pages/list_pages) and that the account owns it.",
-            });
+        const { config, missing } = cfgFor(extra);
+        // Resolve the base source: a cached draft (create-before-save), else a live page.
+        let base;
+        const draft = draft_id ? getDraft(draft_id) : null;
+        if (draft_id) {
+            if (!draft) {
+                return text({
+                    patched: false,
+                    reason: "draft_expired",
+                    hint: "The cached draft is gone (expired after ~30 min or evicted). Re-send the full source via create_page.",
+                });
+            }
+            base = draft.source; // already an expanded full tree
         }
-        let base = current.source;
-        if (typeof base === "string") {
-            try {
-                base = JSON.parse(base);
+        else {
+            if (!config) {
+                return text({
+                    patched: false,
+                    reason: "missing_env",
+                    missing_env: missing,
+                    hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
+                });
             }
-            catch {
-                return text({ patched: false, reason: "bad_source", hint: "The stored page source could not be parsed." });
+            const current = await getPageSource(config, page_id);
+            if (!current.ok || current.source == null) {
+                return text({
+                    patched: false,
+                    reason: "fetch_failed",
+                    status: current.status,
+                    error: current.error ?? "Page source not found.",
+                    hint: "Check the page_id (find_pages/list_pages) and that the account owns it.",
+                });
+            }
+            base = current.source;
+            if (typeof base === "string") {
+                try {
+                    base = JSON.parse(base);
+                }
+                catch {
+                    return text({ patched: false, reason: "bad_source", hint: "The stored page source could not be parsed." });
+                }
             }
         }
         const treeRoots = [base.page, base.popup].filter((a) => Array.isArray(a));
@@ -533,6 +571,10 @@ export function registerPersistenceTools(server, domain) {
             else {
                 // update (default)
                 const changed = [];
+                if (typeof p.type === "string" && p.type.trim() !== "") {
+                    hit.node.type = p.type;
+                    changed.push("type");
+                }
                 if (p.specials && typeof p.specials === "object") {
                     hit.node.specials = { ...(hit.node.specials ?? {}), ...p.specials };
                     changed.push("specials");
@@ -564,6 +606,58 @@ export function registerPersistenceTools(server, domain) {
         // Validate the WHOLE merged tree (hydrate sparse replaced/added nodes first).
         const expanded = domain.expand(base);
         const result = domain.validate(expanded);
+        // DRAFT path: the source came from a failed create_page. Keep the applied fixes
+        // cached between rounds; once valid, CREATE the page (no page_id yet).
+        if (draft_id && draft) {
+            if (!result.valid) {
+                updateDraft(draft_id, base); // persist the partial fixes for the next patch round
+                return text({
+                    patched: false,
+                    reason: "validation_failed",
+                    errors: result.errors,
+                    warnings: result.warnings,
+                    patches_applied: applied,
+                    draft_id,
+                    hint: "Still invalid — fix the remaining errors with another patch_page({ draft_id, … }). Your applied fixes are kept in the draft.",
+                });
+            }
+            const parsed = domain.coerce(expanded);
+            if (isDry) {
+                updateDraft(draft_id, base);
+                return text({
+                    dry_run: true,
+                    draft_id,
+                    patches_applied: applied,
+                    validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                    env_ready: missing.length === 0,
+                    missing_env: missing,
+                    request: config
+                        ? buildRequestRedacted(config, draft.name ?? "AI Page", parsed, draft.organization_id)
+                        : { note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT (env) or send the x-webcake-jwt header to enable creation." },
+                    hint: "Draft is now valid. Re-run with dry_run=false to create the page from it.",
+                });
+            }
+            if (!config) {
+                updateDraft(draft_id, base); // keep the now-valid draft so a creds-ready retry can persist it
+                return text({ patched: false, reason: "missing_env", missing_env: missing, hint: "Add WEBCAKE_API_BASE + WEBCAKE_JWT, then retry patch_page({ draft_id, dry_run:false })." });
+            }
+            const outcome = await createPage(config, draft.name ?? "AI Page", parsed, draft.organization_id);
+            if (outcome.ok)
+                deleteDraft(draft_id); // created — drop the draft
+            return text({
+                patched: outcome.ok,
+                created: outcome.ok,
+                from_draft: draft_id,
+                patches_applied: applied,
+                page_id: outcome.page_id,
+                editor_url: outcome.editor_url,
+                preview_url: outcome.preview_url,
+                status: outcome.status,
+                error: outcome.error,
+                warnings: result.warnings,
+            });
+        }
+        // LIVE-PAGE path: edit an existing page (page_id) and update it in place.
         if (!result.valid) {
             return text({
                 patched: false,

package/dist/tools/reference.js

@@ -4,7 +4,9 @@
  * Schema. All driven by the injected Domain, so they work for any domain.
  */
 import { z } from "zod";
+import { sparseTemplate } from "../core/compact.js";
 import { text } from "../mcp/response.js";
+const SPARSE_NOTE = "Skeletons and examples are in the SPARSE authoring shape — emit elements exactly like this (id, type, BOTH breakpoints' styles, specials, real events). OMIT properties/runtime/empty events+children/config: the server hydrates them from factory defaults on validate/persist.";
 export function registerReferenceTools(server, domain) {
     // 1) Generation guide -------------------------------------------------------
     server.tool("get_generation_guide", "Returns the page-building conventions reference: output shape, the absolute-positioning coordinate system, event vocabulary, and the recommended workflow.", { title: "Get Generation Guide", readOnlyHint: true, openWorldHint: false }, async () => text(domain.guide));
@@ -23,7 +25,7 @@ export function registerReferenceTools(server, domain) {
         return text({ total: domain.elementTypes.length, categories: byCategory });
     });
     // 3) Get element ------------------------------------------------------------
-    server.tool("get_element", "Returns detailed usage for one element type — or for many in a single call (BATCH MODE): summary, when to use it, key `specials` fields, a default skeleton node, and (for common types) a filled example. Pass `types: [...]` to fetch a whole section's worth of element types at once (e.g. ['section','text-block','image-block','button']) — returns { elements: { [type]: details } } and saves a round-trip per type. `type` (single) returns the doc directly for backward compatibility.", {
+    server.tool("get_element", "Returns detailed usage for one element type — or for many in a single call (BATCH MODE): summary, when to use it, key `specials` fields, a SPARSE skeleton node (the exact shape to emit — the server hydrates omitted boilerplate), and (for common types) a filled example. Pass `types: [...]` to fetch a whole section's worth of element types at once (e.g. ['section','text-block','image-block','button']) — returns { elements: { [type]: details } } and saves a round-trip per type. `type` (single) returns the doc directly for backward compatibility.", {
         type: z.string().optional().describe("Single element type — backward-compat. Prefer `types` when fetching more than one."),
         types: z
             .array(z.string())
@@ -49,7 +51,7 @@ export function registerReferenceTools(server, domain) {
                 summary: doc.summary,
                 useWhen: doc.useWhen,
                 keySpecials: doc.keySpecials,
-                skeleton: domain.createElement(t),
+                skeleton: sparseTemplate(domain.createElement(t)),
                 example: doc.example ?? null,
             };
         }
@@ -57,9 +59,10 @@ export function registerReferenceTools(server, domain) {
         if (!types && type) {
             if (unknown.length)
                 return text({ error: `Unknown element type "${unknown[0]}".`, valid_types: domain.elementTypes });
-            return text(elements[type]);
+            return text({ ...elements[type], authoring: SPARSE_NOTE });
         }
         return text({
+            authoring: SPARSE_NOTE,
             elements,
             unknown: unknown.length ? unknown : undefined,
             valid_types: unknown.length ? domain.elementTypes : undefined,

package/package.json

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