webcake-landing-mcp 1.0.48 → 1.0.50

package/README.md

@@ -89,7 +89,7 @@ persists it (source-only — the page opens in the editor where re-saving render
 | **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, a JWT, or none (reference tools) |
 | **Hosted URL** — use our live server, nothing to install | No Node.js, teams, the claude.ai dialog | your personal `?jwt=` link / `x-webcake-jwt` header |
 
-The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `patch_page`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
+The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `patch_page`, `publish_page`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 > 🛠️ Prefer a shell-script installer (`install.sh`/`install.ps1`), a cloned local build, or hand-written per-IDE config? See **[docs/manual-install.md](docs/manual-install.md)**.
 
@@ -222,7 +222,8 @@ lands in logs). Any header that's missing falls back to the matching env var:
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | default org |
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | overrides the env preset's API base |
 | `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's SPA base (login connect page) |
-| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor/preview links |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor links |
+| `x-webcake-preview-base` | `WEBCAKE_PREVIEW_BASE` | overrides the public preview host used for `/preview/<id>` links |
 
 > The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need **no
 > token** — only the persistence tools (`create_page`, `update_page`, …) use it. Without a JWT, those return
@@ -292,7 +293,8 @@ flow can also be done entirely in the SPA, no backend route needed.)
 | `WEBCAKE_JWT` | No* | Account JWT (dashboard auth). Required to persist — expires, refresh when needed. |
 | `WEBCAKE_ORG_ID` | No | Default organization id for `create_page` (overridden by its `organization_id` arg). Omit → personal page. |
 | `WEBCAKE_APP_BASE` | No | Optional SPA base — used for the browser `login` connect page. |
-| `WEBCAKE_BUILDER_BASE` | No | Optional builder host for the editor/preview links in the result. Defaults to the env preset, else derived from the API host (`api.x`→`builder.x`). |
+| `WEBCAKE_BUILDER_BASE` | No | Optional builder host for the editor links in the result. Defaults to the env preset, else derived from the API host (`api.x`→`builder.x`). |
+| `WEBCAKE_PREVIEW_BASE` | No | Optional public preview host for the `/preview/<id>` links — NOT the builder subdomain. Defaults to the env preset (`preview.localhost:5800` local / `staging.webcake.me` staging / `www.webcake.me` prod). |
 | `WEBCAKE_CONFIG_DIR` | No | Dir for the saved `auth.json` written by `login` (default `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` and `WEBCAKE_JWT` are only needed for the persistence tools. The reference and
@@ -419,6 +421,9 @@ update_page({ page_id, source, dry_run: false })         # overwrite (dry_run=tr
 create_page({ source: smallSkeleton, dry_run: false })   # → page_id
 add_section({ page_id, sections: heroSection, dry_run: false })   # backend appends server-side (no whole-source get+put)
 add_section({ page_id, sections: [formSection, footerSection], dry_run: false })
+
+# Go LIVE (the preview link works without this — publish to attach a domain / set live status)
+publish_page({ page_id, custom_domain: "shop.example.com", custom_path: "sale", dry_run: false })
 ```
 
 `create_page` calls **`POST {WEBCAKE_API_BASE}/api/v1/ai/create_page_from_source`** on the backend.
