webcake-landing-mcp 1.0.55 → 1.0.57

package/README.md

@@ -152,6 +152,11 @@ npx -y webcake-landing-mcp login    # opens the browser once, saves the token to
 
 …or set `WEBCAKE_ENV` (`local` | `staging` | `prod` — fills in all base URLs) + `WEBCAKE_JWT`.
 
+For `publish_page` to produce a **rendered** (non-blank) page, a build host is needed:
+- `prod` preset auto-configures `https://build.webcake.io` — no extra setup.
+- For staging/local, set `WEBCAKE_BUILD_BASE=<url>` or send the `x-webcake-build-base` header per request.
+- Without it, `publish_page` falls back to source-only with `rendered:false` + a warning.
+
 Everything else — the full env-var table, environment presets, per-request headers for the hosted
 server, the `login` browser flow (+ backend contract), and how to grab a JWT by hand — lives in
 **[docs/configuration.md](docs/configuration.md)**.
@@ -164,7 +169,7 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 |-------|---------------|
 | **[Connect your IDE / claude.ai](docs/connect-mcp.md)** | Step-by-step connection for every client (npx & hosted URL), troubleshooting table. |
 | **[Configuration](docs/configuration.md)** | Env vars, `--env` presets, browser `login`, per-request headers, getting a JWT. |
-| **[Tools reference](docs/tools.md)** | All 19 tools in detail + the step-by-step workflow + model notes. |
+| **[Tools reference](docs/tools.md)** | All 20 tools in detail + the step-by-step workflow + model notes. |
 | **[Usage examples](docs/usage-examples.md)** | Three end-to-end walkthroughs: build from a brief, surgical edit, inspect a type. |
 | **[Manual / advanced install](docs/manual-install.md)** | Shell installers, cloned builds, hand-written per-IDE config. |
 | **[Page-element schema](docs/page-element-schema.md)** | The full element-model reference (+ [every special/event](docs/element-specials-reference.md)). |
@@ -173,13 +178,13 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 
 ## 🧰 The tools at a glance
 
-19 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
+20 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
 
 | Group | Tools | Needs |
 |-------|-------|-------|
 | **Reference** | `get_generation_guide` · `list_elements` · `get_element` · `get_page_schema` | nothing |
 | **Generation** | `new_element` · `new_page_skeleton` · `validate_page` | nothing |
-| **Media** | `search_images` (real Pexels stock photos) | nothing (optional own key) |
+| **Media** | `search_images` (real Pexels stock photos) · `upload_images` (re-host external images) | nothing |
 | **Ingest** | `ingest_html` · `ingest_url` (recreate an existing page) | nothing |
 | **Persistence** | `list_organizations` · `create_page` · `list_pages` · `find_pages` · `get_page` · `update_page` · `add_section` · `patch_page` · `publish_page` | `WEBCAKE_API_BASE` + `WEBCAKE_JWT` |
 

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.57",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "New upload_images tool re-hosts up to 20 external image URLs or data: URIs as Webcake-hosted URLs (statics.pancake.vn) by downloading and uploading…",
+    "vi": "Công cụ upload_images mới tải lại tối đa 20 URL ảnh ngoài hoặc data: URI thành URL do Webcake lưu trữ (statics.pancake.vn) bằng cách tải về và…"
+  },
+  {
+    "v": "1.0.56",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "The expand pipeline now automatically derives styles.background from specials.src for every image-block node; the live published renderer reads only…",
+    "vi": "Pipeline expand nay tự động tính styles.background từ specials.src cho mọi node image-block; renderer trên trang published chỉ đọc…"
+  },
   {
     "v": "1.0.55",
     "d": "10/06/2026",
@@ -26,19 +40,5 @@
     "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,…"
-  },
-  {
-    "v": "1.0.51",
-    "d": "10/06/2026",
-    "type": "Added",
-    "en": "create_page, update_page, and add_section dry-run responses now include a draft_id, and all three tools now accept draft_id as an input parameter:…",
-    "vi": "Các response dry-run của create_page, update_page và add_section nay đều trả về draft_id, đồng thời cả ba công cụ đều nhận draft_id làm tham số đầu…"
-  },
-  {
-    "v": "1.0.50",
-    "d": "10/06/2026",
-    "type": "Added",
-    "en": "New publish_page tool makes a page live: reads the page's current stored source, saves it as a new version, and creates or updates the…",
-    "vi": "Công cụ publish_page mới giúp đưa trang lên live: đọc source đang lưu của trang, lưu thành phiên bản mới và tạo hoặc cập nhật bản ghi…"
   }
 ]

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

