webcake-landing-mcp 1.0.57 → 1.0.58

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.58",
+    "d": "11/06/2026",
+    "type": "Changed",
+    "en": "html-box descriptor (get_element) has been rewritten to document COMPOSITE VISUALS as the primary use case: intricate non-interactive mockups such…",
+    "vi": "Descriptor html-box (get_element) được viết lại để ghi lại COMPOSITE VISUALS là trường hợp sử dụng chính: các mockup phi tương tác phức tạp như…"
+  },
   {
     "v": "1.0.57",
     "d": "11/06/2026",
@@ -33,12 +40,5 @@
     "type": "Fixed",
     "en": "The login command on Windows now opens the connect URL correctly: cmd /c start previously split the URL at the first & character (treating it as a…",
     "vi": "Lệnh login trên Windows nay mở URL kết nối chính xác: trước đây cmd /c start tách URL tại ký tự & đầu tiên (do hiểu & là dấu phân cách lệnh), khiến…"
-  },
-  {
-    "v": "1.0.52",
-    "d": "10/06/2026",
-    "type": "Added",
-    "en": "validate_page now errors when an element type that the renderer cannot animate (any type other than group, image-block, text-block, rectangle,…",
-    "vi": "validate_page nay báo lỗi khi một element có loại không được renderer hỗ trợ animation (chỉ group, image-block, text-block, rectangle, button,…"
   }
 ]

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

