webcake-landing-mcp 1.0.56 → 1.0.57

package/README.md

@@ -152,6 +152,11 @@ npx -y webcake-landing-mcp login    # opens the browser once, saves the token to
 
 …or set `WEBCAKE_ENV` (`local` | `staging` | `prod` — fills in all base URLs) + `WEBCAKE_JWT`.
 
+For `publish_page` to produce a **rendered** (non-blank) page, a build host is needed:
+- `prod` preset auto-configures `https://build.webcake.io` — no extra setup.
+- For staging/local, set `WEBCAKE_BUILD_BASE=<url>` or send the `x-webcake-build-base` header per request.
+- Without it, `publish_page` falls back to source-only with `rendered:false` + a warning.
+
 Everything else — the full env-var table, environment presets, per-request headers for the hosted
 server, the `login` browser flow (+ backend contract), and how to grab a JWT by hand — lives in
 **[docs/configuration.md](docs/configuration.md)**.
@@ -164,7 +169,7 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 |-------|---------------|
 | **[Connect your IDE / claude.ai](docs/connect-mcp.md)** | Step-by-step connection for every client (npx & hosted URL), troubleshooting table. |
 | **[Configuration](docs/configuration.md)** | Env vars, `--env` presets, browser `login`, per-request headers, getting a JWT. |
-| **[Tools reference](docs/tools.md)** | All 19 tools in detail + the step-by-step workflow + model notes. |
+| **[Tools reference](docs/tools.md)** | All 20 tools in detail + the step-by-step workflow + model notes. |
 | **[Usage examples](docs/usage-examples.md)** | Three end-to-end walkthroughs: build from a brief, surgical edit, inspect a type. |
 | **[Manual / advanced install](docs/manual-install.md)** | Shell installers, cloned builds, hand-written per-IDE config. |
 | **[Page-element schema](docs/page-element-schema.md)** | The full element-model reference (+ [every special/event](docs/element-specials-reference.md)). |
@@ -173,13 +178,13 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 
 ## 🧰 The tools at a glance
 
-19 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
+20 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
 
 | Group | Tools | Needs |
 |-------|-------|-------|
 | **Reference** | `get_generation_guide` · `list_elements` · `get_element` · `get_page_schema` | nothing |
 | **Generation** | `new_element` · `new_page_skeleton` · `validate_page` | nothing |
-| **Media** | `search_images` (real Pexels stock photos) | nothing (optional own key) |
+| **Media** | `search_images` (real Pexels stock photos) · `upload_images` (re-host external images) | nothing |
 | **Ingest** | `ingest_html` · `ingest_url` (recreate an existing page) | nothing |
 | **Persistence** | `list_organizations` · `create_page` · `list_pages` · `find_pages` · `get_page` · `update_page` · `add_section` · `patch_page` · `publish_page` | `WEBCAKE_API_BASE` + `WEBCAKE_JWT` |
 

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.57",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "New upload_images tool re-hosts up to 20 external image URLs or data: URIs as Webcake-hosted URLs (statics.pancake.vn) by downloading and uploading…",
+    "vi": "Công cụ upload_images mới tải lại tối đa 20 URL ảnh ngoài hoặc data: URI thành URL do Webcake lưu trữ (statics.pancake.vn) bằng cách tải về và…"
+  },
   {
     "v": "1.0.56",
     "d": "11/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "validate_page now errors when an element type that the renderer cannot animate (any type other than group, image-block, text-block, rectangle,…",
     "vi": "validate_page nay báo lỗi khi một element có loại không được renderer hỗ trợ animation (chỉ group, image-block, text-block, rectangle, button,…"
-  },
-  {
-    "v": "1.0.51",
-    "d": "10/06/2026",
-    "type": "Added",
-    "en": "create_page, update_page, and add_section dry-run responses now include a draft_id, and all three tools now accept draft_id as an input parameter:…",
-    "vi": "Các response dry-run của create_page, update_page và add_section nay đều trả về draft_id, đồng thời cả ba công cụ đều nhận draft_id làm tham số đầu…"
   }
 ]

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