@@ -2,22 +2,60 @@ 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.",
+        summary: "Product list bound to the page store; clicking a card opens the popup-checkout overlay configured by page-level cartConfigs.checkoutConfig.",
         useWhen: "Show purchasable products.",
         keySpecials: {
+            // --- filter / layout ---
             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').",
+            type: "'expect' | 'except' — treat the expect*/except* arrays as an allowlist (expect) or denylist (except). FOOTGUN: type='expect' + select='product' + empty expect array renders ZERO products (empty allowlist = nothing; category/tag allowlists treat empty differently). SSR caps at 200 products.",
+            expect: "array of product id strings to include (select='product', type='expect'). Must be non-empty when type='expect', otherwise no products render.",
             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).",
+            direction: "'column' | (other) — layout direction. With the SSR wrapper every card is fully clickable in BOTH directions; thumbnail+cart-only handlers are a legacy path.",
+            row_layout: "'layout_1' | 'layout_2' — row-direction card variant (row only).",
             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.",
+            // --- title / price ---
+            format_title: "'default' | 'sku' | 'sku-name' | 'name-category' — product title composition.",
+            format_price: "'range' | 'discount' | 'discount-revert' — 'discount' shows % off badge when original > retail; 'discount-revert' reverses the cost/price order + badge; any non-'range' value shows the first variation's original+retail pair.",
+            // --- quantity / stock ---
+            show_remain_quantity: "boolean — show remaining stock count (default true).",
+            remain_quantity_text: "string — low-stock label; {{value}} replaced with actual count.",
+            is_runout: "boolean — hide sold-out products.",
+            // --- rating / social proof ---
+            show_rating_star: "boolean — show fake star rating derived from product name. WARNING: if any product has a null name this throws at product.name.charCodeAt and crashes the build for that card.",
+            show_total_sold: "boolean — show total sold count.",
+            // --- image ---
+            hide_product_image: "boolean — hide product thumbnail.",
+            thumbnail_size: "number (px, default 195) — thumbnail width.",
+            thumbnail_height: "number (px) — thumbnail height override.",
+            background_size: "'cover' | 'contain' | … (default 'cover') — thumbnail background-size.",
+            // --- button ---
+            show_add_button: "'show' | 'hide' | 'hide_icon' (default 'show') — add-to-cart button visibility.",
+            text_add_button: "string — custom add-to-cart button label.",
+            iconCart: "url string — custom cart icon for the button.",
+            btn_width: "number (px, default 182) — button width.",
+            btn_height: "number (px) — button height.",
+            btn_border: "string — button border shorthand.",
+            border_type_btn: "string — button border type.",
+            border_width_btn: "number — button border width.",
+            // --- SKU / extras ---
+            show_extra_sku: "boolean — show additional SKU attributes on the card.",
+            // --- typography / font ---
+            font_family: "string — card font family.",
+            textAlign: "'left' | 'center' | 'right' — card text alignment.",
+            boldName: "boolean — bold product name.",
+            boldExtraTitle: "boolean — bold extra SKU title.",
+            list_product_font: "object — per-element font sizes (px numbers): { pName, pPrice, pOrgPrice, pQuantity, pButton, pStarSize, pTotalSold }.",
+            // --- flash sale ---
+            show_flash_sale_icon: "boolean (default true) — show flash-sale badge icon.",
+            // --- checkout overlay ---
+            // NOTE: the checkout overlay itself is configured by page-level
+            // cartConfigs.checkoutConfig (show_description / show_attrs /
+            // show_quantity / popup_position …), NOT by list-product specials.
+            // Only format_price passes through to the overlay from here.
         },
         seed: (el) => {
             seedPosition(el);
@@ -26,11 +64,21 @@ export const COMMERCE = [
             el.specials.format_title = "sku";
             el.specials.numerical_order = true;
         },
+        // Styles consumed beyond colorBtn (all exportCss.js):
+        // colorIconBtn, colorBtnBorder, colorTextBtn, colorBgIcon,
+        // colorTitle, colorPrice, colorQuantity, colorBg, colorFlashSale,
+        // colorTextSale, borderRadius.
     },
     {
         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).",
