webcake-landing-mcp 1.4.0 → 1.5.1

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.5.1",
+    "d": "24/08/2026",
+    "type": "Added",
+    "en": "update_page now detects when the live page was edited outside this session (e.g. in the Webcake editor) since it was last read, and rejects the…",
+    "vi": "update_page nay phát hiện khi trang đang sống đã bị chỉnh sửa bên ngoài phiên làm việc này (ví dụ trong editor Webcake) kể từ lần đọc gần nhất, và…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "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…"
-  },
-  {
-    "v": "1.1.0",
-    "d": "20/06/2026",
-    "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

@@ -113,8 +113,8 @@ 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.
+- 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.
+- 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/domains/landing/index.js

@@ -226,6 +226,104 @@ function normalizeMisplacedAnimation(node) {
             normalizeMisplacedAnimation(child);
     }
 }
+// ---------------------------------------------------------------------------
+// editor-value normalization: the Webcake EDITOR does not store every numeric
+// style as a number. Confirmed write paths in landing_page_backend/assets/editor:
+//   • fontSize   → "59"   (main/panels/EditTextPanel.vue: updateStyle('fontSize', e.target.value))
+//                  "13px" / "11px" / "70"  (main/pickers/*.vue seed values)
+//   • height     → "600"  (main/traits/SizeAndPosition.vue handleBlur: e.target.value)
+//   • borderWidth→ "1" / "0px"
+//   • opacity    → "50%"  (main/traits/Layer.vue: updateStyle('opacity', val + '%'))
+//   • top/left   → "unset"
+// The published renderer copes (landing_page_build/render/build/exportCss.js
+// parseInt()s the KEY_PREFIX_PIXEL group and string-concatenates '+ "px"' for
+// top/left/width/height), so these pages are perfectly valid — but the MCP
+// schema demanded numbers, so ONE manual tweak in the editor locked the page out
+// of every MCP edit tool. That is the bug this pass removes.
+//
+// Fix: after every expand pass, coerce a unit-less or px-suffixed numeric string
+// back to a number for the keys the renderer treats as bare px numbers, and turn
+// an editor percent opacity into the 0–1 fraction. Values the coercion cannot
+// read (`"unset"`, `"auto"`, `"100%"`) are left alone — the schema accepts them
+// and validate.ts warns where the renderer would choke. Deterministic +
+// idempotent, so the expand(compact(x)) == expand(x) invariant holds.
+// ---------------------------------------------------------------------------
+/** Style keys the renderer emits as bare px numbers (or parseInt()s). */
+const NUMERIC_STYLE_KEYS = new Set(["top", "left", "width", "height", "zIndex", "fontSize", "borderWidth"]);
+/** Per-breakpoint config keys the renderer appends "px" to / uses as numbers. */
+const NUMERIC_CONFIG_KEYS = new Set([
+    "virtualHeight", "column", "row", "slideWidth", "iconSize", "iconTop", "linePaddingLeft",
+    "topBgImage", "leftBgImage", "widthBgImage", "heightBgImage",
+    "stickyTop", "stickyLeft", "stickyRight", "stickyBottom",
+]);
+/** A number written as a string, with an optional "px" suffix: "59", " 12.5 ", "13px". */
+const NUMERIC_PX_STRING = /^\s*-?\d+(?:\.\d+)?\s*(?:px)?\s*$/i;
+/** "59" | "13px" -> 59 | 13. Anything else (including numbers) passes through. */
+function numFromEditorString(v) {
+    if (typeof v !== "string" || !NUMERIC_PX_STRING.test(v))
+        return v;
+    const n = parseFloat(v);
+    return Number.isFinite(n) ? n : v;
+}
+/** "50%" -> 0.5 (the editor's Layer trait writes percent); else numeric-string coercion. */
+function opacityFromEditorString(v) {
+    if (typeof v !== "string")
+        return v;
+    const pct = v.trim().match(/^(-?\d+(?:\.\d+)?)\s*%$/);
+    if (pct) {
+        const n = parseFloat(pct[1]) / 100;
+        return Number.isFinite(n) ? n : v;
+    }
+    return numFromEditorString(v);
+}
+/** Walk a tree node and coerce editor-written numeric strings in-place (mutates). */
+function normalizeEditorValues(node) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const bp of ["desktop", "mobile"]) {
+        const rbp = node.responsive?.[bp];
+        if (!rbp || typeof rbp !== "object")
+            continue;
+        const styles = rbp.styles;
+        if (styles && typeof styles === "object") {
+            for (const key of NUMERIC_STYLE_KEYS) {
+                if (styles[key] !== undefined)
+                    styles[key] = numFromEditorString(styles[key]);
+            }
+            if (styles.opacity !== undefined && styles.opacity !== null) {
+                styles.opacity = opacityFromEditorString(styles.opacity);
+            }
+        }
+        const config = rbp.config;
+        if (config && typeof config === "object") {
+            for (const key of NUMERIC_CONFIG_KEYS) {
+                if (config[key] !== undefined)
+                    config[key] = numFromEditorString(config[key]);
+            }
+            const anim = config.animation;
+            if (anim && typeof anim === "object") {
+                for (const key of ["delay", "duration"]) {
+                    if (anim[key] !== undefined && anim[key] !== null)
+                        anim[key] = numFromEditorString(anim[key]);
+                }
+            }
+        }
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            normalizeEditorValues(child);
+    }
+}
+/** settings.width_section carries the canvas width the coords live in — keep it numeric. */
+function normalizeSettings(source) {
+    const ws = source?.settings?.width_section;
+    if (!ws || typeof ws !== "object")
+        return;
+    for (const bp of ["desktop", "mobile"]) {
+        if (ws[bp] !== undefined)
+            ws[bp] = numFromEditorString(ws[bp]);
+    }
+}
 /** Apply all post-expand normalizations to every node in a page source. */
 function normalizeSource(source) {
     if (!source || typeof source !== "object")
@@ -233,6 +331,7 @@ function normalizeSource(source) {
     for (const arr of ["page", "popup", "dynamic_pages"]) {
         if (Array.isArray(source[arr])) {
             for (const node of source[arr]) {
+                normalizeEditorValues(node);
                 normalizeMisplacedAnimation(node);
                 normalizeImageBlocks(node);
                 normalizeBorderRadius(node);
@@ -240,6 +339,7 @@ function normalizeSource(source) {
             }
         }
     }
+    normalizeSettings(source);
     return source;
 }
 export const landingDomain = {
@@ -264,7 +364,18 @@ export const landingDomain = {
     },
     compact: (input) => {
         try {
-            return compactSource(coercePage(input), createElement);
+            // Normalize FIRST (on a clone, so a caller's fetched tree is never mutated):
+            // a page hand-tweaked in the editor stores fontSize as "59" and height as
+            // "600", and the model should READ the canonical number it is asked to
+            // WRITE. Normalizing before compaction also lets a value that merely
+            // differs from the seed by its type ("20" vs 20) compact away.
+            const normalized = structuredClone(coercePage(input));
+            for (const arr of ["page", "popup", "dynamic_pages"]) {
+                if (Array.isArray(normalized?.[arr]))
+                    normalized[arr].forEach(normalizeEditorValues);
+            }
+            normalizeSettings(normalized);
+            return compactSource(normalized, createElement);
         }
         catch {
             return input; // bad JSON — return as-is

package/dist/domains/landing/instructions.js

@@ -15,7 +15,7 @@ RULES (follow for every request):
 - BUILD THE SOURCE IN ONE PASS — gather everything you need BEFORE assembling the source, then build the FULL tree once. BATCH the reads: when a section needs several element types (section + text-block + image-block + button + form + input), call get_element({types:[…]}) ONCE instead of one call per type — same for images, call search_images({queries:[…]}) ONCE with one query per image slot (it dedups + parallelizes and returns one best photo per query). Across MULTIPLE pages in one conversation: reusing skeletons you already fetched is correct, but call get_element for any type you have NOT already fetched in this conversation — NEVER author an unfamiliar type from memory; and if the earlier skeletons are no longer in your context (long conversation, compacted history), re-fetch before building. Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the request.
 - create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors, warnings fixed), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
 - LARGE PAGES (4+ sections) — build INCREMENTALLY to avoid the giant single create_page payload that can drop the connection: create_page with a SMALL skeleton (empty/near-empty page) to get a page_id, then call add_section once per section (each call ships ONLY that section; the backend appends it server-side and rejects duplicate ids — no whole-source get+put). Small pages can still go in one create_page pass.
-- EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates. For a SMALL edit, PREFER patch_page over update_page: send only the changed elements by id (ops: update/replace/remove/add) instead of re-shipping the whole tree — the MCP fetches the live source, merges, validates and saves server-side. Use update_page only when you're rewriting most of the page. Never regenerate the whole tree for a small change.
+- EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates. For a SMALL edit, PREFER patch_page over update_page: send only the changed elements by id (ops: update/replace/remove/add) instead of re-shipping the whole tree — the MCP fetches the live source, merges, validates and saves server-side. Use update_page only when you're rewriting most of the page. Never regenerate the whole tree for a small change. CONCURRENCY — the user may be editing the SAME page in the Webcake editor while you work: update_page replaces the whole stored tree, so a source read a while ago (or a cached draft_id, which can be hours old) would silently revert their changes. The server now checks this for you: get_page returns source_version, and update_page re-reads the page and REJECTS the save with reason:"page_changed_externally" (naming the element ids it would have deleted) when the live tree moved. When you see that, do NOT pass force:true on your own — either redo the edit with patch_page({ page_id, patches }), which merges into the live tree and can never revert anyone, or call get_page again, re-apply the change to the fresh tree, and save. Only use force:true after the user has explicitly said to discard the newer edits.
 - FIX-AFTER-ERROR / RETRY-AFTER-TIMEOUT (don't rebuild — this is the #1 time-waster): every mutating tool (create_page, update_page, add_section, patch_page) writes the payload to a draft cache BEFORE the network call and returns a draft_id. On validation failure, timeout, or any network error, the draft is kept — retry or fix without re-sending the full JSON:
   · create_page failed validation OR timed out → its error returns a draft_id (full source cached). Call patch_page({ draft_id, patches:[…], dry_run:false }) to fix ONLY the listed elements, or retry create_page({ draft_id, dry_run:false }) as-is after a timeout.
   · add_section failed validation, timed out, or returned dry_run=true → response returns a draft_id (section batch cached). Call patch_page({ draft_id, patches:[…], dry_run:false }) to fix elements and append, or retry patch_page({ draft_id, dry_run:false }) (no patches) to commit as-is.

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

@@ -97,16 +97,16 @@
       "description": "Per-breakpoint CSS. Positioning is absolute (px numbers). additionalProperties allowed for any camelCase CSS property.",
       "additionalProperties": true,
       "properties": {
-        "top": { "type": "number", "description": "px, absolute within container. Omit on section." },
-        "left": { "type": "number", "description": "px, absolute within container. Omit on section." },
-        "width": { "type": "number", "description": "px." },
-        "height": { "type": "number", "description": "px. Section uses this as canvas height." },
+        "top": { "type": ["number", "string", "null"], "description": "px, absolute within container. EMIT A NUMBER. Read-tolerance: the editor can save a numeric string (\"120\") or the keyword \"unset\" — numeric/px strings are normalized back to numbers before validation. Omit on section." },
+        "left": { "type": ["number", "string", "null"], "description": "px, absolute within container. EMIT A NUMBER. Read-tolerance: same as top (numeric string or \"unset\"). Omit on section." },
+        "width": { "type": ["number", "string", "null"], "description": "px. EMIT A NUMBER — the renderer appends \"px\" verbatim, so a value that already carries a unit would render as \"120pxpx\". Read-tolerance: unit-less/px strings the editor saves are normalized to numbers." },
+        "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" },
+        "zIndex": { "type": ["number", "string", "null"], "description": "Stacking order. EMIT A NUMBER; numeric strings are normalized." },
         "background": { "type": "string", "description": "rgba(...) or gradient." },
         "backgroundImage": { "type": "string", "description": "url(...)." },
         "color": { "type": "string", "description": "rgba(r,g,b,a)." },
-        "fontSize": { "type": "number", "description": "px." },
+        "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"] },
         "fontStyle": { "type": "string" },
@@ -115,12 +115,12 @@
         "letterSpacing": { "type": ["number", "string"] },
         "textTransform": { "type": "string" },
         "textDecoration": { "type": "string" },
-        "borderStyle": { "type": "string", "enum": ["solid", "dashed", "dotted", "double", "none"] },
-        "borderWidth": { "type": "number", "description": "px." },
+        "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" },
         "borderRadius": { "type": ["string", "number"] },
         "boxShadow": { "type": "string" },
-        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
+        "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." },
         "mixBlendMode": { "type": "string" },
         "transform": { "type": "string" },
         "padding": { "type": ["number", "string"] },
@@ -139,26 +139,26 @@
           "additionalProperties": true,
           "properties": {
             "name": { "type": "string", "description": "animate.css name, or \"none\"." },
-            "delay": { "type": "number" },
-            "duration": { "type": "number" },
+            "delay": { "type": ["number", "string"] },
+            "duration": { "type": ["number", "string"] },
             "repeat": { "type": ["number", "null"] }
           }
         },