@@ -443,13 +448,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,8 +470,9 @@ 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`.** |
+| `publish_page` | Publish a page (live status, optional custom domain/path). The preview link works WITHOUT publishing — publish only to go live. **Defaults to `dry_run=true`.** |
 
 ---
 

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.50",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "New publish_page tool makes a page live: reads the page's current stored source, saves it as a new version, and creates or updates the…",
+    "vi": "Công cụ publish_page mới giúp đưa trang lên live: đọc source đang lưu của trang, lưu thành phiên bản mới và tạo hoặc cập nhật bản ghi…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "get_generation_guide workflow condensed to four steps: element-type reads and image fetches are now batched into single calls…",
     "vi": "Workflow trong get_generation_guide được rút gọn xuống còn bốn bước: việc đọc loại phần tử và tìm ảnh nay được gộp thành các lần gọi batch duy nhất…"
-  },
-  {
-    "v": "1.0.44",
-    "d": "09/06/2026",
-    "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.
@@ -32,4 +32,6 @@ MODEL (essentials):
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
 - IMAGES: include them (hero/product, feature icons, about photo). PREFER REAL PHOTOS — call search_images with a short English subject (e.g. 'fresh coffee cup') and put a returned URL (src.large for a hero/banner, src.medium for a card/thumb) into the image-block specials.src; it works out of the box (a shared proxy supplies images). Only if search_images returns ok:false, FALL BACK to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height>. (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
 
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page.`;
+- PREVIEW vs PUBLISH: the preview_url returned by create_page/update_page/add_section lives on the PREVIEW host (preview.localhost:5800 local / staging.webcake.me staging / www.webcake.me prod — NOT the builder subdomain) and renders the stored source immediately — share it as-is for review. When the user wants the page LIVE (public/published, optionally on their custom domain), call publish_page({ page_id, custom_domain?, custom_path?, dry_run:false }).
+
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;

package/dist/persistence/config.js

@@ -19,8 +19,11 @@
  *   WEBCAKE_JWT       the account JWT               (required to call the backend)
  *   WEBCAKE_ORG_ID    optional default organization id for create_page
  *   WEBCAKE_APP_BASE  optional SPA base (used for the login connect page)
- *   WEBCAKE_BUILDER_BASE  optional builder host for editor/preview URLs in the result
+ *   WEBCAKE_BUILDER_BASE  optional builder host for the editor URLs in the result
  *                     (defaults to the env preset, else derived from the API host)
+ *   WEBCAKE_PREVIEW_BASE  optional public preview host for the /preview/<id> links —
+ *                     NOT the builder subdomain (defaults to the env preset:
+ *                     preview.localhost:5800 / staging.webcake.me / www.webcake.me)
  *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
  */
 import { homedir } from "node:os";
@@ -36,9 +39,9 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
  * after create/update (a distinct host — NOT the API and NOT the SPA).
  */
 export const ENVIRONMENTS = {
-    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800" },
-    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io" },
-    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io" },
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800", previewBase: "http://preview.localhost:5800" },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io", previewBase: "https://staging.webcake.me" },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io", previewBase: "https://www.webcake.me" },
 };
 export const ENV_NAMES = Object.keys(ENVIRONMENTS);
 /** True when `v` names a known environment (local|staging|prod). */
@@ -88,6 +91,16 @@ export function readConfig(overrides = {}) {
         preset?.builderBase ??
         saved.builderBase ??
         deriveBuilderBase(cleanBase))?.replace(/\/+$/, "");
+    // The public preview link (/preview/<id>) is served on its OWN root host — NOT
+    // the builder subdomain (preview.localhost:5800 / staging.webcake.me /
+    // www.webcake.me). When nothing matches, default to the backend's own preview
+    // domain (its @preview_domain) so the link still lands on a host that serves
+    // the /preview/:id route.
+    const previewBase = (overrides.previewBase ??
+        process.env.WEBCAKE_PREVIEW_BASE ??
+        preset?.previewBase ??
+        saved.previewBase ??
+        "https://www.webcake.me").replace(/\/+$/, "");
     return {
         config: {
             base: cleanBase,
@@ -95,6 +108,7 @@ export function readConfig(overrides = {}) {
             orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
             appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase)?.replace(/\/+$/, ""),
             builderBase,
+            previewBase,
         },
         missing: [],
     };
