webcake-landing-mcp 1.0.5 → 1.0.6

package/README.md

@@ -190,7 +190,7 @@ The MCP config is the same as the local one, but `command`/`args` point at `npx`
 git clone https://github.com/vuluu2k/webcake-landing-mcp.git
 cd webcake-landing-mcp
 npm install        # postinstall `prepare` builds dist/ automatically
-npm run build      # (re)build: tsc -> dist/ + copies page-schema.json
+npm run build      # (re)build: tsc -> dist/ + copies src/**/*.json (page-schema.json) into dist/
 npm run smoke      # offline self-test of factory + validator (prints "ALL GOOD")
 ```
 
@@ -603,5 +603,5 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 - Colors are `rgba()`; `top/left/width/height/fontSize` are numbers (px); form inputs need a unique `specials.field_name`.
 
 Reference: [docs/page-element-schema.md](docs/page-element-schema.md) and
-[src/page-schema.json](src/page-schema.json) (the bundled JSON Schema, Draft 2020-12). The schema mirrors
+[src/domains/landing/page-schema.json](src/domains/landing/page-schema.json) (the bundled JSON Schema, Draft 2020-12). The schema mirrors
 the real editor `page_source` shape.

package/README.vi.md

@@ -190,7 +190,7 @@ Cấu hình MCP giống bản local, chỉ khác `command`/`args` trỏ tới `n
 git clone https://github.com/vuluu2k/webcake-landing-mcp.git
 cd webcake-landing-mcp
 npm install        # postinstall `prepare` tự build dist/