-        "virtualHeight": { "type": "number" },
+        "virtualHeight": { "type": ["number", "string", "null"] },
         "overlay": { "type": "string", "description": "Overlay color rgba(...)." },
         "hiddenEffect": { "type": "object", "additionalProperties": true },
         "svgMask": { "type": "string" },
         "lock": { "type": "boolean" },
-        "column": { "type": "number" },
-        "row": { "type": "number" },
-        "slideWidth": { "type": "number" },
-        "iconSize": { "type": "number" },
-        "iconTop": { "type": "number" },
-        "linePaddingLeft": { "type": "number" },
-        "topBgImage": { "type": "number" },
-        "leftBgImage": { "type": "number" },
-        "widthBgImage": { "type": "number" },
-        "heightBgImage": { "type": "number" }
+        "column": { "type": ["number", "string", "null"] },
+        "row": { "type": ["number", "string", "null"] },
+        "slideWidth": { "type": ["number", "string", "null"] },
+        "iconSize": { "type": ["number", "string", "null"] },
+        "iconTop": { "type": ["number", "string", "null"] },
+        "linePaddingLeft": { "type": ["number", "string", "null"] },
+        "topBgImage": { "type": ["number", "string", "null"] },
+        "leftBgImage": { "type": ["number", "string", "null"] },
+        "widthBgImage": { "type": ["number", "string", "null"] },
+        "heightBgImage": { "type": ["number", "string", "null"] }
       }
     },
     "responsive": {
@@ -203,8 +203,8 @@
         "id": { "type": "string", "description": "Event id (any string; ~8 chars in real data)." },
         "type": {
           "type": "string",
-          "enum": ["click", "hover", "success", "unset"],
-          "description": "Trigger."
+          "enum": ["click", "hover", "success", "error", "delay", "unset"],
+          "description": "Trigger. Matches the editor's own dropdown: click/hover on any element, success/error on a form, delay on anything (plus the legacy \"unset\")."
         },
         "action": {
           "type": "string",

package/dist/domains/landing/validate.js

@@ -352,6 +352,31 @@ export function validatePage(input) {
                     `Valid examples: fadeInUp, slideInLeft, zoomIn, bounceIn, backInDown, flipInX, lightSpeedInLeft, rotateIn, rollIn, jackInTheBox.`);
             }
         }
