webcake-landing-mcp 1.5.0 → 1.5.1

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "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",
@@ -33,12 +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…"
   }
 ]

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). 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). 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

@@ -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/webcake-client.js

@@ -59,6 +59,7 @@ const ORGS_ENDPOINT = "/api/v1/org/organizations";
 const PAGES_ENDPOINT = "/api/v1/ai/pages";
 const SEARCH_PAGES_ENDPOINT = "/api/v1/ai/search_pages";
 const PAGE_SOURCE_ENDPOINT = "/api/v1/ai/page_source";
+const PAGE_VERSION_ENDPOINT = "/api/v1/ai/page_version";
 const UPDATE_ENDPOINT = "/api/v1/ai/update_page_source";
 const APPEND_ENDPOINT = "/api/v1/ai/append_section";
 // The editor's own publish routes (NOT under /api/v1/ai). Both scopes are
@@ -326,6 +327,27 @@ export async function searchPages(config, filters) {
     return { ok: true, status: r.status, pages };
 }
 /** Read a page's decoded source tree (must be owned by the account). */
+/**
+ * The page source's VERSION only (`updated_at`), a few hundred bytes instead of the
+ * whole tree. Backed by `GET /api/v1/ai/page_version` (LandingPageWeb.V1.AiController.
+ * get_page_version), which selects the timestamp WITHOUT the `source` column.
+ *
+ * `updated_at` moves on every save through `Pages.update_source/2` — the path the
+ * editor and `update_page_source` both take — so it answers "did anyone touch this
+ * page since I last read it?" without a download.
+ *
+ * A backend that predates the route replies 404: `endpoint_missing` says so, and the
+ * caller reads the full source instead (same shape as the append_section fallback).
+ */
+export async function getPageVersion(config, pageId) {
+    const url = `${config.base}${PAGE_VERSION_ENDPOINT}?page_id=${encodeURIComponent(pageId)}`;
+    const r = await getJson(url, config);
+    if (!r.ok)
+        return { ok: false, status: r.status, endpoint_missing: r.status === 404, error: r.error };
+    const d = r.json?.data ?? r.json ?? {};
+    const version = d.updated_at == null ? undefined : String(d.updated_at);
+    return { ok: version !== undefined, status: r.status, version };
+}
 export async function getPageSource(config, pageId) {
     const url = `${config.base}${PAGE_SOURCE_ENDPOINT}?page_id=${encodeURIComponent(pageId)}`;
     const r = await getJson(url, config);
@@ -342,6 +364,8 @@ export async function getPageSource(config, pageId) {
         // publish_page reuse it instead of dropping to a domain-less preview.
         custom_domain: d.custom_domain ?? null,
         custom_path: d.custom_path ?? null,
+        // The same token GET /page_version returns — absent on a backend that predates it.
+        updated_at: d.updated_at == null ? undefined : String(d.updated_at),
         source: d.source,
     };
 }

package/dist/smoke.js

@@ -22,6 +22,7 @@ import { buildMicrolinkUrl } from "./persistence/screenshot-client.js";
 import { isPrivateHost, isAllowedScreenshotUrl } from "./persistence/screenshot-playwright.js";
 import { iconifyCandidates } from "./persistence/icon-client.js";
 import { collectExternalImageUrls, rewriteImageUrls, isRehostableImageUrl } from "./persistence/rehost.js";
+import { sourceFingerprint, collectElementIds, decideOverwrite, rememberPageVersion, forgetPageVersion, lastKnownPageVersion, resetPageVersions, sourceCacheKey, cachePageSource, cachedPageSource, cachedPageSourceVersion, dropCachedPageSource, resetPageSourceCache, } from "./persistence/page-version.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -330,6 +331,66 @@ check("expand preserves provided styles", eTxt.responsive.desktop.styles.fontSiz
 check("expand keeps id/type/specials", eTxt.id === "t_h1" && eTxt.type === "text-block" && eTxt.specials.text === "Sparse hero", eTxt);
 check("expanded sparse page validates", validatePage(exp).valid, validatePage(exp).errors);
 check("expand(full good page) still valid", validatePage(expandSource(good, createElement)).valid);