+        summary: [
+            "Search box + product results overlay. Requires a co-existing list-product element on the page — openProduct() delegates to a list-product vm, so without one nothing opens.",
+            "CRASH: clicking search hard-crashes when product sync is absent (window.sync.products.findIndex, search-list-product.js:51) — page must have synced products.",
+            "Placeholder text and button label are NOT settable — they are locale-fixed by currency.",
+            "background + color style the SEARCH BUTTON only; borderRadius splits input-left / button-right.",
+            "A single search hit skips the results popup and opens the checkout overlay directly.",
+        ].join(" "),
+        useWhen: "Searchable catalog (pair it with a list-product element and ensure product sync is active).",
         keySpecials: {},
         seed: (el) => {
             seedPosition(el);
@@ -41,8 +89,14 @@ export const COMMERCE = [
     },
     {
         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).",
+        summary: [
+            "DO NOT PLACE — renders an empty string on the published page.",
+            "The publish renderer's type-switch has no cart-items case (index.js default ''), and render_v4 has no cart-items class.",
+            "The real cart-items UI is WCart's own floating drawer (div.cart_view) appended beside the cart icon (CartView.ts:172,249; floating.ts:164) — it is positioned by cart settings, not by this element.",
+            "Editor shows a placeholder product card; live page shows nothing (editor ≠ live).",
+            "The page-level cartConfigs.checkoutElements['CART-ITEM'] (itemNameSize / itemPriceSize / inputQuantitySize) styles the FLOATING DRAWER — values must be CSS strings WITH units (e.g. \"14px\"); bare numbers produce invalid CSS.",
+        ].join(" "),
+        useWhen: "Do NOT place this element. Configure cartConfigs.checkoutElements['CART-ITEM'] for drawer font sizes instead.",
         keySpecials: {},
         seed: (el) => {
             seedPosition(el);
@@ -51,11 +105,18 @@ export const COMMERCE = [
     },
     {
         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.",
+        summary: [
+            "Quantity stepper (+/-) for a product variation group.",
+            "Value always starts at 1 (hardcoded); minus clamps at 1; plus is unbounded.",
+            "Publishes <id>__quantity-change on each click so WCart can read input[type=number] in the variation group DOM.",
+            "ignoreOnHidden is DEAD CODE on live — the show/hide dispatcher only handles checkbox-group / select / radio / quantity_input; cart-quantity is not in that list, so hiding this element never suppresses its quantity contribution.",
+            "field_name path: the SSR input has no name attribute; quantity flows via WCart reading input[type=number] in the sprod variation group (WCart path — works with any field_name value, including the seeded cart_quantity_<id>).",
+            "The form quantity-LINK path (linkType / prodId|variationId) requires field_name==='quantity' AND field_type==='number' exactly — the seeded cart_quantity_<id> never satisfies that; only change field_name to 'quantity' when using the explicit form-link path, not the WCart group path.",
+        ].join(" "),
+        useWhen: "Per-variation quantity inside a WCart 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).",
+            field_name: "REQUIRED for the renderer. WCart group path: any unique value (seed's cart_quantity_<id> is fine). Form quantity-LINK path: must be exactly 'quantity' + field_type='number' + linkType/prodId/variationId.",
+            ignoreOnHidden: "boolean — DEAD CODE on live (dispatcher does not handle cart-quantity). Has no effect on quantity contribution when hidden.",
         },
         // NOT a FIELD_TYPE (field flag omitted) but the renderer still requires a
         // field_name, so the seed sets one explicitly.
@@ -77,13 +138,34 @@ export const COMMERCE = [
     },
     {
         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).",
+        summary: [
+            "Data table rendered server-side from specials.sourceTable (escaped HTML string).",
+            "The published SSR renders ONLY unescapeHTML(specials.sourceTable) — the Google Sheets branch is commented out in the publisher (index.js:1172-1226).",
+            "EDITOR ≠ LIVE: the editor is DATASET-driven (specials.datasetId → /api/datasets/records) and snapshots its rendered DOM back into specials.sourceTable on every save — an MCP-authored google_sheet_data-only table shows BLANK in the editor, and re-saving from the editor can WIPE sourceTable.",
+            "ALWAYS author specials.sourceTable (the escaped HTML string) as the primary content key.",
+            "dataType=1 + google_sheet_data: renders blank on first paint / no-JS / SEO (render_v4 Table class overwrites .table-wrapper client-side at table.js:16,81). A google_sheet_data with exactly 1 row renders an empty box (table.js:20-21).",
+        ].join(" "),
+        useWhen: "Pricing/comparison/spec tables. Always provide specials.sourceTable (escaped HTML); google_sheet_data alone is blank on SSR/SEO.",
         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.",
+            // --- content (primary) ---
+            sourceTable: "PRIMARY CONTENT — escaped HTML string of the full rendered table. The SSR publisher outputs unescapeHTML(sourceTable) directly. Without this the published table is blank. Author this first; the editor will update it from its dataset on re-save.",
+            dataType: "0 | 1 — set to 1 to enable the client-side Table renderer; 0 = no client-side render. Does not affect SSR (sourceTable is always used server-side).",
+            source: "string — data source label (metadata only; not rendered).",
+            sheetID: "string — Google Sheet document id (metadata only; not rendered on publish).",
+            google_sheet_data: "string[][] — 2D table data for the client-side renderer (render_v4); row 0 = headers as 'Title|type' (type ∈ image|video|link|time; absent = plain text); rows 1+ are data cells. BLANK on SSR/no-JS — always pair with sourceTable.",
+            // --- styling specials (all consumed by exportCss.js:2047-2106 / cssTable) ---
+            // These are specials, NOT styles. Values are CSS strings.
+            hidden_title: "truthy — hides thead on live (editor only hides when === 'none'). E.g. 'none' to hide on both.",
+            head_background: "CSS color string — header row background.",
+            head_color: "CSS color string — header row text color.",
+            row_even_background: "CSS color string — even data-row background.",
+            row_even_color: "CSS color string — even data-row text color.",
+            row_odd_background: "CSS color string — odd data-row background.",
+            row_odd_color: "CSS color string — odd data-row text color.",
+            padding_content: "CSS padding string — cell padding (e.g. '8px 12px').",
+            borderWidth: "CSS length string — table border width (e.g. '1px').",
+            borderColor: "CSS color string — table border color.",
+            borderStyle: "CSS border-style string — table border style (e.g. 'solid').",
         },
         seed: (el) => {
             seedPosition(el);

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

@@ -3,7 +3,7 @@ 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). ALWAYS set color to CONTRAST the band it sits on: near-black (e.g. rgba(26,32,44,1)) on light bands, near-white ONLY on a dark/image band — white text on a light band renders invisible.",
+        useWhen: "Any headline, paragraph, label. Use tag h1/h2 for headings, p for body. Style via responsive.styles (fontSize, color, fontWeight, textAlign). ALWAYS set color to CONTRAST the band it sits on: near-black (e.g. rgba(26,32,44,1)) on light bands, near-white ONLY on a dark/image band — white text on a light band renders invisible. styles.background on a text-block = a GRADIENT TEXT FILL (emits -webkit-text-fill-color:transparent); you must also set styles['-webkitBackgroundClip']:'text' or the glyphs go invisible. The box background key is styles.backgroundTxt — use that for a colored box behind the text. NEVER set styles.background expecting a box fill. text-block does NOT emit border-radius — for a rounded pill/badge, put a rectangle (borderRadius '13px', pill bg color) BEHIND the text-block (zIndex 2 on the text-block); the rounded shape comes from the rectangle, never from the text-block itself.",
         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.",
@@ -15,6 +15,9 @@ export const CONTENT = [
             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.",
+            backgroundTxt: "(styles key) box background color rgba(...) — use this for a colored box behind the text. Do NOT use styles.background for a box fill; that key activates gradient text-fill mode.",
+            "-webkitBackgroundClip": "(styles key) set to 'text' when styles.background is a gradient — without it the gradient text-fill makes glyphs invisible.",
+            virtualHeight: "(config, per breakpoint, px) — live overrides height:auto with this value. If set it must be ≥ the rendered text height or live clips the text. Optional.",
         },
         seed: (el) => {
             seedPosition(el);
@@ -35,11 +38,17 @@ export const CONTENT = [
     },
     {
         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.",
+        summary: "Bulleted list. specials.text is a string of <li>…</li> items. specials.text is REQUIRED — if omitted the live renderer renders the literal string 'undefined'.",
+        useWhen: "Feature checklists, benefit lists. One <li> per bullet. Always set iconSize and linePaddingLeft together — the live renderer defaults are iconSize=40 (very large) and linePaddingLeft=0 (text overlaps bullet). A safe starting config: iconSize:12, iconTop:5, linePaddingLeft:23.",
         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.",
+            text: "string of <li>item</li><li>item</li>… (no <ul> wrapper). REQUIRED — missing text renders the literal string 'undefined' on the live page.",
+            iconType: "(config, per breakpoint) 'shape' | 'image' | 'disc' | 'circle' | 'square' | 'decimal' | 'none'… — 'shape' uses an SVG mask colored by iconColor, 'image' uses a background image URL. Live default: 'shape'.",
+            iconImage: "(config, per breakpoint) SVG string (must start with '<svg', no leading whitespace — leading whitespace triggers a URL fetch) or image URL when iconType='image'.",
+            iconColor: "(config, per breakpoint) rgba(...) — bullet color when iconType='shape'. Live default: black.",
+            iconSize: "(config, per breakpoint) bullet icon size in px. Live default: 40 (very large) — always set this explicitly, e.g. 12.",
+            iconTop: "(config, per breakpoint) vertical offset for the bullet icon in px. Live default: 0. Use ~4–6 to vertically align with text.",
+            linePaddingLeft: "(config, per breakpoint) text indent in px. Live default: 0 (text overlaps bullet) — always set this explicitly to ≥ iconSize+4, e.g. 23.",
+            linePaddingBottom: "(config, per breakpoint) line spacing in px.",
         },
         seed: (el) => {
             setBox(el, 400);
@@ -50,13 +59,17 @@ export const CONTENT = [
     },
     {
         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>. NEVER leave src empty (it renders blank). The user replaces placeholders later.",
+        summary: "Image. The LIVE published page paints the image from styles.background (exportCss.js) — the server automatically derives this from specials.src on every expand (create/update/validate). specials.src is the EDITOR key; always set it and let the server keep both in sync. config.overlay tints the image.",
+        useWhen: "Add images where a landing page would have them: hero/product shot, feature icons, about photo, logos. Set specials.src to the image URL. Use https://placehold.co/WxH?text=Label if you don't have a real image. NEVER leave src empty — it renders blank on the live page.",
         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.",
+            src: "image URL — REQUIRED. The editor reads this key; the server derives styles.background (the live renderer's key) automatically from it: 'center center/ cover no-repeat scroll content-box url(<src>) border-box'. If you hand-write styles.background it must contain url(...). Use https://placehold.co/WxH if no real image.",
+            keep_solution: "boolean — true = no-crop CDN resize (preserves aspect ratio); false = crop to box. Live reads config.keep_solution ?? specials.keep_solution. The editor's 'resize' key is editor-only sugar for this — set keep_solution directly.",
+            widthBgImage: "(config) CDN width for the background image crop — defaults to the element's styles.width.",
+            heightBgImage: "(config) CDN height for the background image crop — defaults to the element's styles.height.",
+            topBgImage: "(config) vertical crop offset in px — default 0.",
+            leftBgImage: "(config) horizontal crop offset in px — default 0.",
             enable_background_compare: "boolean — show a before/after image-comparison slider (companion config.backgroundCompare holds the second image).",
-            overlay: "(config) overlay color rgba(...).",
+            overlay: "(config) overlay tint color rgba(...). Gradient border recipe: set styles.borderColor to linear-gradient/radial-gradient AND styles.borderImage to activate a gradient-border underlay.",
         },
         seed: (el) => {
             seedPosition(el);
@@ -64,39 +77,77 @@ export const CONTENT = [
             setStyle(el, "position", "absolute");
             el.specials.imageCompression = true;
             el.specials.src = imgPlaceholder(600, 400);
+            // Stamp styles.background from the placeholder src so the live renderer
+            // paints the image even before the normalization pass (seed is the baseline).
+            const bg = `center center/ cover no-repeat scroll content-box url(${imgPlaceholder(600, 400)}) border-box`;
+            el.responsive.desktop.styles.background = bg;
+            el.responsive.mobile.styles.background = bg;
         },
         example: {
             id: "hero_img", type: "image-block",
             responsive: {
-                desktop: { styles: { top: 40, left: 540, width: 360, height: 300, position: "absolute" } },
-                mobile: { styles: { top: 260, left: 60, width: 300, height: 240, position: "absolute" } },
+                desktop: {
+                    styles: {
+                        top: 40, left: 540, width: 360, height: 300, position: "absolute",
+                        background: "center center/ cover no-repeat scroll content-box url(https://placehold.co/360x300?text=Product) border-box",
+                    },
+                },
+                mobile: {
+                    styles: {
+                        top: 260, left: 60, width: 300, height: 240, position: "absolute",
+                        background: "center center/ cover no-repeat scroll content-box url(https://placehold.co/300x240?text=Product) border-box",
+                    },
+                },
             },
             specials: { src: "https://placehold.co/360x300?text=Product", imageCompression: true },
         },
     },
     {
         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: {},
+        summary: "Colored block — divider, badge background, color band, card backdrop. Also doubles as an SVG icon/shape via per-breakpoint config.svgMask: set a raw <svg> string there and the renderer applies it as a mask; the shape color comes entirely from styles.background. Can also hold a CDN-resized image as a clipped background (styles.background with url(...)). Gradient border: set styles.borderColor to a linear/radial-gradient AND styles.borderImage — the renderer activates the gradient-border underlay. config.overlay adds a tint layer on top of a background image.",
+        useWhen: "Backgrounds behind text/groups, dividers, decorative shapes. Style via background/borderRadius/boxShadow. LEAF — it must NEVER have children (validation blocks it): for a card, wrap a group around it and make this the group's full-size FIRST child as the backdrop. For feature/benefit icons, USE THIS with config.svgMask + a brand-colored styles.background INSTEAD of emoji characters in text — it looks far more professional and scales cleanly on all devices.",
+        keySpecials: {
+            svgMask: "(config, per breakpoint) — raw <svg viewBox='…'>…</svg> string. The renderer base64-encodes it and applies it as -webkit-mask-image on the element; the shape color comes from styles.background (solid rgba or gradient). The SVG's own fill/stroke colors are IGNORED — only painted pixels (alpha) matter, so the SVG must paint via fill or stroke to produce a silhouette. Aspect: the published renderer force-inserts preserveAspectRatio='none' (SVG stretches to the box) but the editor preview keeps the SVG's own aspect ratio — so ALWAYS match the box aspect to the viewBox aspect (square box for a square viewBox) or editor and live render differently. Use single quotes for SVG attributes to avoid JSON-escaping noise. Set on BOTH desktop and mobile config or mobile renders a plain rectangle.",
+            overlay: "(config) tint layer rgba(...) drawn on top of the background image.",
+        },
         seed: (el) => {
             seedPosition(el);
             setBox(el, 100, 100);
         },
+        example: {
+            id: "icon_star", type: "rectangle",
+            responsive: {
+                desktop: {
+                    styles: { top: 40, left: 456, width: 48, height: 48, background: "rgba(34,197,94,1)" },
+                    config: { svgMask: "<svg viewBox='0 0 24 24'><path fill='black' d='M12 2l2.9 6.26L22 9.27l-5 4.87L18.18 21 12 17.27 5.82 21 7 14.14l-5-4.87 7.1-1.01z'/></svg>" },
+                },
+                mobile: {
+                    styles: { top: 40, left: 186, width: 48, height: 48, background: "rgba(34,197,94,1)" },
+                    config: { svgMask: "<svg viewBox='0 0 24 24'><path fill='black' d='M12 2l2.9 6.26L22 9.27l-5 4.87L18.18 21 12 17.27 5.82 21 7 14.14l-5-4.87 7.1-1.01z'/></svg>" },
+                },
+            },
+            specials: {},
+        },
     },
     {
         type: "line", category: "content", container: false, defaultName: "Line",
-        summary: "Horizontal rule / divider line.",
-        useWhen: "Separating content rows.",
+        summary: "Horizontal rule / divider line. The visible line is the TOP border only: the base CSS zeroes left/right/bottom borders. Thickness is styles.borderWidth (NOT styles.height — height is auto). The .line-css class adds padding:8px 0 so the line sits 8px below the element's top. Color via styles.borderColor; style via styles.borderStyle.",
+        useWhen: "Separating content rows. Always set borderWidth, borderStyle, and borderColor — without them the line renders as an invisible element.",
         keySpecials: {},
         seed: (el) => {
             setBox(el, 236);
+            el.responsive.desktop.styles.borderWidth = 1;
+            el.responsive.desktop.styles.borderStyle = "solid";
+            el.responsive.desktop.styles.borderColor = "rgba(208,213,221,1)";
+            el.responsive.mobile.styles.borderWidth = 1;
+            el.responsive.mobile.styles.borderStyle = "solid";
+            el.responsive.mobile.styles.borderColor = "rgba(208,213,221,1)";
         },
     },
     {
         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.",
+        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. Hover color changes: use the modern change_color action with change_color_type:'text'|'background'|'border'|'reset' — the legacy change_background (--hover-color var) and change_text_color (--hover-text var) actions are broken on published pages because the CSS variables are never defined at publish time.",
         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.",
@@ -125,16 +176,17 @@ export const CONTENT = [
     },
     {
         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.",
+        summary: "Video player (YouTube/Vimeo/upload/CDN). Required specials by typeVideo: 'youtube' → specials.id REQUIRED (YouTube videoId); 'vimeo' → specials.video REQUIRED (full Vimeo URL); 'webcake' → specials.video REQUIRED (missing causes a video.replace TypeError that breaks the page); 'upload'/other → specials.video (src = video_cdn || video). Poster: first url() in styles.background takes precedence over specials.img — a flat background color (no url()) suppresses the img poster. specials.videoFit default 'cover'; false = 'contain'. showControl default-off hides Vimeo controls entirely.",
+        useWhen: "Demo or promo videos. Set specials.img to a poster placeholder (https://placehold.co/640x360) when there's no real thumbnail. Do NOT set a flat styles.background color — it suppresses the poster image.",
         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).",
+            typeVideo: "'youtube' | 'vimeo' | 'webcake' | 'upload' — video source type. REQUIRED to match the right specials keys below.",
+            id: "string — YouTube video ID. REQUIRED when typeVideo='youtube'. Example: 'dQw4w9WgXcQ'.",
+            video: "string — full video URL. REQUIRED when typeVideo='vimeo' (full Vimeo page URL, e.g. https://vimeo.com/123456) or typeVideo='webcake' (missing crashes the page with TypeError). For 'upload' / other CDN types this is the raw video file URL.",
+            video_cdn: "string — CDN video URL or identifier (for 'upload'/'webcake' types; renderer uses video_cdn ?? video as source).",
+            img: "string — poster/thumbnail image URL. Use a placeholder if none: https://placehold.co/640x360. Overridden by the first url() in styles.background — do NOT set a flat styles.background color or the poster is suppressed.",
+            videoFit: "string — 'cover' (default, fills box) | false (contain, shows letterbox).",
             autoReplay: "boolean — loop the video.",
-            showControl: "boolean — show player controls.",
+            showControl: "boolean — show player controls (default off; when off, Vimeo controls are entirely hidden).",
             hideRelated: "boolean — hide YouTube related videos at end.",
             muteOnPlay: "boolean — mute audio when video plays.",
             autoPlay: "boolean — autoplay on load.",
@@ -148,18 +200,20 @@ export const CONTENT = [
     },
     {
         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 image objects (see media). NEVER use plain URL strings — the gallery reads item.link and renders blank for a string.",
+        summary: "Multi-image/video gallery with thumbnail strip. Content comes entirely from specials.media — this is NOT a container and has no children. config.showThumbnail is tri-state: when UNSET the editor hides thumbnails but the live renderer shows an 80px strip overlapping the main image — always set it explicitly.",
+        useWhen: "Photo grids/galleries with several images or videos. No image API — fill specials.media with placeholder image objects (see media). NEVER use plain URL strings — the gallery reads item.link and renders blank for a string. Video items: use typeVideo 'youtube' or 'webcake' (NOT 'upload' — renders an empty item); set item.type:'video' so the play-overlay and zoom/lightbox fire correctly.",
         keySpecials: {
-            media: "array of media OBJECTS (NOT plain URLs — the gallery reads item.link). Image item: {type:'image', link:'<url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} — use a https://placehold.co/WxH URL for link if no real image. Video item: {type:'image', link:'<poster-url>', linkVideo:'<video-url>', typeVideo:'youtube'|'upload', imageCompression:true}.",
+            media: "array of media OBJECTS (NOT plain URLs — the gallery reads item.link). Image item: {type:'image', link:'<url>', linkVideo:'', typeVideo:'youtube', imageCompression:true}. Video item: {type:'video', link:'<poster-url>', linkVideo:'<video-url>', typeVideo:'youtube'|'webcake', imageCompression:true} — item.type must be 'video' for the play-overlay and lightbox to fire; typeVideo 'upload' renders an empty item on live.",
+            showThumbnail: "(config) boolean — show the thumbnail strip. ALWAYS set explicitly: when unset the live renderer shows an 80px strip overlapping the main image while the editor hides it. Default when set: true (thumbnailWidth/Height:80, distanceAmong:10, position:bottom, distanceToGallery:10).",
             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.",
+            thumbnailAutoplay: "number (ms) | 'off' — (config) auto-advance thumbnails; delay default 3000ms. Starts only when thumbnailAutoplay != 'off' AND thumbnailAutoplayRepeat is truthy.",
+            thumbnailAutoplayRepeat: "boolean — (config) loop thumbnail autoplay. Required alongside thumbnailAutoplay for autoplay to start.",
             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.",
+            thumbnailWidth: "number — (config) width of each thumbnail in px. Default 80.",
+            thumbnailHeight: "number — (config) height of each thumbnail in px. Default 80.",
+            distanceAmong: "number — (config) gap between thumbnails in px. Default 10.",
+            distanceToGallery: "number — (config) gap between thumbnail strip and main image in px. Default 10.",
         },
         seed: (el) => {
             seedPosition(el);
@@ -173,14 +227,18 @@ export const CONTENT = [
                 typeVideo: "youtube",
                 imageCompression: true,
             }));
+            // Always set showThumbnail explicitly — unset causes the live renderer to
+            // overlay an 80px strip on the main image even though the editor hides it.
+            el.responsive.desktop.config = { ...el.responsive.desktop.config, showThumbnail: true };
+            el.responsive.mobile.config = { ...el.responsive.mobile.config, showThumbnail: true };
             // 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).",
+        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.",
-        keySpecials: { html: "string — raw HTML content (the only content key; stored HTML-escaped, unescaped at render)." },
+        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);
@@ -189,9 +247,9 @@ export const CONTENT = [
     },
     {
         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)." },
+        summary: "Long-form rich text / article body. specials.html holds the rich-text markup stored RAW (NOT escaped). Contrast with html-box which stores escaped HTML. The publisher injects specials.html raw with NO unescape — storing escaped HTML causes the live page to display literal '&lt;p&gt;' text instead of rendered markup. Live wrapper height is FIXED to styles.height (the editor shows auto) — a long article overflows the band; set a generous height.",
+        useWhen: "Blog/article content blocks. Set styles.height to a generous value (≥ the rendered article height) — content taller than the box overflows the live page silently.",
+        keySpecials: { html: "string — rich-text HTML content stored RAW (not escaped). Store exactly what you want the browser to render — e.g. '<p>Hello</p>' not '&lt;p&gt;Hello&lt;/p&gt;'. Storing escaped HTML causes the live page to display literal tag strings. The live wrapper height is FIXED to styles.height — set generously." },
         seed: (el) => {
             el.responsive.mobile.styles.width = 340;
             el.responsive.mobile.styles.height = 303;