webcake-landing-mcp 1.0.59 → 1.0.60

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.60",
+    "d": "11/06/2026",
+    "type": "Fixed",
+    "en": "The expand pipeline (invoked by create_page, update_page, add_section, validate_page, and patch_page) now auto-canonicalizes every url() layer in…",
+    "vi": "Pipeline expand (được gọi bởi create_page, update_page, add_section, validate_page, và patch_page) nay tự chuẩn hóa mọi layer url() trong…"
+  },
   {
     "v": "1.0.59",
     "d": "11/06/2026",
@@ -33,12 +40,5 @@
     "type": "Fixed",
     "en": "The install command now correctly locates claude_desktop_config.json on Windows when Claude Desktop was installed from the Microsoft Store: the…",
     "vi": "Lệnh install nay xác định đúng đường dẫn claude_desktop_config.json trên Windows khi Claude Desktop được cài từ Microsoft Store: bản Store bị…"
-  },
-  {
-    "v": "1.0.54",
-    "d": "10/06/2026",
-    "type": "Added",
-    "en": "The installer (install command) now supports five additional IDE/agent targets: Antigravity, Gemini CLI, Cline, Kiro, and OpenCode; pass --ide…",
-    "vi": "Trình cài đặt (lệnh install) nay hỗ trợ thêm năm IDE/agent: Antigravity, Gemini CLI, Cline, Kiro và OpenCode; truyền --ide antigravity, --ide…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -107,7 +107,7 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 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). 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.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image) → re-host them via upload_images and use those EXACT images in their slots — never swap them for stock photos; (2) only for slots with NO source image → 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(...). A SECTION background may layer a gradient overlay over an image: 'linear-gradient(...), center center/ cover no-repeat scroll content-box url(<src>) border-box' — the server canonicalises any url() layer into that exact editor shorthand on expand (other url() formats survive the first save but get mangled to 'undefined/ undefined/ …' the moment the page is edited in the Webcake editor). 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 {}.
 - Every form input MUST have a unique specials.field_name.
@@ -139,7 +139,7 @@ WORKFLOW (recommended)
 1. Call get_generation_guide (this) once, then new_page_skeleton for the top-level shape.
 2. For each element type you'll use, call get_element to learn its specials & see an example.
 3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
-3b. For every image the page needs (hero, product, about, feature, gallery), call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
+3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image (user-supplied or from the reference HTML/URL), upload_images it and use the returned Webcake URL; otherwise call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
 4. Assemble { page, popup, settings, options, cartConfigs }.
 5. Call validate_page and fix every error.
 6. To save: call list_organizations. If the account has EXACTLY ONE organization, create_page will auto-select it — no need to ask. If there are MULTIPLE organizations, show them to the user and ask which to use (highlight is_default as the suggested default); pass the chosen organization_id to create_page. If the user explicitly wants to save without any organization, pass organization_id:"personal". Then create_page (dry_run first, then dry_run:false). Note: create_page itself enforces this — it refuses to guess between multiple orgs and returns the org list asking you to pick.
@@ -155,4 +155,4 @@ EDITING an existing page
 REFERENCE INPUT (HTML page to clone or adapt)
 - ingest_html(html, detail:'full') / ingest_url(url, detail:'full') returns a richer AST for clone-quality rebuilds: CSS custom-property palette (design tokens by name), background_images from stylesheets (hero/CTA bg images invisible to a plain img scan), per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, gradients, and images as { src, alt } objects. Use detail:'compact' (default) for a quick layout-only reference.
 - Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links. When the ingested page contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), NOT as element soup.
-- 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.`;
+- Reference images are the user's assets — for BOTH intents (adapt AND clone), re-host every real image URL found in the AST (images, background_images, og_image) via upload_images and reuse it in the matching slot; never hotlink and never replace it with a search_images stock photo. intent='adapt' rewrites TEXT for the user's brand, not the imagery; search_images only fills slots that have no source image.`;

package/dist/domains/landing/index.js

@@ -98,6 +98,79 @@ function normalizeBorderRadius(node) {
             normalizeBorderRadius(child);
     }
 }
