webcake-landing-mcp 1.4.0 → 1.5.0

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.5.0",
+    "d": "23/07/2026",
+    "type": "Added",
+    "en": "search_images now returns a sizes map on every photo (the delivered width/height in px for each src variant, accounting for retina dpr) plus a…",
+    "vi": "search_images nay trả về một sizes map trên mỗi ảnh (kích thước width/height thực tế theo px của từng biến thể src, có tính đến dpr cho màn hình…"
+  },
   {
     "v": "1.4.0",
     "d": "23/07/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "create_page, add_section, and validate_page now apply a deterministic layout auto-fix before validating or saving: off-canvas children are pulled…",
     "vi": "create_page, add_section và validate_page nay tự động áp dụng một lần auto-fix layout xác định trước khi validate hoặc lưu: các phần tử con nằm…"
-  },
-  {
-    "v": "1.0.84",
-    "d": "17/06/2026",
-    "type": "Added",
-    "en": "create_page now sends a by_ai field in the create request body (default value \"mcp\") so the backend can stamp each MCP-generated page in its by_ai…",
-    "vi": "create_page nay gửi thêm trường by_ai trong body của request tạo trang (giá trị mặc định \"mcp\") để backend có thể đánh dấu từng trang được tạo qua…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -114,7 +114,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). The save AUTO-HOSTS external image URLs: any real http(s) URL you put in specials.src / a url(...) background / gallery item.link / video poster gets downloaded and re-hosted to the Webcake CDN automatically on create_page/update_page/add_section/patch_page (the response's rehost field reports the count) — so reference and web image URLs do NOT need a pre-call to upload_images. SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image, canvas src/background) → put the REAL source URL straight into the slot and let the save host it; use those EXACT images, never swap them for stock photos, and carry the URL through un-altered (never drop it, never placeholder a slot that had a real source image). The ONE case you must call upload_images yourself FIRST: LOCAL FILE PATHS from the user's computer (pass the path directly in upload_images 'urls' — the save can't read local files; NEVER relay the user's local file through a third-party host like catbox or imgur), then use the returned URL. (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); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). 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.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). The save AUTO-HOSTS external image URLs: any real http(s) URL you put in specials.src / a url(...) background / gallery item.link / video poster gets downloaded and re-hosted to the Webcake CDN automatically on create_page/update_page/add_section/patch_page (the response's rehost field reports the count) — so reference and web image URLs do NOT need a pre-call to upload_images. SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image, canvas src/background) → put the REAL source URL straight into the slot and let the save host it; use those EXACT images, never swap them for stock photos, and carry the URL through un-altered (never drop it, never placeholder a slot that had a real source image). The ONE case you must call upload_images yourself FIRST: LOCAL FILE PATHS from the user's computer (pass the path directly in upload_images 'urls' — the save can't read local files; NEVER relay the user's local file through a third-party host like catbox or imgur), then use the returned URL. (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. MATCH THE VARIANT TO THE SLOT SIZE — search_images returns a per-photo \`sizes\` map (delivered WxH per variant) + a \`size_guide\`; pick the variant whose width ≈ the element's RENDERED width (×1–2 for retina), then stop: full-bleed hero/banner (~900–1200px) → src.large (~940px) or src.large2x (~1880px); feature card/thumb (~260–360px) → src.medium (~350px); avatar/logo (~64–120px) → src.tiny (280px). NEVER stretch a small variant across a big slot — it pixelates ('vỡ ảnh'); NEVER put src.original (full-res, often several MB) or an oversized variant in a small card — it makes the page slow/heavy ('nặng trang'). If a photo's NATIVE width (photo.width) is smaller than the slot, pick a higher-res photo instead of upscaling. (avg_color helps pick a matching section background); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). 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.

package/dist/persistence/pexels-client.js

@@ -57,6 +57,54 @@ export function normalizePhoto(p) {
         src: p?.src && typeof p.src === "object" ? p.src : {},
     };
 }
