webcake-landing-mcp 1.0.73 → 1.0.75

package/README.md

@@ -172,7 +172,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 20 tools in detail + the step-by-step workflow + model notes. |
+| **[Tools reference](docs/tools.md)** | All 21 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)). |
@@ -181,13 +181,13 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 
 ## 🧰 The tools at a glance
 
-20 tools in five groups — full descriptions in **[docs/tools.md](docs/tools.md)**:
+21 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) · `upload_images` (re-host external images, data: URIs, or local file paths from the user's machine) | nothing |
+| **Media** | `search_images` (real Pexels stock photos) · `get_icon_svg` (Material Symbols / Font Awesome icon names → inline SVG via Iconify) · `upload_images` (re-host external images, data: URIs, or local file paths from the user's machine) | 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.75",
+    "d": "15/06/2026",
+    "type": "Added",
+    "en": "New get_icon_svg tool resolves Material Symbols (ms:<name>) and Font Awesome (fa:<name>) icon-font references to real inline SVG markup via the…",
+    "vi": "Tool mới get_icon_svg resolve tên icon-font Material Symbols (ms:<name>) và Font Awesome (fa:<name>) thành SVG inline thực sự qua Iconify API công…"
+  },
+  {
+    "v": "1.0.74",
+    "d": "13/06/2026",
+    "type": "Added",
+    "en": "ingest_html and ingest_url now extract Tailwind gradient utilities (bg-gradient-to-*/from-*/via-*/to-*) from the page's class attributes, resolve…",
+    "vi": "ingest_html và ingest_url nay trích xuất các utility gradient Tailwind (bg-gradient-to-*/from-*/via-*/to-*) từ các thuộc tính class của trang,…"
+  },
   {
     "v": "1.0.73",
     "d": "13/06/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "upload_images default changed from dry_run:true to dry_run:false — the tool now uploads images and returns the hosted URL map on every call without…",
     "vi": "Mặc định của upload_images được đổi từ dry_run:true thành dry_run:false — tool này nay upload ảnh và trả về bản đồ URL trong mọi lần gọi mà không…"
-  },
-  {
-    "v": "1.0.69",
-    "d": "12/06/2026",
-    "type": "Changed",
-    "en": "upload_images dry-run response now returns an action_required field (replacing the previous soft hint) that explicitly blocks the model from…",
-    "vi": "Phản hồi dry-run của upload_images nay trả về trường action_required (thay thế hint mềm trước đó) để chặn model lắp ráp trang hoặc dùng placeholder…"
-  },
-  {
-    "v": "1.0.68",
-    "d": "12/06/2026",
-    "type": "Added",
-    "en": "ingest_html and ingest_url now auto-detect absolute-canvas builder exports (LadiPage-family pages and Webcake-published HTML): bare positioned-div…",
-    "vi": "ingest_html và ingest_url nay tự động phát hiện các bản export từ builder absolute-canvas (trang LadiPage-family và HTML đã publish của Webcake):…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -15,7 +15,7 @@ OUTPUT (top-level page source — matches the real editor shape)
 - "page" is an array of SECTIONS stacked vertically (index 0 = top). Each item MUST be type "section" (or "dynamic_page").
 - "popup" is a SEPARATE top-level array of popup elements — do NOT nest popups inside "page". A button opens one via a click event { action:"open_popup", target:"<popup id>" }.
 - All other elements (text, image, button, form…) live inside a section's "children".
-- "settings" carries SEO + page config: title, description, keywords, robots, canonical, favicon, fontGeneral, width_section {desktop:960,mobile:420}, country, currency, fb_tracking_code, tiktok_script, extra_css, extra_script, bhet (head code), bbet (body-end code) (call new_page_skeleton for a ready default).
+- "settings" carries SEO + page config: title, description, keywords, robots, canonical, favicon, fontGeneral, width_section {desktop:960|1200, mobile:420|360 — the canvas width CHOICE; see the canvas-width rule below}, country, currency, fb_tracking_code, tiktok_script, extra_css, extra_script, bhet (head code), bbet (body-end code) (call new_page_skeleton for a ready default).
 
 ELEMENT NODE (every element)
 { "id": "<unique ~8-char [A-Za-z0-9_]>", "type": "<type>",
@@ -34,7 +34,7 @@ FULL ELEMENT CATALOG (all ${ELEMENT_TYPES.length} types — the complete menu, n
 COORDINATE SYSTEM (critical)
 - Absolute-positioning canvas (NOT flexbox). Children carry top/left/width/height in px (numbers).
 - section has NO top/left; it has height (canvas height, default ${CANVAS.defaultSectionHeight}) and position:"relative".
-- Canvas width is FIXED: desktop = ${CANVAS.desktopWidth}px, mobile = ${CANVAS.mobileWidth}px (settings.width_section). Provide BOTH breakpoints; do not overlap elements within a section.
+- Canvas width is a per-breakpoint CHOICE you set in settings.width_section — desktop ${CANVAS.desktopWidthOptions.join(" or ")}px, mobile ${CANVAS.mobileWidthOptions.join(" or ")}px (these are the ONLY allowed values; editor default ${CANVAS.desktopWidth}/${CANVAS.mobileWidth}). PICK the width to fit the design, then place EVERY element's top/left/width in THAT coordinate space (changing width does NOT rescale elements — coords are absolute in the chosen width): use desktop 1200 for wide, multi-column, or editorial layouts and ALWAYS when cloning a reference drawn wider than 960 (e.g. a Google Stitch screen at ~1280 — clone at 1200 and map its coords by ×1200/sourceWidth, so 2-/3-column bands aren't crushed into 960 leaving big empty gaps); use 960 for simple, single-column, text-led pages. Mobile: 360 to match a ~360–390 design, else 420. Set settings.width_section.desktop/mobile to your choice up front. Provide BOTH breakpoints; do not overlap elements within a section.
 - Every child must stay on-canvas: 0 ≤ left and left + width ≤ canvas width (${CANVAS.desktopWidth} desktop / ${CANVAS.mobileWidth} mobile). Same for top + height ≤ section height.
 
 CENTERING & ALIGNMENT (do the math — do NOT eyeball \`left\`; off-center layouts are the #1 defect)
@@ -120,6 +120,8 @@ RULES
 - Every form input MUST have a unique specials.field_name.
 - events item: { "id", "type", "action", "target", ...action-specific extra fields }. TRIGGER (type): click & hover on any element; success & error on a FORM (success = after a successful submit, error = on validation failure); delay on any element (when it scrolls into view); unset on init. Action vocab per trigger: click→CLICK_ACTIONS, hover→HOVER_ACTIONS, success→SUCCESS_ACTIONS, error→ERROR_ACTIONS, delay→DELAY_ACTIONS (all returned by get_generation_guide). For element-targeting actions (open_popup, close_popup, scroll_to, show_section, hide_section, show_hide_element, change_tab, collapse) target = the target element's id; open_link/download_file target = URL; open_sms/send_email/phone_call target = phone/email; copy target = text (or element id when copyType='elementValue'); set_field_value target = field_name; target may be null (e.g. animation_hover). Each action also reads extra fields (e.g. open_link→targetURL/delayTime, scroll_to→scrollMore, change_tab→moveTo/tabIndex, lightbox→typeLightbox/alt, show_hide_element→onlyMode, open_app→appTarget+provider fields, set_field_value→set_value) — see the action maps for the full list.
 - ANIMATION: each breakpoint's config has config.animation = { "name":"none", "delay":0, "duration":3, "repeat":null }. Animations only run on these 9 element types: group, image-block, text-block, rectangle, button, countdown, line, list-paragraph, notify (renderer contract: landing_page_build/render/build/animate.js). Any other type with a non-"none" name renders stuck/dim in its pre-animation state — keep "none" on all other types. The name must be from the editor's animate.css set; common entrance families: fadeIn* (fadeInUp, fadeInDown, fadeInLeft, fadeInRight…), slideIn* (slideInUp, slideInDown, slideInLeft, slideInRight), zoomIn* (zoomIn, zoomInUp, zoomInDown…), bounceIn* (bounceIn, bounceInUp…), backIn* (backInDown, backInLeft…), flipIn* (flipInX, flipInY), lightSpeedIn* (lightSpeedInLeft, lightSpeedInRight), rotateIn* (rotateIn, rotateInDownLeft…), rollIn, jackInTheBox; attention seekers: bounce, pulse, tada, headShake, wobble, jello, heartBeat, rubberBand, shakeX, shakeY. The full set is enforced by validate_page — use an invalid name and the element renders stuck. NEVER set styles.opacity < 1 for a "subtle" or "muted" look — opacity is permanent and renders the element and all its content faded forever; use rgba() alpha on the color or background property instead.
+- BEYOND ELEMENT CAPABILITY (custom CSS / class / JS — use these so the page is as COMPLETE as possible instead of dropping an effect the built-in specials can't express): the renderer supports real escape hatches — REACH FOR THEM when a reference (esp. a Google Stitch / Tailwind page) has hover/transition effects, gradients, glassmorphism, custom shadows, gradient/clipped text, sticky tricks, or keyframe animations outside the 9-type entrance set. Tools, in order of preference: (1) element specials.custom_css — extra CSS DECLARATIONS injected INTO that element's own rule "#w-<id>{ … }" (declarations only — NO selector, NO :hover, NO @keyframes). Requires specials.customAdvance:true (without it the renderer drops it). Use for: "background:linear-gradient(...)" (gradient button/hero — also reproduces the AST's gradients), "box-shadow:0 20px 40px rgba(0,0,0,.08)", "backdrop-filter:blur(20px)" (glass header — pair with an rgba background), "transition:transform .3s ease", "-webkit-background-clip:text;-webkit-text-fill-color:transparent" (gradient text). (2) element specials.custom_class (comma-separated, also needs customAdvance:true) — adds class names to "#w-<id>" so settings.extra_css can target a group of elements. (3) page settings.extra_css — a FULL stylesheet injected raw into <head>: this is where SELECTORS live — :hover, :focus, @keyframes, media queries. The DOM id of any element is "#w-<its id>". THIS is how you implement the AST's per-section hover_effects: scale → "#w-<id>{transition:transform .3s} #w-<id>:hover{transform:scale(1.05)}"; card lift → "#w-<id>:hover{transform:translateY(-8px)}"; image-zoom in a card → "#w-<cardId>{overflow:hidden} #w-<imgId>{transition:transform .5s} #w-<cardId>:hover #w-<imgId>{transform:scale(1.1)}"; color/underline on hover are also fine as a hover EVENT (change_color / change_underline) — pick whichever, but DON'T silently drop the effect. (4) page settings.extra_script — raw JS injected before </body> for behavior the event vocab can't express. (5) page settings.bhet ('before </head>') and settings.bbet ('before </body>') — raw HTML BLOCKS (not just CSS/JS): bhet for <link> webfonts/stylesheets, <style>, <meta>, verification tags, analytics/pixels (GTM, FB); bbet for chat widgets, deferred <script>, GTM <noscript>, third-party embeds. Use these when you need a real font file, a tag/pixel, or an external widget — extra_css/extra_script are for raw CSS/JS only, bhet/bbet take arbitrary HTML (valid markup only). RULES: custom_css is declarations-only (validate_page warns if you put a selector there) and needs customAdvance:true (validate_page warns if missing); extra_css/extra_script are raw and unscoped, so keep selectors specific to "#w-<id>" / your custom_class to avoid bleeding into the rest of the page; don't use these to replace a capability a built-in special already has (e.g. entrance animation → config.animation; click behavior → events).
+- ICONS (icon-font glyphs — don't drop them, and DON'T blind-svg-mask them): references (esp. Google Stitch) render icons with an icon-font CLASS, not images or inline SVG — Material Symbols (<span class="material-symbols-outlined">verified</span>) or Font Awesome (<i class="fa-solid fa-check">). ingest gives only the NAME as block.icon "ms:<name>" / "fa:<name>" (e.g. "ms:support_agent"). render it as Webcake's NATIVE icon element — a RECTANGLE with an svg mask: STEP 1 — call get_icon_svg with those refs to get each REAL <svg> (Material Symbols outlined / Font Awesome) via Iconify (NEVER invent an SVG from a name). STEP 2 — make a rectangle and put that svg in BOTH responsive.desktop.config.svgMask AND responsive.mobile.config.svgMask, set styles.background = the icon color, and use a SQUARE box (width === height). Why each rule: the svg is only a MASK (its own fill is IGNORED) — visible pixels come ENTIRELY from styles.background, so WITHOUT a solid background the icon is BLANK (that's the "svg in a rectangle doesn't show" bug); the renderer reads each breakpoint's config separately (no fallback), so the mask must be in BOTH; and it forces preserveAspectRatio='none', so a non-square box stretches the icon. validate_page warns if background / viewBox / both breakpoints are missing. If get_icon_svg can't resolve a ref, fall back to an emoji inline in a sentence or skip that slot — NEVER leave a feature card iconless.
 - Real data the page DISPLAYS must come from the user — never invent it: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, exact stats/social-proof numbers. If a value the page needs is missing, ASK for it (in intake, or pause before generating); use a clearly-labelled placeholder ONLY when the user explicitly declines, and tell them exactly what to fill. Write ALL page copy in the SAME language the user is chatting in (mirror it), with FULL, CORRECT diacritics/accents — for Vietnamese this means proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025"), NEVER accent-stripped "không dấu" text. Do not romanize, transliterate, or drop accent marks from any language.
 
 INTAKE — act as a DESIGN CONSULTANT, not a form. Goal: understand what the customer actually wants, then design as close to their intent as possible. Ask BEFORE generating, EVERY time (even a "quick"/"test" page).

package/dist/domains/landing/instructions.js

@@ -25,7 +25,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 ~2 h.
 - 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 before saving. If the account has exactly ONE org, create_page auto-selects it — no need to ask. If there are MULTIPLE orgs, show them and ask the user which to use (is_default is the suggested default); pass the chosen organization_id to create_page. Pass organization_id:"personal" only when the user explicitly wants no org. create_page enforces this itself (it refuses to guess between multiple orgs). 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). 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. (4) GOOGLE STITCH design (when a Stitch MCP is connected and the user points at a Stitch screen/project) → bridge the two MCPs: call the Stitch tool get_screen, take the returned htmlCode.downloadUrl, and pass THAT url to ingest_url(detail:'full') (or fetch the HTML and use ingest_html) — Stitch output is a Tailwind-CDN page, so the AST comes back with a token-named palette + design_tokens (the real spacing/radii/type-scale); LOCK the design system from those tokens, reuse the page's image URLs (they auto-host on save — Stitch's googleusercontent images included), then create_page. ABSOLUTE-CANVAS builder exports (LadiPage-family / Webcake-published HTML) are AUTO-DETECTED by ingest_html/ingest_url and converted DETERMINISTICALLY into a ready-to-save source (folded into the response as source + clone_notes + clone_notice, the per-element geometry summarized to canvas_summary) — a faithful 1:1 clone on the matching 420/960 canvas: pass that source STRAIGHT to create_page (dry_run:true first to validate, then dry_run:false) instead of hand-rebuilding; its images auto-host on save (no upload_images), and clone_notes lists the few lossy approximations (fixed/floating elements, svg-less shapes, skipped social-proof toasts) to patch_page afterward. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), a token-named palette + design_tokens (for Tailwind-CDN pages like Google Stitch, lifted from the page's tailwind.config: palette names every color token e.g. primary→#a43b38, and design_tokens carries the resolved spacing grid + corner radii + TYPE SCALE e.g. display-lg→48px — rebuild sizing/spacing/color FROM these tokens, not by guessing), 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). IMAGES FROM THE REFERENCE ARE THE USER'S ASSETS — for BOTH intents (adapt AND clone), put every real image URL found in the AST (images, background_images, og_image, canvas src/background) straight into the corresponding slot's specials.src / url(...) background / gallery link; the save AUTO-HOSTS it to the Webcake CDN, so you do NOT need to call upload_images first — just carry the URL through un-altered (never drop it, never swap it for a search_images stock photo or a placeholder). Call search_images ONLY for slots that have no source image in the reference. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt' (adapt rewrites TEXT, not the imagery). 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. (4) GOOGLE STITCH design (when a Stitch MCP is connected and the user points at a Stitch screen/project) → bridge the two MCPs: call the Stitch tool get_screen, take the returned htmlCode.downloadUrl, and pass THAT url to ingest_url(detail:'full') (or fetch the HTML and use ingest_html) — Stitch output is a Tailwind-CDN page, so the AST comes back with a token-named palette + design_tokens (the real spacing/radii/type-scale) + gradients (Tailwind gradient utilities reconstructed as linear-gradient(...) with resolved color stops — apply them as the element's background, e.g. on CTA/hero) + per-section hover_effects (the interactions Stitch packs in: scale/image-zoom/lift/underline/color-change — REPRODUCE them via Webcake hover events: change_color (change_color_type text/background/border) for color/underline, the button's hovered* specials or animation_hover for scale/lift/zoom — don't ship a static page); LOCK the design system from those tokens, reuse the page's image URLs (they auto-host on save — Stitch's googleusercontent images included), then create_page. ABSOLUTE-CANVAS builder exports (LadiPage-family / Webcake-published HTML) are AUTO-DETECTED by ingest_html/ingest_url and converted DETERMINISTICALLY into a ready-to-save source (folded into the response as source + clone_notes + clone_notice, the per-element geometry summarized to canvas_summary) — a faithful 1:1 clone on the matching 420/960 canvas: pass that source STRAIGHT to create_page (dry_run:true first to validate, then dry_run:false) instead of hand-rebuilding; its images auto-host on save (no upload_images), and clone_notes lists the few lossy approximations (fixed/floating elements, svg-less shapes, skipped social-proof toasts) to patch_page afterward. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), a token-named palette + design_tokens (for Tailwind-CDN pages like Google Stitch, lifted from the page's tailwind.config: palette names every color token e.g. primary→#a43b38, and design_tokens carries the resolved spacing grid + corner radii + TYPE SCALE e.g. display-lg→48px — rebuild sizing/spacing/color FROM these tokens, not by guessing), background_images from stylesheets, gradients (incl. reconstructed Tailwind gradient backgrounds), per-section hover_effects (reproduce them — via hover events, or the custom-CSS escape hatch below), and in full mode: per-section blocks (cards/tiles/steps with title/body/image/cta) and li lists — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). IMAGES FROM THE REFERENCE ARE THE USER'S ASSETS — for BOTH intents (adapt AND clone), put every real image URL found in the AST (images, background_images, og_image, canvas src/background) straight into the corresponding slot's specials.src / url(...) background / gallery link; the save AUTO-HOSTS it to the Webcake CDN, so you do NOT need to call upload_images first — just carry the URL through un-altered (never drop it, never swap it for a search_images stock photo or a placeholder). Call search_images ONLY for slots that have no source image in the reference. intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt' (adapt rewrites TEXT, not the imagery). 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.
@@ -39,6 +39,7 @@ MODEL (essentials):
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
 - IMAGES: include them (hero/product, feature icons, about photo). The server AUTO-HOSTS external image URLs on every save: any real http(s) image URL you put in specials.src / a url(...) background / gallery item.link / video poster is downloaded and re-hosted to the Webcake CDN automatically by create_page/update_page/add_section/patch_page (the result's rehost field reports how many) — so you do NOT have to pre-call upload_images for reference or web images. SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL → put the REAL source URL straight into specials.src and let the save host it (use those exact images, never swap them for stock photos; the original URL must reach the save un-altered — NEVER replace a real source image URL with a placeholder). The ONE case you MUST still call upload_images yourself: LOCAL FILE PATHS from the user's computer (pass the path directly in upload_images urls — the save can't read local files; NEVER upload a user's local file to a third-party host like catbox or imgur first), then use the returned URL. (2) only for slots with NO source image → call search_images with a short English subject (e.g. 'fresh coffee cup') and put a returned URL (src.large for a hero/banner, src.medium for a card/thumb) into the image-block specials.src; it works out of the box (a shared proxy supplies images); (3) if search_images returns ok:false / is unreachable / has no fitting photo → find a real image YOURSELF using whatever web search/fetch capability you have (brand site, product page, free-to-use source) and re-host it via upload_images; (4) a PLACEHOLDER sized to the box (https://placehold.co/<width>x<height>) is the LAST resort, only after (2) AND (3) both failed. (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
 
+- BEYOND ELEMENT CAPABILITY: when a reference effect can't be expressed with an element's built-in specials (hover scale/lift/zoom & transitions, gradients, glassmorphism/backdrop-blur, custom shadows, gradient/clipped text, keyframe animations outside the 9 entrance types) DON'T drop it — use the escape hatches so the page is as complete as possible: element specials.custom_css (extra DECLARATIONS in #w-<id>{…}; declarations-only) + specials.custom_class (both need specials.customAdvance:true) for per-element styling, and page settings.extra_css (a full raw stylesheet in <head> — where :hover/@keyframes/media-queries live, target #w-<element id>) + settings.extra_script (raw JS) + settings.bhet/bbet (raw HTML blocks at end of <head>/<body> — for webfont <link>s, <meta>/verification, analytics/pixels, chat widgets, third-party embeds). get_generation_guide has the recipes; validate_page warns if custom_css lacks customAdvance or holds a selector.
 - PREVIEW vs PUBLISH: for review share the EDITOR url (the builder renders the raw source). The editor_url SIGNS THE BROWSER IN automatically (it routes through the builder's /transport with the account token), so it works even when the user isn't logged in — but for the same reason it must go to the PAGE OWNER ONLY, never into anything public. create_page AUTO-PUBLISHES on success (builds the rendered app + publish_html), so a fresh page's preview_url renders right away — but the preview host (preview.localhost:5800 local / staging.webcake.me staging / www.webcake.me prod) only serves it for ~10 MINUTES after the last publish, then shows "Preview page is expired". The EDIT routes (update_page/add_section/patch_page) store source only — after finishing a round of edits, run publish_page({ page_id, dry_run:false }) to rebuild the rendered app (else the preview shows the STALE pre-edit build). ONLY a custom_domain (publish_page({ page_id, custom_domain, dry_run:false })) gives a permanent public URL; without one the page has just the ephemeral preview link — say so and suggest attaching a domain the user already points at Webcake.
 
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, upload_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, get_icon_svg, upload_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;

package/dist/domains/landing/page-schema.json

@@ -46,8 +46,11 @@
         "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" } }
+          "description": "The canvas width per breakpoint (px) — the coordinate space every element's top/left/width lives in. Editor-allowed values ONLY: desktop 960 or 1200, mobile 420 or 360 (default 960/420). Choose 1200 for wide/multi-column/editorial layouts or when cloning a reference wider than 960 (e.g. Google Stitch ~1280) so columns aren't squished; 360 mobile to match a ~360–390 design. Changing it does NOT rescale existing coords.",
+          "properties": {
+            "desktop": { "type": "number", "enum": [960, 1200], "description": "960 or 1200." },
+            "mobile": { "type": "number", "enum": [420, 360], "description": "420 or 360." }
+          }
         },
         "country": { "type": "string", "description": "Dialing/locale code, e.g. \"84\"." },
         "currency": { "type": "string", "description": "Page currency (the editor's canonical home for currency).", "examples": ["VND", "USD"] },
@@ -58,8 +61,10 @@
         "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." },
+        "extra_css": { "type": "string", "description": "Page-level custom CSS — a FULL stylesheet injected raw into <head>. The escape hatch for effects beyond element specials: SELECTORS, :hover/:focus, @keyframes, media queries. Target any element by its DOM id #w-<element id> (or a specials.custom_class). E.g. hover scale: '#w-abc{transition:transform .3s}#w-abc:hover{transform:scale(1.05)}'. Keep selectors specific (it is raw/unscoped) to avoid bleeding." },
+        "extra_script": { "type": "string", "description": "Page-level custom JavaScript injected raw before </body> — behavior beyond the event vocab." },
+        "bhet": { "type": "string", "description": "'Before </head>' — a raw HTML block injected at the END of <head>. Unlike extra_css (CSS-only)/extra_script (JS-only) this takes ARBITRARY HTML: <link> webfonts/stylesheets, <style>, <meta>, verification tags, analytics/pixels (GTM, FB). Rendered raw — valid HTML only." },
+        "bbet": { "type": "string", "description": "'Before </body>' — a raw HTML block injected at the END of <body>: chat widgets, deferred <script>, GTM <noscript>, third-party embeds. Rendered raw — valid HTML only." },
         "auto_save_draft": { "type": "boolean" },
         "auto_save_info_user": { "type": "boolean" },
         "send_info_to_thank_page": { "type": "boolean" }
@@ -230,7 +235,7 @@
     },
     "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(vietnam|english|filipino|khmer|lao|indonesian|thai|malay|custom — NOT a locale code; 'custom' uses customTranslation),customTranslation{day,hour,minute,second}}; survey{options[{id,image,title,value,field_name}],type,multiOption,selectedBackground,selectedBorder}; list-product{format_title,numerical_order,remain_quantity_text}.",
+      "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(vietnam|english|filipino|khmer|lao|indonesian|thai|malay|custom — NOT a locale code; 'custom' uses customTranslation),customTranslation{day,hour,minute,second}}; survey{options[{id,image,title,value,field_name}],type,multiOption,selectedBackground,selectedBorder}; list-product{format_title,numerical_order,remain_quantity_text}. UNIVERSAL escape-hatch keys (any element): customAdvance(boolean — MUST be true for the next two to apply, else the renderer drops them), custom_css(string — extra CSS DECLARATIONS injected inside this element's #w-<id>{…} rule; declarations only, no selector/:hover/@keyframes — those go in settings.extra_css), custom_class(string — comma-separated extra class names added to #w-<id>, to target from settings.extra_css). Section-only: isCustomTracking(boolean)+customTracking(string HTML/JS) for per-section tracking snippets.",
       "additionalProperties": true,
       "properties": {
         "text": { "type": "string", "description": "text-block/button label/list-paragraph (may contain HTML)." },

package/dist/domains/landing/validate.js

@@ -298,6 +298,25 @@ export function validatePage(input) {
                 });
             }
         }
+        // custom CSS/class escape hatches (effects beyond an element's built-in specials).
+        // Renderer gates BOTH on specials.customAdvance===true (render/build/index.js
+        // custom_class + exportCss.js custom_css); without it they are silently dropped.
+        // And custom_css is injected as plain DECLARATIONS inside #w-<id>{…}, so a
+        // selector / :hover / @keyframes there corrupts the rule — those go in
+        // settings.extra_css (full stylesheet, injected raw into <head>).
+        {
+            const sp = node.specials;
+            if (sp && typeof sp === "object") {
+                const hasCustom = (typeof sp.custom_css === "string" && sp.custom_css.trim() !== "") ||
+                    (typeof sp.custom_class === "string" && sp.custom_class.trim() !== "");
+                if (hasCustom && sp.customAdvance !== true) {
+                    warnings.push(`${path} (${type}): specials.custom_css/custom_class is set but specials.customAdvance!==true — the renderer ignores both. Set "customAdvance": true.`);
+                }
+                if (typeof sp.custom_css === "string" && /[{}]|@keyframes|:hover|:focus|::/.test(sp.custom_css)) {
+                    warnings.push(`${path} (${type}): specials.custom_css is injected as plain declarations inside #w-${node.id}{…} — a selector/:hover/@keyframes/media-query there breaks the rule. Keep declarations only here (e.g. "box-shadow:0 20px 40px rgba(0,0,0,.08);backdrop-filter:blur(20px);"); put hover/keyframes/media rules in settings.extra_css targeting #w-${node.id} (or a specials.custom_class).`);
+                }
+            }
+        }
         // animation contract — checked per breakpoint
         // Source: landing_page_build/render/build/animate.js (animatable type list)
         //         landing_page_backend/assets/editor/main/traits/TraitAnimation.vue (name set)
@@ -400,8 +419,12 @@ export function validatePage(input) {
                     // variation selector-16 (FE0F), keycap (20E3), whitespace
                     /^(?:\p{Extended_Pictographic}|\p{Emoji_Component}|[\u200D\uFE0F\u20E3\s])+$/u.test(visible);
                 if (onlyEmoji) {
-                    warnings.push(`${path} (text-block): specials.text is only the emoji "${visible}" — keyboard emoji as standalone icons look unprofessional and render inconsistently across devices. Use a rectangle with per-breakpoint config.svgMask (raw <svg> string) + styles.background set to the brand accent color instead (see the rectangle element's example). Emoji are fine inline within sentences, never as card icons.`);
+                    warnings.push(`${path} (text-block): specials.text is only the emoji "${visible}" — keyboard emoji as standalone icons look unprofessional and render inconsistently across devices. Use a real icon instead: call get_icon_svg to fetch the <svg>, then a rectangle with that svg in per-breakpoint config.svgMask + styles.background set to the accent color (the native Webcake icon). Emoji are fine inline within sentences, never as card icons.`);
                 }
+                // An icon-font text-block (Material Symbols / Font Awesome span) is a
+                // SINGLE glyph, not wrapping text — the ligature name ("verified") is not
+                // displayed, so the text-metrics estimate is meaningless here. Skip it.
+                const isIconGlyph = /\b(material-symbols|material-icons)\b/.test(rawText) || /<i\b[^>]*\bfa-/.test(rawText);
                 // Wrapped-text overflow: live text height is AUTO — text that wraps to
                 // more lines than the declared box spills DOWN and overlaps the element
                 // below (the classic "2-line card title over the card body" defect).
@@ -410,6 +433,8 @@ export function validatePage(input) {
                 // 1-line-tall box — slip through, while body text (16px → 22px line)
                 // keeps its old tolerance against the rough estimate.
                 for (const bp of ["desktop", "mobile"]) {
+                    if (isIconGlyph)
+                        break;
                     const styles = node.responsive?.[bp]?.styles;
                     const w = num(styles?.width);
                     const h = num(styles?.height);
@@ -835,7 +860,9 @@ export function validatePage(input) {
                 return;
             const cpath = `${path}.children[${idx}]`;
             const rawText = child.type === "text-block" ? child.specials?.text : undefined;
-            if (typeof rawText === "string") {
+            // Icon-font glyph (Material Symbols / Font Awesome) — one glyph, not wrapping text.
+            const isIconGlyph = typeof rawText === "string" && (/\b(material-symbols|material-icons)\b/.test(rawText) || /<i\b[^>]*\bfa-/.test(rawText));
+            if (typeof rawText === "string" && !isIconGlyph) {
                 for (const bp of ["desktop", "mobile"]) {
                     if (overlapWarnings >= MAX_OVERLAP_WARNINGS)
                         break;

package/dist/domains/landing/vocab.js

@@ -4,7 +4,20 @@
  * fields the render_v4 dispatcher reads beyond { id, type, action, target }.
  * Derived from assets/render_v4/event/index.js.
  */
-export const CANVAS = { desktopWidth: 960, mobileWidth: 420, defaultSectionHeight: 800 };
+// Canvas width is a per-breakpoint CHOICE (settings.width_section), NOT a single
+// fixed value — the editor's Page Configuration offers desktop 960|1200 and
+// mobile 420|360. desktopWidth/mobileWidth are the DEFAULTS (the editor default);
+// desktopWidthOptions/mobileWidthOptions are the full allowed sets. Pick 1200 for
+// wide/multi-column/editorial layouts and when cloning a reference wider than 960
+// (e.g. Google Stitch ~1280) so columns aren't squished; pick 360 mobile to
+// match a ~360–390 mobile design. Source: landing_page_backend Page Configuration.
+export const CANVAS = {
+    desktopWidth: 960,
+    mobileWidth: 420,
+    defaultSectionHeight: 800,
+    desktopWidthOptions: [960, 1200],
+    mobileWidthOptions: [420, 360],
+};
 /**
  * Element types the runtime animator handles.
  * Source: landing_page_build/render/build/animate.js — the switch statement

package/dist/persistence/html-ingest.js

@@ -16,7 +16,7 @@
 import { parse } from "node-html-parser";
 import { extractStyleBlocks, extractGoogleFonts, extractGradients, fixMojibake } from "./ingest/stylesheets.js";
 import { extractTailwindConfig } from "./ingest/tailwind.js";
-import { findSections, classifySection, computeSizeHint, detectWidgets, brandHints } from "./ingest/semantic.js";
+import { findSections, classifySection, computeSizeHint, detectWidgets, detectHoverEffects, brandHints } from "./ingest/semantic.js";
 import { parseAbsoluteCanvas, canvasRoleSections, stripCdnSizePrefix } from "./ingest/canvas.js";
 // Re-export the public surface so existing imports of "./persistence/html-ingest.js"
 // (parseHtml, fetchHtml, and the IngestedAst/IngestedCanvas/CanvasElement/CanvasSection
@@ -95,6 +95,9 @@ export function parseHtml(html, detail = "compact", opts = {}) {
     const sections = sectionEls.map((el) => {
         const sec = classifySection(el, detail);
         sec.size_hint = computeSizeHint(el, sec, styleBlocks);
+        const hover = detectHoverEffects(el);
+        if (hover.length)
+            sec.hover_effects = hover;
         if (detail === "full") {
             const widgets = detectWidgets(el, styleBlocks);
             if (widgets.length)
@@ -114,13 +117,18 @@ export function parseHtml(html, detail = "compact", opts = {}) {
         fonts: hints.fonts.length ? hints.fonts : undefined,
         palette: hints.palette,
         design_tokens: hints.design_tokens,
+        // Tailwind gradient utilities (Stitch CTA/hero backgrounds) reconstructed as
+        // linear-gradient strings — surfaced in BOTH modes since they're design-critical
+        // and the Play CDN never emits the resolved CSS.
+        gradients: hints.tailwind_gradients.length ? hints.tailwind_gradients : undefined,
         background_images: hints.background_images.length ? hints.background_images : undefined,
         warnings: warnings.length ? warnings : undefined,
     };
     if (detail !== "full")
         return base;
-    // Full mode extras.
-    const gradients = extractGradients(styleBlocks);
+    // Full mode extras: merge stylesheet gradients with the Tailwind ones (deduped).
+    const styleGradients = extractGradients(styleBlocks);
+    const gradients = [...new Set([...hints.tailwind_gradients, ...styleGradients])];
     const result = {
         ...base,
         gradients: gradients.length ? gradients : undefined,

package/dist/persistence/icon-client.js

@@ -0,0 +1,81 @@
+/**
+ * Icon resolver: turn an icon-font NAME (Material Symbols / Font Awesome, the form
+ * ingest surfaces as block.icon "ms:<name>" / "fa:<name>") into a real inline SVG,
+ * via the public Iconify API (https://iconify.design — unifies both icon sets).
+ *
+ * This is what lets a clone reproduce a Stitch icon FAITHFULLY and SELF-CONTAINED:
+ * the SVG is embedded straight into a text-block (fill="currentColor", colored by
+ * the element's styles.color) — no webfont to load, no svg-mask background trap.
+ *
+ * Pure network helper (no Webcake creds). Mirrors the search_images pattern.
+ */
+const ICONIFY_BASE = "https://api.iconify.design";
+const ICON_FETCH_TIMEOUT_MS = 8_000;
+/** Normalize a Material/FA icon name to the Iconify token form (underscores → hyphens, lowercased, trimmed). */
+function normName(name) {
+    return name.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "");
+}
+/**
+ * Ordered Iconify "prefix/name" candidates for an icon reference. Tries the most
+ * faithful variant first, then sensible fallbacks:
+ *  - ms:NAME           → material-symbols/NAME-outline (the "-outlined" class look), then the filled base
+ *  - fa:NAME / fas:    → fa6-solid, fa-solid
+ *  - far: / fab:       → regular / brands variants
+ *  - prefix:NAME       → used as-is (already an Iconify id)
+ *  - NAME (bare)       → assumed Material Symbols
+ */
+export function iconifyCandidates(ref) {
+    const raw = ref.trim();
+    // Already an Iconify id "prefix:name" (but NOT our ms:/fa: shorthands).
+    const m = /^([a-z0-9]+(?:-[a-z0-9]+)*):(.+)$/i.exec(raw);
+    const kind = m ? m[1].toLowerCase() : "";
+    const rest = m ? normName(m[2]) : normName(raw);
+    if (!rest)
+        return [];
+    if (kind === "ms" || kind === "material-symbols" || kind === "msr") {
+        return [`material-symbols/${rest}-outline`, `material-symbols/${rest}`];
+    }
+    if (kind === "fa" || kind === "fas" || kind === "fa-solid" || kind === "fa6-solid") {
+        return [`fa6-solid/${rest}`, `fa-solid/${rest}`, `fa6-regular/${rest}`, `fa6-brands/${rest}`];
+    }
+    if (kind === "far" || kind === "fa-regular")
+        return [`fa6-regular/${rest}`, `fa-regular/${rest}`];
+    if (kind === "fab" || kind === "fa-brands")
+        return [`fa6-brands/${rest}`, `fa-brands/${rest}`];
+    // A real Iconify prefix (e.g. mdi:home, lucide:check) → use verbatim, then bare-as-material.
+    if (kind)
+        return [`${kind}/${rest}`];
+    // Bare name → assume Material Symbols (the Stitch default).
+    return [`material-symbols/${rest}-outline`, `material-symbols/${rest}`];
+}
+/** Fetch one Iconify "prefix/name" → SVG string, or null when it 404s / isn't an SVG. */
+async function fetchOne(prefixName) {
+    let res;
+    try {
+        res = await fetch(`${ICONIFY_BASE}/${prefixName}.svg`, { signal: AbortSignal.timeout(ICON_FETCH_TIMEOUT_MS) });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    const body = (await res.text()).trim();
+    // Unknown icons return a non-SVG body ("404"/"Not found"); only accept real SVG markup.
+    return body.startsWith("<svg") ? body : null;
+}
+/**
+ * Resolve an icon reference ("ms:verified" / "fa:chart-line" / "mdi:home" / a bare
+ * name) to an inline SVG. The SVG keeps fill="currentColor" so the embedding
+ * element's styles.color decides the icon color.
+ */
+export async function resolveIconSvg(ref) {
+    const candidates = iconifyCandidates(ref);
+    if (!candidates.length)
+        return { ok: false, error: `Empty/invalid icon ref: "${ref}"` };
+    for (const c of candidates) {
+        const svg = await fetchOne(c);
+        if (svg)
+            return { ok: true, svg, iconify: c };
+    }
+    return { ok: false, error: `No icon found for "${ref}" (tried: ${candidates.join(", ")})` };
+}

package/dist/persistence/ingest/semantic.js

@@ -3,7 +3,7 @@
  */
 import { parse } from "node-html-parser";
 import { extractStylesheetColors, extractStylesheetFonts, extractBackgroundImages, extractCssVarPalette, topColors, topFonts, mergeTopN, mergeTopNFonts, } from "./stylesheets.js";
-import { resolveTailwindColors } from "./tailwind.js";
+import { resolveTailwindColors, resolveTailwindGradients } from "./tailwind.js";
 export const HEADING_TAGS = ["h1", "h2", "h3", "h4"];
 // ─── section helpers ─────────────────────────────────────────────────────────
 const BLOCK_TAGS = new Set(["div", "main", "section", "article", "header", "footer", "aside", "nav"]);
@@ -49,12 +49,38 @@ function isPricingSection(el) {
     // Currency symbol + per-period pattern anywhere in the element.
     return /[$€£¥₫]\s*\d/.test(text) && /\/(month|mo\b|year|yr\b|annual)/i.test(text);
 }
+/** A top navigation bar without a <header> tag: <nav>, or a sticky/fixed top bar (no heading) with a logo + links. Stitch desktops use <nav class="fixed top-0 …">. A BOTTOM-pinned bar (mobile sticky action/nav bar, <nav class="fixed bottom-0 …">) is NOT the header. */
+function looksLikeTopBar(el) {
+    const cls = (el.getAttribute("class") ?? "").toLowerCase();
+    if (/\bbottom-0\b|bottom:\s*0/.test(cls))
+        return false; // bottom action/nav bar, not the page header
+    const tag = el.tagName?.toLowerCase();
+    if (tag === "nav")
+        return true;
+    const pinnedTop = /\b(fixed|sticky)\b/.test(cls) && /\btop-0\b|top:\s*0/.test(cls);
+    if (!pinnedTop)
+        return false;
+    if (el.querySelector(HEADING_TAGS.join(",")))
+        return false; // a pinned hero/banner, not a nav bar
+    return !!el.querySelector("nav") || el.querySelectorAll("a").length >= 2;
+}
+/** A repeating grid of ≥2 card-like siblings that each carry a title (heading/strong) or an icon — a feature/benefit grid. Catches 2-column Stitch grids that the ≥3 count misses. */
+function looksLikeCardGrid(el) {
+    const found = findRepeatingContainer(el);
+    if (!found || found.items.length < 2)
+        return false;
+    const titled = found.items.filter((it) => it.querySelector(HEADING_TAGS.join(",")) || it.querySelector("strong, b") || detectIconFont(it)).length;
+    return titled >= 2;
+}
 export function classifySection(el, detail) {
     const tag = el.tagName?.toLowerCase();
     if (tag === "header")
         return classifyHeader(el, detail);
     if (tag === "footer")
         return classifyFooter(el, detail);
+    // A top nav bar without a <header> tag (Stitch uses <nav class="fixed top-0…">) is the header.
+    if (looksLikeTopBar(el))
+        return classifyHeader(el, detail);
     const form = el.querySelector("form");
     if (form)
         return classifyForm(el, form, detail);
@@ -82,7 +108,10 @@ export function classifySection(el, detail) {
         }
         return sec;
     }
-    if (countFeatureBlocks(el) >= 3) {
+    const headingTag = heading?.tagName?.toLowerCase();
+    // features: the classic ≥3 count OR a ≥2-card repeating grid (Stitch 2-column
+    // benefit grids) — but never steal an h1 section (that's the hero).
+    if (countFeatureBlocks(el) >= 3 || (headingTag !== "h1" && looksLikeCardGrid(el))) {
         const sec = { role: "features", heading: elText(heading), subheading, ctas: ctas.length ? ctas : undefined };
         if (detail === "full") {
             const blocks = detectBlocks(el);
@@ -94,7 +123,7 @@ export function classifySection(el, detail) {
         }
         return sec;
     }
-    if (heading?.tagName?.toLowerCase() === "h1" && (imgSrcs.length > 0 || ctas.length > 0)) {
+    if (headingTag === "h1" && (imgSrcs.length > 0 || ctas.length > 0)) {
         const sec = {
             role: "hero",
             heading: elText(heading),
@@ -105,8 +134,35 @@ export function classifySection(el, detail) {
         };
         return sec;
     }
-    if (ctas.length > 0 && paragraphs.length <= 1) {
-        return { role: "cta", heading: elText(heading), subheading, ctas };
+    // CTA band: a heading + call-to-action with no card grid and no imagery — allow
+    // a couple of supporting paragraphs (a closing "ready to start?" band), not just one.
+    if (ctas.length > 0 && imgSrcs.length === 0 && paragraphs.length <= 3) {
+        return {
+            role: "cta",
+            heading: elText(heading),
+            subheading,
+            paragraphs: paragraphs.length ? paragraphs.slice(0, detail === "full" ? 2 : 1) : undefined,
+            ctas,
+        };
+    }
+    // Content/about band: a heading with real prose (and maybe an image) — a far more
+    // useful role than "unknown" for the rebuild. Reserve "unknown" for sections with
+    // no heading AND no paragraphs.
+    if (elText(heading) && paragraphs.length >= 1) {
+        const sec = {
+            role: "about",
+            heading: elText(heading),
+            subheading,
+            paragraphs: paragraphs.slice(0, detail === "full" ? 6 : 3),
+            images: detail === "full" ? images.slice(0, 4) : images.slice(0, 4),
+            ctas: ctas.length ? ctas : undefined,
+        };
+        if (detail === "full") {
+            const blocks = detectBlocks(el);
+            if (blocks.length)
+                sec.blocks = blocks;
+        }
+        return sec;
     }
     const sec = {
         role: "unknown",
@@ -239,7 +295,11 @@ function pickCtas(el) {
     });
     el.querySelectorAll("a").forEach((a) => {
         const cls = (a.getAttribute("class") ?? "").toLowerCase();
-        if (/(btn|button|cta)/.test(cls)) {
+        // An <a> is a CTA when it's named like one, OR styled like a button —
+        // Tailwind/Stitch pill buttons carry NO btn/button/cta class, just utilities
+        // (`px-8 py-4 rounded-xl bg-… …`): rounded + a fill/border + padding.
+        const styledButton = /\brounded(-|\b)/.test(cls) && /(\bbg-|bg-gradient|\bborder\b|\bborder-)/.test(cls) && /\b[pmg][xytrbl]?-/.test(cls);
+        if (/(btn|button|cta)/.test(cls) || styledButton) {
             const t = a.text.trim();
             const href = a.getAttribute("href") ?? undefined;
             if (t)
@@ -326,31 +386,69 @@ function findRepeatingContainer(root, maxDepth = 4) {
  *   text is ≤4 chars (emoji/badge) — surfaced separately so the model can map
  *   it to a Webcake svg-mask rectangle.
  */
+// Font-Awesome style classes that are NOT the icon name (fa-solid, fa-2x, …).
+const FA_STYLE_TOKENS = new Set(["solid", "regular", "light", "thin", "duotone", "brands", "sharp", "fw", "lg", "sm", "xs", "xl", "2xs", "1x", "2x", "3x", "4x", "5x", "6x", "7x", "8x", "9x", "10x", "rotate", "flip", "spin", "pulse", "border", "pull", "stack"]);
+/**
+ * A Material-Symbols / Material-Icons / Font-Awesome icon inside `scope`,
+ * normalized to "ms:<name>" / "fa:<name>" (the icon NAME, not a glyph). These
+ * are font ligatures the clone can't render as plain text — surfaced so the model
+ * loads the icon font (settings.bhet) and renders each as a text-block/html-box,
+ * instead of dropping the icon or pasting the raw ligature word.
+ */
+function detectIconFont(scope) {
+    const ms = scope.querySelector('[class*="material-symbols"],[class*="material-icons"]');
+    if (ms) {
+        const name = ms.textContent.trim().toLowerCase().replace(/\s+/g, "_");
+        if (name && /^[a-z0-9_]+$/.test(name))
+            return `ms:${name}`;
+    }
+    const fa = scope.querySelector('i[class*="fa-"],span[class*="fa-"]');
+    if (fa) {
+        const name = (fa.getAttribute("class") ?? "")
+            .split(/\s+/)
+            .map((c) => /^fa-([a-z0-9-]+)$/i.exec(c)?.[1])
+            .find((n) => !!n && !FA_STYLE_TOKENS.has(n));
+        if (name)
+            return `fa:${name}`;
+    }
+    return undefined;
+}
 function detectBlocks(el) {
     const found = findRepeatingContainer(el);
     if (!found || found.items.length < 2)
         return [];
     return found.items.slice(0, 12).map((c) => {
         const kids = elementChildren(c);
-        // ── icon slot ──
+        // True when a child IS or CONTAINS an icon-font glyph (so it's never mistaken
+        // for the title/body — Material Symbols ligature text like "verified" reads as
+        // a word but is an icon).
+        const containsIcon = (k) => /material-symbols|material-icons|\bfa-/.test(k.getAttribute("class") ?? "") ||
+            !!k.querySelector('[class*="material-symbols"],[class*="material-icons"],i[class*="fa-"]');
+        // ── icon slot ── prefer a real icon-font glyph (Material Symbols / Font
+        // Awesome), captured as "ms:<name>"/"fa:<name>" regardless of name length;
+        // fall back to an emoji / short-text / icon-class child.
+        const iconFont = detectIconFont(c);
         const iconEl = kids.find((k) => {
             const cls = (k.getAttribute("class") ?? "").toLowerCase();
-            if (/icon|emoji|badge|img/.test(cls))
+            if (/icon|emoji|badge|img|material-symbols|material-icons/.test(cls))
+                return true;
+            if (containsIcon(k))
                 return true;
             const t = k.textContent.trim();
             return t.length > 0 && t.length <= 4; // likely a single emoji
         });
-        const icon = iconEl?.textContent?.trim() || undefined;
+        const icon = iconFont ?? (iconEl?.textContent?.trim() || undefined);
+        const isIcon = (k) => k === iconEl || containsIcon(k);
         // ── title ──
         const headingEl = c.querySelector(HEADING_TAGS.join(","));
         const titleClassEl = kids.find((k) => {
             const cls = (k.getAttribute("class") ?? "").toLowerCase();
-            return /title|name|heading|label/.test(cls) && k !== iconEl;
+            return /title|name|heading|label/.test(cls) && !isIcon(k);
         });
         const strongEl = c.querySelector("strong") || c.querySelector("b");
         // fallback: first non-icon short-text child
         const fallbackTitleEl = kids.find((k) => {
-            if (k === iconEl)
+            if (isIcon(k))
                 return false;
             const cls = (k.getAttribute("class") ?? "").toLowerCase();
             if (/icon|emoji|badge/.test(cls))
@@ -363,15 +461,14 @@ function detectBlocks(el) {
         // ── body ──
         // Prefer <p> tags; fall back to div children whose class contains body|desc|text|content
         const titleText = title ?? "";
-        const iconText = icon ?? "";
         const bodyFromP = c.querySelectorAll("p")
             .map((p) => p.text.trim())
-            .filter((t) => t && t !== titleText && t !== iconText && t.length > 5)
+            .filter((t) => t && t !== titleText && t.length > 5)
             .join(" ")
             .slice(0, 250);
         const bodyFromDiv = !bodyFromP ? kids
             .filter((k) => {
-            if (k === iconEl || k === titleEl)
+            if (isIcon(k) || k === titleEl)
                 return false;
             const cls = (k.getAttribute("class") ?? "").toLowerCase();
             return /body|desc|text|content|copy/.test(cls);
@@ -633,11 +730,52 @@ export function brandHints(body, styleBlocks, googleFonts, tw) {
             ...(Object.keys(tw.fontFamily).length ? { font_family: tw.fontFamily } : {}),
         }
         : undefined;
+    const tailwind_gradients = tw ? resolveTailwindGradients(body, tw.colors) : [];
     return {
         colors,
         fonts,
         background_images,
         palette: Object.keys(palette).length ? palette : undefined,
         design_tokens: design_tokens && Object.keys(design_tokens).length ? design_tokens : undefined,
+        tailwind_gradients,
     };
 }
+/**
+ * Interaction effects present in a section's hover/transition utility classes
+ * (`hover:`/`group-hover:`/`active:`), normalized to the kinds Webcake can
+ * reproduce. The static AST otherwise drops every hover, so the cloned page has
+ * none — this lets the rebuild wire the matching Webcake hover behavior.
+ */
+export function detectHoverEffects(el) {
+    const set = new Set();
+    for (const node of el.querySelectorAll("[class]")) {
+        const cls = node.getAttribute("class");
+        if (!cls)
+            continue;
+        for (const t of cls.split(/\s+/)) {
+            const group = t.startsWith("group-hover:");
+            const h = t.startsWith("hover:") ? t.slice(6) : group ? t.slice(12) : t.startsWith("active:") ? t.slice(7) : null;
+            if (h === null)
+                continue;
+            if (/^scale-/.test(h))
+                set.add(group ? "image-zoom" : "scale");
+            else if (/^-?translate-y/.test(h))
+                set.add("lift");
+            else if (/^-?translate-x/.test(h))
+                set.add("slide");
+            else if (/^bg-/.test(h))
+                set.add("bg-color-change");
+            else if (/^text-/.test(h))
+                set.add("text-color-change");
+            else if (/^border/.test(h))
+                set.add("border-color-change");
+            else if (/^opacity-/.test(h))
+                set.add("fade");
+            else if (h === "underline")
+                set.add("underline");
+            else if (/^shadow/.test(h))
+                set.add("shadow");
+        }
+    }
+    return [...set];
+}

package/dist/persistence/ingest/tailwind.js

@@ -189,6 +189,49 @@ const TW_COLOR_PREFIXES = [
 const TW_PREFIX_RE = new RegExp(`^(?:${TW_COLOR_PREFIXES.join("|")})-(.+)$`);
 // Tailwind's always-available keyword colors (present even without a config entry).
 const TW_KNOWN = { white: "#ffffff", black: "#000000" };
+/** Tailwind gradient direction utility → CSS gradient direction keyword. */
+const TW_GRADIENT_DIR = {
+    t: "to top", tr: "to top right", r: "to right", br: "to bottom right",
+    b: "to bottom", bl: "to bottom left", l: "to left", tl: "to top left",
+};
+/** Resolve a color token to a value: config token, keyword color, or an arbitrary `[#hex]`/`[rgb(...)]` value. */
+function resolveColorToken(tok, colors) {
+    const t = tok.split("/")[0]; // drop /80 opacity modifier
+    const arb = /^\[(.+)\]$/.exec(t);
+    if (arb)
+        return arb[1].replace(/_/g, " "); // arbitrary value: bg-[#ff7f78] / from-[rgb(0_0_0)]
+    return colors[t] ?? TW_KNOWN[t];
+}
+/**
+ * Reconstruct `linear-gradient(...)` strings from Tailwind gradient utilities
+ * (`bg-gradient-to-br from-primary via-x to-y`) — Stitch uses gradient CTAs and
+ * hero backgrounds heavily, and Play-CDN never emits the resolved CSS, so the
+ * gradient would otherwise be invisible to the rebuild. Stops are resolved
+ * through the same color map (config token / keyword / arbitrary [#hex]).
+ */
+export function resolveTailwindGradients(body, colors) {
+    const out = new Set();
+    body.querySelectorAll("[class]").forEach((el) => {
+        const cls = el.getAttribute("class");
+        if (!cls)
+            return;
+        const utils = cls.split(/\s+/).map((c) => (c.includes(":") ? c.slice(c.lastIndexOf(":") + 1) : c));
+        const dirCls = utils.find((u) => /^bg-gradient-to-(t|tr|r|br|b|bl|l|tl)$/.test(u));
+        if (!dirCls)
+            return;
+        const dir = TW_GRADIENT_DIR[dirCls.replace("bg-gradient-to-", "")];
+        const stops = [
+            utils.map((u) => /^from-(.+)/.exec(u)?.[1]).find(Boolean),
+            utils.map((u) => /^via-(.+)/.exec(u)?.[1]).find(Boolean),
+            utils.map((u) => /^to-(.+)/.exec(u)?.[1]).find(Boolean),
+        ]
+            .map((t) => (t ? resolveColorToken(t, colors) : undefined))
+            .filter((v) => !!v);
+        if (stops.length >= 2)
+            out.add(`linear-gradient(${dir}, ${stops.join(", ")})`);
+    });
+    return [...out];
+}
 /** Rank the config colors ACTUALLY used by utility classes in the body → resolved value list (usage-weighted). */
 export function resolveTailwindColors(body, colors) {
     const counts = new Map();

package/dist/smoke.js

@@ -15,6 +15,7 @@ import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsPr
 import { putDraft, getDraft, updateDraft, deleteDraft } from "./persistence/draft-cache.js";
 import { buildConnectUrl, parseCallback } from "./auth/login.js";
 import { isLocalPath, resolveLocalPath, sniffMime, localContentType } from "./tools/media.js";
+import { iconifyCandidates } from "./persistence/icon-client.js";
 import { collectExternalImageUrls, rewriteImageUrls, isRehostableImageUrl } from "./persistence/rehost.js";
 let failures = 0;
 const check = (name, cond, extra) => {
@@ -176,6 +177,86 @@ console.log("== expand: relocates misplaced responsive.<bp>.animation into confi
 console.log("== validate: accepts JSON string input ==");
 const r3 = validatePage(JSON.stringify(good));
 check("string input parsed & valid", r3.valid, r3.errors);
+console.log("== canvas width is a CHOICE (settings.width_section 960|1200 / 420|360) ==");
+{
+    // createPageSource sets the chosen width up front.
+    const wide = landingDomain.createPageSource({ settings: { width_section: { desktop: 1200, mobile: 360 } } });
+    check("width: createPageSource honors width_section override", wide.settings.width_section.desktop === 1200 && wide.settings.width_section.mobile === 360, wide.settings.width_section);
+    // An element at left:1000 width:180 (right edge 1180) overflows a 960 canvas but FITS a 1200 canvas.
+    const mk = (deskW) => {
+        const p = JSON.parse(JSON.stringify(good));
+        p.settings.width_section = { desktop: deskW, mobile: 420 };
+        p.page[0].children[0].responsive.desktop.styles = { top: 100, left: 1000, width: 180, height: 44 };
+        return p;
+    };
+    const at960 = validatePage(mk(960));
+    check("width: overflow flagged against the 960 canvas", at960.warnings.some((w) => /exceeds canvas 960/.test(w)), at960.warnings);
+    const at1200 = validatePage(mk(1200));
+    check("width: SAME element fits the 1200 canvas (no overflow warning)", !at1200.warnings.some((w) => /exceeds canvas/.test(w)), at1200.warnings);
+    check("width: 1200 canvas page is valid", at1200.valid, at1200.errors);
+    // Only the editor-allowed widths pass — a stray width is a schema error.
+    const badW = JSON.parse(JSON.stringify(good));
+    badW.settings.width_section = { desktop: 1000, mobile: 420 };
+    check("width: non-allowed desktop width (1000) rejected by schema enum", !validatePage(badW).valid, validatePage(badW).errors);
+}
+console.log("== validate: custom CSS/class/JS escape hatches (beyond-element capability) ==");
+{
+    const clone = () => JSON.parse(JSON.stringify(good));
+    // Proper usage: customAdvance + declarations-only custom_css + page settings.extra_css/script → valid, no escape-hatch warnings.
+    const okPage = clone();
+    okPage.page[0].children[0].specials = { text: "CTA", customAdvance: true, custom_css: "background:linear-gradient(to right,#0058bc,#0070eb);box-shadow:0 20px 40px rgba(0,0,0,.08);", custom_class: "cta-pill,glow" };
+    okPage.settings.extra_css = "#w-btn1{transition:transform .3s}#w-btn1:hover{transform:scale(1.05)}";
+    okPage.settings.extra_script = "console.log('hi')";
+    okPage.settings.bhet = "<link href='https://fonts.googleapis.com/css2?family=Inter&display=swap' rel='stylesheet'>";
+    okPage.settings.bbet = "<script src='https://widget.example.com/chat.js'></script>";
+    const okR = validatePage(okPage);
+    check("escape hatch: valid page with custom_css/class + extra_css/script + bhet/bbet passes", okR.valid, okR.errors);
+    check("escape hatch: no false warning when used correctly", !okR.warnings.some((w) => /custom_css|customAdvance/.test(w)), okR.warnings.filter((w) => /custom_css|customAdvance/.test(w)));
+    // custom_css set but customAdvance missing → silent no-op warning.
+    const noAdvance = clone();
+    noAdvance.page[0].children[0].specials = { text: "CTA", custom_css: "box-shadow:0 2px 8px rgba(0,0,0,.1);" };
+    const naR = validatePage(noAdvance);
+    check("escape hatch: warns custom_css without customAdvance", naR.warnings.some((w) => /customAdvance!==true/.test(w)), naR.warnings);
+    // custom_css containing a selector/:hover → declarations-only warning.
+    const selInCss = clone();
+    selInCss.page[0].children[0].specials = { text: "CTA", customAdvance: true, custom_css: "#w-btn1:hover{transform:scale(1.1)}" };
+    const selR = validatePage(selInCss);
+    check("escape hatch: warns selector/:hover inside custom_css", selR.warnings.some((w) => /declarations inside/.test(w)), selR.warnings);
+    check("escape hatch: declarations-only misuse does NOT block (warning, not error)", selR.valid, selR.errors);
+}
+console.log("== validate: icon rendering (svg-mask needs background; font-class route is clean) ==");
+{
+    const cloneG = () => JSON.parse(JSON.stringify(good));
+    const maskChild = (bg) => ({
+        id: "icon1", type: "rectangle", properties: { name: "icon", movable: true, sync: true },
+        specials: {}, runtime: {}, events: [],
+        responsive: {
+            desktop: { config: { svgMask: "<svg viewBox='0 0 24 24'><path d='M4 4h16v16H4z'/></svg>" }, styles: { top: 10, left: 10, width: 40, height: 40, ...(bg ? { background: bg } : {}) } },
+            mobile: { config: { svgMask: "<svg viewBox='0 0 24 24'><path d='M4 4h16v16H4z'/></svg>" }, styles: { top: 10, left: 10, width: 40, height: 40, ...(bg ? { background: bg } : {}) } },
+        },
+    });
+    // svg-mask WITHOUT a background fill → invisible-icon warning (the "svg in a rectangle doesn't show" bug).
+    const noBg = cloneG();
+    noBg.page[0].children = [maskChild()];
+    check("icon-render: svg-mask rectangle without background → invisible warning", validatePage(noBg).warnings.some((w) => /svgMask is set but styles\.background/.test(w)), validatePage(noBg).warnings);
+    // svg-mask WITH a solid background → no invisible warning.
+    const withBg = cloneG();
+    withBg.page[0].children = [maskChild("rgba(0,88,188,1)")];
+    check("icon-render: svg-mask rectangle WITH background → no invisible warning", !validatePage(withBg).warnings.some((w) => /svgMask is set but styles\.background/.test(w)), validatePage(withBg).warnings);
+    // font-class route (the Stitch-faithful one): text-block with a Material Symbols span + the font loaded via bhet → valid & clean.
+    const fontRoute = cloneG();
+    fontRoute.settings.bhet = "<link href='https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined' rel='stylesheet'>";
+    fontRoute.page[0].children = [{
+            id: "icon2", type: "text-block", properties: { name: "icon", movable: true, sync: true },
+            specials: { text: "<span class=\"material-symbols-outlined\">verified</span>" }, runtime: {}, events: [],
+            responsive: {
+                desktop: { config: {}, styles: { top: 10, left: 10, width: 40, height: 40, fontSize: 32, color: "rgba(0,88,188,1)" } },
+                mobile: { config: {}, styles: { top: 10, left: 10, width: 40, height: 40, fontSize: 28, color: "rgba(0,88,188,1)" } },
+            },
+        }];
+    const fr = validatePage(fontRoute);
+    check("icon-render: font-class text-block icon validates clean (no svg/emoji warning)", fr.valid && !fr.warnings.some((w) => /svgMask|emoji/.test(w)), { errors: fr.errors, warnings: fr.warnings });
+}
 console.log("== expand: hydrates sparse nodes ==");
 const sparse = {
     page: [
@@ -278,6 +359,31 @@ check("ingest: hero image captured", (hero?.images?.length ?? 0) > 0, hero?.imag
 const form = ast.sections.find((s) => s.role === "form");
 check("ingest: form fields captured", (form?.form_fields?.length ?? 0) >= 2, form?.form_fields);
 check("ingest: form submit CTA captured", !!form?.ctas?.[0]?.text?.includes("Place"), form?.ctas);
+console.log("== ingest: Stitch-structure section classification (generalizes to any Stitch HTML) ==");
+{
+    // Mirrors the real Stitch shape: <nav> top bar (no <header>), <main> with a
+    // h1 hero, 2-column card grids, a card-less CTA band, <footer>, and a sticky
+    // BOTTOM <nav> action bar.
+    const stitchStruct = `<!DOCTYPE html><html><head></head><body>
+    <nav class="fixed top-0 w-full z-50 bg-white/80"><div class="font-bold">BrandName</div><div><a href="#">Pricing</a><a href="#">Docs</a></div><a class="px-5 py-2 rounded-xl bg-primary" href="#">Sign in</a></nav>
+    <main class="pt-20">
+      <section class="pt-24 pb-32"><div class="grid lg:grid-cols-12"><div class="lg:col-span-7"><h1>Become a strategic partner</h1><p>Earn recurring commission on every customer you refer to us.</p><a class="px-8 py-4 rounded-xl bg-primary" href="#">Join now</a></div><div class="lg:col-span-5"><img src="https://x/hero.jpg"/></div></div></section>
+      <section class="py-24 bg-surface-container-low"><div class="text-center"><h2>Transparent income</h2></div><div class="grid md:grid-cols-2 gap-6"><div class="card p-8 rounded-xl"><span class="material-symbols-outlined">payments</span><h3>Fast payouts</h3><p>Money in your account within days, not months at all.</p></div><div class="card p-8 rounded-xl"><span class="material-symbols-outlined">monitoring</span><h3>Live tracking</h3><p>Watch every referral convert in a real-time dashboard.</p></div></div></section>
+      <section class="py-20"><div class="rounded-3xl p-12 text-center"><h2>Ready to boost your income?</h2><p>Join thousands of partners already earning with us.</p><p>No setup fee, cancel anytime, get started in minutes.</p><a class="px-8 py-4 rounded-xl bg-primary" href="#">Get started</a></div></section>
+    </main>
+    <footer class="pt-12 pb-8"><div class="grid grid-cols-4"><a href="#">About</a><a href="#">Blog</a><a href="#">Terms</a><a href="#">Contact</a></div><p>© 2026 BrandName</p></footer>
+    <nav class="fixed bottom-0 left-0 right-0 z-50 bg-white"><a class="px-6 py-3 rounded-xl bg-primary" href="#">Join now</a></nav>
+  </body></html>`;
+    const ss = parseHtml(stitchStruct, "full");
+    const roles = ss.sections.map((s) => s.role);
+    check("stitch-struct: <nav> top bar (no <header>) → header", roles[0] === "header", roles);
+    check("stitch-struct: h1 section → hero", ss.sections.some((s) => s.role === "hero" && /strategic partner/.test(s.heading ?? "")), roles);
+    check("stitch-struct: 2-card grid → features (not unknown)", ss.sections.some((s) => s.role === "features" && (s.blocks?.length ?? 0) === 2), roles);
+    check("stitch-struct: card-less CTA band with 2 paragraphs → cta (not unknown)", ss.sections.some((s) => s.role === "cta" && /Ready to boost/.test(s.heading ?? "")), roles);
+    check("stitch-struct: <footer> → footer", roles.includes("footer"), roles);
+    check("stitch-struct: sticky BOTTOM <nav> is NOT a second header", roles.filter((r) => r === "header").length === 1, roles);
+    check("stitch-struct: no 'unknown' sections left", !roles.includes("unknown"), roles);
+}
 console.log("== ingest: size_hint (desktop section heights) ==");
 check("ingest: every section has a size_hint", ast.sections.every((s) => (s.size_hint?.height ?? 0) > 0), ast.sections.map((s) => s.size_hint));
 const headerHint = ast.sections.find((s) => s.role === "header")?.size_hint;
@@ -434,6 +540,55 @@ check("tw: palette names every flattened token", twAst.palette?.["gray-900"] ===
 check("tw: usage-ranked colors resolve nested + directional-border classes", (twAst.colors ?? []).includes("#2563eb") && (twAst.colors ?? []).includes("#111827") && (twAst.colors ?? []).includes("#3b82f6"), twAst.colors);
 check("tw: design_tokens carries the resolved type scale", twAst.design_tokens?.font_size?.["lg"] === "18px" && twAst.design_tokens?.radius?.["full"] === "9999px", twAst.design_tokens);
 check("tw: no config → extractTailwindConfig null", extractTailwindConfig("<div class='text-primary'>x</div>") === null);
+console.log("== tailwind: gradient utilities + hover/transition effects (Stitch fidelity) ==");
+const fxCfg = `<script id="tailwind-config">tailwind.config = { theme: { extend: { "colors": {
+  "primary": "#0058bc", "primary-container": "#0070eb", "secondary": "#fcd664", "surface": "#ffffff"
+} } } }</script>`;
+const fxPage = `<!DOCTYPE html><html><head>${fxCfg}</head><body>
+  <header class="bg-surface"><a class="text-primary hover:text-secondary transition-colors">Navigation menu link here</a></header>
+  <main>
+    <section class="bg-gradient-to-br from-primary to-primary-container"><h1 class="text-white">Join the affiliate program today</h1><p>Earn recurring commission from every referral you bring in.</p><a class="px-8 py-4 rounded-xl bg-gradient-to-br from-primary to-primary-container hover:scale-105 transition-transform" href="#">Get started now</a></section>
+    <section><h2 class="text-primary">Why partners choose us</h2>
+      <div class="group hover:-translate-y-1 transition-all"><img class="group-hover:scale-110" src="https://x/a.jpg"/><h3 class="group-hover:underline">Fast payouts</h3><p>Money in your account within days, not months.</p></div>
+      <div class="group hover:-translate-y-1 transition-all"><img class="group-hover:scale-110" src="https://x/b.jpg"/><h3>Real-time tracking</h3><p>Watch your referrals convert in a live dashboard.</p></div>
+      <div class="group hover:-translate-y-1 transition-all"><img class="group-hover:scale-110" src="https://x/c.jpg"/><h3>Dedicated support</h3><p>A partner manager helps you grow your revenue.</p></div>
+    </section>
+  </main>
+  <footer class="bg-primary"><a class="hover:opacity-80" href="#">Footer contact and company info link</a></footer>
+</body></html>`;
+const fxAst = parseHtml(fxPage, "compact");
+check("fx: gradient utility reconstructed with resolved color stops", (fxAst.gradients ?? []).includes("linear-gradient(to bottom right, #0058bc, #0070eb)"), fxAst.gradients);
+check("fx: gradients surfaced in COMPACT mode (design-critical)", (fxAst.gradients?.length ?? 0) >= 1, fxAst.gradients);
+const heroFx = fxAst.sections.find((s) => s.role === "hero");
+check("fx: hero hover scale captured", (heroFx?.hover_effects ?? []).includes("scale"), heroFx?.hover_effects);
+const featFx = fxAst.sections.find((s) => s.role === "features");
+check("fx: card lift captured", (featFx?.hover_effects ?? []).includes("lift"), featFx?.hover_effects);
+check("fx: image-zoom (group-hover scale) captured", (featFx?.hover_effects ?? []).includes("image-zoom"), featFx?.hover_effects);
+check("fx: underline (group-hover) captured", (featFx?.hover_effects ?? []).includes("underline"), featFx?.hover_effects);
+const headFx = fxAst.sections.find((s) => s.role === "header");
+check("fx: header hover text-color-change captured", (headFx?.hover_effects ?? []).includes("text-color-change"), headFx?.hover_effects);
+// arbitrary-value gradient stop resolves too.
+const arbGrad = parseHtml(`<!DOCTYPE html><html><head>${fxCfg}</head><body><main><section class="bg-gradient-to-r from-[#ff0000] to-primary"><h1>Heading text for the arbitrary gradient test case here</h1><p>Some descriptive paragraph text to clear the CSR shell threshold.</p></section></main></body></html>`, "compact");
+check("fx: arbitrary [#hex] gradient stop resolved", (arbGrad.gradients ?? []).includes("linear-gradient(to right, #ff0000, #0058bc)"), arbGrad.gradients);
+// no tailwind config → no gradients from this path, no hover noise on a plain page.
+check("fx: plain page (no config, no hover classes) has no gradients/hover", (() => { const a = parseHtml(stylesheetHtml, "compact"); return a.gradients === undefined && a.sections.every((s) => s.hover_effects === undefined); })());
+console.log("== ingest: icon-font extraction (Material Symbols / Font Awesome) ==");
+{
+    // Feature cards with Material Symbols icons (a long ligature name + a nested-wrapper icon) and one Font Awesome card.
+    const iconHtml = `<!DOCTYPE html><html><head></head><body><main><section><h2>Why choose us</h2>
+    <div class="grid"><div class="card"><span class="material-symbols-outlined">verified</span><h3>Trusted</h3><p>Verified by thousands of happy partners every month.</p></div>
+    <div class="card"><div class="icon-wrap"><span class="material-symbols-outlined">support_agent</span></div><h3>Support</h3><p>A dedicated manager helps you grow revenue fast.</p></div>
+    <div class="card"><i class="fa-solid fa-chart-line fa-2x"></i><h3>Analytics</h3><p>Track every referral conversion in real time dashboards.</p></div></div>
+  </section></main></body></html>`;
+    const ia = parseHtml(iconHtml, "full");
+    const fsec = ia.sections.find((s) => (s.blocks || []).length >= 3);
+    const blocks = fsec?.blocks ?? [];
+    check("icon: Material Symbols long ligature captured as ms:<name>", blocks[0]?.icon === "ms:verified", blocks[0]);
+    check("icon: nested-wrapper Material Symbol captured", blocks[1]?.icon === "ms:support_agent", blocks[1]);
+    check("icon: Font Awesome captured as fa:<name> (style tokens skipped)", blocks[2]?.icon === "fa:chart-line", blocks[2]);
+    check("icon: ligature name does NOT leak into the card title", blocks[0]?.title === "Trusted" && blocks[1]?.title === "Support", blocks.map((b) => b.title));
+    check("icon: real body kept (icon excluded)", /Verified by thousands/.test(blocks[0]?.body ?? ""), blocks[0]?.body);
+}
 console.log("== ingest: full mode — blocks detection, gradients, images-as-objects ==");
 const fullAst = parseHtml(stylesheetHtml, "full");
 check("ingest: full mode palette present", fullAst.palette?.["primary"] === "#0A7C6E", fullAst.palette);
@@ -1542,6 +1697,12 @@ console.log("== rehost: external-image URL collect + rewrite (pure, offline) =="
 }
 console.log("== upload_images: local-path detector (pure, offline) ==");
 {
+    // get_icon_svg name → Iconify candidate mapping (pure; the fetch itself is networked)
+    check("icon-svg: ms:<name> → material-symbols outline-first, underscore→hyphen", JSON.stringify(iconifyCandidates("ms:support_agent")) === JSON.stringify(["material-symbols/support-agent-outline", "material-symbols/support-agent"]), iconifyCandidates("ms:support_agent"));
+    check("icon-svg: fa:<name> → fa6-solid first with fallbacks", iconifyCandidates("fa:chart-line")[0] === "fa6-solid/chart-line", iconifyCandidates("fa:chart-line"));
+    check("icon-svg: bare name assumed Material Symbols", iconifyCandidates("verified")[0] === "material-symbols/verified-outline", iconifyCandidates("verified"));
+    check("icon-svg: real Iconify id passes through", iconifyCandidates("mdi:home")[0] === "mdi/home", iconifyCandidates("mdi:home"));
+    check("icon-svg: empty ref → no candidates", iconifyCandidates("")?.length === 0, iconifyCandidates(""));
     // isLocalPath: recognised forms
     check("localPath: absolute POSIX /…", isLocalPath("/home/user/photo.jpg"));
     check("localPath: home-dir ~/…", isLocalPath("~/Pictures/logo.png"));

package/dist/tools/generation.js

@@ -21,7 +21,16 @@ export function registerGenerationTools(server, domain) {
         return text(el);
     });
     // 6) New page skeleton ------------------------------------------------------
-    server.tool("new_page_skeleton", "Returns an empty but complete top-level page source { page:[], popup:[], settings:{...defaults}, options:{...}, cartConfigs:{} } matching the real editor shape.", { mobileOnly: z.boolean().optional().describe("true if the page renders mobile-only.") }, { title: "New Page Skeleton", readOnlyHint: true, openWorldHint: false }, async ({ mobileOnly }) => text(domain.createPageSource({ mobileOnly: mobileOnly ?? false })));
+    server.tool("new_page_skeleton", "Returns an empty but complete top-level page source { page:[], popup:[], settings:{...defaults}, options:{...}, cartConfigs:{} } matching the real editor shape. Pass desktopWidth/mobileWidth to set the canvas width (settings.width_section) up front — pick desktop 1200 for wide/multi-column/editorial pages or when cloning a reference wider than 960 (e.g. Google Stitch ~1280), else 960; then place every element's coords in that width's space.", {
+        mobileOnly: z.boolean().optional().describe("true if the page renders mobile-only."),
+        desktopWidth: z.union([z.literal(960), z.literal(1200)]).optional().describe("Desktop canvas width (settings.width_section.desktop). 960 (default, simple/narrow) or 1200 (wide/multi-column/editorial, or cloning a >960 reference)."),
+        mobileWidth: z.union([z.literal(420), z.literal(360)]).optional().describe("Mobile canvas width (settings.width_section.mobile). 420 (default) or 360 (to match a ~360–390 mobile design)."),
+    }, { title: "New Page Skeleton", readOnlyHint: true, openWorldHint: false }, async ({ mobileOnly, desktopWidth, mobileWidth }) => text(domain.createPageSource({
+        mobileOnly: mobileOnly ?? false,
+        settings: desktopWidth || mobileWidth
+            ? { width_section: { desktop: desktopWidth ?? 960, mobile: mobileWidth ?? 420 } }
+            : undefined,
+    })));
     // 7) Validate page ----------------------------------------------------------
     server.tool("validate_page", "Validates a page source against the schema + semantic rules (unique ids, dangling event targets, children only on containers, missing field_name, top-level types) plus form-data bindings (duplicate field_name within one form, dangling option-event promoId / connectedSurvey / connectedForm / set_field_value targets). Returns errors (blocking — fix before persisting) and warnings (visible design defects — fix these too and re-validate to an empty list; only a demonstrably false positive may remain).", {
         page: z

package/dist/tools/media.js

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { text } from "../mcp/response.js";
 import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
 import { uploadImageMultipart } from "../persistence/webcake-client.js";
+import { resolveIconSvg } from "../persistence/icon-client.js";
 import { configFromHeaders, ENVIRONMENTS, stripTrailingSlash } from "../persistence/config.js";
 /** Resolve just the API base (no JWT required) from per-request headers → env → WEBCAKE_ENV preset → prod default. */
 function resolveApiBase(headers) {
@@ -221,6 +222,36 @@ export function registerMediaTools(server, allowLocalFiles = true) {
         }
         return text({ queries: out });
     });
+    // 13b) Resolve icon-font names to real inline SVGs --------------------------
+    server.tool("get_icon_svg", "Resolves icon-font NAMES into real inline SVG markup via the public Iconify API — so a clone reproduces a reference's icons (esp. Google Stitch, which renders icons with a Material Symbols / Font Awesome CLASS, not an image). ingest_html/ingest_url surface those icons as block.icon \"ms:<name>\" (Material Symbols) / \"fa:<name>\" (Font Awesome); pass them here to get the SVG. ACCEPTS: \"ms:verified\", \"fa:chart-line\", a real Iconify id (\"mdi:home\"), or a bare name (assumed Material Symbols); underscores are normalized to hyphens, and Material Symbols resolve to the OUTLINED variant (the Stitch look) with a filled fallback. Returns { icons: { \"<ref>\": { ok, svg, iconify } } }. RENDER each svg as Webcake's native icon element — a RECTANGLE: put the svg in BOTH responsive.desktop.config.svgMask AND responsive.mobile.config.svgMask, set styles.background = the icon color, and keep the box SQUARE (width === height). The svg is only a MASK (its own fill is ignored), so the icon is BLANK without a solid styles.background; the renderer reads each breakpoint's svgMask separately (no fallback) and forces preserveAspectRatio='none' (a non-square box stretches it). No Webcake credentials needed.", {
+        icons: z
+            .array(z.string())
+            .min(1)
+            .max(40)
+            .describe("Icon references to resolve (1–40), e.g. [\"ms:verified\", \"ms:support_agent\", \"fa:chart-line\"] — typically the block.icon values from an ingest result."),
+    }, { title: "Resolve Icon SVGs", readOnlyHint: true, openWorldHint: true }, async ({ icons }) => {
+        const unique = [...new Set(icons)];
+        const results = await Promise.all(unique.map(async (ref) => [ref, await resolveIconSvg(ref)]));
+        const out = {};
+        let resolved = 0;
+        let failed = 0;
+        for (const [ref, r] of results) {
+            if (r.ok) {
+                resolved++;
+                out[ref] = { ok: true, svg: r.svg, iconify: r.iconify };
+            }
+            else {
+                failed++;
+                out[ref] = { ok: false, error: r.error };
+            }
+        }
+        return text({
+            icons: out,
+            resolved,
+            failed,
+            usage: "For each icons[<ref>].svg, make a rectangle in that card's icon slot: copy the svg into BOTH responsive.desktop.config.svgMask AND responsive.mobile.config.svgMask, set styles.background to the icon color, and keep the box SQUARE (width === height) — without styles.background the masked icon is invisible, and a non-square box stretches it. For any ok:false ref, fall back to an emoji inline or skip — never leave a feature card iconless.",
+        });
+    });
     // 14) Upload images to Webcake -----------------------------------------------
     server.tool("upload_images", "Converts external image URLs (typically collected from ingest_html/ingest_url results), data: URIs, or LOCAL FILE PATHS from the user's computer into Webcake-hosted URLs (statics.pancake.vn) by reading/downloading each image and re-uploading it to the Webcake backend via multipart upload (200 MB backend limit). Use this whenever the page is built from a reference HTML/URL (BOTH intents — adapt AND clone), the user supplies their own image URLs, OR the user provides local image files from their machine — pass the path directly in `urls`; NEVER upload a user's local file to a third-party host (catbox, imgur, transfer.sh…) to obtain a URL first. The returned URLs go directly into specials.src — same as search_images results. Processes up to 20 entries per call in parallel, with a 200 MB per-image cap. No Webcake credentials required (the upload endpoint is public). UPLOADS BY DEFAULT (dry_run defaults to FALSE — unlike the page-persistence tools, this touches no account data, so the default is the real upload): the call downloads/reads each entry, uploads it, and returns the images map (original URL → hosted URL); WAIT for that map before assembling the page and never fall back to a placeholder for a slot whose upload succeeded. Pass dry_run:true only to preview what would be processed without any network/filesystem activity. Use search_images instead when you need stock photos. Local file paths are only permitted when the MCP server runs locally (stdio mode); on the remote HTTP transport they are rejected per-entry.", {
         urls: z

package/package.json

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