@@ -111,7 +125,8 @@ function header(headers, name) {
  *   x-webcake-env        named environment (local|staging|prod) for the base URLs
  *   x-webcake-api-base   backend base URL (overrides the env preset)
  *   x-webcake-app-base   SPA base used for the login connect page (overrides the preset)
- *   x-webcake-builder-base  builder host for editor/preview URLs (overrides the preset)
+ *   x-webcake-builder-base  builder host for editor URLs (overrides the preset)
+ *   x-webcake-preview-base  public preview host for /preview/<id> links (overrides the preset)
  * Any header that is absent falls back to the corresponding env var in readConfig.
  */
 export function configFromHeaders(headers) {
@@ -123,6 +138,7 @@ export function configFromHeaders(headers) {
         orgId: header(headers, "x-webcake-org-id"),
         appBase: header(headers, "x-webcake-app-base"),
         builderBase: header(headers, "x-webcake-builder-base"),
+        previewBase: header(headers, "x-webcake-preview-base"),
         env: header(headers, "x-webcake-env"),
     };
 }

package/dist/persistence/webcake-client.js

@@ -5,6 +5,13 @@ const SEARCH_PAGES_ENDPOINT = "/api/v1/ai/search_pages";
 const PAGE_SOURCE_ENDPOINT = "/api/v1/ai/page_source";
 const UPDATE_ENDPOINT = "/api/v1/ai/update_page_source";
 const APPEND_ENDPOINT = "/api/v1/ai/append_section";
+// The editor's own publish route (NOT under /api/v1/ai): saves the source as a
+// new version and creates/updates the page_published record (+ optional custom
+// domain/path) so the page goes live. NOTE: this scope is host-constrained to
+// the BUILDER host (router scope `host: "builder."`), so the request goes to
+// config.builderBase, not the API base.
+const publishEndpoint = (pageId) => `/api/pages/${encodeURIComponent(pageId)}/edit/publish`;
+const publishUrl = (config, pageId) => `${(config.builderBase ?? config.base).replace(/\/+$/, "")}${publishEndpoint(pageId)}`;
 function authHeaders(config, orgId) {
     const headers = {
         "Content-Type": "application/json",
@@ -44,6 +51,33 @@ export function toEditorUrl(config, raw) {
         pathQuery = `/${pathQuery}`;
     return `${builder.replace(/\/+$/, "")}${pathQuery}`;
 }
+/**
+ * Resolve the public preview link (`/preview/<page_id>`) onto the PREVIEW host
+ * (config.previewBase) — NOT the builder subdomain. The /preview/:id route only
+ * exists on the root preview hosts (preview.localhost:5800 local /
+ * staging.webcake.me staging / www.webcake.me prod); the v4 renderer there reads
+ * the stored page_source directly, so the link works without publishing.
+ */
+export function toPreviewUrl(config, raw) {
+    if (!raw)
+        return raw;
+    const preview = config.previewBase;
+    if (!preview)
+        return toEditorUrl(config, raw); // legacy fallback
+    let pathQuery = raw;
+    if (/^https?:\/\//i.test(raw)) {
+        try {
+            const u = new URL(raw);
+            pathQuery = u.pathname + u.search + u.hash;
+        }
+        catch {
+            /* not a parseable URL — use as-is */
+        }
+    }
+    if (!pathQuery.startsWith("/"))
+        pathQuery = `/${pathQuery}`;
+    return `${preview.replace(/\/+$/, "")}${pathQuery}`;
+}
 /** Build (but do not send) the create request — used for dry-run previews. */
 export function buildRequest(config, name, source, orgId) {
     return {
@@ -134,7 +168,7 @@ export async function createPage(config, name, source, orgId) {
         status: res.status,
         page_id: pageId,
         editor_url: toEditorUrl(config, editorPath),
-        preview_url: toEditorUrl(config, previewPath),
+        preview_url: toPreviewUrl(config, previewPath),
         organization_id: (orgId ?? config.orgId) ?? null,
         raw: data,
     };
@@ -278,7 +312,7 @@ export async function appendSection(config, pageId, sections) {
         status: res.status,
         page_id: pageIdOut,
         editor_url: toEditorUrl(config, data?.editor_url),
-        preview_url: toEditorUrl(config, data?.preview_url),
+        preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         section_count: data?.section_count,
         sections_added: data?.sections_added,
@@ -323,8 +357,111 @@ export async function updatePageSource(config, pageId, source) {
         status: res.status,
         page_id: pageIdOut,
         editor_url: toEditorUrl(config, data?.editor_url),
-        preview_url: toEditorUrl(config, data?.preview_url),
+        preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         raw: data,
     };
 }
+function publishBody(sourceString, opts = {}) {
+    // The publish action expects `source` as a JSON STRING (it Jason.decode!s it),
+    // plus optional custom_domain/custom_path. is_publish marks the save as a
+    // publish in save_page_with_source.
+    return JSON.stringify({
+        source: sourceString,
+        custom_domain: opts.customDomain ?? "",
+        custom_path: opts.customPath ?? "",
+        is_publish: true,
+    });
+}
+/** Build (but do not send) the publish request with the token masked — for dry-run previews. */
+export function buildPublishRequestRedacted(config, pageId, sourceString, opts = {}) {
+    const body = publishBody(sourceString, opts);
+    return {
+        method: "POST",
+        url: publishUrl(config, pageId),
+        headers: { ...authHeaders(config), Authorization: "Bearer ***JWT***", Cookie: "jwt=***JWT***" },
+        body: body.replace(config.jwt, "***JWT***").slice(0, 400) + (body.length > 400 ? `… (${body.length} bytes)` : ""),
+    };
+}
+/**
+ * POST to a host-scoped route. Node's fetch cannot reach `*.localhost` hosts
+ * (browsers special-case .localhost; Node's DNS does not, and undici forbids a
+ * manual Host header) — so for those we connect to loopback via node:http and
+ * carry the real host in the Host header. Everything else uses plain fetch.
+ */
+async function postToHost(url, headers, body) {
+    const u = new URL(url);
+    if (!u.hostname.endsWith(".localhost")) {
+        const res = await fetch(url, { method: "POST", headers, body });
+        return { status: res.status, text: await res.text() };
+    }
+    const { request } = await import("node:http");
+    return new Promise((resolve, reject) => {
+        const req = request({
+            host: "127.0.0.1",
+            port: u.port || 80,
+            path: u.pathname + u.search,
+            method: "POST",
+            headers: { ...headers, Host: u.host },
+        }, (res) => {
+            let data = "";
+            res.on("data", (c) => (data += c));
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, text: data }));
+        });
+        req.on("error", reject);
+        req.end(body);
+    });
+}
+/**
+ * Publish a page: saves the source as a new version and creates/updates the
+ * page_published record (live status + optional custom domain/path). Returns the
+ * resulting public URL — `https://<domain>/<path>` when a custom domain is
+ * attached, else the preview-host link (`<previewBase>/preview/<page_id>`).
+ */
+export async function publishPage(config, pageId, sourceString, opts = {}) {
+    const url = publishUrl(config, pageId);
+    let status;
+    let text;
+    try {
+        // The builder-host pipeline runs an `accepts ["html"]` plug (it serves the
+        // editor SPA); a literal application/json Accept gets a 406, so send */*
+        // like the browser does — the action still returns JSON.
+        ({ status, text } = await postToHost(url, { ...authHeaders(config), Accept: "*/*" }, publishBody(sourceString, opts)));
+    }
+    catch (e) {
+        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+    }
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        /* non-JSON */
+    }
+    const resOk = status >= 200 && status < 300;
+    const success = json?.success !== false && resOk;
+    if (!success) {
+        const backendMsg = json?.message ?? json?.reason ?? (json ? undefined : text.slice(0, 200));
+        return {
+            ok: false,
+            status,
+            raw: json ?? text.slice(0, 600),
+            error: `Backend returned ${status}${backendMsg ? `: ${backendMsg}` : ""}`,
+        };
+    }
+    const data = json?.data ?? json;
+    const domain = data?.domain ?? null;
+    const path = data?.path ?? null;
+    const previewUrl = toPreviewUrl(config, `/preview/${pageId}`);
+    const publishedUrl = domain ? `https://${domain}${path ? `/${String(path).replace(/^\/+/, "")}` : ""}` : previewUrl;
+    return {
+        ok: true,
+        status,
+        page_id: pageId,
+        published_url: publishedUrl,
+        preview_url: previewUrl,
+        domain,
+        path,
+        raw: data,
+    };
+}

package/dist/smoke.js

@@ -5,9 +5,10 @@
 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";
+import { readConfig, resolveEnv, ENV_NAMES, configFromHeaders } from "./persistence/config.js";
+import { toEditorUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
 import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
 let failures = 0;
 const check = (name, cond, extra) => {
@@ -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) ==");
@@ -295,7 +327,7 @@ check("clean form has no binding warnings", rbg.warnings.length === 0, rbg.warni
 console.log("== config: named environment presets (local/staging/prod) ==");
 {
     // Deterministic: isolate from any ambient WEBCAKE_* and the saved auth.json on the dev box.
-    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_BUILDER_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
+    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_BUILDER_BASE", "WEBCAKE_PREVIEW_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
         delete process.env[k];
     process.env.WEBCAKE_CONFIG_DIR = "/nonexistent/webcake-smoke";
     check("env names are local/staging/prod", setEq(new Set(ENV_NAMES), ["local", "staging", "prod"]), ENV_NAMES);
@@ -321,6 +353,23 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     check("editor url from a path → builder host", toEditorUrl(localCfg, "/editor/v2/abc") === "http://builder.localhost:5800/editor/v2/abc");
     check("editor url from an absolute api url → builder host", toEditorUrl(localCfg, "http://localhost:5800/editor/v2/abc?x=1") === "http://builder.localhost:5800/editor/v2/abc?x=1");
     check("editor url passthrough when empty", toEditorUrl(localCfg, undefined) === undefined);
+    // The PREVIEW link lives on its own root host (NOT the builder subdomain):
+    // preview.localhost:5800 / staging.webcake.me / www.webcake.me.
+    check("env presets carry preview bases", resolveEnv("local")?.previewBase === "http://preview.localhost:5800" && resolveEnv("staging")?.previewBase === "https://staging.webcake.me" && resolveEnv("prod")?.previewBase === "https://www.webcake.me");
+    check("readConfig(env=local) sets previewBase", localCfg.previewBase === "http://preview.localhost:5800", localCfg);
+    check("readConfig(env=prod) sets previewBase", readConfig({ env: "prod", jwt: "t" }).config?.previewBase === "https://www.webcake.me");
+    check("previewBase defaults to www.webcake.me without a preset", readConfig({ base: "https://api.example.com", jwt: "t" }).config?.previewBase === "https://www.webcake.me");
+    check("explicit previewBase overrides the preset", readConfig({ env: "prod", previewBase: "https://p.test/", jwt: "t" }).config?.previewBase === "https://p.test");
+    check("x-webcake-preview-base header parsed", configFromHeaders({ "x-webcake-preview-base": "https://p.example" }).previewBase === "https://p.example");
+    check("preview url from a path → preview host (not builder)", toPreviewUrl(localCfg, "/preview/abc") === "http://preview.localhost:5800/preview/abc");
+    check("preview url from an absolute api url → preview host", toPreviewUrl(localCfg, "http://localhost:5800/preview/abc?x=1") === "http://preview.localhost:5800/preview/abc?x=1");
+    check("preview url passthrough when empty", toPreviewUrl(localCfg, undefined) === undefined);
+    check("preview url falls back to builder when previewBase missing", toPreviewUrl({ ...localCfg, previewBase: undefined }, "/preview/abc") === "http://builder.localhost:5800/preview/abc");
+    // publish request preview: JWT must be masked everywhere.
+    const pub = buildPublishRequestRedacted({ ...localCfg, jwt: "SECRETJWT" }, "pg1", JSON.stringify({ page: [] }), { customDomain: "shop.example.com", customPath: "sale" });
+    check("publish request hits the editor publish route on the BUILDER host", pub.url === "http://builder.localhost:5800/api/pages/pg1/edit/publish", pub.url);
+    check("publish request masks the JWT", !JSON.stringify(pub).includes("SECRETJWT"), pub);
+    check("publish request carries domain/path + source string", pub.body.includes("shop.example.com") && pub.body.includes("custom_path") && pub.body.includes("is_publish"), pub.body);
 }
 console.log("== pexels: key resolution + photo normalization (offline, no network) ==");
 {

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

@@ -12,7 +12,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 { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, buildPublishRequestRedacted, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, publishPage, toPreviewUrl, } 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.
@@ -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()
@@ -677,4 +691,51 @@ export function registerPersistenceTools(server, domain) {
             warnings: result.warnings,
         });
     });
+    // 15) Publish page (go live) -------------------------------------------------
+    server.tool("publish_page", "Publishes an EXISTING page: saves the stored source as a new version and creates/updates its page_published record (live status), optionally attaching a custom domain/path. NOT needed for the preview link — /preview/<page_id> on the preview host renders the stored source directly; publish when the user wants the page LIVE (custom domain, or the public published URL). Note: this publishes source-only (no editor-rendered HTML); pages last published from the editor with custom head/body should be re-published there. DEFAULTS to dry_run=true. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+        page_id: z.string().describe("The page id to publish (must be owned by the account)."),
+        custom_domain: z
+            .string()
+            .optional()
+            .describe("Optional custom domain to serve the page at (e.g. 'shop.example.com' — must already point at Webcake). Omit to publish without a domain (served at the preview-host URL)."),
+        custom_path: z.string().optional().describe("Optional path under the custom domain (e.g. 'sale')."),
+        dry_run: z.boolean().optional().describe("Default TRUE — preview the request without sending. Set false to actually publish."),
+    }, { title: "Publish Webcake Page", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, custom_domain, custom_path, dry_run }, extra) => {
+        const isDry = dry_run !== false; // default true (safe)
+        const { config, missing } = cfgFor(extra);
+        if (!config)
+            return text({ published: false, reason: "missing_env", missing_env: missing });
+        // Publish re-saves the page's CURRENT stored source (the publish endpoint
+        // requires the source in the request), so read it first — even on dry_run,
+        // to show the real payload.
+        const res = await getPageSource(config, page_id);
+        if (!res.ok || res.source == null) {
+            return text({ published: false, reason: "page_not_found", status: res.status, error: res.error ?? "No source on this page." });
+        }
+        const sourceString = JSON.stringify(res.source);
+        const opts = { customDomain: custom_domain, customPath: custom_path };
+        if (isDry) {
+            return text({
+                dry_run: true,
+                page_id,
+                name: res.name,
+                would_publish_to: custom_domain
+                    ? `https://${custom_domain}${custom_path ? `/${custom_path}` : ""}`
+                    : toPreviewUrl(config, `/preview/${page_id}`),
+                request: buildPublishRequestRedacted(config, page_id, sourceString, opts),
+                hint: "Re-run with dry_run=false to actually publish.",
+            });
+        }
+        const outcome = await publishPage(config, page_id, sourceString, opts);
+        return text({
+            published: outcome.ok,
+            page_id,
+            url: outcome.published_url,
+            preview_url: outcome.preview_url,
+            domain: outcome.domain,
+            path: outcome.path,
+            status: outcome.status,
+            error: outcome.error,
+        });
+    });
 }

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