+console.log("== editor tolerance: a page hand-tweaked in the Webcake editor still validates ==");
+{
+    // Every value shape below is one the EDITOR actually writes (verified against
+    // landing_page_backend/assets/editor): fontSize "59" (EditTextPanel inline box),
+    // "32px" (element pickers), height "520" (SizeAndPosition blur), borderWidth
+    // "1"/"0px", opacity "50%" (Layer trait), width_section as strings, and the
+    // "delay"/"error" event triggers the EventTrait dropdown offers.
+    const edited = {
+        page: [{
+                id: "sec_edit", type: "section",
+                properties: { name: "Section", movable: false, sync: true },
+                specials: {}, runtime: {}, events: [],
+                responsive: {
+                    desktop: { config: {}, styles: { height: "600", background: "rgba(255,255,255,1)" } },
+                    mobile: { config: {}, styles: { height: "520", background: "rgba(255,255,255,1)" } },
+                },
+                children: [{
+                        id: "txt_edit", type: "text-block",
+                        properties: { name: "Text", movable: true, sync: true },
+                        specials: { text: "Hand-edited headline", tag: "h1" }, runtime: {},
+                        events: [{ id: "EVENT1", type: "delay", action: "none", target: null }],
+                        responsive: {
+                            desktop: { config: { animation: { name: "none", delay: "0", duration: "3", repeat: null } },
+                                styles: { top: 60, left: 80, width: 500, height: 70, fontSize: "59", borderWidth: "1", opacity: "50%", color: "rgba(20,20,20,1)" } },
+                            mobile: { config: {},
+                                styles: { top: "50", left: 20, width: 380, height: 60, fontSize: "32px", borderWidth: "0px", color: "rgba(20,20,20,1)" } },
+                        },
+                    }],
+            }],
+        popup: [],
+        settings: { title: "Edited", description: "d", keywords: "a", width_section: { desktop: "960", mobile: "420" } },
+        options: { mobileOnly: false, versionID: null },
+        cartConfigs: {},
+    };
+    const ex = landingDomain.expand(edited);
+    const v = landingDomain.validate(ex);
+    check("editor tolerance: hand-edited page has NO schema errors", v.valid, v.errors);
+    const dTxt = ex.page[0].children[0].responsive.desktop;
+    const mTxt = ex.page[0].children[0].responsive.mobile;
+    check('editor tolerance: fontSize "59" -> 59', dTxt.styles.fontSize === 59, dTxt.styles.fontSize);
+    check('editor tolerance: fontSize "32px" -> 32', mTxt.styles.fontSize === 32, mTxt.styles.fontSize);
+    check('editor tolerance: borderWidth "1"/"0px" -> 1/0', dTxt.styles.borderWidth === 1 && mTxt.styles.borderWidth === 0, [dTxt.styles.borderWidth, mTxt.styles.borderWidth]);
+    check('editor tolerance: opacity "50%" -> 0.5', dTxt.styles.opacity === 0.5, dTxt.styles.opacity);
+    check('editor tolerance: height "600"/"520" -> numbers', ex.page[0].responsive.desktop.styles.height === 600 && ex.page[0].responsive.mobile.styles.height === 520, ex.page[0].responsive);
+    check('editor tolerance: top "50" -> 50', mTxt.styles.top === 50, mTxt.styles.top);
+    check('editor tolerance: animation delay/duration strings -> numbers', dTxt.config.animation.delay === 0 && dTxt.config.animation.duration === 3, dTxt.config.animation);
+    check('editor tolerance: width_section strings -> numbers', ex.settings.width_section.desktop === 960 && ex.settings.width_section.mobile === 420, ex.settings.width_section);
+    check('editor tolerance: "delay" event trigger accepted', !v.errors.some((e) => /type/.test(e) && /delay/.test(e)), v.errors);
+    check("editor tolerance: normalization is idempotent", JSON.stringify(landingDomain.expand(ex)) === JSON.stringify(ex));
+    // get_page COMPACTS the stored tree — the model must read the canonical number it is asked to write.
+    const readBack = landingDomain.compact(edited);
+    check("editor tolerance: compact (the get_page read path) normalizes too", readBack.page[0].children[0].responsive.desktop.styles.fontSize === 59, readBack.page[0].children[0].responsive.desktop.styles);
+    check("editor tolerance: compact does not mutate the caller’s tree", edited.page[0].children[0].responsive.desktop.styles.fontSize === "59", edited.page[0].children[0].responsive.desktop.styles.fontSize);
+    // A unit the renderer cannot use (it appends "px" itself) stays a string and is WARNED, not blocked.
+    const unit = JSON.parse(JSON.stringify(edited));
+    unit.page[0].children[0].responsive.desktop.styles.width = "100%";
+    const uv = landingDomain.validate(landingDomain.expand(unit));
+    check("editor tolerance: non-px dimension unit is a warning, not an error", uv.valid, uv.errors);
+    check("editor tolerance: non-px dimension unit IS warned", uv.warnings.some((w) => /styles\.width="100%"/.test(w)), uv.warnings);
+}
 console.log("== compact: the inverse of expand (round-trip persists the same tree) ==");
 {
     const cGood = compactSource(good, createElement);
@@ -1963,6 +2024,105 @@ console.log("== layout: exact centering/row/grid/stack coordinates (both breakpo
     const lastRight = rightWide.desktop[1].left + rightWide.desktop[1].width;
     check("layout: align right ends at canvas − margin (1200 − 80 = 1120)", lastRight === 1120, { lastRight, desktop: rightWide.desktop });
 }
+console.log("== stale-overwrite guard: a UI edit is never silently reverted ==");
+{
+    const el = (id, extra = {}) => ({
+        id, type: "text-block",
+        properties: { name: id, movable: true, sync: true },
+        specials: { text: id }, runtime: {}, events: [],
+        responsive: {
+            desktop: { config: {}, styles: { top: 0, left: 0, width: 100, height: 20, ...extra } },
+            mobile: { config: {}, styles: { top: 0, left: 0, width: 100, height: 20, ...extra } },
+        },
+    });
+    const pageWith = (children) => ({
+        page: [{
+                id: "sec1", type: "section",
+                properties: { name: "Section", movable: false, sync: true },
+                specials: {}, runtime: {}, events: [],
+                responsive: { desktop: { config: {}, styles: { height: 600 } }, mobile: { config: {}, styles: { height: 500 } } },
+                children,
+            }],
+        popup: [], settings: { title: "t" }, options: {}, cartConfigs: {},
+    });
+    // --- fingerprint --------------------------------------------------------
+    const a = { page: [], settings: { title: "x", description: "d" } };
+    const b = { settings: { description: "d", title: "x" }, page: [] };
+    check("page-version: fingerprint ignores object key order", sourceFingerprint(a) === sourceFingerprint(b), [sourceFingerprint(a), sourceFingerprint(b)]);
+    check("page-version: fingerprint survives the JSON string round-trip", sourceFingerprint(JSON.stringify(a)) === sourceFingerprint(a));
+    check("page-version: fingerprint changes when content changes", sourceFingerprint(a) !== sourceFingerprint({ ...a, settings: { title: "y" } }));
+    check("page-version: array order still matters", sourceFingerprint({ page: [1, 2] }) !== sourceFingerprint({ page: [2, 1] }));
+    // --- element ids --------------------------------------------------------
+    const ids = collectElementIds(pageWith([el("t1"), el("t2")]));
+    check("page-version: collectElementIds walks nested children", ids.has("sec1") && ids.has("t1") && ids.has("t2") && ids.size === 3, [...ids]);
+    // --- the decision -------------------------------------------------------
+    const live = pageWith([el("t1"), el("t2")]);
+    const liveFp = sourceFingerprint(live);
+    const sameContent = pageWith([el("t1"), el("t2", { fontSize: 30 })]); // model edited t2
+    const fresh = decideOverwrite(live, sameContent, { fp: liveFp, origin: "read" });
+    check("guard: baseline matches live → allowed", fresh.allow === true, fresh);
+    // The model deliberately deletes t2 while holding a current baseline.
+    const deleting = decideOverwrite(live, pageWith([el("t1")]), { fp: liveFp, origin: "read" });
+    check("guard: deliberate delete on a current baseline → allowed", deleting.allow === true, deleting);
+    // THE BUG: user edited in the editor after the model read the page.
+    const uiEdited = pageWith([el("t1"), el("t2"), el("t3_added_in_editor")]);
+    const stale = decideOverwrite(uiEdited, sameContent, { fp: liveFp, origin: "read" });
+    check("guard: page changed in the editor → REFUSED", stale.allow === false && stale.reason === "page_changed_externally", stale);
+    check("guard: refusal names the elements the overwrite would delete", stale.allow === false && stale.dropped.includes("t3_added_in_editor"), stale);
+    // Even a change that drops nothing is refused on a trusted baseline: the
+    // overwrite would still revert the user's tweak to the elements it does touch.
+    const tweaked = pageWith([el("t1"), el("t2", { fontSize: 99 })]);
+    const noDrop = decideOverwrite(tweaked, sameContent, { fp: liveFp, origin: "read" });
+    check("guard: editor tweak with no id loss → still REFUSED on a read baseline", noDrop.allow === false && noDrop.reason === "page_changed_externally", noDrop);
+    // No baseline at all (fresh process / no get_page): fall back to id loss.
+    const blind = decideOverwrite(uiEdited, sameContent, undefined);
+    check("guard: no baseline + would delete live ids → REFUSED", blind.allow === false && blind.reason === "unverified_overwrite", blind);
+    const blindSafe = decideOverwrite(live, sameContent, undefined);
+    check("guard: no baseline + nothing dropped → allowed as unverified", blindSafe.allow === true && blindSafe.unverified === true, blindSafe);
+    // A baseline we only PREDICTED after a write must never produce a false
+    // "someone edited it" — the backend re-encodes JSON, so a mismatch proves nothing.
+    const predicted = decideOverwrite(live, sameContent, { fp: "deadbeefdeadbeef", origin: "write" });
+    check("guard: stale WRITE baseline + nothing dropped → allowed (no false conflict)", predicted.allow === true, predicted);
+    const predictedDrop = decideOverwrite(uiEdited, sameContent, { fp: "deadbeefdeadbeef", origin: "write" });
+    check("guard: stale WRITE baseline + id loss → REFUSED", predictedDrop.allow === false && predictedDrop.reason === "unverified_overwrite", predictedDrop);
+    // --- the baseline store -------------------------------------------------
+    resetPageVersions();
+    check("page-version: unknown page has no baseline", lastKnownPageVersion("p1") === undefined);
+    rememberPageVersion("p1", liveFp, "read");
+    check("page-version: remember/lastKnown round-trip", lastKnownPageVersion("p1")?.fp === liveFp && lastKnownPageVersion("p1")?.origin === "read");
+    rememberPageVersion("p1", "other", "write");
+    check("page-version: a later write downgrades the origin", lastKnownPageVersion("p1")?.origin === "write");
+    forgetPageVersion("p1");
+    check("page-version: add_section-style forget clears it", lastKnownPageVersion("p1") === undefined);
+    // --- version-keyed source cache ----------------------------------------
+    resetPageSourceCache();
+    const k1 = sourceCacheKey("pageA", "jwt-user-1");
+    const k2 = sourceCacheKey("pageA", "jwt-user-2");
+    check("source cache: key is scoped to the credentials, not just the page", k1 !== k2, [k1, k2]);
+    check("source cache: same page + same creds → same key", sourceCacheKey("pageA", "jwt-user-1") === k1);
+    cachePageSource(k1, "2026-08-24T10:00:00", { ok: true, source: live });
+    check("source cache: stores the version it was read at", cachedPageSourceVersion(k1) === "2026-08-24T10:00:00");
+    check("source cache: hit when the backend reports the SAME version", cachedPageSource(k1, "2026-08-24T10:00:00")?.source === live);
+    check("source cache: MISS when the page moved (the download is unavoidable)", cachedPageSource(k1, "2026-08-24T10:05:00") === undefined);
+    check("source cache: another caller's key never hits", cachedPageSource(k2, "2026-08-24T10:00:00") === undefined);
+    check("source cache: no version probe → never a hit", cachedPageSource(k1, undefined) === undefined);
+    // An older backend has no /page_version and no updated_at: nothing caches, so
+    // every read stays a single full fetch exactly as before.
+    resetPageSourceCache();
+    cachePageSource(k1, undefined, { ok: true, source: live });
+    check("source cache: a backend without updated_at caches nothing", cachedPageSourceVersion(k1) === undefined);
+    cachePageSource(k1, "v1", { ok: true, source: live });
+    dropCachedPageSource(k1);
+    check("source cache: our own write drops the entry", cachedPageSourceVersion(k1) === undefined);
+    for (let i = 0; i < 10; i++)
+        cachePageSource(sourceCacheKey("big" + i, "j"), "v", { ok: true, source: live });
+    check("source cache: bounded (a source can be megabytes)", cachedPageSourceVersion(sourceCacheKey("big0", "j")) === undefined && cachedPageSourceVersion(sourceCacheKey("big9", "j")) === "v");
+    resetPageSourceCache();
+    for (let i = 0; i < 120; i++)
+        rememberPageVersion("bulk" + i, "fp" + i, "read");
+    check("page-version: store is bounded (LRU evicts the oldest)", lastKnownPageVersion("bulk0") === undefined && lastKnownPageVersion("bulk119")?.fp === "fp119");
+    resetPageVersions();
+}
 console.log("== server: MCP serverInfo.version follows package.json (no hardcoded constant) ==");
 {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/dist/tools/persistence.js

@@ -12,11 +12,102 @@
 import { z } from "zod";
 import { text, warningsField, autoFixedField } from "../mcp/response.js";
 import { readConfig, configFromHeaders } from "../persistence/config.js";
-import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, buildPublishRequestRedacted, buildPageApp, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, publishPage, toPreviewUrl, } from "../persistence/webcake-client.js";
+import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, buildPublishRequestRedacted, buildPageApp, createPage, listOrganizations, listPages, searchPages, getPageSource, getPageVersion, updatePageSource, appendSection, publishPage, toPreviewUrl, } from "../persistence/webcake-client.js";
 import { putDraft, getDraft, updateDraft, deleteDraft } from "../persistence/draft-cache.js";
