webcake-landing-mcp 1.5.2 → 1.5.4

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.5.4",
+    "d": "09/10/2026",
+    "type": "Added",
+    "en": "ingest_html and ingest_url now return font_groups (the page's self-hosted @font-face fonts, already shaped for settings.fontGroups) and…",
+    "vi": "ingest_html và ingest_url nay trả về font_groups (các font @font-face tự host của trang, đã đóng gói theo đúng dạng settings.fontGroups) và…"
+  },
+  {
+    "v": "1.5.3",
+    "d": "17/09/2026",
+    "type": "Added",
+    "en": "validate_page now detects inline base64 images (data:image/…;base64,… URIs) anywhere in an element's specials, a styles background, gallery…",
+    "vi": "validate_page nay phát hiện ảnh base64 nhúng (URI data:image/…;base64,…) ở bất kỳ đâu trong specials của phần tử, nền styles, gallery item.link,…"
+  },
   {
     "v": "1.5.2",
     "d": "25/08/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "publish_page now reuses the page's currently-attached domain when custom_domain is omitted — mirroring the editor's publish modal, a plain…",
     "vi": "publish_page nay tự động dùng lại domain đang gắn với trang khi bỏ trống custom_domain — giống cách modal publish của editor hoạt động, gọi…"
-  },
-  {
-    "v": "1.3.0",
-    "d": "17/07/2026",
-    "type": "Added",
-    "en": "upload_images and the automatic image re-hosting on create_page, update_page, add_section, and patch_page now file uploaded images into the…",
-    "vi": "upload_images và bước tự động re-host ảnh khi lưu trong create_page, update_page, add_section, patch_page nay lưu ảnh đã upload vào bộ sưu tập…"
-  },
-  {
-    "v": "1.2.1",
-    "d": "21/06/2026",
-    "type": "Changed",
-    "en": "Server instructions and get_generation_guide now restrict the visual-check step to three explicit triggers — cloning a reference to compare pixel…",
-    "vi": "Instruction của server và get_generation_guide nay giới hạn bước visual-check chỉ trong ba trường hợp cụ thể — clone trang tham chiếu để so sánh độ…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -114,7 +114,7 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 RULES
 - Visible content goes in "specials" (text-block.specials.text, image-block.specials.src…), NEVER in "styles".
 - Colors as rgba(r,g,b,a) — ALWAYS, and on BOTH breakpoints. The published page renders any CSS color, but the EDITOR does not read them all back: its color traits only parse the rgba() form, so a hex / rgb() / hsl() / named color shows BLACK in the trait panel and that black is SAVED the first moment a user touches the trait; and because the traits read one breakpoint at a time with no desktop→mobile fallback, a color set on only one breakpoint shows black on the other (and renders black there, since that breakpoint's CSS carries no color at all). The server repairs both slips on every save — it converts hex/rgb()/hsl()/named to rgba() and mirrors color/backgroundTxt/borderColor onto the breakpoint that lacks it — but write rgba() on both breakpoints yourself; what it cannot convert (var(--x), color-mix(…)) comes back as a warning. fontSize/borderWidth/top/left/width/height are NUMBERS (px) — always EMIT numbers. (Reading an existing page you may still meet strings: the editor saves fontSize as "59"/"13px", height as "600", opacity as "50%". The server normalizes those back to numbers on both get_page and save, so a hand-edited page is never locked out of the MCP; only a value with a unit the renderer cannot use — e.g. width:"100%" — is reported, as a warning.) borderRadius is a STRING with CSS units ("8px", "50%", "16px 16px 0 0") — a bare number or unit-less string is auto-coerced to px by the server, but write the unit explicitly to avoid surprises.
-- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). The save AUTO-HOSTS external image URLs: any real http(s) URL you put in specials.src / a url(...) background / gallery item.link / video poster gets downloaded and re-hosted to the Webcake CDN automatically on create_page/update_page/add_section/patch_page (the response's rehost field reports the count) — so reference and web image URLs do NOT need a pre-call to upload_images. SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image, canvas src/background) → put the REAL source URL straight into the slot and let the save host it; use those EXACT images, never swap them for stock photos, and carry the URL through un-altered (never drop it, never placeholder a slot that had a real source image). The ONE case you must call upload_images yourself FIRST: LOCAL FILE PATHS from the user's computer (pass the path directly in upload_images 'urls' — the save can't read local files; NEVER relay the user's local file through a third-party host like catbox or imgur), 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', 'modern office team') and put a returned URL into image-block specials.src. MATCH THE VARIANT TO THE SLOT SIZE — search_images returns a per-photo \`sizes\` map (delivered WxH per variant) + a \`size_guide\`; pick the variant whose width ≈ the element's RENDERED width (×1–2 for retina), then stop: full-bleed hero/banner (~900–1200px) → src.large (~940px) or src.large2x (~1880px); feature card/thumb (~260–360px) → src.medium (~350px); avatar/logo (~64–120px) → src.tiny (280px). NEVER stretch a small variant across a big slot — it pixelates ('vỡ ảnh'); NEVER put src.original (full-res, often several MB) or an oversized variant in a small card — it makes the page slow/heavy ('nặng trang'). If a photo's NATIVE width (photo.width) is smaller than the slot, pick a higher-res photo instead of upscaling. (avg_color helps pick a matching section background); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). NEVER leave src empty — it renders blank on the live page. The server automatically derives styles.background from specials.src on every expand (create/update/validate) using the editor's exact format: 'center center/ cover no-repeat scroll content-box url(<src>) border-box' — you do NOT need to set styles.background manually; if you do hand-write it, it must contain url(...). A SECTION background may layer a gradient overlay over an image: 'linear-gradient(...), center center/ cover no-repeat scroll content-box url(<src>) border-box' — the server canonicalises any url() layer into that exact editor shorthand on expand (other url() formats survive the first save but get mangled to 'undefined/ undefined/ …' the moment the page is edited in the Webcake editor). gallery.media = array of OBJECTS {type:'image', link:'<real-or-placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster image (real photo, else placeholder). Do NOT set a flat (no url()) styles.background on a video element — it suppresses the poster image.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). The save AUTO-HOSTS external image URLs: any real http(s) URL you put in specials.src / a url(...) background / gallery item.link / video poster gets downloaded and re-hosted to the Webcake CDN automatically on create_page/update_page/add_section/patch_page (the response's rehost field reports the count) — so reference and web image URLs do NOT need a pre-call to upload_images. SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image, canvas src/background) → put the REAL source URL straight into the slot and let the save host it; use those EXACT images, never swap them for stock photos, and carry the URL through un-altered (never drop it, never placeholder a slot that had a real source image). The ONE case you must call upload_images yourself FIRST: LOCAL FILE PATHS from the user's computer (pass the path directly in upload_images 'urls' — the save can't read local files; NEVER relay the user's local file through a third-party host like catbox or imgur), 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', 'modern office team') and put a returned URL into image-block specials.src. MATCH THE VARIANT TO THE SLOT SIZE — search_images returns a per-photo \`sizes\` map (delivered WxH per variant) + a \`size_guide\`; pick the variant whose width ≈ the element's RENDERED width (×1–2 for retina), then stop: full-bleed hero/banner (~900–1200px) → src.large (~940px) or src.large2x (~1880px); feature card/thumb (~260–360px) → src.medium (~350px); avatar/logo (~64–120px) → src.tiny (280px). NEVER stretch a small variant across a big slot — it pixelates ('vỡ ảnh'); NEVER put src.original (full-res, often several MB) or an oversized variant in a small card — it makes the page slow/heavy ('nặng trang'). If a photo's NATIVE width (photo.width) is smaller than the slot, pick a higher-res photo instead of upscaling. (avg_color helps pick a matching section background); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). NEVER leave src empty — it renders blank on the live page. BASE64: the save also handles inline 'data:image/...;base64,...' images — it decodes the payload and uploads it to the CDN like a remote URL, then rewrites the slot (specials.src, a url(...) background, gallery item.link, video img, settings favicon/og image), so base64 that arrives from a reference or a user paste needs NO manual fix and validate_page only warns about it. But do NOT AUTHOR base64 yourself: the image travels through the MCP connection inside your payload and megabytes there can drop it — put a real http(s) URL in the slot, or call upload_images (it accepts data: URIs) and use the returned statics.pancake.vn URL. Non-base64 data: URIs (data:image/svg+xml;utf8,<svg…>) are tiny and left alone. The server automatically derives styles.background from specials.src on every expand (create/update/validate) using the editor's exact format: 'center center/ cover no-repeat scroll content-box url(<src>) border-box' — you do NOT need to set styles.background manually; if you do hand-write it, it must contain url(...). A SECTION background may layer a gradient overlay over an image: 'linear-gradient(...), center center/ cover no-repeat scroll content-box url(<src>) border-box' — the server canonicalises any url() layer into that exact editor shorthand on expand (other url() formats survive the first save but get mangled to 'undefined/ undefined/ …' the moment the page is edited in the Webcake editor). gallery.media = array of OBJECTS {type:'image', link:'<real-or-placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster image (real photo, else placeholder). Do NOT set a flat (no url()) styles.background on a video element — it suppresses the poster image.
 - CONTRAST (check EVERY text element against the band it sits on, especially SATURATED / mid-tone bands like yellow, orange, teal, pink — there "light vs dark text" is not obvious, so decide by the band's luminance): light bands → near-black text (e.g. rgba(20,30,25,1)); dark bands → near-white text; a saturated/mid-tone band → whichever of near-black or near-white actually reads (for a bright yellow/amber band that means DARK text, not white/grey). NEVER use muted-grey, low-alpha (alpha < ~0.85), or near-white text on a colored band — that is exactly what makes labels look faded/sunken. Muted-grey is ONLY for secondary text on a white/very-light band. Icons and their captions follow the SAME rule as the text beside them.
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.
@@ -148,7 +148,7 @@ WORKFLOW (recommended)
 1. Call get_generation_guide (this) once, then new_page_skeleton for the top-level shape.
 2. For each element type you'll use, call get_element to learn its specials & see an example.
 3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
-3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image from the reference HTML/URL or a user-supplied URL → put that REAL URL straight into specials.src / gallery item.link and let the save auto-host it (no upload_images needed). For a user's LOCAL FILE PATH, upload_images it first (pass the path directly in upload_images 'urls'; NEVER relay the user's local file through a third-party host like catbox or imgur) and use the returned URL. Otherwise call search_images and put a returned URL into specials.src / gallery item.link. If search_images fails or has no fitting photo, find a real image yourself (web search/fetch) and put that URL in. Use placehold.co ONLY as the last resort when both search_images AND your own search failed. Never drop or placeholder a slot that had a real source image.
+3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image from the reference HTML/URL or a user-supplied URL → put that REAL URL straight into specials.src / gallery item.link and let the save auto-host it (no upload_images needed). For a user's LOCAL FILE PATH, upload_images it first (pass the path directly in upload_images 'urls'; NEVER relay the user's local file through a third-party host like catbox or imgur) and use the returned URL. Otherwise call search_images and put a returned URL into specials.src / gallery item.link. If search_images fails or has no fitting photo, find a real image yourself (web search/fetch) and put that URL in. Use placehold.co ONLY as the last resort when both search_images AND your own search failed. Never drop or placeholder a slot that had a real source image. Never write a base64 data: URI into a slot yourself (it ships the whole image through the connection) — use a real URL or upload_images; a base64 URI that came in from the reference is fine to leave, the save uploads it.
 4. Assemble { page, popup, settings, options, cartConfigs }.
 5. Call validate_page and fix every error AND every warning — warnings are visible defects (text spilling onto the element below, off-canvas boxes, empty bands at a section's bottom, missing field_name, dead event targets), not advisory polish. Re-validate until the warning list is empty; only a demonstrably false positive may remain (tell the user which and why).
 6. To save: call list_organizations. If the account has EXACTLY ONE organization, create_page will auto-select it — no need to ask. If there are MULTIPLE organizations, show them to the user and ask which to use (highlight is_default as the suggested default); pass the chosen organization_id to create_page. If the user explicitly wants to save without any organization, pass organization_id:"personal". Then create_page (dry_run first, then dry_run:false). Note: create_page itself enforces this — it refuses to guess between multiple orgs and returns the org list asking you to pick.
@@ -167,4 +167,5 @@ REFERENCE INPUT (HTML page to clone or adapt)
 - SECTION HEIGHTS: every AST section carries size_hint = { height, basis, css? } — the section's desktop height on the 960px canvas (basis:'css' = an explicit height/min-height found in the source, css holds the raw value e.g. "100vh"; basis:'estimate' = content-volume math). Set each rebuilt section's desktop height FROM its size_hint (±15% to fit your actual element placement) instead of the 800px default, so the page's vertical rhythm tracks the source: a 72px header stays a slim bar, a 1200px pricing band stays tall. Mobile is NOT hinted — redo the height per the mobile text math (stacked content is taller).
 - Map AST section roles to Webcake elements: hero → section (background image/overlay) + text-block H1 + text-block subheading + button; features → group per card (icon rectangle + text-block title + text-block body); stats bar → group with text-block per stat; pricing → group with text-block list + button; footer → section (dark bg) + text-block + links. When the ingested page contains a composite widget (phone/device mockup, chat thread, mini dashboard, browser frame) → rebuild it as ONE html-box, NOT as element soup. The full AST hands you the SOURCE for this: section.widgets = [{ hint, html, css? }] — the widget's cleaned outerHTML plus the stylesheet rules that style it. Build the html-box FROM that html verbatim: inline each css rule into the matching elements' style="" attributes (an html-box has no <style> scope), wrap in a root div with width:100%;height:100%;box-sizing:border-box;overflow:hidden, and size the html-box to the widget's box — do NOT re-imagine the widget's markup from the summary fields.
 - Reference images are the user's assets — for BOTH intents (adapt AND clone), carry every real image URL found in the AST (images, background_images, og_image, canvas src/background) straight into the matching slot; the save auto-hosts it to the Webcake CDN (no upload_images needed, no hotlinking), so never replace it with a search_images stock photo or a placeholder. intent='adapt' rewrites TEXT for the user's brand, not the imagery; search_images only fills slots that have no source image.
+- FONTS + TYPE SCALE (clone/adapt): the AST's \`font_groups\` are the page's SELF-HOSTED fonts (from its @font-face rules — the platform doesn't have them). Put them into settings.fontGroups VERBATIM and set each text element's styles.fontFamily to "'<group name>', sans-serif" (fontGeneral too when it's the body font); keep the original file URLs — every save downloads them, uploads them to the media collection and files the group into the org's Font Groups (the result's \`fonts\` report), so never skip or substitute the font. Families NOT in font_groups are Google fonts and load by name. Each section's \`text_styles\` {heading, body, cta} and the page-level \`typography\` are the source's COMPUTED type (cascade, @media, var(), clamp(), Tailwind classes): set desktop styles.fontSize = font_size, mobile styles.fontSize = mobile_font_size (else font_size, shrunk only if the mobile text math needs it), and fontWeight/fontFamily/lineHeight/letterSpacing EXACTLY — never eyeball a size the AST already gives. Any fontWeight works (500/600/800 included): the save adds the Google weight links the build would otherwise skip. An absolute-canvas \`source\` already carries all of this. For ingest_html of HTML copied from a live site, pass base_url so external stylesheets (and their fonts) are read. Custom font files belong to the source site's license — clone fonts only for pages the user owns or is allowed to copy; for a third-party ADAPT, prefer the nearest Google family over its font_groups.
 - VERIFY THE CLONE VISUALLY (clones only — where fidelity is the whole point): for a clone/adapt build, do the VISUAL CHECK from BUILDING step 7 ONCE — screenshot the rendered preview with your own browser/screenshot capability (or render_preview as fallback), compare it side-by-side with the reference (screenshot the reference URL too if you only have HTML), patch_page the clear mismatches, and re-check ONLY if you changed something material (don't loop reflexively). For a NON-clone page, validate_page + the save-time auto-fix are the gate — skip the screenshot unless the user asks or you have a specific aesthetic doubt. Eyeballing a reference and rebuilding once typically lands ~60% similar; a targeted look-and-patch pass closes the gap when fidelity matters.`;

