webcake-landing-mcp 1.0.1

package/dist/page-schema.json

@@ -0,0 +1,266 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://webcake/landing-page/page-schema.json",
+  "title": "WebcakePage",
+  "description": "Schema of a Webcake landing page source (the JSON stored in PageSource.source). A page is a list of absolutely-positioned section trees plus global settings. See docs/ai/page-element-schema.md for full conventions. NOTE: this is a descriptive/validation schema (not OpenAI strict-mode); specials and styles are intentionally open (additionalProperties:true) because the editor model is freeform.",
+  "type": "object",
+  "required": ["page"],
+  "additionalProperties": true,
+  "properties": {
+    "page": {
+      "type": "array",
+      "description": "Top-level SECTIONS stacked vertically (index 0 = top). Items are section (or dynamic_page). Popups go in the separate `popup` array, NOT here.",
+      "items": { "$ref": "#/$defs/element" }
+    },
+    "popup": {
+      "type": "array",
+      "description": "Separate top-level array of popup elements (type:\"popup\"). Triggered by events { action:\"open_popup\", target:<popup id> }.",
+      "items": { "$ref": "#/$defs/element" }
+    },
+    "dynamic_pages": {
+      "type": "array",
+      "description": "Dynamic (dataset-bound) page sections. Empty/absent for static pages.",
+      "items": { "$ref": "#/$defs/element" }
+    },
+    "options": {
+      "type": "object",
+      "description": "Editor options.",
+      "additionalProperties": true,
+      "properties": {
+        "currency": { "type": "string", "examples": ["VND", "USD"] },
+        "mobileOnly": { "type": "boolean", "description": "true = page only renders the mobile breakpoint." },
+        "versionID": { "type": ["string", "null"] }
+      }
+    },
+    "cartConfigs": { "type": "object", "additionalProperties": true, "description": "Cart/commerce config; {} when unused." },
+    "settings": {
+      "type": "object",
+      "description": "Page-wide config + SEO + fonts + tracking + custom code (real pages carry ~20-40 keys).",
+      "additionalProperties": true,
+      "properties": {
+        "title": { "type": "string", "description": "SEO title, <= 60 chars." },
+        "description": { "type": "string", "description": "SEO meta description, <= 160 chars." },
+        "keywords": { "type": "string", "description": "Comma-separated keywords." },
+        "favicon": { "type": "string" },
+        "thumbnail": { "type": "string", "description": "Social/share thumbnail URL." },
+        "fontGeneral": { "type": "string", "description": "Default page font-family, e.g. \"'Roboto', sans-serif\"." },
+        "width_section": {
+          "type": "object",
+          "description": "Canvas reference widths.",
+          "properties": { "desktop": { "type": "number" }, "mobile": { "type": "number" } }
+        },
+        "country": { "type": "string", "description": "Dialing/locale code, e.g. \"84\"." },
+        "fb_tracking_code": { "type": "string", "description": "Facebook pixel id." },
+        "tiktok_script": { "type": "string" },
+        "global_track_ids": { "type": "array" },
+        "extra_css": { "type": "string", "description": "Custom CSS injected into the page." },
+        "extra_script": { "type": "string", "description": "Custom JS injected into the page." },
+        "auto_save_draft": { "type": "boolean" },
+        "auto_save_info_user": { "type": "boolean" },
+        "send_info_to_thank_page": { "type": "boolean" }
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_]{4,32}$",
+      "description": "Unique id within the whole page (~8 chars). Referenced by event.target."
+    },
+    "elementType": {
+      "type": "string",
+      "description": "Element kind. Container types (have children): section, dynamic_page, group, grid, grid-item, carousel, slide, popup, form, gallery, checkbox-group, radio, group-select.",
+      "enum": [
+        "section", "dynamic_page", "group", "grid", "grid-item", "carousel", "slide", "popup",
+        "text-block", "list-paragraph", "image-block", "rectangle", "line", "button", "video",
+        "gallery", "html-box", "editor-blog",
+        "form", "input", "textarea", "select", "checkbox", "checkbox-group", "radio", "address",
+        "country-select", "quantity_input", "input-datetime", "input-file", "signature",
+        "verify-code", "group-select", "group-select-item",
+        "list-product", "search-list-product", "cart-items", "cart-quantity", "product-select", "table",
+        "countdown", "timegroup", "auto-number", "random-number", "notify", "spin-wheel", "survey",
+        "alertMessage"
+      ]
+    },
+    "styles": {
+      "type": "object",
+      "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." },
+        "position": { "type": "string", "enum": ["absolute", "relative", "fixed", "static"] },
+        "zIndex": { "type": "number" },
+        "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." },
+        "fontFamily": { "type": "string" },
+        "fontWeight": { "type": ["string", "number"] },
+        "fontStyle": { "type": "string" },
+        "textAlign": { "type": "string", "enum": ["start", "center", "end", "left", "right", "justify"] },
+        "lineHeight": { "type": ["number", "string"] },
+        "letterSpacing": { "type": ["number", "string"] },
+        "textTransform": { "type": "string" },
+        "textDecoration": { "type": "string" },
+        "borderStyle": { "type": "string", "enum": ["solid", "dashed", "dotted", "double", "none"] },
+        "borderWidth": { "type": "number", "description": "px." },
+        "borderColor": { "type": "string" },
+        "borderRadius": { "type": ["string", "number"] },
+        "boxShadow": { "type": "string" },
+        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
+        "mixBlendMode": { "type": "string" },
+        "transform": { "type": "string" },
+        "padding": { "type": ["number", "string"] },
+        "margin": { "type": ["number", "string"] }
+      }
+    },
+    "config": {
+      "type": "object",
+      "description": "Per-breakpoint non-CSS config (lazy-load flags, grid/carousel/countdown options).",
+      "additionalProperties": true,
+      "properties": {
+        "notloaded": { "type": "boolean" },
+        "animation": {
+          "type": "object",
+          "description": "Entrance animation for this element on this breakpoint.",
+          "additionalProperties": true,
+          "properties": {
+            "name": { "type": "string", "description": "animate.css name, or \"none\"." },
+            "delay": { "type": "number" },
+            "duration": { "type": "number" },
+            "repeat": { "type": ["number", "null"] }
+          }
+        },
+        "virtualHeight": { "type": "number" },
+        "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" }
+      }
+    },
+    "responsive": {
+      "type": "object",
+      "required": ["desktop", "mobile"],
+      "additionalProperties": false,
+      "properties": {
+        "desktop": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "config": { "$ref": "#/$defs/config" },
+            "styles": { "$ref": "#/$defs/styles" }
+          }
+        },
+        "mobile": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "config": { "$ref": "#/$defs/config" },
+            "styles": { "$ref": "#/$defs/styles" }
+          }
+        }
+      }
+    },
+    "properties": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "description": "Display label in the layer panel." },
+        "movable": { "type": "boolean", "description": "false for section/slide/grid-item/popup." },
+        "sync": { "type": "boolean" },
+        "thumbnail": { "type": "string" }
+      }
+    },
+    "event": {
+      "type": "object",
+      "description": "Interaction. type=trigger, action=behavior, target=id/url/text depending on action.",
+      "required": ["type", "action"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "description": "Event id (any string; ~8 chars in real data)." },
+        "type": {
+          "type": "string",
+          "enum": ["click", "hover", "success", "unset"],
+          "description": "Trigger."
+        },
+        "action": {
+          "type": "string",
+          "description": "Behavior. Common click actions and what target holds: none(-), open_link(URL), open_popup(popup id), close_popup(popup id), scroll_to(element/section id), show_section/hide_section(section id), show_hide_element(element id), change_tab(id), lightbox(image id/url), copy(text), collapse(id), set_field_value(field_name + set_value), back_to/back_home(url), share(url), play_audio/stop_audio(id), open_cart/add_to_cart(product id), open_app(provider: botcake|whatsapp|mess_prefill|tiktok_prefill|line_prefill), change_color, custom_js. Hover actions: change_color, change_background, change_text_color, change_underline, change_overline, change_image, animation_hover, show_hide_element.",
+          "examples": [
+            "none", "open_link", "open_popup", "close_popup", "scroll_to",
+            "show_section", "hide_section", "show_hide_element", "copy",
+            "set_field_value", "add_to_cart", "open_app"
+          ]
+        },
+        "target": {
+          "type": ["string", "null"],
+          "description": "Element id, URL, or text depending on action (null for some, e.g. animation_hover)."
+        },
+        "appTarget": {
+          "type": "string",
+          "description": "Secondary target for open_app / link behaviors (often empty string)."
+        },
+        "hoverColor": {
+          "type": "string",
+          "description": "Color for hover color-change actions (often empty string)."
+        },
+        "set_value": {
+          "type": "string",
+          "description": "Value to assign when action = set_field_value."
+        }
+      }
+    },
+    "specials": {
+      "type": "object",
+      "description": "Type-specific content/config. The user-visible CONTENT lives here, NOT in styles. Open object; key fields by type: section{globalSection,globalSectionName,custom_class,imageCompression}; text-block{text(HTML),tag}; list-paragraph{text(<li>..)}; image-block{src,resize}; button{text,required,format,connectedSurvey}; video{typeVideo,video_cdn,img,autoReplay}; gallery{media[]}; form{field_type,form_type,sheetOrder,validate,submit_success,fb_event_type,fb_conversion_value,fb_tracking_currency,tiktok_conversion_value,tiktok_tracking_currency}; input/textarea/select/checkbox/radio/address/...{field_name,field_placeholder,field_type,required,options}; countdown{type,duration,startTime,endTime,showDay,showSecond,showText,language,customTranslation}; survey{options[{id,image,title,value,field_name}],type,multiOption,selectedBackground,selectedBorder}; list-product{format_title,numerical_order,remain_quantity_text}.",
+      "additionalProperties": true,
+      "properties": {
+        "text": { "type": "string", "description": "text-block/button label/list-paragraph (may contain HTML)." },
+        "tag": { "type": "string", "enum": ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "div"] },
+        "src": { "type": "string", "description": "image-block image URL." },
+        "media": { "type": "array", "description": "gallery items (URLs or objects)." },
+        "field_name": { "type": "string", "description": "REQUIRED & unique for form inputs — the submitted data column." },
+        "field_placeholder": { "type": "string" },
+        "field_type": { "type": "string", "examples": ["text", "email", "phone", "number"] },
+        "required": { "type": "boolean" },
+        "options": { "type": "array", "description": "choices for select/radio/checkbox-group/survey/group-select-item." },
+        "typeVideo": { "type": "string", "examples": ["youtube", "upload", "vimeo"] },
+        "type": { "type": "string", "description": "sub-type for countdown/survey/etc." },
+        "duration": { "type": ["string", "number"] },
+        "imageCompression": { "type": "boolean" }
+      }
+    },
+    "element": {
+      "type": "object",
+      "required": ["id", "type", "properties", "responsive", "specials"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "type": { "$ref": "#/$defs/elementType" },
+        "properties": { "$ref": "#/$defs/properties" },
+        "responsive": { "$ref": "#/$defs/responsive" },
+        "specials": { "$ref": "#/$defs/specials" },
+        "runtime": { "type": "object", "description": "Always {} when generating.", "additionalProperties": true },
+        "events": { "type": "array", "items": { "$ref": "#/$defs/event" } },
+        "children": {
+          "type": "array",
+          "description": "Only on container types. Each child is itself an element.",
+          "items": { "$ref": "#/$defs/element" }
+        }
+      }
+    }
+  }
+}