+// ---------------------------------------------------------------------------
+// background normalization: the editor's background trait can only parse a
+// url() layer written in its own canonical shorthand
+//   '<pos>/ <size> <repeat> <attachment> content-box url(<src>) border-box'
+// (splitBackground in landing_page_backend/assets/editor/common.js). A url()
+// layer in any other format — e.g. plain CSS copied from a reference page like
+// 'url(x) center/cover no-repeat' — survives the first save, but the moment the
+// page is touched in the editor the picker re-composes it from unparsed parts
+// as 'undefined/ undefined/ … content-box url(x)' and SAVES that garbage, so
+// the band renders blank. Gradient/color layers are unaffected.
+//
+// Fix: after every expand pass, split styles.background into top-level comma
+// layers (paren-aware); keep gradient/color layers unless they carry a literal
+// 'undefined' token (a previously mangled layer — drop it); rewrite every url()
+// layer that is not already editor-canonical into the canonical shorthand,
+// preserving the url. Deterministic + idempotent, so expand(compact(x)) ==
+// expand(x) still holds.
+// ---------------------------------------------------------------------------
+/** Split a CSS background value into top-level comma-separated layers. */
+function splitBackgroundLayers(bg) {
+    const layers = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of bg) {
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth--;
+        if (ch === "," && depth === 0) {
+            layers.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    layers.push(cur);
+    return layers.map((l) => l.trim()).filter((l) => l !== "");
+}
+/** The editor-canonical url() layer shape its splitBackground() can re-parse. */
+const CANONICAL_URL_LAYER = /^(left|center|right) (top|center|bottom)\/ (cover|contain|auto|[\d.]+(?:px|%)(?: [\d.]+(?:px|%))?) (no-repeat|repeat|repeat-x|repeat-y|space|round)(?: (scroll|fixed|local))? content-box url\(.+\)(?: border-box)?$/;
+/** Normalise one styles.background value (returns the input when no url layer). */
+function normalizeBackgroundValue(bg) {
+    if (typeof bg !== "string" || !bg.includes("url("))
+        return bg;
+    const out = [];
+    for (const layer of splitBackgroundLayers(bg)) {
+        const url = layer.match(/url\((['"]?)(.*?)\1\)/);
+        if (url) {
+            out.push(CANONICAL_URL_LAYER.test(layer) ? layer : imgBackground(url[2]));
+        }
+        else if (!/\bundefined\b/.test(layer)) {
+            out.push(layer);
+        }
+    }
+    return out.length ? out.join(", ") : bg;
+}
+/** Walk a tree node and canonicalise every url() background layer in-place (mutates). */
+function normalizeBackgrounds(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 fixed = normalizeBackgroundValue(styles.background);
+        if (fixed !== styles.background)
+            styles.background = fixed;
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            normalizeBackgrounds(child);
+    }
+}
 /** Apply all post-expand normalizations to every node in a page source. */
 function normalizeSource(source) {
     if (!source || typeof source !== "object")
@@ -107,6 +180,7 @@ function normalizeSource(source) {
             for (const node of source[arr]) {
                 normalizeImageBlocks(node);
                 normalizeBorderRadius(node);
+                normalizeBackgrounds(node);
             }
         }
     }

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 before saving. If the account has exactly ONE org, create_page auto-selects it — no need to ask. If there are MULTIPLE orgs, show them and ask the user which to use (is_default is the suggested default); pass the chosen organization_id to create_page. Pass organization_id:"personal" only when the user explicitly wants no org. create_page enforces this itself (it refuses to guess between multiple orgs). 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 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). When the reference contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), not as element soup. (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.
+- 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). When the reference contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), not as element soup. (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). IMAGES FROM THE REFERENCE ARE THE USER'S ASSETS — for BOTH intents (adapt AND clone), every real image URL found in the AST (images, background_images, og_image) MUST be re-hosted via upload_images and reused in the corresponding slot; do NOT replace them with search_images stock photos. Call search_images ONLY for slots that have no source image in the reference. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt' (adapt rewrites TEXT, not the imagery). 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.
@@ -35,7 +35,7 @@ MODEL (essentials):
 - 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.
 - STICKY HEADER: a sticky/fixed header (config.sticky) OVERLAYS the page — it does NOT push sections below it down. Offset the first section's top content DOWN by the header height (~60–72px) so nothing hides behind it, and do NOT duplicate the shop name in both the header and the top of the hero. A non-sticky header stacks normally and needs no offset.
 - 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.
+- IMAGES: include them (hero/product, feature icons, about photo). SOURCE PRIORITY: (1) images the user provided or that exist in the reference HTML/URL → re-host via upload_images and use those exact images; (2) only for slots with NO source image → 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.
 
 - 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 }).
 