package/dist/domains/landing/index.js

@@ -369,15 +369,25 @@ function normalizeEditorValues(node) {
             normalizeEditorValues(child);
     }
 }
-/** settings.width_section carries the canvas width the coords live in — keep it numeric. */
+/**
+ * settings.width_section carries the canvas width the coords live in — keep it
+ * numeric, and default it (960/420) when absent: the build host reads
+ * `settings.width_section.mobile` unguarded, so a hand-written settings object
+ * without it saves fine but crashes every publish.
+ */
 function normalizeSettings(source) {
-    const ws = source?.settings?.width_section;
-    if (!ws || typeof ws !== "object")
+    const settings = source?.settings;
+    if (!settings || typeof settings !== "object")
         return;
+    if (!settings.width_section || typeof settings.width_section !== "object")
+        settings.width_section = {};
+    const ws = settings.width_section;
     for (const bp of ["desktop", "mobile"]) {
         if (ws[bp] !== undefined)
             ws[bp] = numFromEditorString(ws[bp]);
     }
+    ws.desktop ??= CANVAS.desktopWidth;
+    ws.mobile ??= CANVAS.mobileWidth;
 }
 /** Apply all post-expand normalizations to every node in a page source. */
 function normalizeSource(source) {

package/dist/domains/landing/instructions.js

@@ -38,7 +38,7 @@ MODEL (essentials):
 - PREMIUM CRAFT (read "sang"): generous whitespace (don't cram; ~48–72px above each band's first element, ≥16–24px between elements); clear type scale (H1 40–56 / body 16–18, big jump); ONE accent used sparingly + neutrals; snap spacing to an 8px grid; reuse the same content width / margin / card+button radius across sections.
 - STICKY HEADER: a sticky/fixed header (config.sticky) OVERLAYS the page — it does NOT push sections below it down. Offset the first section's top content DOWN by the header height (~60–72px) so nothing hides behind it, and do NOT duplicate the shop name in both the header and the top of the hero. A non-sticky header stacks normally and needs no offset.
 - 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 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. WHERE THEY LAND: with credentials AND the settled org, every image is filed into THAT ORG's MEDIA COLLECTION (bộ sưu tập) — the same library the editor's media picker reads — so the user can re-pick it later; rehost.collection:true (and images[x].collection:true from upload_images) confirms it. This is why the org must be settled before any image work (see ORGANIZATION FIRST). With no credentials the image goes to the public CDN instead — the URL works and the page renders, but it is absent from every collection (collection:false); that is a server-setup issue to report, not something to fix by hand-uploading elsewhere. 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.
+- 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 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. WHERE THEY LAND: with credentials AND the settled org, every image is filed into THAT ORG's MEDIA COLLECTION (bộ sưu tập) — the same library the editor's media picker reads — so the user can re-pick it later; rehost.collection:true (and images[x].collection:true from upload_images) confirms it. This is why the org must be settled before any image work (see ORGANIZATION FIRST). With no credentials the image goes to the public CDN instead — the URL works and the page renders, but it is absent from every collection (collection:false); that is a server-setup issue to report, not something to fix by hand-uploading elsewhere. 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). DON'T AUTHOR BASE64 IMAGES. A 'data:image/...;base64,...' URI never reaches the stored source — the save DECODES it and uploads it to the CDN like any other image (it counts in the rehost report), and validate_page only WARNS, so a base64 URI that came in from a reference/user paste needs no manual fix: just save. What you must not do is EMIT base64 yourself: the whole image travels through this connection inside your payload, and megabytes there can drop it. Put a real http(s) URL in the slot, or call upload_images (it accepts data: URIs) and use the returned statics.pancake.vn URL. 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. SAFETY (custom is raw + global → sloppy custom BREAKS the whole UI): SCOPE every extra_css rule to "#w-<id>" or a specials.custom_class — NEVER a bare tag / "*" / a Webcake-internal class (.section-container/.rectangle-css/.text-block-css/.group-*…); keep custom_css to VISUAL props only (no position/top/left/width/height/display/float); close every bhet/bbet tag; don't restructure "#w-…" elements in extra_script. validate_page flags unscoped selectors, layout props in custom_css, unbalanced braces/tags, missing customAdvance, and CSS/JS in the wrong field — fix every such warning.
 - 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.

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