+/**
+ * Delivered pixel size of ONE Pexels src-variant URL. Pexels encodes the size in
+ * the query string (`w`, `h`, and `dpr` for retina): `large`/`large2x` carry
+ * `w`+`h` (large2x adds `dpr=2` → the file is twice as many pixels), `medium`/
+ * `small` carry only `h` (width follows the native aspect ratio), and `original`
+ * has NO query params → it is the full native resolution. `dpr` multiplies both
+ * sides because the served file really is that many pixels. Pure + defensive:
+ * an unparseable URL or a variant with no size hint falls back to native w/h.
+ */
+export function variantPixels(url, nativeW, nativeH) {
+    const aspect = nativeW > 0 && nativeH > 0 ? nativeW / nativeH : 1;
+    let q;
+    try {
+        q = new URL(url).searchParams;
+    }
+    catch {
+        return { w: nativeW || 0, h: nativeH || 0 };
+    }
+    const dprRaw = parseInt(q.get("dpr") ?? "1", 10);
+    const dpr = Number.isFinite(dprRaw) && dprRaw > 0 ? dprRaw : 1;
+    const wRaw = parseInt(q.get("w") ?? "", 10);
+    const hRaw = parseInt(q.get("h") ?? "", 10);
+    const hasW = Number.isFinite(wRaw) && wRaw > 0;
+    const hasH = Number.isFinite(hRaw) && hRaw > 0;
+    if (!hasW && !hasH)
+        return { w: nativeW || 0, h: nativeH || 0 }; // original / no size hint
+    const baseW = hasW ? wRaw : Math.round(hRaw * aspect);
+    const baseH = hasH ? hRaw : Math.round(wRaw / aspect);
+    return { w: baseW * dpr, h: baseH * dpr };
+}
+/** Map every src variant of a photo to its delivered {w,h} in px (see variantPixels). */
+export function annotateVariantSizes(photo) {
+    const out = {};
+    for (const [variant, url] of Object.entries(photo.src ?? {})) {
+        if (typeof url === "string" && url)
+            out[variant] = variantPixels(url, photo.width, photo.height);
+    }
+    return out;
+}
+/**
+ * How to pick the RIGHT variant: match the delivered width to the slot's rendered
+ * width — too small pixelates ("vỡ ảnh"), too big bloats the page ("nặng trang").
+ * Returned in search_images responses so the model chooses by size, not just topic.
+ */
+export const IMAGE_SIZE_GUIDE = "Match the src variant's delivered WIDTH (see each photo's `sizes` map) to the slot's RENDERED width — aim for ~1–2× it (extra headroom = crisp on retina), then STOP. " +
+    "Rules of thumb on the 960/1200 canvas: full-bleed hero/banner (~900–1200px wide) → src.large (940px) or src.large2x (1880px, retina); half-hero / product shot (~450–650px) → src.large or src.medium; feature card / thumbnail (~260–360px) → src.medium (~350px); avatar / logo / small icon (~64–120px) → src.tiny (280px). " +
+    "NEVER stretch a small variant across a big slot — upscaling looks broken/pixelated ('vỡ ảnh'). NEVER drop src.original (full-res, often several MB) or an oversized variant into a small card — it makes the page slow and heavy ('nặng trang'). " +
+    "Also check the photo's NATIVE width/height: if a photo's native width is smaller than the slot, it cannot fill it crisply — choose a higher-resolution photo (or a smaller slot) rather than upscaling.";
 /** Build the shared query string for both the direct Pexels call and the proxy. */
 export function buildSearchQuery(params) {
     const q = new URLSearchParams();

package/dist/smoke.js

@@ -14,7 +14,7 @@ import { parseHtml, extractTailwindConfig } from "./persistence/html-ingest.js";
 import { warningsField } from "./mcp/response.js";
 import { readConfig, resolveEnv, ENV_NAMES, configFromHeaders } from "./persistence/config.js";
 import { toEditorUrl, toEditorLoginUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
-import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
+import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT, variantPixels, annotateVariantSizes } from "./persistence/pexels-client.js";
 import { putDraft, getDraft, updateDraft, deleteDraft } from "./persistence/draft-cache.js";
 import { buildConnectUrl, parseCallback } from "./auth/login.js";
 import { isLocalPath, resolveLocalPath, sniffMime, localContentType } from "./tools/media.js";
@@ -1143,6 +1143,25 @@ console.log("== pexels: key resolution + photo normalization (offline, no networ
     const q = buildSearchQuery({ query: "coffee cup", perPage: 3, orientation: "landscape" });
     check("buildSearchQuery encodes query + per_page + orientation", q.get("query") === "coffee cup" && q.get("per_page") === "3" && q.get("orientation") === "landscape");
     check("buildSearchQuery clamps per_page to 1..80", buildSearchQuery({ query: "x", perPage: 999 }).get("per_page") === "80" && buildSearchQuery({ query: "x", perPage: 0 }).get("per_page") === "1");
+    // variantPixels: parse the delivered pixel size from a Pexels src-variant URL.
+    const large = variantPixels("https://images.pexels.com/photos/1/x.jpeg?auto=compress&cs=tinysrgb&h=650&w=940", 4000, 2600);
+    check("variantPixels: large reads w+h from query", large.w === 940 && large.h === 650, large);
+    const large2x = variantPixels("https://images.pexels.com/photos/1/x.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940", 4000, 2600);
+    check("variantPixels: dpr=2 doubles both sides (retina)", large2x.w === 1880 && large2x.h === 1300, large2x);
+    const medium = variantPixels("https://images.pexels.com/photos/1/x.jpeg?auto=compress&cs=tinysrgb&h=350", 4000, 2000);
+    check("variantPixels: h-only derives width from native aspect (2:1 → 700×350)", medium.w === 700 && medium.h === 350, medium);
+    const original = variantPixels("https://images.pexels.com/photos/1/x.jpeg", 4000, 2600);
+    check("variantPixels: no query → native size", original.w === 4000 && original.h === 2600, original);
+    check("variantPixels: unparseable URL → native size", variantPixels("not a url", 800, 600).w === 800);
+    const annotated = annotateVariantSizes(normalizePhoto({
+        id: 1, width: 3840, height: 2160,
+        src: {
+            original: "https://images.pexels.com/photos/1/x.jpeg",
+            large: "https://images.pexels.com/photos/1/x.jpeg?h=650&w=940",
+            medium: "https://images.pexels.com/photos/1/x.jpeg?h=350",
+        },
+    }));
+    check("annotateVariantSizes maps every variant to {w,h}", annotated.original.w === 3840 && annotated.large.w === 940 && annotated.medium.h === 350, annotated);
 }
 console.log("== draft-cache: page draft round-trip (create_page failure flow) ==");
 {

package/dist/tools/media.js

@@ -27,7 +27,7 @@ import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { text, image, images } from "../mcp/response.js";
-import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
+import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, annotateVariantSizes, IMAGE_SIZE_GUIDE, } from "../persistence/pexels-client.js";
 import { captureScreenshot, captureScreenshotTiles, resolveScreenshotProxyBase, screenshotProxyBaseFromHeaders, resolveMicrolinkKey, microlinkKeyFromHeaders, } from "../persistence/screenshot-client.js";
 import { uploadImageMultipart, uploadImagePreferCollection, resolveCollectionOrgId, listOrganizations, } from "../persistence/webcake-client.js";
 import { resolveIconSvg } from "../persistence/icon-client.js";
@@ -196,7 +196,7 @@ export function localContentType(ext, buf) {
 }
 export function registerMediaTools(server, allowLocalFiles = true) {
     // 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. 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.", {
+    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, `avg_color` for matching section backgrounds, plus photographer name and attribution URL. PICK BY SIZE, NOT JUST TOPIC: each photo carries a `sizes` map (delivered WxH px per variant) and the response includes a `size_guide` — match the variant width to the slot's rendered width (hero/banner → src.large ~940px or src.large2x ~1880px retina; card/thumb → src.medium ~350px; avatar → src.tiny), because a too-small variant stretched across a big slot pixelates ('vỡ ảnh') and src.original / an oversized variant in a small card bloats the page ('nặng trang'). 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())
@@ -225,6 +225,10 @@ export function registerMediaTools(server, allowLocalFiles = true) {
             const params = { query: q, perPage: per_page, page, orientation, size, color };
             return key ? searchPexels(key, params) : searchImagesViaProxy(base, params);
         };
+        // Annotate a photo with the delivered pixel size of each src variant so the
+        // model can match variant width to the slot's rendered width (too small →
+        // pixelated, too big → heavy page). Non-mutating: returns an enriched copy.
+        const withSizes = (p) => ({ ...p, sizes: annotateVariantSizes(p) });
         // Dedup + parallelize so two slots asking for the same subject only cost one call.
         const unique = [...new Set(list)];
         const results = await Promise.all(unique.map(runOne));
@@ -237,7 +241,7 @@ export function registerMediaTools(server, allowLocalFiles = true) {
                     hint: "Couldn't fetch images — set PEXELS_API_KEY (env) or the x-pexels-key header for your own Pexels key (free at https://www.pexels.com/api/), or fall back to https://placehold.co/<width>x<height> placeholders.",
                 });
             }