+import { sourceFingerprint, decideOverwrite, rememberPageVersion, forgetPageVersion, lastKnownPageVersion, sourceCacheKey, cachePageSource, cachedPageSource, cachedPageSourceVersion, dropCachedPageSource, } from "../persistence/page-version.js";
 export function registerPersistenceTools(server, domain) {
     // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
     const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
+    // ---- live source read (version-validated cache) ---------------------------
+    // Every live read used to download the whole tree, and the concurrency guard
+    // added one more. It cannot be served from a plain cache — a cached answer
+    // cannot see an edit made after it was written, which is the bug the guard
+    // exists to catch. So the SERVER decides: GET /api/v1/ai/page_version returns
+    // page_source.updated_at (a few hundred bytes; bumped by every save, editor and
+    // MCP alike), and we reuse the cached tree only when that token is unchanged.
+    // Freshness is identical to a full read because the token comes from the backend.
+    //
+    // We probe only when something IS cached, so a cold read costs exactly one
+    // request as before; a warm one costs a tiny probe and no download. A backend
+    // without the route answers 404 → nothing ever caches → one full read, as before.
+    const readLiveSource = async (config, pageId) => {
+        const key = sourceCacheKey(pageId, config.jwt);
+        if (cachedPageSourceVersion(key)) {
+            const probe = await getPageVersion(config, pageId);
+            if (probe.ok && probe.version) {
+                const hit = cachedPageSource(key, probe.version);
+                if (hit)
+                    return { ...hit, from_cache: true };
+            }
+        }
+        const full = await getPageSource(config, pageId);
+        if (full.ok && full.source != null)
+            cachePageSource(key, full.updated_at, full);
+        return { ...full, from_cache: false };
+    };
+    /** Our own write changed the stored tree — the cached copy is spent. */
+    const invalidateSource = (config, pageId) => {
+        if (pageId)
+            dropCachedPageSource(sourceCacheKey(pageId, config.jwt));
+    };
+    // ---- stale-overwrite guard ------------------------------------------------
+    // update_page (and a committed 'update' draft) REPLACES the stored source with a
+    // tree the model read earlier. If the user edited the page in the Webcake editor
+    // in between, that overwrite silently reverts their work — the exact failure the
+    // draft cache makes easy to hit, since a draft can sit for ~2 h. The backend has
+    // no version column, so we do optimistic concurrency ourselves: re-read the page
+    // and compare its fingerprint with the baseline we recorded when the model last
+    // read/wrote it (or with an explicit base_version the caller passes back).
+    //
+    //   baseline matches live  → the model is current; overwrite (deletes are intentional)
+    //   baseline differs       → someone else edited the page → REFUSE
+    //   no baseline + the overwrite would DROP live element ids → REFUSE
+    //   no baseline + nothing is dropped → allow, but say the check could not be made
+    //
+    // force:true skips the check (an explicit "yes, discard the editor's changes").
+    const guardOverwrite = async (config, pageId, incoming, opts) => {
+        if (opts.force)
+            return { ok: true, notice: "force:true — the staleness check was skipped and any newer editor changes were overwritten." };
+        const live = await readLiveSource(config, pageId);
+        // Cannot read the live page (offline/404): don't block the write on our own check.
+        if (!live.ok || live.source == null)
+            return { ok: true };
+        // An explicit base_version comes from get_page's source_version — a real read.
+        const baseline = opts.baseVersion
+            ? { fp: opts.baseVersion, origin: "read" }
+            : lastKnownPageVersion(pageId);
+        const verdict = decideOverwrite(live.source, incoming, baseline);
+        if (verdict.allow) {
+            return {
+                ok: true,
+                liveVersion: verdict.liveVersion,
+                ...(verdict.unverified
+                    ? {
+                        notice: "No baseline for this page in this session, so the overwrite could not be verified against the live tree — " +
+                            "no live element ids are lost, so it was allowed. Call get_page first next time to make the check exact.",
+                    }
+                    : {}),
+            };
+        }
+        const { reason, liveVersion, baseVersion, dropped } = verdict;
+        return {
+            ok: false,
+            payload: {
+                reason,
+                page_id: pageId,
+                live_version: liveVersion,
+                base_version: baseVersion,
+                would_delete_element_ids: dropped.slice(0, 30),
+                would_delete_count: dropped.length,
+                hint: (baseVersion
+                    ? "The page was edited OUTSIDE this session (the Webcake editor, another agent) after this source was read, so saving it would revert those changes. "
+                    : "This source was not read from the live page in this session and the overwrite would delete element ids that exist on the page right now. ") +
+                    "Do ONE of these: (a) patch_page({ page_id, patches:[…] }) — it always merges into the LIVE tree, so it never reverts anything; " +
+                    "(b) get_page({ page_id }) again, re-apply your edit to the fresh tree, then save; " +
+                    `(c) if discarding the newer changes is intended, re-run ${opts.retryHint} with force:true.`,
+            },
+        };
+    };
     // After a successful CREATE, build the rendered app and publish via the
     // editor's publish_html route so the page renders immediately — without this
     // a fresh page's preview is a blank shell until publish_page runs or the page
@@ -294,6 +385,8 @@ export function registerPersistenceTools(server, domain) {
         const outcome = await createPage(config, pageName, parsed, resolvedOrgId);
         if (outcome.ok) {
             await deleteDraft(existingDraftId); // created — drop the draft
+            rememberPageVersion(outcome.page_id, sourceFingerprint(outcome.rehosted_source ?? parsed), "write");
+            invalidateSource(config, outcome.page_id);
             // Auto-publish (default): build + publish_html so the preview renders
             // immediately. Never fails the create — result.publish carries the state.
             const publishOutcome = publish === false
@@ -392,14 +485,22 @@ export function registerPersistenceTools(server, domain) {
         const { config, missing } = cfgFor(extra);
         if (!config)
             return text({ ok: false, reason: "missing_env", missing_env: missing });
-        const res = await getPageSource(config, page_id);
-        if (!res.ok || compact === false || res.source == null)
+        const res = await readLiveSource(config, page_id);
+        if (!res.ok || res.source == null)
             return text(res);
+        // Fingerprint what the page holds RIGHT NOW: this read is the baseline a
+        // later update_page is checked against, so an edit made in the Webcake
+        // editor after this point cannot be silently overwritten.
+        const source_version = sourceFingerprint(res.source);
+        rememberPageVersion(page_id, source_version, "read");
+        if (compact === false)
+            return text({ ...res, source_version });
         return text({
             ...res,
             source: domain.compact(res.source),
             compacted: true,
-            note: "Source is COMPACTED (factory-default boilerplate stripped). Edit elements in this same sparse shape — keep ids — and send the edited tree back to update_page (or use patch_page for small edits); the server re-hydrates omitted boilerplate.",
+            source_version,
+            note: "Source is COMPACTED (factory-default boilerplate stripped). Edit elements in this same sparse shape — keep ids — and send the edited tree back to update_page (or use patch_page for small edits); the server re-hydrates omitted boilerplate. Pass source_version back as update_page({ base_version }) so a save is rejected instead of reverting an edit someone made in the editor meanwhile.",
         });
     });
     // 12) Update page (edit existing) -------------------------------------------
@@ -413,13 +514,24 @@ export function registerPersistenceTools(server, domain) {
             .string()
             .optional()
             .describe("A draft_id from a previous update_page call (dry_run=true or a timed-out/failed update). Loads the cached source — no need to re-send the full JSON. Use for dry-run → real call transitions and retrying after a timeout."),
+        base_version: z
+            .string()
+            .optional()
+            .describe("The source_version get_page returned for this page. When it no longer matches the live page the save is REJECTED instead of reverting whatever was edited in the Webcake editor meanwhile. Optional — omit it and the server uses the version it recorded on your last read/write of this page."),
+        force: z
+            .boolean()
+            .optional()
+            .describe("Default false. true = save even when the page changed outside this session, discarding those changes. Only pass it after the user has said to."),
         dry_run: z.boolean().optional().describe("Default TRUE — validate, cache the source as draft_id, and preview without sending. Set false to actually save."),
-    }, { title: "Update Webcake Page (Overwrite)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, source, draft_id, dry_run }, extra) => {
+    }, { title: "Update Webcake Page (Overwrite)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, source, draft_id, base_version, force, dry_run }, extra) => {
         const isDry = dry_run !== false;
         // --- Resolve source: from cache (draft_id) or from the argument ---
         let expanded;
         let existingDraftId = draft_id;
         let resolvedPageId = page_id;
+        // The version of the live page this source was built from. Explicit wins;
+        // a draft carries the one captured when it was first cached.
+        let resolvedBaseVersion = base_version;
         if (draft_id) {
             const cached = await getDraft(draft_id);
             if (!cached) {
@@ -438,6 +550,7 @@ export function registerPersistenceTools(server, domain) {
             }
             expanded = cached.source;
             resolvedPageId = page_id ?? cached.page_id;
+            resolvedBaseVersion = base_version ?? cached.base_version;
         }
         else {
             if (source == null) {
@@ -458,7 +571,7 @@ export function registerPersistenceTools(server, domain) {
                 await updateDraft(existingDraftId, expanded);
             }
             else {
-                existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId });
+                existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId, base_version: resolvedBaseVersion });
             }
             return text({
                 updated: false,
@@ -478,7 +591,7 @@ export function registerPersistenceTools(server, domain) {
                 await updateDraft(existingDraftId, expanded);
             }
             else {
-                existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId });
+                existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId, base_version: resolvedBaseVersion });
             }
             return text({
                 dry_run: true,
@@ -500,12 +613,23 @@ export function registerPersistenceTools(server, domain) {
             await updateDraft(existingDraftId, expanded);
         }
         else {
-            existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId });
+            existingDraftId = await putDraft({ source: expanded, kind: "update", page_id: resolvedPageId, base_version: resolvedBaseVersion });
+        }
+        const guard = await guardOverwrite(config, resolvedPageId, parsed, {
+            baseVersion: resolvedBaseVersion,
+            force,
+            retryHint: `update_page({ draft_id: "${existingDraftId}", dry_run:false })`,
+        });
+        if (!guard.ok) {
+            return text({ updated: false, ...guard.payload, draft_id: existingDraftId });
         }
         const outcome = await updatePageSource(config, resolvedPageId, parsed);
         if (outcome.ok) {
             await deleteDraft(existingDraftId);
-            return text({ updated: true, ...outcome, ...warningsField(result.warnings) });
+            // The page now holds exactly what we sent — that becomes the new baseline.
+            rememberPageVersion(resolvedPageId, sourceFingerprint(outcome.rehosted_source ?? parsed), "write");
+            invalidateSource(config, resolvedPageId);
+            return text({ updated: true, ...outcome, ...warningsField(result.warnings), ...(guard.notice ? { stale_check: guard.notice } : {}) });
         }
         await updateDraft(existingDraftId, expanded);
         return text({
@@ -688,6 +812,11 @@ export function registerPersistenceTools(server, domain) {
                 // Success: drop the draft now that sections are persisted.
                 if (existingDraftId)
                     await deleteDraft(existingDraftId);
+                // The BACKEND appended server-side, so the stored tree is no longer any
+                // source we hold — drop the baseline so the next whole-source overwrite
+                // has to prove itself against a fresh read.
+                forgetPageVersion(page_id);
+                invalidateSource(config, page_id);
             }
             else {
                 // Server-side failure (duplicate id vs live tree, etc.): keep the draft so
@@ -720,7 +849,7 @@ export function registerPersistenceTools(server, domain) {
         }
         // Fallback for an older backend WITHOUT /append_section (404): the original
         // heavier path — get the live source → merge → validate the WHOLE tree → put.
-        const current = await getPageSource(config, page_id);
+        const current = await readLiveSource(config, page_id);
         if (!current.ok || current.source == null) {
             return text({
                 added: false,
@@ -757,6 +886,12 @@ export function registerPersistenceTools(server, domain) {
         const fbOutcome = await updatePageSource(config, page_id, parsed);
         if (fbOutcome.ok && existingDraftId)
             await deleteDraft(existingDraftId);
+        // The fallback merged into the tree it JUST read, so no staleness guard is
+        // needed here — but the save makes a new baseline worth recording.
+        if (fbOutcome.ok)
+            rememberPageVersion(page_id, sourceFingerprint(fbOutcome.rehosted_source ?? parsed), "write");
+        if (fbOutcome.ok)
+            invalidateSource(config, page_id);
         return text({
             added: fbOutcome.ok,
             sections_added: newSections.length,
@@ -842,11 +977,15 @@ export function registerPersistenceTools(server, domain) {
             .any()
             .optional()
             .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted; set `type` to fix a wrong element type; update MERGES — it cannot DELETE an existing/stray key, so 'must NOT have additional properties' errors need op:'replace' with a clean node); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container. `element` may be a SPARSE node (id/type/styles/specials/events only) — the server hydrates omitted boilerplate from factory defaults. OMIT (or pass empty array) when draft_id is given and you just want to commit/retry the cached draft as-is."),
+        force: z
+            .boolean()
+            .optional()
+            .describe("Default false. Only meaningful when committing an 'update' draft: true saves the cached snapshot even though the page changed outside this session, discarding those changes. A page_id patch never needs it — it merges into the tree it just read."),
         dry_run: z
             .boolean()
             .optional()
             .describe("Default TRUE — load, merge, validate and preview the resulting save WITHOUT writing. Set false to actually save."),
-    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, draft_id, patches, dry_run }, extra) => {
+    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, draft_id, patches, force, dry_run }, extra) => {
         const isDry = dry_run !== false; // default true (safe)
         const ops = asArray(patches).filter((p) => p != null && typeof p === "object");
         // Empty ops are only valid when a draft_id is supplied (commit-as-is / retry path).
@@ -880,7 +1019,7 @@ export function registerPersistenceTools(server, domain) {
                     hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
                 });
             }
-            const current = await getPageSource(config, page_id);
+            const current = await readLiveSource(config, page_id);
             if (!current.ok || current.source == null) {
                 return text({
                     patched: false,
@@ -890,6 +1029,9 @@ export function registerPersistenceTools(server, domain) {
                     hint: "Check the page_id (find_pages/list_pages) and that the account owns it.",
                 });
             }
+            // This read is by definition current, so it becomes the baseline: a later
+            // update_page that still matches it is provably not reverting anything.
+            rememberPageVersion(page_id, sourceFingerprint(current.source), "read");
             base = current.source;
             if (typeof base === "string") {
                 try {
@@ -1050,6 +1192,8 @@ export function registerPersistenceTools(server, domain) {
                 const outcome = await appendSection(config, targetPageId, sectionsToAppend);
                 if (outcome.ok) {
                     await deleteDraft(draft_id);
+                    forgetPageVersion(targetPageId);
+                    invalidateSource(config, targetPageId);
                 }
                 else {
                     await updateDraft(draft_id, base);
@@ -1100,9 +1244,20 @@ export function registerPersistenceTools(server, domain) {
                     await updateDraft(draft_id, base);
                     return text({ patched: false, reason: "missing_env", missing_env: missing, hint: `Add WEBCAKE_API_BASE + WEBCAKE_JWT, then retry patch_page({ draft_id: "${draft_id}", dry_run:false }).` });
                 }
+                const guard = await guardOverwrite(config, targetPageId, parsed, {
+                    baseVersion: draft.base_version,
+                    force,
+                    retryHint: `patch_page({ draft_id: "${draft_id}", dry_run:false })`,
+                });
+                if (!guard.ok) {
+                    await updateDraft(draft_id, base);
+                    return text({ patched: false, updated: false, ...guard.payload, draft_id, patches_applied: applied });
+                }
                 const outcome = await updatePageSource(config, targetPageId, parsed);
                 if (outcome.ok) {
                     await deleteDraft(draft_id);
+                    rememberPageVersion(targetPageId, sourceFingerprint(outcome.rehosted_source ?? parsed), "write");
+                    invalidateSource(config, targetPageId);
                 }
                 else {
                     await updateDraft(draft_id, base);
@@ -1146,6 +1301,8 @@ export function registerPersistenceTools(server, domain) {
             const outcome = await createPage(config, draft.name ?? "AI Page", parsed, draft.organization_id);
             if (outcome.ok) {
                 await deleteDraft(draft_id);
+                rememberPageVersion(outcome.page_id, sourceFingerprint(outcome.rehosted_source ?? parsed), "write");
+                invalidateSource(config, outcome.page_id);
             }
             else {
                 await updateDraft(draft_id, base); // keep for retry
@@ -1182,7 +1339,12 @@ export function registerPersistenceTools(server, domain) {
         const parsed = domain.coerce(expanded);
         // CACHE-FIRST: write an 'update' draft BEFORE the network call so a timeout or
         // failure is recoverable via patch_page({ draft_id, dry_run:false }) with no patches.
-        const liveDraftId = await putDraft({ source: expanded, kind: "update", page_id: page_id });
+        const liveDraftId = await putDraft({
+            source: expanded,
+            kind: "update",
+            page_id: page_id,
+            base_version: lastKnownPageVersion(page_id)?.fp,
+        });
         if (isDry) {
             return text({
                 dry_run: true,
@@ -1197,6 +1359,8 @@ export function registerPersistenceTools(server, domain) {
         const outcome = await updatePageSource(config, page_id, parsed);
         if (outcome.ok) {
             await deleteDraft(liveDraftId);
+            rememberPageVersion(page_id, sourceFingerprint(outcome.rehosted_source ?? parsed), "write");
+            invalidateSource(config, page_id);
             return text({
                 patched: true,
                 patches_applied: applied,
@@ -1237,7 +1401,7 @@ export function registerPersistenceTools(server, domain) {
         // Publish re-saves the page's CURRENT stored source (the publish endpoint
         // requires it in the request), so read it first — even on dry_run, to show
         // the real payload.
-        const res = await getPageSource(config, page_id);
+        const res = await readLiveSource(config, page_id);
         if (!res.ok || res.source == null) {
             return text({ published: false, reason: "page_not_found", status: res.status, error: res.error ?? "No source on this page." });
         }

package/package.json

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