@@ -44,6 +44,7 @@
         "favicon": { "type": "string" },
         "thumbnail": { "type": "string", "description": "Social/share thumbnail URL." },
         "fontGeneral": { "type": "string", "description": "Default page font-family, e.g. \"'Roboto', sans-serif\"." },
+        "fontGroups": { "type": "array", "description": "Custom (non-Google) fonts the build renders as @font-face: [{ name: <CSS family elements use in styles.fontFamily>, fonts: [{ name: <file name WITH extension — the format is sniffed from it>, url, font_weight: thin|light|normal|medium|semibold|bold|extrabold|black, font_style: normal|italic }] }]. External font URLs are uploaded to the media collection on save.", "items": { "type": "object" } },
         "width_section": {
           "type": "object",
           "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.",

package/dist/domains/landing/validate.js

@@ -126,6 +126,49 @@ function isVividColor(v) {
         return false; // fully transparent
     return Math.max(r, g, b) - Math.min(r, g, b) >= 16; // channel spread ⇒ has hue
 }
+// ── inline base64 image data (never STORED — auto-uploaded on save) ─────────
+// A `data:image/…;base64,…` URI must not end up in a saved page source: the bytes
+// would stay embedded forever, and that JSON is re-read and re-written on every
+// later get_page / update_page / patch_page. The save no longer just refuses it —
+// the rehost pass DECODES the payload and uploads it to the CDN like any remote
+// image (rehost.ts `parseInlineBase64Image` → webcake-client `fetchAndHostOne`),
+// then rewrites the URI in-tree. So this is a WARNING, not an error: blocking here
+// would stop the very save that fixes it. What it still tells the model is "do not
+// AUTHOR base64" — the payload travels through the MCP link before the server can
+// do anything about it, and megabytes there can drop the connection.
+// Matches the URI's header only (`data:image/png;base64,`), so it never fires on
+// bare base64 payloads that are not images (e.g. spin-wheel prize lists) nor on
+// non-base64 data: URIs (`data:image/svg+xml;utf8,<svg…>` — tiny, inline by design).
+const BASE64_IMAGE_RE = /data:image\/[a-z0-9.+-]+\s*;(?:[^,;]*;)*\s*base64\s*,/i;
+/** Key-path of the first string under `value` carrying inline base64 image data (undefined if none). */
+function findBase64Image(value, path) {
+    if (typeof value === "string")
+        return BASE64_IMAGE_RE.test(value) ? path : undefined;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const hit = findBase64Image(value[i], `${path}[${i}]`);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    }
+    if (value && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            const hit = findBase64Image(v, `${path}.${k}`);
+            if (hit)
+                return hit;
+        }
+    }
+    return undefined;
+}
+/** The inline-base64-image notice, worded the same everywhere it is reported. */
+function base64ImageNotice(where) {
+    return (`${where} carries an INLINE BASE64 IMAGE (data:image/…;base64,…). The save uploads it to the Webcake CDN and rewrites the URL ` +
+        `in-tree (it counts in the response's rehost report), so NO manual fix is needed and base64 never reaches the stored source. ` +
+        `But do not AUTHOR base64: the whole image travels through this connection in your payload (megabytes can drop it). Put a real ` +
+        `http(s) image URL in ${where} — the save hosts that too — or call upload_images (it accepts data: URIs) and use the returned ` +
+        `statics.pancake.vn URL. If the upload fails (no credentials/network), the data: URI stays and the page keeps the bloat.`);
+}
 /** Accept an object or a JSON string. Returns the parsed page or throws. */
 export function coercePage(input) {
     if (typeof input === "string")
@@ -329,6 +372,21 @@ export function validatePage(input) {
                 }
             }
         }