@@ -3,7 +3,7 @@ export const CONTENT = [
     {
         type: "text-block", category: "content", container: false, defaultName: "Text",
         summary: "Text. specials.text holds the content (may contain inline HTML); specials.tag sets the semantic tag. Supports template variables ({{key}}), formula mode, URL-param injection, and date formatting.",
-        useWhen: "Any headline, paragraph, label. Use tag h1/h2 for headings, p for body. Style via responsive.styles (fontSize, color, fontWeight, textAlign). ALWAYS set color to CONTRAST the band it sits on: near-black (e.g. rgba(26,32,44,1)) on light bands, near-white ONLY on a dark/image band — white text on a light band renders invisible. styles.background on a text-block = a GRADIENT TEXT FILL (emits -webkit-text-fill-color:transparent); you must also set styles['-webkitBackgroundClip']:'text' or the glyphs go invisible. The box background key is styles.backgroundTxt — use that for a colored box behind the text. NEVER set styles.background expecting a box fill.",
+        useWhen: "Any headline, paragraph, label. Use tag h1/h2 for headings, p for body. Style via responsive.styles (fontSize, color, fontWeight, textAlign). ALWAYS set color to CONTRAST the band it sits on: near-black (e.g. rgba(26,32,44,1)) on light bands, near-white ONLY on a dark/image band — white text on a light band renders invisible. styles.background on a text-block = a GRADIENT TEXT FILL (emits -webkit-text-fill-color:transparent); you must also set styles['-webkitBackgroundClip']:'text' or the glyphs go invisible. The box background key is styles.backgroundTxt — use that for a colored box behind the text. NEVER set styles.background expecting a box fill. text-block does NOT emit border-radius — for a rounded pill/badge, put a rectangle (borderRadius '13px', pill bg color) BEHIND the text-block (zIndex 2 on the text-block); the rounded shape comes from the rectangle, never from the text-block itself.",
         keySpecials: {
             text: "string — the visible text; may include inline HTML (<b>, <br>, <span style>…). Also supports template variables: {{today}}, {{yesterday}}, {{tomorrow}} (formatted dates), {{coupon_text}}, {{coupon_code}}, {{coupon_codes}}, {{spin_turn_left}}, {{cart_total_price}}, {{cart_subtotal}}, {{cart_shipping_fee}}, {{cart_discount_code}}, {{voucher_price_cart}}, {{cart_item}}, {{cart_bonus_item}}, {{form_error_log}}, {{total_cart}}. Dynamic form field binding: {{formId__fieldName}} substitutes a field value from a sibling form.",
             tag: "p | h1 | h2 | h3 | h4 | h5 | h6 | span | div.",

package/dist/domains/landing/guide.js

@@ -101,10 +101,11 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 - SOCIAL PROOF — testimonial cards, a logo strip, or a row of stat counters (auto-number + label). Center the row.
 - FORM / CTA — center the form box; stack inputs vertically with comfortable spacing; each input needs a unique specials.field_name (canonical: full_name, phone_number, email, address, quantity); prominent submit button.
 - FOOTER — name + real contact lines, usually centered on a dark band. Only real data the user provided.
+- TAG/BADGE "PILL" recipe — a rounded rectangle (borderRadius "13px", the pill bg color) BEHIND a text-block (zIndex 2, styles.backgroundTxt for the box fill if needed, textAlign center). NEVER put the pill color in styles.background on the text-block — that key activates gradient-text-fill mode (the renderer emits -webkit-text-fill-color:transparent and the glyphs go invisible). text-block does NOT emit border-radius at all — the rounded shape must come from a rectangle behind the text.
 
 RULES
 - Visible content goes in "specials" (text-block.specials.text, image-block.specials.src…), NEVER in "styles".
-- Colors as rgba(r,g,b,a). fontSize/borderWidth/top/left/width/height are NUMBERS (px).
+- Colors as rgba(r,g,b,a). fontSize/borderWidth/top/left/width/height are NUMBERS (px). borderRadius is a STRING with CSS units ("8px", "50%", "16px 16px 0 0") — a bare number or unit-less string is auto-coerced to px by the server, but write the unit explicitly to avoid surprises.
 - IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). PREFER REAL PHOTOS: call search_images with a short English subject (e.g. 'fresh coffee cup', 'modern office team') and put a returned URL into image-block specials.src — use src.large for a hero/banner, src.medium for a card/thumb (avg_color helps pick a matching section background). ONLY if search_images returns ok:false (or is unreachable) FALL BACK to a PLACEHOLDER sized to the box: "https://placehold.co/<width>x<height>". NEVER leave src empty — it renders blank on the live page. The server automatically derives styles.background from specials.src on every expand (create/update/validate) using the editor's exact format: 'center center/ cover no-repeat scroll content-box url(<src>) border-box' — you do NOT need to set styles.background manually; if you do hand-write it, it must contain url(...). gallery.media = array of OBJECTS {type:'image', link:'<real-or-placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster image (real photo, else placeholder). Do NOT set a flat (no url()) styles.background on a video element — it suppresses the poster image.
 - CONTRAST (check EVERY text element against the band it sits on, especially SATURATED / mid-tone bands like yellow, orange, teal, pink — there "light vs dark text" is not obvious, so decide by the band's luminance): light bands → near-black text (e.g. rgba(20,30,25,1)); dark bands → near-white text; a saturated/mid-tone band → whichever of near-black or near-white actually reads (for a bright yellow/amber band that means DARK text, not white/grey). NEVER use muted-grey, low-alpha (alpha < ~0.85), or near-white text on a colored band — that is exactly what makes labels look faded/sunken. Muted-grey is ONLY for secondary text on a white/very-light band. Icons and their captions follow the SAME rule as the text beside them.
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
@@ -148,4 +149,9 @@ EDITING an existing page
 - SMALL edit → PREFER patch_page(page_id, patches): send ONLY the changed elements by id, not the whole source. Ops — {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merge; op defaults to 'update'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. The MCP fetches the live source, applies the ops, validates the whole tree, and saves. Reserve update_page(page_id, full source) for when you're rewriting most of the page.
 - To add an element: give it a unique id + top/left/width/height, then patch_page({op:'add', parent_id:<section id>, element:<node>}).
 - FIX-AFTER-ERROR (never rebuild the whole source): when create_page/update_page/add_section reports validation errors, fix ONLY the offending element ids with patch_page. If create_page failed, its error returns a draft_id (source cached) → patch_page({ draft_id, patches, dry_run:false }) fixes + creates the page (a wrong type → { op:'update', id, type:'<allowed type>' }). If update_page/add_section failed, the page has a page_id → patch_page({ page_id, patches }).
-- patch_page/update_page default to dry_run=true (preview); pass dry_run:false to save.`;
+- patch_page/update_page default to dry_run=true (preview); pass dry_run:false to save.
+
+REFERENCE INPUT (HTML page to clone or adapt)
+- ingest_html(html, detail:'full') / ingest_url(url, detail:'full') returns a richer AST for clone-quality rebuilds: CSS custom-property palette (design tokens by name), background_images from stylesheets (hero/CTA bg images invisible to a plain img scan), per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, gradients, and images as { src, alt } objects. Use detail:'compact' (default) for a quick layout-only reference.
+- Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links.
+- When intent='clone': re-host image URLs found in the AST (images, background_images, og_image) via upload_images instead of hotlinking. For intent='adapt' (default): use the AST for layout/hierarchy only and write fresh content for the user's brand.`;

package/dist/domains/landing/index.js

@@ -62,14 +62,52 @@ function normalizeImageBlocks(node) {
             normalizeImageBlocks(child);
     }
 }
-/** Apply image-block normalization to every node in a page source. */
+// ---------------------------------------------------------------------------
+// borderRadius normalization: the renderer emits border-radius RAW from the
+// styles object (exportCss.js: `border-radius: ${style.borderRadius};`).
+// A bare number (e.g. 16) or a unit-less string (e.g. "16") produces invalid
+// CSS that browsers silently ignore — every corner renders square. Valid values
+// are strings with CSS units: "16px", "50%", "16px 16px 0 0".
+//
+// Fix: after every expand pass, walk every node and, for each breakpoint whose
+// styles.borderRadius is a number or a unit-less numeric string, coerce it to
+// "<n>px". Already-valid strings (contain a letter or %) pass through untouched.
+// ---------------------------------------------------------------------------
+/** True when s is a plain number-string with no CSS unit (e.g. "16", "0"). */
+function isUnitless(s) {
+    return /^\s*-?\d+(\.\d+)?\s*$/.test(s);
+}
+/** Walk a tree node and coerce numeric/unit-less borderRadius to "<n>px" in-place (mutates). */
+function normalizeBorderRadius(node) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const bp of ["desktop", "mobile"]) {
+        const styles = node.responsive?.[bp]?.styles;
+        if (!styles || typeof styles !== "object")
+            continue;
+        const br = styles.borderRadius;
+        if (typeof br === "number" && Number.isFinite(br)) {
+            styles.borderRadius = `${br}px`;
+        }
+        else if (typeof br === "string" && isUnitless(br)) {
+            styles.borderRadius = `${parseFloat(br)}px`;
+        }
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            normalizeBorderRadius(child);
+    }
+}
+/** Apply all post-expand normalizations to every node in a page source. */
 function normalizeSource(source) {
     if (!source || typeof source !== "object")
         return source;
     for (const arr of ["page", "popup", "dynamic_pages"]) {
         if (Array.isArray(source[arr])) {
-            for (const node of source[arr])
+            for (const node of source[arr]) {
                 normalizeImageBlocks(node);
+                normalizeBorderRadius(node);
+            }
         }
     }
     return source;

package/dist/domains/landing/instructions.js

@@ -24,7 +24,7 @@ RULES (follow for every request):
   A wrong element type is the most common error → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements if unsure). Drafts expire in ~30 min.
 - DRY-RUN CACHE: create_page, update_page, and add_section dry_run=true all cache the validated payload and return a draft_id. Re-run the same tool with { draft_id, dry_run:false } — no need to re-send the source.
 - Organizations: call list_organizations and ask which to use; default to the is_default org. Endpoints are owner-scoped (only the account's own pages).
-- REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements. (2) HTML string → call ingest_html(html) to get a compact AST. (3) URL → call ingest_url(url) for the same AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts) — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
+- REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements using role→element hints (hero → section with background image/overlay + heading + paragraph + button; features → group blocks with icon/title/text; stats bar → group with heading+text per stat; pricing → group with text list + button; footer → section with text + links). (2) HTML string → call ingest_html(html, detail:'full') to get the richer AST when cloning; use detail:'compact' (default) for a layout-only reference. (3) URL → call ingest_url(url, detail:'full') for the same richer AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), CSS custom-property palette, background_images from stylesheets, and in full mode: per-section blocks (cards/tiles/steps with title/body/image/cta), li lists, and gradients — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). When cloning (intent='clone'), re-host image URLs found in the AST (images, background_images, og_image) via upload_images instead of hotlinking. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
 
 MODEL (essentials):
 - Top-level: { page:[sections], popup:[popups], dynamic_pages:[], settings:{}, options:{mobileOnly,versionID}, cartConfigs:{isActive:false}, svariations:[] }. Popups are a SEPARATE top-level array, NOT inside page; currency lives in settings.currency (not options). Leave dynamic_pages/svariations as [] for a static page, but keep them on edit round-trips.