package/dist/smoke.js

@@ -0,0 +1,122 @@
+/**
+ * Offline smoke test (no MCP transport): exercises the pure logic so we can
+ * verify the server's building blocks without a client. Run: npm run smoke
+ */
+import { createElement, CONTAINER_TYPES } from "./factory.js";
+import { LIBRARY } from "./library.js";
+import { validatePage } from "./validate.js";
+let failures = 0;
+const check = (name, cond, extra) => {
+    if (cond) {
+        console.log(`  ok  ${name}`);
+    }
+    else {
+        failures++;
+        console.log(`FAIL  ${name}`, extra ?? "");
+    }
+};
+console.log("== factory: every library type produces a valid skeleton ==");
+for (const type of Object.keys(LIBRARY)) {
+    const el = createElement(type);
+    const okBase = typeof el.id === "string" &&
+        el.type === type &&
+        !!el.responsive.desktop &&
+        !!el.responsive.mobile &&
+        typeof el.specials === "object";
+    const okChildren = CONTAINER_TYPES.has(type) ? Array.isArray(el.children) : el.children === undefined;
+    check(`skeleton ${type}`, okBase && okChildren, el);
+}
+console.log("== validate: a good page passes ==");
+const good = {
+    page: [
+        {
+            id: "sec1",
+            type: "section",
+            properties: { name: "Hero", movable: false, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { position: "relative", height: 600, background: "rgba(17,24,39,1)" } },
+                mobile: { config: {}, styles: { position: "relative", height: 520, background: "rgba(17,24,39,1)" } },
+            },
+            specials: {},
+            runtime: {},
+            events: [],
+            children: [
+                {
+                    id: "btn1",
+                    type: "button",
+                    properties: { name: "CTA", movable: true, sync: true },
+                    responsive: {
+                        desktop: { config: {}, styles: { top: 300, left: 400, width: 160, height: 44 } },
+                        mobile: { config: {}, styles: { top: 200, left: 130, width: 160, height: 44 } },
+                    },
+                    specials: { text: "Mở popup" },
+                    runtime: {},
+                    events: [{ id: "e1", type: "click", action: "open_popup", target: "pop1" }],
+                },
+            ],
+        },
+        {
+            id: "pop1",
+            type: "popup",
+            properties: { name: "Thanks", movable: false, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { width: 420, height: 220 } },
+                mobile: { config: {}, styles: { width: 360, height: 220 } },
+            },
+            specials: {},
+            runtime: {},
+            events: [],
+            children: [],
+        },
+    ],
+    settings: { title: "Demo", description: "d", keywords: "a,b", lang: "vi" },
+};
+const r1 = validatePage(good);
+check("good page valid", r1.valid, r1.errors);
+check("good page has no dangling-target warnings", r1.warnings.length === 0, r1.warnings);
+check("good page stats", r1.stats.sections === 2 && r1.stats.ids === 3, r1.stats);
+console.log("== validate: catches problems ==");
+const bad = {
+    page: [
+        {
+            id: "dup",
+            type: "text-block", // not a container, but has children -> error
+            properties: { name: "x" },
+            responsive: { desktop: { config: {}, styles: {} } }, // missing mobile -> error
+            specials: {},
+            children: [{ id: "dup", type: "input", properties: {}, responsive: { desktop: { config: {}, styles: {} }, mobile: { config: {}, styles: {} } }, specials: {} }],
+        },
+    ],
+};
+const r2 = validatePage(bad);
+check("bad page invalid", !r2.valid, r2);
+check("bad page detects duplicate id", r2.errors.some((e) => e.includes("Duplicate id")), r2.errors);
+check("bad page detects children-on-noncontainer", r2.errors.some((e) => e.includes("not a container")), r2.errors);
+check("bad page detects missing mobile", r2.errors.some((e) => e.toLowerCase().includes("mobile")), r2.errors);
+check("bad page warns missing field_name", r2.warnings.some((w) => w.includes("field_name")), r2.warnings);
+console.log("== validate: accepts JSON string input ==");
+const r3 = validatePage(JSON.stringify(good));
+check("string input parsed & valid", r3.valid, r3.errors);
+console.log("== library: each example validates as a single element subtree ==");
+for (const [type, doc] of Object.entries(LIBRARY)) {
+    if (!doc.example)
+        continue;
+    const wrapped = {
+        page: [
+            {
+                id: "wrapsec",
+                type: "section",
+                properties: { name: "w", movable: false, sync: true },
+                responsive: { desktop: { config: {}, styles: { position: "relative", height: 800 } }, mobile: { config: {}, styles: { position: "relative", height: 800 } } },
+                specials: {},
+                runtime: {},
+                events: [],
+                children: [doc.example],
+            },
+        ],
+    };
+    const rr = validatePage(wrapped);
+    check(`example ${type} valid`, rr.valid, rr.errors);
+}
+console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
+process.exit(failures === 0 ? 0 : 1);