-npm run build      # (re)build: tsc -> dist/ + copy page-schema.json
+npm run build      # (re)build: tsc -> dist/ + copy src/**/*.json (page-schema.json) vào dist/
 npm run smoke      # self-test offline của factory + validator (in "ALL GOOD")
 ```
 
@@ -604,5 +604,5 @@ gửi, JWT được che); đặt `dry_run=false` để ghi thật. Kết quả t
 
 Tham khảo: [docs/page-element-schema.md](docs/page-element-schema.md),
 [docs/element-specials-reference.md](docs/element-specials-reference.md) (tham chiếu đầy đủ mọi specials/event),
-và [src/page-schema.json](src/page-schema.json) (JSON Schema, Draft 2020-12). Schema phản ánh đúng
+và [src/domains/landing/page-schema.json](src/domains/landing/page-schema.json) (JSON Schema, Draft 2020-12). Schema phản ánh đúng
 hình dạng `page_source` thật của editor.

package/dist/core/descriptor.js

@@ -0,0 +1,43 @@
+/**
+ * The single-descriptor element model.
+ *
+ * Every element type is declared ONCE as an `ElementDescriptor`: its category,
+ * its container/field flags, its default layer name, its AI usage docs, an
+ * optional filled example, and a `seed` that stamps the factory's visual
+ * defaults onto a fresh node. From a list of descriptors we DERIVE the catalog
+ * (docs), the container-type set, and the field-type set — so adding an element
+ * is a one-file change instead of editing four files that must stay in sync.
+ */
+import { base } from "./element.js";
+/** Build a default node for a descriptor (replaces the old `createElement` switch). */
+export function createElementFrom(d, overrides = {}) {
+    const el = base();
+    el.type = d.type;
+    el.properties.name = overrides.name ?? d.defaultName;
+    if (d.container)
+        el.children = [];
+    d.seed?.(el);
+    return el;
+}
+/** Catalog (docs) derived from descriptors — the LIBRARY the reference tools read. */
+export function buildCatalog(elements) {
+    const catalog = {};
+    for (const d of elements) {
+        catalog[d.type] = {
+            type: d.type,
+            category: d.category,
+            container: d.container,
+            summary: d.summary,
+            useWhen: d.useWhen,
+            keySpecials: d.keySpecials,
+            example: d.example,
+        };
+    }
+    return catalog;
+}
+export function deriveContainerTypes(elements) {
+    return new Set(elements.filter((d) => d.container).map((d) => d.type));
+}
+export function deriveFieldTypes(elements) {
+    return new Set(elements.filter((d) => d.field).map((d) => d.type));
+}

package/dist/core/domain.js

@@ -0,0 +1 @@
+export {};

package/dist/core/element.js

@@ -0,0 +1,60 @@
+/**
+ * Domain-agnostic element primitives shared by every domain that builds an
+ * absolute-positioned, per-breakpoint element tree (the Webcake editor model).
+ *
+ * Holds the node shape, the empty-node factory (`base`), the small style
+ * helpers, and the id/placeholder/animation utilities. A domain's per-element
+ * `seed` (see ../core/descriptor.ts) builds on these to produce a structurally
+ * valid default node. Nothing here knows about "landing pages" specifically.
+ */
+const ALNUM = "abcdefghijklmnopqrstuvwxyz0123456789";
+export function randomId(len = 8) {
+    let s = "";
+    for (let i = 0; i < len; i++)
+        s += ALNUM[Math.floor(Math.random() * ALNUM.length)];
+    return s;
+}
+/**
+ * Placeholder image URL. There is no image API yet, so generated image elements
+ * get a visible placeholder (sized to the element) instead of an empty src —
+ * otherwise the page renders blank where images should be. Users swap these later.
+ */
+export function imgPlaceholder(w = 600, h = 400, label = "Image") {
+    return `https://placehold.co/${Math.round(w)}x${Math.round(h)}?text=${encodeURIComponent(label)}`;
+}
+/** Default per-breakpoint animation block (matches real page_source). */
+export function defaultAnimation() {
+    return { name: "none", delay: 0, duration: 3, repeat: null };
+}
+/** An empty, structurally-valid element node (no type yet). */
+export function base() {
+    return {
+        id: randomId(),
+        type: "",
+        properties: { movable: true, sync: true },
+        responsive: {
+            desktop: { config: { notloaded: false, animation: defaultAnimation() }, styles: {} },
+            mobile: { config: { notloaded: false, animation: defaultAnimation() }, styles: {} },
+        },
+        specials: {},
+        runtime: {},
+        events: [],
+    };
+}
+/** Set the same style key on both breakpoints. */
+export function setStyle(el, key, value) {
+    el.responsive.desktop.styles[key] = value;
+    el.responsive.mobile.styles[key] = value;
+}
+/** Set width+height on both breakpoints. */
+export function setBox(el, w, h) {
+    if (w != null)
+        setStyle(el, "width", w);
+    if (h != null)
+        setStyle(el, "height", h);
+}
+/** Seed top/left = 0 on both breakpoints (absolute-positioned leaf inside a container). */
+export function seedPosition(el) {
+    setStyle(el, "top", 0);
+    setStyle(el, "left", 0);
+}

package/dist/domains/landing/elements/commerce.js

