webcake-landing-mcp 1.0.48 → 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,11 @@
 [
+  {
+    "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",
@@ -33,12 +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à…"
   }
 ]

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).

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

@@ -24,7 +24,7 @@ RULES (follow for every request):
 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/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

@@ -34,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()])
@@ -160,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;
@@ -243,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()
@@ -441,7 +455,7 @@ export function registerPersistenceTools(server, domain) {
         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,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."),
+            .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()

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.48",
+  "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",