package/dist/validate.js

@@ -0,0 +1,211 @@
+/**
+ * Page validation: JSON-Schema structural check (ajv, draft 2020-12) plus
+ * semantic checks the schema can't express (unique ids, dangling event targets,
+ * children only on containers, missing field_name, top-level types).
+ */
+import { readFileSync } from "node:fs";
+import Ajv2020Module from "ajv/dist/2020.js";
+import { CONTAINER_TYPES, FIELD_TYPES } from "./factory.js";
+// ajv ships as CJS; under Node16 ESM the constructor is on `.default`.
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+// Loaded at runtime (the build copies src/page-schema.json -> dist/page-schema.json)
+// to avoid JSON-import-attribute differences across Node versions.
+export const pageSchema = JSON.parse(readFileSync(new URL("./page-schema.json", import.meta.url), "utf8"));
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const validateSchema = ajv.compile(pageSchema);
+// Actions whose `target` is expected to be an element id (vs a URL / text).
+const ELEMENT_TARGET_ACTIONS = new Set([
+    "open_popup", "close_popup", "scroll_to", "show_section", "hide_section",
+    "show_hide_element", "change_tab", "play_audio", "stop_audio",
+]);
+const TOP_LEVEL_TYPES = new Set(["section", "dynamic_page", "popup"]);
+// Fixed canvas reference (matches library CANVAS) used for the layout/bounds check.
+const CANVAS_DESKTOP = 960;
+const CANVAS_MOBILE = 420;
+const DEFAULT_SECTION_HEIGHT = 800;
+const BOUNDS_TOL = 1; // px tolerance for rounding
+const MAX_LAYOUT_WARNINGS = 12;
+/** Coerce a style value (number or "300px"/"300") to a finite number, else undefined. */
+function num(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : undefined;
+    if (typeof v === "string") {
+        const n = parseFloat(v);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+/** Accept an object or a JSON string. Returns the parsed page or throws. */
+export function coercePage(input) {
+    if (typeof input === "string")
+        return JSON.parse(input);
+    return input;
+}
+export function validatePage(input) {
+    const errors = [];
+    const warnings = [];
+    let page;
+    try {
+        page = coercePage(input);
+    }
+    catch (e) {
+        return { valid: false, errors: [`Invalid JSON: ${e.message}`], warnings: [], stats: { sections: 0, popups: 0, elements: 0, ids: 0 } };
+    }
+    // 1) Structural (JSON Schema)
+    const ok = validateSchema(page);
+    if (!ok && validateSchema.errors) {
+        for (const err of validateSchema.errors) {
+            errors.push(`schema ${err.instancePath || "/"} ${err.message}`);
+        }
+    }
+    // 2) Semantic
+    const ids = new Map();
+    const eventTargets = [];
+    let elementCount = 0;
+    const topList = Array.isArray(page?.page)
+        ? page.page
+        : page?.page
+            ? [page.page]
+            : [];
+    if (topList.length === 0)
+        errors.push('Root "page" must be a non-empty array of sections.');
+    topList.forEach((sec, i) => {
+        if (sec && sec.type && !TOP_LEVEL_TYPES.has(sec.type)) {
+            warnings.push(`page[${i}] is type "${sec.type}"; top-level items are normally section/dynamic_page/popup.`);
+        }
+    });
+    const walk = (node, path) => {
+        if (!node || typeof node !== "object")
+            return;
+        elementCount++;
+        if (typeof node.id === "string")
+            ids.set(node.id, (ids.get(node.id) || 0) + 1);
+        else
+            errors.push(`${path}: missing string "id".`);
+        const type = node.type;
+        if (typeof type !== "string")
+            errors.push(`${path}: missing "type".`);
+        // responsive presence
+        if (!node.responsive?.desktop || !node.responsive?.mobile) {
+            errors.push(`${path} (${type}): must have responsive.desktop AND responsive.mobile.`);
+        }
+        // children only on containers
+        if (Array.isArray(node.children) && node.children.length > 0 && type && !CONTAINER_TYPES.has(type)) {
+            errors.push(`${path} (${type}): has children but "${type}" is not a container type.`);
+        }
+        // form fields need field_name
+        if (type && FIELD_TYPES.has(type)) {
+            const fn = node.specials?.field_name;
+            if (!fn || typeof fn !== "string" || fn.trim() === "") {
+                warnings.push(`${path} (${type}): form input should have a unique specials.field_name.`);
+            }
+        }
+        // collect events
+        if (Array.isArray(node.events)) {
+            for (const ev of node.events) {
+                if (ev && typeof ev.action === "string" && typeof ev.target === "string") {
+                    eventTargets.push({ from: node.id ?? path, action: ev.action, target: ev.target });
+                }
+            }
+        }
+        if (Array.isArray(node.children)) {
+            node.children.forEach((c, idx) => walk(c, `${path}.children[${idx}]`));
+        }
+    };
+    topList.forEach((sec, i) => walk(sec, `page[${i}]`));
+    // popups + dynamic_pages are SEPARATE top-level element arrays (not inside `page`)
+    const popups = Array.isArray(page?.popup) ? page.popup : [];
+    const dynPages = Array.isArray(page?.dynamic_pages) ? page.dynamic_pages : [];
+    popups.forEach((p, i) => {
+        if (p && p.type && p.type !== "popup") {
+            warnings.push(`popup[${i}] has type "${p.type}"; entries of "popup" should be type "popup".`);
+        }
+        walk(p, `popup[${i}]`);
+    });
+    dynPages.forEach((p, i) => walk(p, `dynamic_pages[${i}]`));
+    // duplicate ids
+    for (const [id, count] of ids) {
+        if (count > 1)
+            errors.push(`Duplicate id "${id}" used ${count} times — ids must be unique.`);
+    }
+    // dangling element-target events
+    for (const t of eventTargets) {
+        if (ELEMENT_TARGET_ACTIONS.has(t.action)) {
+            const cleaned = t.target.replace(/^#?w-/, "");
+            if (!ids.has(t.target) && !ids.has(cleaned)) {
+                warnings.push(`event on "${t.from}" action="${t.action}" target="${t.target}" does not match any element id.`);
+            }
+        }
+    }
+    // 3) Layout bounds — flag children that fall off their container's canvas (a
+    //    common cause of "off-center / misaligned" pages). Warnings only.
+    let layoutWarnings = 0;
+    const widthSection = page?.settings?.width_section ?? {};
+    const rootCanvasD = num(widthSection.desktop) ?? CANVAS_DESKTOP;
+    const rootCanvasM = num(widthSection.mobile) ?? CANVAS_MOBILE;
+    const checkBounds = (container, canvasWD, canvasHD, canvasWM, canvasHM, path) => {
+        if (!container || !Array.isArray(container.children))
+            return;
+        container.children.forEach((child, idx) => {
+            if (!child || typeof child !== "object")
+                return;
+            const cpath = `${path}.children[${idx}]`;
+            const label = `${cpath} (${child.type ?? "?"})`;
+            for (const [bp, canvasW, canvasH] of [
+                ["desktop", canvasWD, canvasHD],
+                ["mobile", canvasWM, canvasHM],
+            ]) {
+                const styles = child?.responsive?.[bp]?.styles;
+                if (!styles)
+                    continue;
+                const left = num(styles.left) ?? 0;
+                const top = num(styles.top) ?? 0;
+                const width = num(styles.width);
+                const height = num(styles.height);
+                if (layoutWarnings < MAX_LAYOUT_WARNINGS) {
+                    if (left < -BOUNDS_TOL) {
+                        warnings.push(`${label} ${bp}: left=${left} is negative (off-canvas left). Set left ≥ 0.`);
+                        layoutWarnings++;
+                    }
+                    else if (width != null && left + width > canvasW + BOUNDS_TOL) {
+                        warnings.push(`${label} ${bp}: left+width=${left + width} exceeds canvas ${canvasW} (overflows right). To center: left = round((${canvasW} - ${width})/2) = ${Math.round((canvasW - width) / 2)}.`);
+                        layoutWarnings++;
+                    }
+                }
+                if (layoutWarnings < MAX_LAYOUT_WARNINGS && top < -BOUNDS_TOL) {
+                    warnings.push(`${label} ${bp}: top=${top} is negative (above its section). Set top ≥ 0.`);
+                    layoutWarnings++;
+                }
+                if (layoutWarnings < MAX_LAYOUT_WARNINGS &&
+                    canvasH > 0 &&
+                    height != null &&
+                    top + height > canvasH + BOUNDS_TOL) {
+                    warnings.push(`${label} ${bp}: top+height=${top + height} exceeds container height ${canvasH} (extends below). Move it up or increase the section/container height.`);
+                    layoutWarnings++;
+                }
+            }
+            // Recurse into nested containers using the child's own box as the canvas.
+            if (Array.isArray(child.children) && child.children.length > 0) {
+                const ds = child?.responsive?.desktop?.styles ?? {};
+                const ms = child?.responsive?.mobile?.styles ?? {};
+                checkBounds(child, num(ds.width) ?? canvasWD, num(ds.height) ?? canvasHD, num(ms.width) ?? canvasWM, num(ms.height) ?? canvasHM, cpath);
+            }
+        });
+    };
+    topList.forEach((sec, i) => {
+        const ds = sec?.responsive?.desktop?.styles ?? {};
+        const ms = sec?.responsive?.mobile?.styles ?? {};
+        checkBounds(sec, rootCanvasD, num(ds.height) ?? DEFAULT_SECTION_HEIGHT, rootCanvasM, num(ms.height) ?? DEFAULT_SECTION_HEIGHT, `page[${i}]`);
+    });
+    popups.forEach((p, i) => {
+        const ds = p?.responsive?.desktop?.styles ?? {};
+        const ms = p?.responsive?.mobile?.styles ?? {};
+        checkBounds(p, num(ds.width) ?? rootCanvasD, num(ds.height) ?? DEFAULT_SECTION_HEIGHT, num(ms.width) ?? rootCanvasM, num(ms.height) ?? DEFAULT_SECTION_HEIGHT, `popup[${i}]`);
+    });
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        stats: { sections: topList.length, popups: popups.length, elements: elementCount, ids: ids.size },
+    };
+}