@@ -0,0 +1,92 @@
+import { seedPosition, setStyle, setBox } from "../../../core/element.js";
+export const COMMERCE = [
+    {
+        type: "list-product", category: "commerce", container: false, defaultName: "ListProduct",
+        summary: "Product list bound to the page store; clicking a card opens the popup-checkout overlay.",
+        useWhen: "Show purchasable products.",
+        keySpecials: {
+            select: "'product' | 'tag' | 'category' — which dimension to filter products by.",
+            type: "'expect' | 'except' — treat the expect*/except* arrays as an allowlist (expect) or denylist (except).",
+            expect: "array of product id strings to include (select='product', type='expect').",
+            except: "array of product id strings to exclude (select='product', type='except').",
+            expectCategory: "array of category ids to include (select='category').",
+            exceptCategory: "array of category ids to exclude (select='category').",
+            expectTags: "array of tag slugs to include (select='tag').",
+            exceptTags: "array of tag slugs to exclude (select='tag').",
+            format_title: "'default' | 'sku' | 'sku-name' | 'name-category' — product title composition.",
+            format_price: "'range' | 'discount' — 'discount' shows the % off badge when original > retail.",
+            direction: "'column' | (other) — 'column' = whole card is one click target; otherwise thumbnail + cart button each get handlers (and remain-quantity shows).",
+            numerical_order: "boolean — show numbered labels (01, 02 …) on thumbnails.",
+            remain_quantity_text: "string — low-stock label; {{value}} is replaced with the actual remaining count.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 400, 162);
+            el.specials.format_title = "sku";
+            el.specials.numerical_order = true;
+        },
+    },
+    {
+        type: "search-list-product", category: "commerce", container: false, defaultName: "SearchListProduct",
+        summary: "Search box + product results. Reads NO specials (all DOM-driven) and REQUIRES a co-existing list-product element on the page — openProduct() delegates to a list-product vm, so without one nothing opens.",
+        useWhen: "Searchable catalog (pair it with a list-product element).",
+        keySpecials: {},
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 400, 40);
+            setStyle(el, "background", "rgba(246, 4, 87, 1)");
+            setStyle(el, "color", "rgba(255,255,255,1)");
+        },
+    },
+    {
+        type: "cart-items", category: "commerce", container: false, defaultName: "CartItems",
+        summary: "Items currently in the cart. Has NO element specials — the WCart system writes its inner HTML at runtime and it needs the cart active (is_cart_active). Item name/price/quantity font sizes come from the page-level cartConfigs.checkoutElements['CART-ITEM'] (itemNameSize/itemPriceSize/inputQuantitySize), not from this node.",
+        useWhen: "Cart/checkout area (requires WCart active).",
+        keySpecials: {},
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 233, 80);
+        },
+    },
+    {
+        type: "cart-quantity", category: "commerce", container: false, defaultName: "Cart Quantity",
+        summary: "Quantity stepper (+/-) that controls a field in the parent variation group; publishes <id>__quantity-change on each click.",
+        useWhen: "Per-variation quantity inside a cart/form group.",
+        keySpecials: {
+            field_name: "REQUIRED — identifies which field in the parent variation group this stepper controls.",
+            ignoreOnHidden: "boolean — when hidden, suppress this element's quantity contribution (calls _addIgnoreField/_removeIgnoreField on the parent vm).",
+        },
+        // NOT a FIELD_TYPE (field flag omitted) but the renderer still requires a
+        // field_name, so the seed sets one explicitly.
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 150, 36);
+            el.specials.field_name = `cart_quantity_${el.id}`;
+        },
+    },
+    {
+        type: "product-select", category: "commerce", container: false, defaultName: "product-select",
+        summary: "STUB — no runtime renderer exists in render_v4, so placing this type produces a non-functional element that does nothing on the page. Use list-product (catalog) or form (order capture) instead.",
+        useWhen: "Do NOT use — it is a reserved/legacy stub. Prefer list-product or form.",
+        keySpecials: {},
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 200, 100);
+        },
+    },
+    {
+        type: "table", category: "commerce", container: false, defaultName: "Table",
+        summary: "Data table rendered from a pre-fetched Google Sheets 2D array.",
+        useWhen: "Pricing/comparison/spec tables (data must be pre-loaded into specials).",
+        keySpecials: {
+            dataType: "0 | 1 — MUST be 1 to render anything; the renderer returns early when dataType != 1.",
+            source: "string — data source label (metadata only).",
+            sheetID: "string — Google Sheet document id (metadata only).",
+            google_sheet_data: "string[][] — the 2D table data; row 0 = headers as 'Title|type' where type ∈ image|video|link|time (absent type = plain text); rows 1+ are data cells.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 400, 210);
+        },
+    },
+];

package/dist/domains/landing/elements/content.js