+        // inline base64 image data anywhere on this element (specials.src, a
+        // url(data:…) background, gallery item.link, video poster, config.svgMask…).
+        // Scans the whole node except `children` (walked on its own turn).
+        {
+            let hit;
+            for (const [k, v] of Object.entries(node)) {
+                if (k === "children")
+                    continue;
+                hit = findBase64Image(v, k);
+                if (hit)
+                    break;
+            }
+            if (hit)
+                warnings.push(`${path} (${type}): ${base64ImageNotice(hit)}`);
+        }
         // 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)
@@ -1198,6 +1256,14 @@ export function validatePage(input) {
             }
         }
     }
+    // ── inline base64 image data in page settings ───────────────────────────────
+    // Same rule as on elements: favicon / og image / a url(data:…;base64,…) inside
+    // settings.extra_css / bhet / bbet are auto-uploaded by the save's rehost pass.
+    {
+        const hit = findBase64Image(page?.settings, "settings");
+        if (hit)
+            warnings.push(base64ImageNotice(hit));
+    }
     return {
         valid: errors.length === 0,
         errors,

package/dist/persistence/html-ingest.js

@@ -16,8 +16,10 @@
 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, detectHoverEffects, brandHints } from "./ingest/semantic.js";
+import { findSections, classifySection, computeSizeHint, detectWidgets, detectHoverEffects, brandHints, pickHeading } from "./ingest/semantic.js";
 import { parseAbsoluteCanvas, canvasRoleSections, stripCdnSizePrefix } from "./ingest/canvas.js";