package/dist/smoke.js

@@ -817,6 +817,44 @@ console.log("== borderRadius normalization: numeric/unitless coerced to px by ex
     const reexpanded16 = landingDomain.expand(compacted16);
     check("borderRadius round-trip: expand(compact(expand(br=16))) deep-equals expand(br=16)", deepEq(reexpanded16, expanded16));
 }
+console.log("== background normalization: url() layers canonicalised to the editor shorthand ==");
+{
+    const CANON = "center center/ cover no-repeat scroll content-box url(https://x.test/a.jpg) border-box";
+    const mkBgPage = (bgValue) => ({
+        page: [
+            {
+                id: "bg_sec", type: "section",
+                responsive: {
+                    desktop: { styles: { height: 400, background: bgValue } },
+                    mobile: { styles: { height: 400, background: bgValue } },
+                },
+                children: [],
+            },
+        ],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    const bgOf = (src) => src.page[0].responsive.desktop.styles.background;
+    // 1) plain-CSS url layer (reference-page style) → canonical shorthand
+    const expPlain = landingDomain.expand(mkBgPage("url(https://x.test/a.jpg) center/cover no-repeat"));
+    check("background: plain 'url(x) center/cover no-repeat' → canonical", bgOf(expPlain) === CANON, bgOf(expPlain));
+    // 2) gradient overlay + non-canonical url layer → gradient kept, url layer canonicalised
+    const grad = "linear-gradient(160deg, rgba(13,45,58,0.88) 0%, rgba(10,124,110,0.75) 60%, rgba(13,45,58,0.9) 100%)";
+    const expGrad = landingDomain.expand(mkBgPage(`${grad}, url(https://x.test/a.jpg) center/cover`));
+    check("background: gradient + url layer → gradient kept + canonical url", bgOf(expGrad) === `${grad}, ${CANON}`, bgOf(expGrad));
+    // 3) editor-mangled 'undefined/ …' layer → repaired to canonical, gradient kept
+    const expBroken = landingDomain.expand(mkBgPage(`${grad}, undefined/ undefined/ undefined/ undefined/ content-box url(https://x.test/a.jpg)`));
+    check("background: mangled 'undefined/…' url layer → repaired", bgOf(expBroken) === `${grad}, ${CANON}`, bgOf(expBroken));
+    // 4) already-canonical layer left byte-identical (idempotent)
+    const expCanon = landingDomain.expand(mkBgPage(CANON));
+    check("background: canonical layer untouched", bgOf(expCanon) === CANON, bgOf(expCanon));
+    // 5) gradient-only / color-only backgrounds untouched
+    const expOnlyGrad = landingDomain.expand(mkBgPage(grad));
+    check("background: gradient-only untouched", bgOf(expOnlyGrad) === grad, bgOf(expOnlyGrad));
+    // 6) expand(compact(x)) invariant with a canonicalised background
+    const expanded = landingDomain.expand(mkBgPage(`${grad}, url(https://x.test/a.jpg) center/cover`));
+    const reexpanded = landingDomain.expand(landingDomain.compact(expanded));
+    check("background round-trip: expand(compact(expand(x))) deep-equals expand(x)", deepEq(reexpanded, expanded));
+}
 console.log("== text-block styles.background warning (gradient-text-fill mode) ==");
 {
     const mkTbBgPage = (bgValue, withClip) => ({

package/dist/tools/ingest.js

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

package/dist/tools/media.js

@@ -69,7 +69,7 @@ function extFromUrl(url) {
 }
 export function registerMediaTools(server) {
     // 13) Search images ---------------------------------------------------------
-    server.tool("search_images", "Searches Pexels stock photos (see https://www.pexels.com/api/) by short English subject queries. Returns hotlinkable URLs at several sizes (src.large for heroes/banners, src.medium for cards/thumbs), `avg_color` for matching section backgrounds, plus photographer name and attribution URL. BATCH MODE: pass `queries: [...]` to fetch multiple subjects in PARALLEL — e.g. ['fresh coffee cup','barista pouring','interior cafe'] for hero + about + gallery — returns { queries: { [q]: result } } so the caller picks one image per slot in a single round-trip; default `pick='best'` returns only the top photo per query (compact, drop-in for specials.src), `pick='all'` returns the full list. `query` (single) returns the full result like before. Works out of the box via a shared hosted proxy; set PEXELS_API_KEY env or x-pexels-key header to use your own quota.", {
+    server.tool("search_images", "Searches Pexels stock photos (see https://www.pexels.com/api/) by short English subject queries. Returns hotlinkable URLs at several sizes (src.large for heroes/banners, src.medium for cards/thumbs), `avg_color` for matching section backgrounds, plus photographer name and attribution URL. BATCH MODE: pass `queries: [...]` to fetch multiple subjects in PARALLEL — e.g. ['fresh coffee cup','barista pouring','interior cafe'] for hero + about + gallery — returns { queries: { [q]: result } } so the caller picks one image per slot in a single round-trip; default `pick='best'` returns only the top photo per query (compact, drop-in for specials.src), `pick='all'` returns the full list. `query` (single) returns the full result like before. Works out of the box via a shared hosted proxy; set PEXELS_API_KEY env or x-pexels-key header to use your own quota. ONLY for image slots with NO source image: when the user supplied images or the reference HTML/URL contains image URLs (ingest AST images/background_images/og_image), re-host THOSE via upload_images instead of searching stock photos.", {
         query: z.string().optional().describe("Single subject query — backward-compat. Prefer `queries` when the page needs 2+ images."),
         queries: z
             .array(z.string())
@@ -130,7 +130,7 @@ export function registerMediaTools(server) {
         return text({ queries: out });
     });
     // 14) Upload images to Webcake -----------------------------------------------
-    server.tool("upload_images", "Converts external image URLs (typically collected from ingest_html/ingest_url results) or data: URIs into Webcake-hosted URLs (statics.pancake.vn) by downloading each image and re-uploading it to the Webcake backend. Use this when cloning a page (intent='clone') or when the user supplies their own image URLs, so the generated page does not hotlink third-party hosts that may block hotlinking or disappear. The returned URLs go directly into specials.src — same as search_images results. Processes up to 20 URLs per call in parallel, with an 8 MB per-image cap. No Webcake credentials required (the upload endpoint is public). DEFAULTS to dry_run=true (returns a preview of what would be uploaded, no network calls); set dry_run=false to actually upload. Use search_images instead when you need stock photos.", {
+    server.tool("upload_images", "Converts external image URLs (typically collected from ingest_html/ingest_url results) or data: URIs into Webcake-hosted URLs (statics.pancake.vn) by downloading each image and re-uploading it to the Webcake backend. Use this whenever the page is built from a reference HTML/URL (BOTH intents — adapt AND clone) or the user supplies their own image URLs: reference images are the user's assets, so re-host and reuse them rather than replacing them with stock photos, and never hotlink third-party hosts that may block hotlinking or disappear. The returned URLs go directly into specials.src — same as search_images results. Processes up to 20 URLs per call in parallel, with an 8 MB per-image cap. No Webcake credentials required (the upload endpoint is public). DEFAULTS to dry_run=true (returns a preview of what would be uploaded, no network calls); set dry_run=false to actually upload. Use search_images instead when you need stock photos.", {
         urls: z
             .array(z.string())
             .min(1)

package/package.json

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