webcake-landing-mcp 1.5.1 → 1.5.2

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.5.2",
+    "d": "25/08/2026",
+    "type": "Fixed",
+    "en": "Colors written in any CSS notation other than the legacy rgba(r,g,b,a) form (hex, rgb(), hsl(), CSS named colors, and the modern space/slash rgba()…",
+    "vi": "Các giá trị màu được viết ở bất kỳ dạng CSS nào khác ngoài dạng rgba(r,g,b,a) kiểu cũ (hex, rgb(), hsl(), tên màu CSS, và cú pháp rgba() mới dùng…"
+  },
   {
     "v": "1.5.1",
     "d": "24/08/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "Server instructions and get_generation_guide now restrict the visual-check step to three explicit triggers — cloning a reference to compare pixel…",
     "vi": "Instruction của server và get_generation_guide nay giới hạn bước visual-check chỉ trong ba trường hợp cụ thể — clone trang tham chiếu để so sánh độ…"
-  },
-  {
-    "v": "1.2.0",
-    "d": "21/06/2026",
-    "type": "Added",
-    "en": "New layout tool computes exact top/left/width/height coordinates for both breakpoints so the model never hand-calculates left/top (the number-one…",
-    "vi": "Tool mới layout tính toán chính xác tọa độ top/left/width/height cho cả hai breakpoint để model không cần tự tính left/top bằng tay (nguyên nhân…"
   }
 ]

package/dist/domains/landing/color.js