+import { extractFontFaces, toFontGroups, extractTypography, parseCssRules, makeTypeResolver, resolveCssVars, rootFontPx, stripComments } from "./ingest/fonts.js";
+import { isAllowedScreenshotUrl } from "./screenshot-playwright.js";
 // Re-export the public surface so existing imports of "./persistence/html-ingest.js"
 // (parseHtml, fetchHtml, and the IngestedAst/IngestedCanvas/CanvasElement/CanvasSection
 // types) keep resolving unchanged.
@@ -26,6 +28,7 @@ export * from "./ingest/stylesheets.js";
 export * from "./ingest/tailwind.js";
 export * from "./ingest/semantic.js";
 export * from "./ingest/canvas.js";
+export * from "./ingest/fonts.js";
 const FETCH_TIMEOUT_MS = 10_000;
 const MAX_HTML_BYTES = 2_000_000; // 2MB
 const FULL_SIZE_CAP = 25_000; // ~25 KB serialized cap for full mode
@@ -44,6 +47,12 @@ export function parseHtml(html, detail = "compact", opts = {}) {
     const styleBlocks = extractStyleBlocks(html);
     const googleFonts = extractGoogleFonts(html);
     const tw = extractTailwindConfig(html);
+    const cssSources = orderedCss(html, opts.baseUrl, opts.extraCss ?? []);
+    const fontGroups = toFontGroups(extractFontFaces(cssSources));
+    const cssRules = resolveCssVars(cssSources.flatMap((c) => parseCssRules(c.css)));
+    const remPx = rootFontPx(cssRules);
+    const typography = extractTypography(cssRules, remPx);
+    const fontFields = { ...(fontGroups.length ? { font_groups: fontGroups } : {}), ...(typography ? { typography } : {}) };
     const root = parse(html, { lowerCaseTagName: true });
     const head = root.querySelector("head");
     const title = head?.querySelector("title")?.text?.trim() || undefined;
@@ -74,6 +83,7 @@ export function parseHtml(html, detail = "compact", opts = {}) {
             palette: hints.palette,
             design_tokens: hints.design_tokens,
             background_images: bg.length ? bg : undefined,
+            ...fontFields,
             warnings: warnings.length ? warnings : undefined,
         };
     }