@@ -39,4 +39,4 @@ MODEL (essentials):
 
 - 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.`;
+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, upload_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

@@ -39,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", 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" },
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800", previewBase: "http://preview.localhost:5800", buildBase: undefined },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io", previewBase: "https://staging.webcake.me", buildBase: undefined },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io", previewBase: "https://www.webcake.me", buildBase: "https://build.webcake.io" },
 };
 export function stripTrailingSlash(s) {
     return s?.replace(/\/+$/, "");
@@ -104,6 +104,13 @@ export function readConfig(overrides = {}) {
         preset?.previewBase ??
         saved.previewBase ??
         "https://www.webcake.me");
+    // The build host is used by publish_page to build app/app_css before publishing.
+    // Prod preset has https://build.webcake.io; staging/local have no reliable public
+    // host so they leave it undefined — callers must set WEBCAKE_BUILD_BASE explicitly.
+    const buildBase = stripTrailingSlash(overrides.buildBase ??
+        process.env.WEBCAKE_BUILD_BASE ??
+        preset?.buildBase ??
+        saved.buildBase);
     return {
         config: {
             base: cleanBase,
@@ -112,6 +119,7 @@ export function readConfig(overrides = {}) {
             appBase: stripTrailingSlash(overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase),
             builderBase,
             previewBase,
+            buildBase,
         },
         missing: [],
     };
@@ -142,6 +150,7 @@ export function configFromHeaders(headers) {
         appBase: header(headers, "x-webcake-app-base"),
         builderBase: header(headers, "x-webcake-builder-base"),
         previewBase: header(headers, "x-webcake-preview-base"),
+        buildBase: header(headers, "x-webcake-build-base"),
         env: header(headers, "x-webcake-env"),
     };
 }