+        // top/left/width/height are the ONE style group the renderer does NOT emit
+        // verbatim: exportCss.js strips them from the generic loop (PROPERTY_NOT_SHOW)
+        // and re-emits them as `${getStyle(el, mode, key)}px`. A value that already
+        // carries a unit therefore renders as "100%px"/"autopx" — invalid CSS the
+        // browser drops, so the element collapses or jumps to 0. Plain numbers and
+        // numeric strings are fine (expand() normalizes the latter to numbers first).
+        for (const bp of ["desktop", "mobile"]) {
+            const styles = node.responsive?.[bp]?.styles;
+            if (!styles || typeof styles !== "object")
+                continue;
+            // A sticky element takes exportCss.js handleStyleSticky(), which positions
+            // it from config.sticky* and never reads styles.top/left — the editor
+            // deliberately parks "unset" there, so those two are not a problem here.
+            const isSticky = !!node.responsive?.[bp]?.config?.sticky;
+            for (const key of ["top", "left", "width", "height"]) {
+                if (isSticky && (key === "top" || key === "left"))
+                    continue;
+                const raw = styles[key];
+                if (typeof raw !== "string" || raw.trim() === "")
+                    continue;
+                warnings.push(`${path} (${type ?? "?"}) [${bp}]: styles.${key}="${raw}" is not a plain px number — ` +
+                    `the renderer emits this property as \`${key}:${raw}px\`, which the browser drops. ` +
+                    `Set it to a NUMBER: patch_page({op:'update',id:'${node.id ?? "?"}',styles:{${bp}:{${key}:<px>}}}).`);
+            }
+        }
         // styles.opacity < 1 renders the element permanently faded (exportCss.js emits opacity:<v>)
         for (const bp of ["desktop", "mobile"]) {
             const styles = node.responsive?.[bp]?.styles;

package/dist/persistence/page-version.js

@@ -0,0 +1,198 @@
+/**
+ * Optimistic-concurrency guard for whole-source overwrites.
+ *
+ * THE PROBLEM. `update_page` (and a committed `kind:'update'` draft) REPLACES a
+ * page's stored source with a tree the model read earlier — from `get_page`, or
+ * from a draft the MCP cached minutes/hours ago. If the user opens the Webcake
+ * editor in between and moves an element, retypes a headline or adds a section,
+ * that overwrite silently reverts their work: the snapshot wins and the UI edit
+ * is gone. The backend cannot help — `/api/v1/ai/update_page_source` is a blind
+ * `update_source(record, %{source: …})` with no version column and no ETag
+ * (LandingPageWeb.V1.AiController.update_page_source), so last-write-wins is the
+ * only semantics it offers.
+ *
+ * THE FIX. Fingerprint the STORED source and remember it per page:
+ *   - every READ we do (`get_page`, the live read inside `patch_page`) records a
+ *     TRUSTED baseline — the exact bytes the backend just handed us;
+ *   - every WRITE records an UNTRUSTED baseline — our prediction of what the page
+ *     now holds. It should match a later read, but the backend re-encodes the JSON
+ *     on the way in and out, so a mismatch here must never be read as "someone
+ *     else edited the page";
+ *   - a server-side append (`add_section`) FORGETS it — the backend rewrote the
+ *     tree behind our back, so nothing we hold is a baseline any more.
+ * Before a blind overwrite we re-read the page and compare (see decideOverwrite).
+ *
+ * The fingerprint is content-based (canonical key-sorted JSON → sha256), so it
+ * survives the backend's decode→re-encode round-trip and needs no schema change.
+ *
+ * The store is per-process and bounded. Losing it (restart, a second `serve`
+ * instance) is safe: with no baseline the caller falls back to the element-id
+ * loss check, which still catches the destructive case.
+ */
+import { createHash } from "node:crypto";
+/** Canonical JSON: object keys sorted recursively so two equal trees hash equal. */
+function canonical(v) {
+    if (Array.isArray(v))
+        return v.map(canonical);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = canonical(v[k]);
+        return out;
+    }
+    return v;
+}
+/** Short content fingerprint of a page source (object or JSON string). */
+export function sourceFingerprint(source) {
+    let v = source;
+    if (typeof v === "string") {
+        try {
+            v = JSON.parse(v);
+        }
+        catch {
+            /* not JSON — hash the raw string */
+        }
+    }
+    return createHash("sha256").update(JSON.stringify(canonical(v) ?? null)).digest("hex").slice(0, 16);
+}
+/** Every element id in a source tree (page + popup + dynamic_pages, recursively). */
+export function collectElementIds(source) {
+    const ids = new Set();
+    const walk = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (typeof node.id === "string" && typeof node.type === "string")
+            ids.add(node.id);
+        if (Array.isArray(node.children))
+            for (const c of node.children)
+                walk(c);
+    };
+    let v = source;
+    if (typeof v === "string") {
+        try {
+            v = JSON.parse(v);
+        }
+        catch {
+            return ids;
+        }
+    }
+    for (const arr of ["page", "popup", "dynamic_pages"]) {
+        if (Array.isArray(v?.[arr]))
+            for (const n of v[arr])
+                walk(n);
+    }
+    return ids;
+}
+const MAX_PAGES = 100;
+const versions = new Map();
+/** Record what the page holds now, and whether we KNOW it (read) or predict it (write). */
+export function rememberPageVersion(pageId, fp, origin) {
+    if (!pageId)
+        return;
+    versions.delete(pageId); // re-insert so Map iteration order = LRU
+    versions.set(pageId, { fp, origin, at: Date.now() });
+    while (versions.size > MAX_PAGES) {
+        const oldest = versions.keys().next().value;
+        if (oldest === undefined)
+            break;
+        versions.delete(oldest);
+    }
+}
+/** Drop the baseline — the stored tree changed in a way we cannot predict. */
+export function forgetPageVersion(pageId) {
+    if (pageId)
+        versions.delete(pageId);
+}
+/** The baseline we hold for this page, or undefined if we hold none. */
+export function lastKnownPageVersion(pageId) {
+    if (!pageId)
+        return undefined;
+    const v = versions.get(pageId);
+    return v ? { fp: v.fp, origin: v.origin } : undefined;
+}
+/** Test hook — clears the baseline store. */
+export function resetPageVersions() {
+    versions.clear();
+}
+/**
+ * Pure verdict for "may this whole-source overwrite proceed?" — the network read
+ * lives in the caller so this stays testable.
+ *
+ *   trusted baseline matches live            → allow (any deletions are deliberate)
+ *   trusted baseline differs                 → refuse: edited outside this session
+ *   no/untrusted baseline, live ids dropped  → refuse: provable destruction
+ *   no/untrusted baseline, nothing dropped   → allow, flagged unverified
+ */
+export function decideOverwrite(liveSource, incoming, baseline) {
+    const liveVersion = sourceFingerprint(liveSource);
+    if (baseline && baseline.fp === liveVersion)
+        return { allow: true, liveVersion };
+    const liveIds = collectElementIds(liveSource);
+    const incomingIds = collectElementIds(incoming);
+    const dropped = [...liveIds].filter((id) => !incomingIds.has(id));
+    // A stale READ baseline is proof the page moved under us — refuse even when the
+    // overwrite drops nothing, because it would still revert the edits it does touch.
+    if (baseline?.origin === "read") {
+        return { allow: false, reason: "page_changed_externally", liveVersion, baseVersion: baseline.fp, dropped };
+    }
+    // No baseline, or one we only PREDICTED after a write: a mismatch proves nothing,
+    // so fall back to the check that is always sound — does this save destroy content?
+    if (dropped.length === 0)
+        return { allow: true, liveVersion, unverified: true };
+    return { allow: false, reason: "unverified_overwrite", liveVersion, baseVersion: baseline?.fp, dropped };
+}
+// ---- version-keyed source cache -------------------------------------------
+//
+// The concurrency check must never be served from a cache — a cached answer
+// cannot see an edit made after it was written, which is the whole bug. What IS
+// cacheable is the SOURCE, validated by the backend's own version token: ask
+// `GET /api/v1/ai/page_version` for `updated_at` (a few hundred bytes), and only
+// re-download the tree when it moved. Unchanged page ⇒ no download at all; the
+// freshness guarantee is identical because the token comes from the server.
+//
+// Entries are keyed by credentials as well as page id, so a hosted `serve`
+// instance can never hand one caller a tree fetched with another caller's JWT.
+// Bounded to a handful of pages — a source can be megabytes.
+const MAX_CACHED_SOURCES = 6;
+const sources = new Map();
+/** Cache key: the page plus a short digest of the credentials it was fetched with. */
+export function sourceCacheKey(pageId, jwt) {
+    const who = createHash("sha256").update(jwt ?? "").digest("hex").slice(0, 12);
+    return `${who}:${pageId}`;
+}
+/** Store a full getPageSource outcome under the backend version it was read at. */
+export function cachePageSource(key, version, result) {
+    if (!version)
+        return; // no server token ⇒ nothing to validate a hit against
+    sources.delete(key);
+    sources.set(key, { version, result, at: Date.now() });
+    while (sources.size > MAX_CACHED_SOURCES) {
+        const oldest = sources.keys().next().value;
+        if (oldest === undefined)
+            break;
+        sources.delete(oldest);
+    }
+}
+/** The version a cached entry was read at, or undefined when nothing is cached. */
+export function cachedPageSourceVersion(key) {
+    return sources.get(key)?.version;
+}
+/** The cached outcome IF it was read at exactly this version, else undefined. */
+export function cachedPageSource(key, version) {
+    if (!version)
+        return undefined;
+    const hit = sources.get(key);
+    if (!hit || hit.version !== version)
+        return undefined;
+    sources.delete(key); // refresh LRU position
+    sources.set(key, { ...hit, at: Date.now() });
+    return hit.result;
+}
+/** Drop a page's cached source (e.g. after our own write changed it). */
+export function dropCachedPageSource(key) {
+    sources.delete(key);
+}
+/** Test hook — clears the source cache. */
+export function resetPageSourceCache() {
+    sources.clear();
+}

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();