-            return text(r);
+            return text({ ...r, photos: (r.photos ?? []).map(withSizes), size_guide: IMAGE_SIZE_GUIDE });
         }
         // Batch mode → { queries: { [q]: best-photo-or-full } }.
         const mode = pick ?? "best";
@@ -251,10 +255,10 @@ export function registerMediaTools(server, allowLocalFiles = true) {
             }
             out[q] =
                 mode === "all"
-                    ? r
-                    : { ok: true, photo: r.photos?.[0] ?? null, total_results: r.total_results };
+                    ? { ...r, photos: (r.photos ?? []).map(withSizes) }
+                    : { ok: true, photo: r.photos?.[0] ? withSizes(r.photos[0]) : null, total_results: r.total_results };
         }
-        return text({ queries: out });
+        return text({ queries: out, size_guide: IMAGE_SIZE_GUIDE });
     });
     // 13b) Resolve icon-font names to real inline SVGs --------------------------
     server.tool("get_icon_svg", "Resolves icon-font NAMES into real inline SVG markup via the public Iconify API — so a clone reproduces a reference's icons (esp. Google Stitch, which renders icons with a Material Symbols / Font Awesome CLASS, not an image). ingest_html/ingest_url surface those icons as block.icon \"ms:<name>\" (Material Symbols) / \"fa:<name>\" (Font Awesome); pass them here to get the SVG. ACCEPTS: \"ms:verified\", \"fa:chart-line\", a real Iconify id (\"mdi:home\"), or a bare name (assumed Material Symbols); underscores are normalized to hyphens, and Material Symbols resolve to the OUTLINED variant (the Stitch look) with a filled fallback. Returns { icons: { \"<ref>\": { ok, svg, iconify } } }. RENDER each svg as Webcake's native icon element — a RECTANGLE: put the svg in BOTH responsive.desktop.config.svgMask AND responsive.mobile.config.svgMask, set styles.background = the icon color, and keep the box SQUARE (width === height). The svg is only a MASK (its own fill is ignored), so the icon is BLANK without a solid styles.background; the renderer reads each breakpoint's svgMask separately (no fallback) and forces preserveAspectRatio='none' (a non-square box stretches it). No Webcake credentials needed.", {

package/package.json

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