@@ -91,10 +101,22 @@ export function parseHtml(html, detail = "compact", opts = {}) {
             ],
         };
     }
+    // Computed type per text role, so a hand-rebuild copies exact sizes/weights.
+    const resolveType = makeTypeResolver(cssRules, tw ?? undefined, remPx);
+    const textStyles = (el) => {
+        const heading = resolveType(pickHeading(el));
+        const bodyText = resolveType(el.querySelector("p") ?? undefined);
+        const cta = resolveType(el.querySelector("button") ?? el.querySelector('a[class*="btn"], a[class*="button"]') ?? undefined);
+        const out = { ...(heading ? { heading } : {}), ...(bodyText ? { body: bodyText } : {}), ...(cta ? { cta } : {}) };
+        return Object.keys(out).length ? out : undefined;
+    };
     const sectionEls = findSections(body);
     const sections = sectionEls.map((el) => {
         const sec = classifySection(el, detail);
         sec.size_hint = computeSizeHint(el, sec, styleBlocks);
+        const styles = textStyles(el);
+        if (styles)
+            sec.text_styles = styles;
         const hover = detectHoverEffects(el);
         if (hover.length)
             sec.hover_effects = hover;
@@ -122,6 +144,7 @@ export function parseHtml(html, detail = "compact", opts = {}) {
         // 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,
+        ...fontFields,
         warnings: warnings.length ? warnings : undefined,
     };
     if (detail !== "full")
@@ -185,25 +208,11 @@ export async function fetchHtml(url, opts = {}) {
         if (!/html|xml|text/i.test(ctype)) {
             return { ok: false, status: res.status, error: `Content-Type ${ctype} is not HTML` };
         }
-        const reader = res.body?.getReader();
-        if (!reader)
+        const buf = await readCapped(res, MAX_HTML_BYTES);
+        if (buf === "too-large")
+            return { ok: false, status: res.status, error: `Response exceeded ${MAX_HTML_BYTES} bytes` };
+        if (!buf)
             return { ok: false, status: res.status, error: "no response body" };
-        const chunks = [];
-        let total = 0;
-        while (true) {
-            const { value, done } = await reader.read();
-            if (done)
-                break;
-            if (!value)
-                continue;
-            total += value.length;
-            if (total > MAX_HTML_BYTES) {
-                await reader.cancel().catch(() => { });
-                return { ok: false, status: res.status, error: `Response exceeded ${MAX_HTML_BYTES} bytes` };
-            }
-            chunks.push(value);
-        }
-        const buf = Buffer.concat(chunks.map((c) => Buffer.from(c)));
         return { ok: true, status: res.status, html: buf.toString("utf-8") };
     }
     catch (e) {
@@ -213,3 +222,192 @@ export async function fetchHtml(url, opts = {}) {
         clearTimeout(timer);
     }
 }
+/** Stream a response body, giving up past `max` bytes (never buffers an unbounded body). */
+async function readCapped(res, max) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return null;
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        total += value.length;
+        if (total > max) {
+            await reader.cancel().catch(() => { });
+            return "too-large";
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}
+const MAX_STYLESHEETS = 12;
+const MAX_CSS_BYTES = 1_000_000;
+const MAX_REDIRECTS = 3;
+/** One attribute of a raw tag (quoted or bare); `data-href` never matches `href`. */
+function tagAttr(tag, name) {
+    const m = new RegExp(`[\\s"']${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, "i").exec(tag);
+    return m ? (m[1] ?? m[2] ?? m[3]) : undefined;
+}
+/**
+ * The page's stylesheet sources in DOCUMENT order (the cascade order): each
+ * `<link rel=stylesheet>` (or `rel=preload as=style`, the async-CSS pattern) by
+ * href, each `<style>` by index. Print-only links are dropped.
+ */
+export function stylesheetTags(html) {
+    const out = [];
+    let styleIndex = 0;
+    for (const m of html.matchAll(/<link\b[^>]*>|<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
+        if (m[0][1].toLowerCase() === "s") {
+            out.push({ kind: "style", index: styleIndex++, css: m[1] ?? "" });
+            continue;
+        }
+        const rel = (tagAttr(m[0], "rel") ?? "").toLowerCase();
+        const isCss = /\bstylesheet\b/.test(rel) || (/\bpreload\b/.test(rel) && (tagAttr(m[0], "as") ?? "").toLowerCase() === "style");
+        const media = (tagAttr(m[0], "media") ?? "").toLowerCase();
+        const href = tagAttr(m[0], "href");
+        if (isCss && href && !(media.includes("print") && !media.includes("screen")))
+            out.push({ kind: "link", href: href.replace(/&amp;/g, "&") });
+    }
+    return out;
+}
+/** `@import url(x)` / `@import "x"` targets of a CSS text (comments stripped; print-only imports skipped). */
+function cssImports(css) {
+    const out = [];
+    for (const m of stripComments(css).matchAll(/@import\s+(?:url\(\s*)?["']?([^"')\s;]+)["']?\s*\)?([^;]*);/gi)) {
+        if (!/\bprint\b/i.test(m[2]) || /\bscreen\b/i.test(m[2]))
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * GET a stylesheet the crawled page pointed us at — that URL is chosen by a
+ * third-party page, so: http(s) only, no private/loopback/link-local host (SSRF;
+ * same policy + RENDER_ALLOW_PRIVATE opt-out as the screenshot route), redirects
+ * followed MANUALLY so each hop is re-checked, CSS/text content-type only, and the
+ * body streamed with a byte cap.
+ */
+async function fetchCss(url) {
+    let target = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (!isAllowedScreenshotUrl(target).ok)
+            return null;
+        let res;
+        try {
+            res = await fetch(target, {
+                redirect: "manual",
+                signal: AbortSignal.timeout(8_000),
+                headers: { "User-Agent": "Mozilla/5.0 (compatible; webcake-landing-mcp/ingest_url)", Accept: "text/css,*/*;q=0.1" },
+            });
+        }
+        catch {
+            return null;
+        }
+        if (res.status >= 300 && res.status < 400) {
+            const loc = res.headers.get("location");
+            if (!loc)
+                return null;
+            try {
+                target = new URL(loc, target).href;
+            }
+            catch {
+                return null;
+            }
+            continue;
+        }
+        const ctype = (res.headers.get("content-type") ?? "").toLowerCase();
+        if (!res.ok || (ctype && !/css|text\/plain|octet-stream/.test(ctype)))
+            return null;
+        try {
+            const buf = await readCapped(res, MAX_CSS_BYTES);
+            return buf && buf !== "too-large" ? buf.toString("utf-8") : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Fetch the page's external stylesheets — and what they (or inline <style> blocks)
+ * `@import`, two levels deep — so `@font-face` + type rules outside the HTML are
+ * seen. Each owner's list is ordered imports-first, like the cascade. Google Fonts
+ * CSS is skipped (those families load by name). Best-effort: a failed sheet is skipped.
+ */
+export async function fetchStylesheets(html, pageUrl) {
+    const seen = new Set();
+    const claim = (href, base) => {
+        if (/fonts\.googleapis\.com/i.test(href) || seen.size >= MAX_STYLESHEETS)
+            return undefined;
+        try {
+            const abs = new URL(href, base).href;
+            if (!/^https?:/i.test(abs) || seen.has(abs))
+                return undefined;
+            seen.add(abs);
+            return abs;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // One sheet → [its imports' sheets (recursively, in order)…, itself].
+    const load = async (abs, owner, depth) => {
+        const css = await fetchCss(abs);
+        if (css === null)
+            return [];
+        const imports = depth < 2 ? cssImports(css).map((h) => claim(h, abs)).filter((h) => !!h) : [];
+        const nested = await Promise.all(imports.map((h) => load(h, owner, depth + 1)));
+        return [...nested.flat(), { owner, css, base: abs }];
+    };
+    const jobs = [];
+    for (const t of stylesheetTags(html)) {
+        if (t.kind === "link") {
+            const abs = claim(t.href, pageUrl);
+            if (abs)
+                jobs.push(load(abs, abs, 0));
+        }
+        else {
+            for (const h of cssImports(t.css)) {
+                const abs = claim(h, pageUrl);
+                if (abs)
+                    jobs.push(load(abs, `style:${t.index}`, 1));
+            }
+        }
+    }
+    return (await Promise.all(jobs)).flat();
+}
+/**
+ * All CSS of the page in cascade (document) order: for each <link> its fetched
+ * sheets, for each <style> its fetched @imports then the block itself; anything
+ * fetched but unplaced goes last.
+ */
+function orderedCss(html, baseUrl, extra) {
+    const out = [];
+    const used = new Set();
+    const take = (owner) => {
+        for (const e of extra)
+            if (e.owner === owner && !used.has(e)) {
+                used.add(e);
+                out.push(e);
+            }
+    };
+    for (const t of stylesheetTags(html)) {
+        if (t.kind === "link") {
+            try {
+                take(new URL(t.href, baseUrl).href);
+            }
+            catch { /* relative href without a base (ingest_html) */ }
+        }
+        else {
+            take(`style:${t.index}`);
+            out.push({ css: t.css, base: baseUrl });
+        }
+    }
+    for (const e of extra)
+        if (!used.has(e))
+            out.push(e);
+    return out;
+}