@@ -0,0 +1,202 @@
+import { seedPosition, setStyle, setBox, imgPlaceholder } from "../../../core/element.js";
+export const CONTENT = [
+    {
+        type: "text-block", category: "content", container: false, defaultName: "Text",
+        summary: "Text. specials.text holds the content (may contain inline HTML); specials.tag sets the semantic tag. Supports template variables ({{key}}), formula mode, URL-param injection, and date formatting.",
+        useWhen: "Any headline, paragraph, label. Use tag h1/h2 for headings, p for body. Style via responsive.styles (fontSize, color, fontWeight, textAlign).",
+        keySpecials: {
+            text: "string — the visible text; may include inline HTML (<b>, <br>, <span style>…). Also supports template variables: {{today}}, {{yesterday}}, {{tomorrow}} (formatted dates), {{coupon_text}}, {{coupon_code}}, {{coupon_codes}}, {{spin_turn_left}}, {{cart_total_price}}, {{cart_subtotal}}, {{cart_shipping_fee}}, {{cart_discount_code}}, {{voucher_price_cart}}, {{cart_item}}, {{cart_bonus_item}}, {{form_error_log}}, {{total_cart}}. Dynamic form field binding: {{formId__fieldName}} substitutes a field value from a sibling form.",
+            tag: "p | h1 | h2 | h3 | h4 | h5 | h6 | span | div.",
+            isFormula: "boolean — enable formula/computed numeric mode.",
+            formula: "string — formula expression evaluated to produce a numeric value (used when isFormula=true).",
+            fixed: "number — decimal places to display when isFormula=true.",
+            isTextParams: "boolean — populate text from a URL query parameter instead of specials.text.",
+            textParams: "string — URL query parameter name to read (used when isTextParams=true).",
+            isFormat: "boolean — apply a date format to template date variables.",
+            format: "string — dayjs format string (e.g. 'D/MM/YYYY') used when isFormat=true.",
+            formParamSeparator: "string — separator between items when rendering {{formId__form_items}} lists.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 200);
+            el.specials.text = "hello world";
+            el.specials.tag = "p";
+        },
+        example: {
+            id: "headline1", type: "text-block",
+            properties: { name: "Headline", movable: true, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { top: 80, left: 180, width: 600, fontSize: 44, fontWeight: "bold", color: "rgba(255,255,255,1)", textAlign: "center" } },
+                mobile: { config: {}, styles: { top: 60, left: 20, width: 380, fontSize: 28, fontWeight: "bold", color: "rgba(255,255,255,1)", textAlign: "center" } },
+            },
+            specials: { text: "Bán hàng dễ hơn với Webcake", tag: "h1" },
+            runtime: {}, events: [],
+        },
+    },
+    {
+        type: "list-paragraph", category: "content", container: false, defaultName: "ListParagraph",
+        summary: "Bulleted list. specials.text is a string of <li>…</li> items.",
+        useWhen: "Feature checklists, benefit lists. One <li> per bullet.",
+        keySpecials: {
+            text: "string of <li>item</li><li>item</li>… (no <ul> wrapper). Bullet/icon styling lives in the per-breakpoint config, not specials: iconType ('shape'|'image'|'disc'|'circle'|'square'|'decimal'|'none'…), iconImage (SVG/URL), iconColor (rgba), iconFontSize, iconSize, iconTop, linePaddingLeft (text indent), linePaddingBottom (line spacing).",
+            iconSize: "(config) bullet icon size.", linePaddingLeft: "(config) text indent.",
+        },
+        seed: (el) => {
+            setBox(el, 400);
+            el.responsive.desktop.config = { ...el.responsive.desktop.config, iconSize: 12, iconTop: 5, linePaddingLeft: 23 };
+            el.responsive.mobile.config = { ...el.responsive.mobile.config, iconSize: 12, iconTop: 5, linePaddingLeft: 23 };
+            el.specials.text = "<li>List Paragraph.</li><li>List Paragraph.</li><li>List Paragraph.</li>";
+        },
+    },
+    {
+        type: "image-block", category: "content", container: false, defaultName: "Image Block",
+        summary: "Image. The editor renders the image from specials.src. config.overlay tints it.",
+        useWhen: "Add images where a landing page would have them: hero/product shot, feature icons, about photo, logos. There is NO image API yet — set specials.src to a PLACEHOLDER URL sized to the box: https://placehold.co/<width>x<height> (or https://picsum.photos/<w>/<h> for a photo). NEVER leave src empty (it renders blank). The user replaces placeholders later.",
+        keySpecials: {
+            src: "image URL — REQUIRED. Use https://placehold.co/WxH (matching width×height) if you don't have a real image.",
+            resize: "number — image crop behavior on resize; a value other than 300 triggers keep_solution (no-crop) mode.",
+            enable_background_compare: "boolean — show a before/after image-comparison slider (companion config.backgroundCompare holds the second image).",
+            overlay: "(config) overlay color rgba(...).",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 110, 80);
+            setStyle(el, "position", "absolute");
+            el.specials.imageCompression = true;
+            el.specials.src = imgPlaceholder(600, 400);
+        },
+        example: {
+            id: "hero_img", type: "image-block",
+            properties: { name: "Image Block", movable: true, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { top: 40, left: 540, width: 360, height: 300, position: "absolute" } },
+                mobile: { config: {}, styles: { top: 260, left: 60, width: 300, height: 240, position: "absolute" } },
+            },
+            specials: { src: "https://placehold.co/360x300?text=Product", imageCompression: true },
+            runtime: {}, events: [],
+        },
+    },
+    {
+        type: "rectangle", category: "content", container: false, defaultName: "Rectangle",
+        summary: "Colored block — divider, badge background, color band, card backdrop.",
+        useWhen: "Backgrounds behind text/groups, dividers, decorative shapes. Style via background/borderRadius/boxShadow.",
+        keySpecials: {},
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 100, 100);
+        },
+    },
+    {
+        type: "line", category: "content", container: false, defaultName: "Line",
+        summary: "Horizontal rule / divider line.",
+        useWhen: "Separating content rows.",
+        keySpecials: {},
+        seed: (el) => {
+            setBox(el, 236);
+        },
+    },
+    {
+        type: "button", category: "content", container: false, defaultName: "Button",
+        summary: "Clickable button. Label in specials.text; behavior in the events array. Supports the same template variable system as text-block ({{today}}, {{cart_total_price}}, {{formId__fieldName}}, etc.).",
+        useWhen: "Every CTA. Add a click event: open_link (to URL), open_popup (lead modal), scroll_to (anchor). Inside a form, a button submits the form.",
+        keySpecials: {
+            text: "button label — supports template variables (same set as text-block: {{today}}, {{cart_total_price}}, {{formId__fieldName}}, etc.).",
+            required: "boolean — gate by form validity.",
+            isTextParams: "boolean — populate label from a URL query parameter instead of specials.text.",
+            textParams: "string — URL query parameter name to read (used when isTextParams=true).",
+            isFormat: "boolean — apply a date format to template date variables.",
+            format: "string — dayjs format string (e.g. 'D/MM/YYYY') used when isFormat=true.",
+            formParamSeparator: "string — separator between items when rendering {{formId__form_items}} lists.",
+            isConnectSurvey: "boolean — link this button to a survey element for required-field validation before submit.",
+            connectedSurvey: "string — id of the survey element to validate when isConnectSurvey=true.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 150, 36);
+            el.specials.text = "Button";
+        },
+        example: {
+            id: "cta_main", type: "button",
+            properties: { name: "CTA", movable: true, sync: true },
+            responsive: {
+                desktop: { config: {}, styles: { top: 300, left: 405, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
+                mobile: { config: {}, styles: { top: 200, left: 135, width: 150, height: 44, background: "rgba(246,4,87,1)", color: "rgba(255,255,255,1)", borderRadius: "8px", textAlign: "center", fontWeight: "bold" } },
+            },
+            specials: { text: "Đăng ký ngay" }, runtime: {},
+            events: [{ id: "ev_cta", type: "click", action: "scroll_to", target: "form_section" }],
+        },
+    },
+    {
+        type: "video", category: "content", container: false, defaultName: "Video",
+        summary: "Video player (YouTube/Vimeo/upload/CDN). Use specials.typeVideo to select the source type.",
+        useWhen: "Demo or promo videos. Set specials.img to a poster placeholder (https://placehold.co/640x360) when there's no real thumbnail.",
+        keySpecials: {
+            typeVideo: "'youtube' | 'vimeo' | 'webcake' | 'upload' — video source type.",
+            video: "string — raw video URL (for upload/webcake/CDN types).",
+            id: "string — YouTube video ID (for typeVideo='youtube').",
+            video_cdn: "string — CDN video URL or identifier.",
+            img: "string — poster/thumbnail image URL — use a placeholder if none (https://placehold.co/640x360).",
+            autoReplay: "boolean — loop the video.",
+            showControl: "boolean — show player controls.",
+            hideRelated: "boolean — hide YouTube related videos at end.",
+            muteOnPlay: "boolean — mute audio when video plays.",
+            autoPlay: "boolean — autoplay on load.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 350, 200);
+            el.specials.imageCompression = true;
+            el.specials.img = imgPlaceholder(640, 360, "Video");
+        },
+    },
+    {
+        type: "gallery", category: "content", container: false, defaultName: "Gallery",
+        summary: "Multi-image/video gallery with thumbnail strip. Content comes entirely from specials.media — this is NOT a container and has no children.",
+        useWhen: "Photo grids/galleries with several images or videos. No image API — fill specials.media with placeholder URLs (https://placehold.co/600x400).",
+        keySpecials: {
+            media: "array of image URLs or video objects {type:'video', linkVideo:'<url>', typeVideo:'youtube'|'upload'} — use placeholder URLs if no real images.",
+            allowZoom: "'off' | 'carousel' | 'lightbox' — (config) zoom/lightbox mode when clicking an image.",
+            showNavigation: "boolean — (config) show prev/next navigation arrows.",
+            thumbnailAutoplay: "number (ms) | 'off' — (config) auto-advance thumbnails every N ms, or 'off' to disable.",
+            thumbnailAutoplayRepeat: "boolean — (config) loop thumbnail autoplay.",
+            thumbnailPosition: "'top' | 'bottom' | 'left' | 'right' — (config) position of the thumbnail strip relative to the main image.",
+            thumbnailWidth: "number — (config) width of each thumbnail in px.",
+            thumbnailHeight: "number — (config) height of each thumbnail in px.",
+            distanceAmong: "number — (config) gap between thumbnails in px.",
+        },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 350, 400);
+            el.specials.media = [imgPlaceholder(600, 400, "1"), imgPlaceholder(600, 400, "2"), imgPlaceholder(600, 400, "3")];
+            // gallery has NO children — content comes entirely from specials.media (gallery.js never reads vm.children)
+        },
+    },
+    {
+        type: "html-box", category: "content", container: false, defaultName: "HTML Box",
+        summary: "Raw HTML embed. specials.html holds the markup (rendered via v-html).",
+        useWhen: "Embedding third-party widgets or custom markup the standard elements can't express.",
+        keySpecials: { html: "string — raw HTML content (the only content key; stored HTML-escaped, unescaped at render)." },
+        seed: (el) => {
+            seedPosition(el);
+            setBox(el, 280, 310);
+            el.specials.html = "";
+        },
+    },
+    {
+        type: "editor-blog", category: "content", container: false, defaultName: "Editor blog",
+        summary: "Long-form rich text / article body. specials.html holds the rich-text markup.",
+        useWhen: "Blog/article content blocks.",
+        keySpecials: { html: "string — rich-text HTML content (stored HTML-escaped, unescaped at render)." },
+        seed: (el) => {
+            el.responsive.mobile.styles.width = 340;
+            el.responsive.mobile.styles.height = 303;
+            el.responsive.desktop.styles.width = 800;
+            el.responsive.desktop.styles.height = 124;
+            el.responsive.mobile.styles.top = 0;
+            el.responsive.mobile.styles.left = 0;
+            el.responsive.desktop.styles.top = 0;
+            el.responsive.desktop.styles.left = 0;
+            el.specials.html = "";
+        },
+    },
+];