@@ -0,0 +1,235 @@
+/**
+ * Colour canonicalisation — pure helpers, no I/O, no domain imports.
+ *
+ * WHY THIS EXISTS. The live renderer emits colour values RAW into CSS, so a hex
+ * / `rgb()` / `hsl()` / named colour renders perfectly on the published page.
+ * The Webcake EDITOR does not: its colour traits re-parse the stored string with
+ * hand-rolled parsers that only understand the legacy comma `rgba(r,g,b,a)`
+ * form, and every one of them falls back to BLACK when the parse fails.
+ * Confirmed read paths in landing_page_backend/assets/editor:
+ *
+ *   • common.js:128 `parseBackground` scans for `url|linear-gradient|
+ *     radial-gradient|rgba` ONLY. Note the literal "rgba" — `rgb(...)` without
+ *     the `a` does not match either.
+ *   • traits/Background.vue:163 — for a text-block the background trait shows
+ *     `styles.color` (that IS the text-colour swatch: traitGroup.js:2 gives
+ *     text-block no 'color' trait). Background.vue:264-277 `makeBg()` runs the
+ *     value through `parseBackground` and, when nothing parses, pushes a
+ *     hard-coded `rgba(0, 0, 0, 1)` for a text-block.
+ *   • traits/Colour.vue:62-67 (button / form / countdown / …) — falls back to
+ *     `'#000000'` when `mixStyle.color` is falsy, and common.js:186
+ *     `rgbaToArray` does a blind `rgba.substr(5)`, so anything not starting with
+ *     `rgba(` decodes to NaN.
+ *
+ * So an MCP-authored page whose text colour is `#ffffff` renders white but shows
+ * BLACK in the editor's trait panel — and the moment a user touches that trait
+ * the black is written back and the page really does turn black.
+ *
+ * Fix: canonicalise every colour-bearing style/config value to `rgba(r,g,b,a)`
+ * during expand (see normalizeColors in ./index.ts). Values already in the
+ * legacy comma-`rgba()` form are returned BYTE-IDENTICAL so a save never
+ * rewrites colours the editor itself wrote.
+ */
+/** Split a CSS value into top-level (paren-aware) comma-separated layers. */
+export function splitCssLayers(value) {
+    const layers = [];
+    let depth = 0;
+    let cur = "";
+    for (const ch of value) {
+        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 exact shape the editor's parsers can read: `rgba(` + three comma-separated
+ * numbers + an alpha. A value matching this is left untouched.
+ * (`rgb(…)`, the modern `rgba(255 255 255 / .5)` space syntax, hex, hsl and
+ * named colours all FAIL the editor's parsers and must be converted.)
+ */
+export const EDITOR_RGBA = /^rgba\(\s*-?[\d.]+\s*,\s*-?[\d.]+\s*,\s*-?[\d.]+\s*,\s*-?[\d.]+%?\s*\)$/i;
+/**
+ * CSS-wide keywords and `transparent` — never rewritten. `transparent` in
+ * particular is load-bearing: the editor's Colour trait pairs it with
+ * `config.colorHidden` to implement its hide/show toggle (Colour.vue:126-133),
+ * so converting it to `rgba(0,0,0,0)` would break that toggle.
+ */
+const PASS_THROUGH = new Set([
+    "transparent", "inherit", "currentcolor", "initial", "unset", "revert", "none", "auto",
+]);
+/** The CSS named colours a model realistically writes. */
+const NAMED_COLORS = {
+    black: [0, 0, 0], white: [255, 255, 255], red: [255, 0, 0], lime: [0, 255, 0],
+    blue: [0, 0, 255], yellow: [255, 255, 0], cyan: [0, 255, 255], aqua: [0, 255, 255],
+    magenta: [255, 0, 255], fuchsia: [255, 0, 255], silver: [192, 192, 192],
+    gray: [128, 128, 128], grey: [128, 128, 128], maroon: [128, 0, 0], olive: [128, 128, 0],
+    green: [0, 128, 0], purple: [128, 0, 128], teal: [0, 128, 128], navy: [0, 0, 128],
+    orange: [255, 165, 0], gold: [255, 215, 0], pink: [255, 192, 203],
+    hotpink: [255, 105, 180], crimson: [220, 20, 60], salmon: [250, 128, 114],
+    coral: [255, 127, 80], tomato: [255, 99, 71], orangered: [255, 69, 0],
+    brown: [165, 42, 42], chocolate: [210, 105, 30], tan: [210, 180, 140],
+    beige: [245, 245, 220], ivory: [255, 255, 240], khaki: [240, 230, 140],
+    indigo: [75, 0, 130], violet: [238, 130, 238], orchid: [218, 112, 214],
+    plum: [221, 160, 221], lavender: [230, 230, 250], turquoise: [64, 224, 208],
+    skyblue: [135, 206, 235], steelblue: [70, 130, 180], royalblue: [65, 105, 225],
+    dodgerblue: [30, 144, 255], midnightblue: [25, 25, 112], seagreen: [46, 139, 87],
+    forestgreen: [34, 139, 34], darkgreen: [0, 100, 0], darkred: [139, 0, 0],
+    darkblue: [0, 0, 139], darkgray: [169, 169, 169], darkgrey: [169, 169, 169],
+    lightgray: [211, 211, 211], lightgrey: [211, 211, 211], dimgray: [105, 105, 105],
+    dimgrey: [105, 105, 105], slategray: [112, 128, 144], slategrey: [112, 128, 144],
+    whitesmoke: [245, 245, 245], snow: [255, 250, 250], linen: [250, 240, 230],
+    wheat: [245, 222, 179], mintcream: [245, 255, 250], aliceblue: [240, 248, 255],
+    ghostwhite: [248, 248, 255],
+};
+const clampByte = (n) => Math.max(0, Math.min(255, Math.round(n)));
+/** 1 → "1", 0.5 → "0.5", 0.88 → "0.88" (never "1.000" — matches the guide's shape). */
+function fmtAlpha(a) {
+    if (!Number.isFinite(a))
+        return "1";
+    const clamped = Math.max(0, Math.min(1, a));
+    const s = clamped.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+    return s === "" ? "0" : s;
+}
+const rgba = (r, g, b, a) => `rgba(${clampByte(r)},${clampByte(g)},${clampByte(b)},${fmtAlpha(a)})`;
+/** One channel of an rgb() function: a 0–255 number or a percentage. */
+function channel(tok) {
+    return tok.endsWith("%") ? (parseFloat(tok) / 100) * 255 : parseFloat(tok);
+}
+/** An rgb()/hsl() alpha argument: a 0–1 number or a percentage. */
+function alphaArg(tok) {
+    if (tok === undefined)
+        return 1;
+    return tok.endsWith("%") ? parseFloat(tok) / 100 : parseFloat(tok);
+}
+/** hsl → rgb (h in degrees, s/l as 0–1 fractions). */
+function hslToRgb(h, s, l) {
+    const hh = (((h % 360) + 360) % 360) / 60;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs((hh % 2) - 1));
+    const m = l - c / 2;
+    const [r, g, b] = hh < 1 ? [c, x, 0] : hh < 2 ? [x, c, 0] : hh < 3 ? [0, c, x]
+        : hh < 4 ? [0, x, c] : hh < 5 ? [x, 0, c] : [c, 0, x];
+    return [(r + m) * 255, (g + m) * 255, (b + m) * 255];
+}
+/**
+ * Canonicalise ONE colour token to the editor-readable `rgba(r,g,b,a)`.
+ * Returns null when the token needs no change (already editor-readable, a
+ * CSS-wide keyword) or cannot be understood (`var(--x)`, `color-mix(…)`, …) —
+ * so a caller can leave the original string exactly as it found it.
+ */
+export function toRgba(input) {
+    const s = input.trim();
+    if (s === "")
+        return null;
+    if (EDITOR_RGBA.test(s))
+        return null; // already the shape every editor trait parses
+    const lower = s.toLowerCase();
+    if (PASS_THROUGH.has(lower))
+        return null;
+    const hex = lower.match(/^#([0-9a-f]+)$/);
+    if (hex) {
+        const h = hex[1];
+        const dup = (c) => parseInt(c + c, 16);
+        const pair = (i) => parseInt(h.slice(i, i + 2), 16);
+        if (h.length === 3)
+            return rgba(dup(h[0]), dup(h[1]), dup(h[2]), 1);
+        if (h.length === 4)
+            return rgba(dup(h[0]), dup(h[1]), dup(h[2]), dup(h[3]) / 255);
+        if (h.length === 6)
+            return rgba(pair(0), pair(2), pair(4), 1);
+        if (h.length === 8)
+            return rgba(pair(0), pair(2), pair(4), pair(6) / 255);
+        return null; // 5/7-digit hex is not valid CSS — leave it for the validator to flag
+    }
+    // rgb()/rgba() in ANY separator syntax (comma, space, slash alpha).
+    const rgbFn = lower.match(/^rgba?\(([^()]*)\)$/);
+    if (rgbFn) {
+        const parts = rgbFn[1].split(/[\s,/]+/).filter((p) => p !== "");
+        if (parts.length < 3)
+            return null;
+        const [r, g, b] = [channel(parts[0]), channel(parts[1]), channel(parts[2])];
+        const a = alphaArg(parts[3]);
+        if (![r, g, b, a].every(Number.isFinite))
+            return null;
+        return rgba(r, g, b, a);
+    }
+    const hslFn = lower.match(/^hsla?\(([^()]*)\)$/);
+    if (hslFn) {
+        const parts = hslFn[1].split(/[\s,/]+/).filter((p) => p !== "");
+        if (parts.length < 3)
+            return null;
+        const h = parseFloat(parts[0]); // deg/turn/rad suffixes: parseFloat takes the number, deg is the default
+        const sat = parseFloat(parts[1]) / 100;
+        const lig = parseFloat(parts[2]) / 100;
+        const a = alphaArg(parts[3]);
+        if (![h, sat, lig, a].every(Number.isFinite))
+            return null;
+        const [r, g, b] = hslToRgb(h, Math.max(0, Math.min(1, sat)), Math.max(0, Math.min(1, lig)));
+        return rgba(r, g, b, a);
+    }
+    const named = NAMED_COLORS[lower];
+    return named ? rgba(named[0], named[1], named[2], 1) : null;
+}
+/**
+ * Colour tokens INSIDE a gradient layer. The bare-word alternative catches named
+ * colours (`linear-gradient(180deg, white 0%, black 100%)`); gradient keywords
+ * (`to`, `deg`, `circle`, `closest-side`…) are not colour names, so toRgba
+ * returns null for them and they pass through untouched.
+ */
+const COLOR_TOKEN = /#[0-9a-fA-F]+\b|\b(?:rgba?|hsla?)\([^()]*\)|\b[a-zA-Z]{3,20}\b/g;
+/**
+ * Canonicalise every colour in a full style value — a bare colour, a
+ * comma-separated layer list, or the colour stops inside a gradient. `url()`
+ * layers are left alone (normalizeBackgrounds in ./index.ts owns those).
+ * Returns the ORIGINAL string when nothing needed changing, so the pass is
+ * byte-stable and idempotent.
+ */
+export function normalizeColorValue(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        return value;
+    let changed = false;
+    const out = splitCssLayers(value).map((layer) => {
+        if (layer.includes("url("))
+            return layer;
+        const next = /gradient\(/i.test(layer)
+            ? layer.replace(COLOR_TOKEN, (tok) => toRgba(tok) ?? tok)
+            : toRgba(layer) ?? layer;
+        if (next !== layer)
+            changed = true;
+        return next;
+    });
+    return changed ? out.join(", ") : value;
+}
+/**
+ * True for a style/config key whose value is a colour the editor's traits parse:
+ * anything named `*color*` (color, borderColor, colorBtn, iconColor, …) plus the
+ * three colour-bearing keys that are not spelled "color".
+ */
+export function isColorKey(key) {
+    return /colou?r/i.test(key) || key === "background" || key === "backgroundTxt" || key === "overlay";
+}
+/**
+ * True when a colour value will render BLACK in the editor's trait panel: not a
+ * gradient/url, not a CSS-wide keyword, and not the legacy `rgba()` form the
+ * traits can parse. Used by the validator to warn about the values
+ * normalizeColorValue could not rescue (`var(--x)`, `color-mix(…)`, …).
+ */
+export function isUnparseableByEditor(value) {
+    if (typeof value !== "string")
+        return false;
+    const s = value.trim();
+    if (s === "" || PASS_THROUGH.has(s.toLowerCase()))
+        return false;
+    if (s.includes("url(") || /gradient\(/i.test(s))
+        return false;
+    return splitCssLayers(s).some((layer) => !EDITOR_RGBA.test(layer));
+}

package/dist/domains/landing/guide.js

@@ -113,7 +113,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) — always EMIT numbers. (Reading an existing page you may still meet strings: the editor saves fontSize as "59"/"13px", height as "600", opacity as "50%". The server normalizes those back to numbers on both get_page and save, so a hand-edited page is never locked out of the MCP; only a value with a unit the renderer cannot use — e.g. width:"100%" — is reported, as a warning.) 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.
+- Colors as rgba(r,g,b,a) — ALWAYS, and on BOTH breakpoints. The published page renders any CSS color, but the EDITOR does not read them all back: its color traits only parse the rgba() form, so a hex / rgb() / hsl() / named color shows BLACK in the trait panel and that black is SAVED the first moment a user touches the trait; and because the traits read one breakpoint at a time with no desktop→mobile fallback, a color set on only one breakpoint shows black on the other (and renders black there, since that breakpoint's CSS carries no color at all). The server repairs both slips on every save — it converts hex/rgb()/hsl()/named to rgba() and mirrors color/backgroundTxt/borderColor onto the breakpoint that lacks it — but write rgba() on both breakpoints yourself; what it cannot convert (var(--x), color-mix(…)) comes back as a warning. fontSize/borderWidth/top/left/width/height are NUMBERS (px) — always EMIT numbers. (Reading an existing page you may still meet strings: the editor saves fontSize as "59"/"13px", height as "600", opacity as "50%". The server normalizes those back to numbers on both get_page and save, so a hand-edited page is never locked out of the MCP; only a value with a unit the renderer cannot use — e.g. width:"100%" — is reported, as a warning.) 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. 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 {}.

package/dist/domains/landing/index.js

@@ -9,6 +9,7 @@ import { autofixLayout } from "./autofix-layout.js";
 import { computeLayout } from "./layout.js";
 import { expandSource } from "../../core/expand.js";
 import { compactSource } from "../../core/compact.js";
+import { splitCssLayers, normalizeColorValue, isColorKey } from "./color.js";
 /** The payload returned by the get_generation_guide tool. */
 export const guidePayload = {
     guide: GENERATION_GUIDE,
@@ -135,26 +136,6 @@ function normalizeBorderRadius(node) {
 // 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). */
@@ -162,7 +143,7 @@ function normalizeBackgroundValue(bg) {
     if (typeof bg !== "string" || !bg.includes("url("))
         return bg;
     const out = [];
-    for (const layer of splitBackgroundLayers(bg)) {
+    for (const layer of splitCssLayers(bg)) {
         const url = layer.match(/url\((['"]?)(.*?)\1\)/);
         if (url) {
             out.push(CANONICAL_URL_LAYER.test(layer) ? layer : imgBackground(url[2]));
@@ -191,6 +172,80 @@ function normalizeBackgrounds(node) {
     }
 }
 // ---------------------------------------------------------------------------
+// colour normalization: the live renderer emits colours RAW into CSS, so a hex
+// / rgb() / hsl() / named colour renders perfectly on the published page — but
+// the EDITOR's colour traits re-parse the stored string and every one of them
+// falls back to BLACK when the parse fails. `parseBackground` (common.js:128)
+// scans for `url|linear-gradient|radial-gradient|rgba` only — note the literal
+// "rgba", so even `rgb(...)` misses — and for a text-block the colour swatch IS
+// that background trait (Background.vue:163 returns styles.color; :272-273
+// pushes a hard-coded rgba(0,0,0,1) when nothing parsed). Colour.vue:67 does the
+// same with '#000000' for button/form/countdown. So `color:"#ffffff"` renders
+// white but shows BLACK in the trait panel — and one touch of that trait writes
+// the black back and the page really does turn black.
+//
+// Second half of the same bug: the traits read `el.responsive[display].styles`
+// (Trait.vue:377-380) with NO desktop→mobile fallback, so a colour set on one
+// breakpoint only shows black on the other — and renders black there too, since
+// the breakpoint's CSS simply carries no colour declaration.
+//
+// Fix: after every expand pass, (a) canonicalise every colour-bearing style/
+// config value to the legacy `rgba(r,g,b,a)` form every editor parser reads, and
+// (b) mirror a foreground colour set on exactly one breakpoint onto the other.
+// Values already in that form are returned byte-identical, so a save never
+// rewrites the colours the editor itself wrote. Deterministic + idempotent, so
+// the expand(compact(x)) == expand(x) invariant holds.
+// ---------------------------------------------------------------------------
+/**
+ * Colour keys copied to the other breakpoint when only one carries them.
+ * Deliberately a short ALLOWLIST, not every `*color*` key: mirroring
+ * `-webkitTextFillColor:transparent` (the gradient-text-fill recipe) without the
+ * gradient `background` that goes with it would render the mobile text
+ * invisible, and a url()-bearing `background` can legitimately differ per
+ * breakpoint. These three are inert when the other breakpoint has no matching
+ * geometry (a borderColor with borderWidth:0 paints nothing).
+ */
+const MIRRORED_COLOR_KEYS = ["color", "backgroundTxt", "borderColor"];
+/** Walk a tree node and canonicalise + mirror every colour in-place (mutates). */
+function normalizeColors(node) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const bp of ["desktop", "mobile"]) {
+        const rbp = node.responsive?.[bp];
+        if (!rbp || typeof rbp !== "object")
+            continue;
+        for (const bag of [rbp.styles, rbp.config]) {
+            if (!bag || typeof bag !== "object")
+                continue;
+            for (const key of Object.keys(bag)) {
+                if (!isColorKey(key))
+                    continue;
+                const fixed = normalizeColorValue(bag[key]);
+                if (fixed !== bag[key])
+                    bag[key] = fixed;
+            }
+        }
+    }
+    const desktop = node.responsive?.desktop?.styles;
+    const mobile = node.responsive?.mobile?.styles;
+    if (desktop && typeof desktop === "object" && mobile && typeof mobile === "object") {
+        for (const key of MIRRORED_COLOR_KEYS) {
+            const dv = desktop[key];
+            const mv = mobile[key];
+            const dHas = typeof dv === "string" && dv.trim() !== "";
+            const mHas = typeof mv === "string" && mv.trim() !== "";
+            if (dHas && !mHas)
+                mobile[key] = dv;
+            else if (mHas && !dHas)
+                desktop[key] = mv;
+        }
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            normalizeColors(child);
+    }
+}
+// ---------------------------------------------------------------------------
 // misplaced-animation normalization: models regularly emit the animation object
 // directly under responsive.<bp> instead of responsive.<bp>.config.animation —
 // the single most common "must NOT have additional properties" schema error,
@@ -335,6 +390,10 @@ function normalizeSource(source) {
                 normalizeMisplacedAnimation(node);
                 normalizeImageBlocks(node);
                 normalizeBorderRadius(node);
+                // Colours BEFORE backgrounds: the colour pass rewrites gradient stops
+                // and bare-colour layers, the background pass then canonicalises any
+                // url() layer in the same value.
+                normalizeColors(node);
                 normalizeBackgrounds(node);
             }
         }

package/dist/domains/landing/page-schema.json

@@ -103,9 +103,9 @@
         "height": { "type": ["number", "string", "null"], "description": "px. Section uses this as canvas height. EMIT A NUMBER (the editor saves the string \"600\" when the height box loses focus — normalized on read)." },
         "position": { "type": "string", "enum": ["absolute", "relative", "fixed", "static"] },
         "zIndex": { "type": ["number", "string", "null"], "description": "Stacking order. EMIT A NUMBER; numeric strings are normalized." },
-        "background": { "type": "string", "description": "rgba(...) or gradient." },
+        "background": { "type": "string", "description": "rgba(...) or gradient. MUST use the rgba() form for every color/gradient stop — the editor's background trait only parses url()/linear-gradient()/radial-gradient()/rgba(), and falls back to BLACK on anything else (hex, rgb(), hsl(), named). Auto-converted on save; unconvertible values are warned." },
         "backgroundImage": { "type": "string", "description": "url(...)." },
-        "color": { "type": "string", "description": "rgba(r,g,b,a)." },
+        "color": { "type": "string", "description": "rgba(r,g,b,a). Set it on BOTH breakpoints: the editor trait reads one breakpoint at a time with no desktop\u2192mobile fallback, and a missing/unparseable color shows (and saves back) BLACK. hex/rgb()/hsl()/named are auto-converted to rgba() on save, and a color present on only one breakpoint is mirrored onto the other." },
         "fontSize": { "type": ["number", "string"], "description": "px. EMIT A NUMBER. Read-tolerance: the editor saves \"59\" (inline text-resize box) and \"13px\" (element pickers); the renderer parseInt()s it, and the MCP normalizes both back to a number." },
         "fontFamily": { "type": "string" },
         "fontWeight": { "type": ["string", "number"] },
@@ -117,7 +117,7 @@
         "textDecoration": { "type": "string" },
         "borderStyle": { "type": "string", "enum": ["none", "solid", "dashed", "dotted", "double", "groove", "ridge", "inset", "outset", "hidden"], "description": "The full set the editor's border-style dropdown offers (Border.vue)." },
         "borderWidth": { "type": ["number", "string"], "description": "px. EMIT A NUMBER. Read-tolerance: the editor saves \"1\" / \"0px\"; parseInt()ed by the renderer and normalized here." },
-        "borderColor": { "type": "string" },
+        "borderColor": { "type": "string", "description": "rgba(r,g,b,a) \u2014 same editor-parse rule as styles.color (auto-converted + mirrored across breakpoints on save)." },
         "borderRadius": { "type": ["string", "number"] },
         "boxShadow": { "type": "string" },
         "opacity": { "type": ["number", "string"], "description": "0–1. EMIT A NUMBER. Read-tolerance: the editor Layer trait saves a percent string (\"50%\") — normalized to the 0–1 fraction (0.5) before validation." },
@@ -145,7 +145,7 @@
           }
         },
         "virtualHeight": { "type": ["number", "string", "null"] },
-        "overlay": { "type": "string", "description": "Overlay color rgba(...)." },
+        "overlay": { "type": "string", "description": "Overlay color rgba(...) \u2014 the editor's overlay trait only parses the rgba() form; other notations are auto-converted on save." },
         "hiddenEffect": { "type": "object", "additionalProperties": true },
         "svgMask": { "type": "string" },
         "lock": { "type": "boolean" },

package/dist/domains/landing/validate.js

@@ -11,6 +11,7 @@ import Ajv2020Module from "ajv/dist/2020.js";
 import { CONTAINER_TYPES, FIELD_TYPES } from "./elements/index.js";
 import { ANIMATABLE_TYPES, ANIMATION_NAMES } from "./vocab.js";
 import { estTextHeightPx, measureTextBlock } from "./text-metrics.js";
+import { isColorKey, isUnparseableByEditor } from "./color.js";
 // ajv ships as CJS; under Node16 ESM the constructor is on `.default`.
 const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
 // Loaded at runtime (the build copies this JSON beside the compiled validator)
@@ -395,6 +396,28 @@ export function validatePage(input) {
                     `for a muted color use rgba() alpha on the color/background property instead.`);
             }
         }
+        // A colour the editor's traits cannot parse shows BLACK in the trait panel
+        // (Background.vue:272-273 / Colour.vue:67) even though the published page
+        // renders it correctly — and one touch of that trait writes the black back.
+        // landingDomain.expand already converts hex / rgb() / hsl() / named colours,
+        // so this fires only for values it could not rescue (var(--x), color-mix(…)).
+        for (const bp of ["desktop", "mobile"]) {
+            const rbp = node.responsive?.[bp];
+            if (!rbp || typeof rbp !== "object")
+                continue;
+            for (const [bag, label] of [[rbp.styles, "styles"], [rbp.config, "config"]]) {
+                if (!bag || typeof bag !== "object")
+                    continue;
+                for (const key of Object.keys(bag)) {
+                    if (!isColorKey(key) || !isUnparseableByEditor(bag[key]))
+                        continue;
+                    warnings.push(`${path} (${type ?? "?"}) [${bp}]: ${label}.${key}="${bag[key]}" is not an rgba() colour — ` +
+                        `the editor's colour trait cannot parse it and shows BLACK, then writes that black back the first ` +
+                        `time a user touches the trait. Use rgba(r,g,b,a): ` +
+                        `patch_page({op:'update',id:'${node.id ?? "?"}',${label}:{${bp}:{${key}:'rgba(…)'}}}).`);
+                }
+            }
+        }
         // countdown.language must be a key the renderer's lang table knows (or 'custom');
         // anything else (e.g. a locale code "vi"/"en") crashes the renderer with
         // "is not iterable" when it destructures lang[language].

package/dist/smoke.js

@@ -1535,6 +1535,87 @@ console.log("== background normalization: url() layers canonicalised to the edit
     const reexpanded = landingDomain.expand(landingDomain.compact(expanded));
     check("background round-trip: expand(compact(expand(x))) deep-equals expand(x)", deepEq(reexpanded, expanded));
 }
+console.log("== colour normalization: editor-readable rgba() + breakpoint mirroring ==");
+{
+    // A text-block is the sharpest case: traitGroup.js gives it no 'color' trait,
+    // so its colour swatch IS the background trait, which falls back to a
+    // hard-coded rgba(0,0,0,1) whenever parseBackground() finds nothing.
+    const mkColorPage = (desktop, mobile = desktop) => ({
+        page: [
+            {
+                id: "c_sec", type: "section",
+                responsive: {
+                    desktop: { styles: { height: 400 } },
+                    mobile: { styles: { height: 400 } },
+                },
+                children: [
+                    {
+                        id: "c_txt", type: "text-block",
+                        responsive: {
+                            desktop: { styles: { top: 10, left: 10, width: 200, height: 40, ...desktop } },
+                            mobile: { styles: { top: 10, left: 10, width: 200, height: 40, ...mobile } },
+                        },
+                        specials: { text: "hello", tag: "p" },
+                    },
+                ],
+            },
+        ],
+        settings: { title: "t", description: "d", keywords: "k", lang: "vi" },
+    });
+    const txtOf = (src, bp = "desktop") => src.page[0].children[0].responsive[bp].styles;
+    // 1) every notation a model realistically writes → the one form the editor parses
+    const cases = [
+        ["hex #ffffff", "#ffffff", "rgba(255,255,255,1)"],
+        ["short hex #fff", "#fff", "rgba(255,255,255,1)"],
+        ["hex+alpha #ffffff80", "#ffffff80", "rgba(255,255,255,0.502)"],
+        ["rgb() (no 'a' → parseBackground misses it)", "rgb(246,4,87)", "rgba(246,4,87,1)"],
+        ["modern slash syntax", "rgba(255 255 255 / 0.5)", "rgba(255,255,255,0.5)"],
+        ["hsl()", "hsl(340,96%,49%)", "rgba(245,5,85,1)"],
+        ["named colour", "white", "rgba(255,255,255,1)"],
+    ];
+    for (const [label, input, want] of cases) {
+        const got = txtOf(landingDomain.expand(mkColorPage({ color: input }))).color;
+        check(`colour: ${label} → ${want}`, got === want, got);
+    }
+    // 2) values the editor ALREADY reads are returned byte-identical (no save churn)
+    for (const untouched of ["rgba(26,32,44,1)", "rgba(0, 0, 0, 1)", "rgba(13,45,58,0.88)", "transparent"]) {
+        const got = txtOf(landingDomain.expand(mkColorPage({ color: untouched }))).color;
+        check(`colour: "${untouched}" left byte-identical`, got === untouched, got);
+    }
+    // 3) idempotent — a second expand changes nothing
+    const once = landingDomain.expand(mkColorPage({ color: "#1a202c" }));
+    const twice = landingDomain.expand(structuredClone(once));
+    check("colour: normalization is idempotent", deepEq(twice, once));
+    // 4) gradient stops are rewritten in place; an all-rgba gradient is untouched
+    const hexGrad = landingDomain.expand(mkColorPage({ background: "linear-gradient(180deg, #fff 0%, #000 100%)" }));
+    check("colour: hex gradient stops → rgba()", txtOf(hexGrad).background === "linear-gradient(180deg, rgba(255,255,255,1) 0%, rgba(0,0,0,1) 100%)", txtOf(hexGrad).background);
+    const rgbaGrad = "linear-gradient(160deg, rgba(13,45,58,0.88) 0%, rgba(10,124,110,0.75) 100%)";
+    check("colour: all-rgba gradient untouched", txtOf(landingDomain.expand(mkColorPage({ background: rgbaGrad }))).background === rgbaGrad);
+    // 5) a url() background layer is left for normalizeBackgrounds (no colour rewrite)
+    const urlBg = landingDomain.expand(mkColorPage({ background: "url(https://x.test/a.jpg) center/cover no-repeat" }));
+    check("colour: url() layer untouched by the colour pass", txtOf(urlBg).background.includes("url(https://x.test/a.jpg)"), txtOf(urlBg).background);
+    // 6) a colour on ONE breakpoint is mirrored onto the other — the trait panel
+    //    reads one breakpoint at a time and shows black for the missing one.
+    const dOnly = landingDomain.expand(mkColorPage({ color: "rgba(26,32,44,1)" }, {}));
+    check("colour: desktop-only color mirrored to mobile", txtOf(dOnly, "mobile").color === "rgba(26,32,44,1)", txtOf(dOnly, "mobile"));
+    const mOnly = landingDomain.expand(mkColorPage({}, { color: "#ffffff" }));
+    check("colour: mobile-only color mirrored to desktop (converted)", txtOf(mOnly, "desktop").color === "rgba(255,255,255,1)", txtOf(mOnly, "desktop"));
+    const bothSet = landingDomain.expand(mkColorPage({ color: "rgba(1,2,3,1)" }, { color: "rgba(4,5,6,1)" }));
+    check("colour: an explicit per-breakpoint colour is never overwritten", txtOf(bothSet, "desktop").color === "rgba(1,2,3,1)" && txtOf(bothSet, "mobile").color === "rgba(4,5,6,1)");
+    // 7) the gradient-text-fill key is NOT mirrored — copying it without the
+    //    gradient background that goes with it would blank the mobile text.
+    const fill = landingDomain.expand(mkColorPage({ background: "linear-gradient(90deg, rgba(1,2,3,1) 0%, rgba(4,5,6,1) 100%)", "-webkitTextFillColor": "transparent" }, {}));
+    check("colour: -webkitTextFillColor NOT mirrored", txtOf(fill, "mobile")["-webkitTextFillColor"] === undefined, txtOf(fill, "mobile"));
+    // 8) round-trip invariant survives the pass
+    const expandedC = landingDomain.expand(mkColorPage({ color: "#1a202c", borderColor: "rgb(1,2,3)" }, {}));
+    check("colour round-trip: expand(compact(expand(x))) deep-equals expand(x)", deepEq(landingDomain.expand(landingDomain.compact(expandedC)), expandedC));
+    // 9) what the pass cannot convert is reported as a warning, not silently shipped
+    const varColor = landingDomain.expand(mkColorPage({ color: "var(--brand)" }));
+    const varWarn = validatePage(varColor).warnings.filter((w) => /not an rgba\(\) colour/.test(w));
+    check("colour: unconvertible var(--x) warned", varWarn.length > 0, validatePage(varColor).warnings);
+    const okColor = landingDomain.expand(mkColorPage({ color: "#1a202c" }));
+    check("colour: no warning once the value is canonical rgba()", !validatePage(okColor).warnings.some((w) => /not an rgba\(\) colour/.test(w)), validatePage(okColor).warnings);
+}
 console.log("== text-block styles.background warning (gradient-text-fill mode) ==");
 {
     const mkTbBgPage = (bgValue, withClip) => ({

package/package.json

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