@@ -237,13 +237,25 @@ export const CONTENT = [
     {
         type: "html-box", category: "content", container: false, defaultName: "HTML Box",
         summary: "Raw HTML embed. specials.html holds the markup stored HTML-escaped (unescaped at render via v-html). Contrast with editor-blog which stores html RAW. Embedded <iframe> is auto-stretched to 100%×100% of the box. Wrapper height is FIXED to styles.height — content taller than the box overflows. &nbsp; in the stored value becomes a space at render. Use unescape-safe HTML (e.g. '&lt;' → the literal character '<' after unescape).",
-        useWhen: "Embedding third-party widgets or custom markup the standard elements can't express.",
+        useWhen: "COMPOSITE VISUALS (primary use): intricate, non-interactive mockups with 10+ nested parts — phone/chat mockup (message thread with bubbles/avatars/tags), mini dashboard, browser-window frame, inbox/notification list, ticket-style card. Use ONE html-box per mockup instead of 30-40 absolute-positioned elements. Recipe: (1) inline styles ONLY — no class/id (no stylesheet inside the box); (2) root div: style='width:100%;height:100%;box-sizing:border-box;overflow:hidden;…' — fills the element box; flex/grid are fine INSIDE the box (absolute-canvas rule applies only to Webcake elements); (3) design inner content to fit styles.height — content taller overflows silently; (4) specials.html must be HTML-ESCAPED ('&lt;div…'); (5) set BOTH breakpoints with real width/height; (6) set font-family inline on the root if the mockup needs a specific font. WHEN NOT to use: real headings, CTAs, forms, prices, any content the user/editor must edit per-piece, or any element that events must target — html-box is an opaque blob in the editor and invisible to form/event wiring; never put the page's primary copy in one. ALSO: embedding third-party widgets or custom markup the standard elements can't express.",
         keySpecials: { html: "string — raw HTML content stored HTML-escaped (e.g. '&lt;p&gt;Hello&lt;/p&gt;'); the renderer unescapes it before injecting via v-html. The wrapper height is FIXED to styles.height — content that is taller overflows the box. An embedded <iframe> is auto-stretched to 100%×100% of the box." },
         seed: (el) => {
             seedPosition(el);
             setBox(el, 280, 310);
             el.specials.html = "";
         },
+        example: {
+            id: "phone_chat1", type: "html-box",
+            responsive: {
+                desktop: { styles: { top: 60, left: 330, width: 300, height: 360, position: "absolute" } },
+                mobile: { styles: { top: 60, left: 60, width: 300, height: 360, position: "absolute" } },
+            },
+            specials: {
+                // Phone-chat mockup: rounded shell + header bar + 2 chat bubbles.
+                // Stored HTML-ESCAPED — the renderer unescapes before v-html injection.
+                html: "&lt;div style=&quot;width:100%;height:100%;box-sizing:border-box;display:flex;flex-direction:column;overflow:hidden;border-radius:24px;background:#fff;box-shadow:0 8px 32px rgba(0,0,0,0.18);font-family:system-ui,sans-serif;&quot;&gt;&lt;div style=&quot;background:#4f46e5;padding:14px 16px;display:flex;align-items:center;gap:10px;&quot;&gt;&lt;div style=&quot;width:36px;height:36px;border-radius:50%;background:#a5b4fc;display:flex;align-items:center;justify-content:center;font-size:16px;color:#fff;font-weight:bold;&quot;&gt;W&lt;/div&gt;&lt;div&gt;&lt;div style=&quot;color:#fff;font-weight:600;font-size:14px;&quot;&gt;Webcake Support&lt;/div&gt;&lt;div style=&quot;color:#c7d2fe;font-size:11px;&quot;&gt;Online&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;&lt;div style=&quot;flex:1;padding:16px;display:flex;flex-direction:column;gap:12px;background:#f5f5f5;&quot;&gt;&lt;div style=&quot;display:flex;gap:8px;align-items:flex-end;&quot;&gt;&lt;div style=&quot;width:28px;height:28px;border-radius:50%;background:#4f46e5;flex-shrink:0;&quot;&gt;&lt;/div&gt;&lt;div style=&quot;background:#fff;border-radius:16px 16px 16px 4px;padding:10px 14px;font-size:13px;color:#1a1a2e;max-width:200px;box-shadow:0 1px 4px rgba(0,0,0,0.08);&quot;&gt;Chào bạn! Mình có thể giúp gì cho bạn hôm nay? 😊&lt;/div&gt;&lt;/div&gt;&lt;div style=&quot;display:flex;gap:8px;align-items:flex-end;flex-direction:row-reverse;&quot;&gt;&lt;div style=&quot;background:#4f46e5;border-radius:16px 16px 4px 16px;padding:10px 14px;font-size:13px;color:#fff;max-width:200px;&quot;&gt;Mình muốn tạo landing page cho shop! 🚀&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;",
+            },
+        },
     },
     {
         type: "editor-blog", category: "content", container: false, defaultName: "Editor blog",

package/dist/domains/landing/guide.js

@@ -102,6 +102,7 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 - FORM / CTA — center the form box; stack inputs vertically with comfortable spacing; each input needs a unique specials.field_name (canonical: full_name, phone_number, email, address, quantity); prominent submit button.
 - FOOTER — name + real contact lines, usually centered on a dark band. Only real data the user provided.
 - TAG/BADGE "PILL" recipe — a rounded rectangle (borderRadius "13px", the pill bg color) BEHIND a text-block (zIndex 2, styles.backgroundTxt for the box fill if needed, textAlign center). NEVER put the pill color in styles.background on the text-block — that key activates gradient-text-fill mode (the renderer emits -webkit-text-fill-color:transparent and the glyphs go invisible). text-block does NOT emit border-radius at all — the rounded shape must come from a rectangle behind the text.
+- COMPLEX COMPOSITE VISUAL (phone/chat mockup, mini dashboard, browser-window frame, inbox/notification list, ticket-style card) → ONE html-box with inline-styled HTML (root div: width:100%;height:100%;box-sizing:border-box;overflow:hidden; flex/grid allowed inside; content must fit styles.height or it overflows silently) instead of dozens of tiny elements. Never use html-box for primary copy, CTAs, form fields, or any element that events must target — it is an opaque blob in the editor.
 
 RULES
 - Visible content goes in "specials" (text-block.specials.text, image-block.specials.src…), NEVER in "styles".
@@ -153,5 +154,5 @@ EDITING an existing page
 
 REFERENCE INPUT (HTML page to clone or adapt)
 - ingest_html(html, detail:'full') / ingest_url(url, detail:'full') returns a richer AST for clone-quality rebuilds: CSS custom-property palette (design tokens by name), background_images from stylesheets (hero/CTA bg images invisible to a plain img scan), per-section blocks (repeating card/tile/step structures with title/body/image/cta), li lists, gradients, and images as { src, alt } objects. Use detail:'compact' (default) for a quick layout-only reference.
-- Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links.
+- Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links. When the ingested page contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), NOT as element soup.
 - When intent='clone': re-host image URLs found in the AST (images, background_images, og_image) via upload_images instead of hotlinking. For intent='adapt' (default): use the AST for layout/hierarchy only and write fresh content for the user's brand.`;

package/dist/domains/landing/instructions.js

@@ -24,7 +24,7 @@ RULES (follow for every request):
   A wrong element type is the most common error → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements if unsure). Drafts expire in ~30 min.
 - DRY-RUN CACHE: create_page, update_page, and add_section dry_run=true all cache the validated payload and return a draft_id. Re-run the same tool with { draft_id, dry_run:false } — no need to re-send the source.
 - Organizations: call list_organizations and ask which to use; default to the is_default org. Endpoints are owner-scoped (only the account's own pages).
-- REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements using role→element hints (hero → section with background image/overlay + heading + paragraph + button; features → group blocks with icon/title/text; stats bar → group with heading+text per stat; pricing → group with text list + button; footer → section with text + links). (2) HTML string → call ingest_html(html, detail:'full') to get the richer AST when cloning; use detail:'compact' (default) for a layout-only reference. (3) URL → call ingest_url(url, detail:'full') for the same richer AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), CSS custom-property palette, background_images from stylesheets, and in full mode: per-section blocks (cards/tiles/steps with title/body/image/cta), li lists, and gradients — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). When cloning (intent='clone'), re-host image URLs found in the AST (images, background_images, og_image) via upload_images instead of hotlinking. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
+- REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements using role→element hints (hero → section with background image/overlay + heading + paragraph + button; features → group blocks with icon/title/text; stats bar → group with heading+text per stat; pricing → group with text list + button; footer → section with text + links). When the reference contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box (clone its HTML with all styles inlined), not as element soup. (2) HTML string → call ingest_html(html, detail:'full') to get the richer AST when cloning; use detail:'compact' (default) for a layout-only reference. (3) URL → call ingest_url(url, detail:'full') for the same richer AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), CSS custom-property palette, background_images from stylesheets, and in full mode: per-section blocks (cards/tiles/steps with title/body/image/cta), li lists, and gradients — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). When cloning (intent='clone'), re-host image URLs found in the AST (images, background_images, og_image) via upload_images instead of hotlinking. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
 
 MODEL (essentials):
 - Top-level: { page:[sections], popup:[popups], dynamic_pages:[], settings:{}, options:{mobileOnly,versionID}, cartConfigs:{isActive:false}, svariations:[] }. Popups are a SEPARATE top-level array, NOT inside page; currency lives in settings.currency (not options). Leave dynamic_pages/svariations as [] for a static page, but keep them on edit round-trips.

package/package.json

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