webcake-landing-mcp 1.2.0 → 1.2.1

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "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 độ…"
+  },
   {
     "v": "1.2.0",
     "d": "21/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "render_preview now accepts a tiles parameter: pass tiles:true to receive the page as a stack of top-to-bottom horizontal band images instead of one…",
     "vi": "render_preview nay nhận tham số tiles: truyền tiles:true để nhận trang dưới dạng stack các ảnh dải ngang từ trên xuống dưới thay vì một ảnh…"
-  },
-  {
-    "v": "1.0.81",
-    "d": "16/06/2026",
-    "type": "Changed",
-    "en": "The Playwright screenshot engine that backs render_preview's GET /api/render/screenshot route now defaults to JPEG output instead of PNG, reducing…",
-    "vi": "Engine chụp màn hình Playwright phục vụ route GET /api/render/screenshot của render_preview nay mặc định xuất ảnh JPEG thay vì PNG, giúp giảm kích…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -152,7 +152,7 @@ WORKFLOW (recommended)
 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.
-7. VISUAL CHECK — do this whenever you built from a reference (clone/adapt) or fidelity matters: after create_page auto-publishes (or after publish_page), actually LOOK at the rendered page and compare it to the reference, then fix what's off. SCREENSHOT IT WITH YOUR OWN CAPABILITY FIRST: if you have a browser/screenshot MCP (e.g. chrome-devtools) or any tool that can capture a URL, screenshot the returned preview_url yourself — it's fresh and unlimited. ONLY if you have no such ability, call render_preview(page_id) (returns a PNG; on a quota/rate-limit it returns ok:false → SKIP the visual check that round, don't fail the build). Put your shot next to the reference and compare section order, colors, spacing, image placement, sizing and text; for EACH mismatch, patch_page the offending element by id, re-publish (publish_page), and screenshot again — loop 2–3 rounds until it matches. The no-domain preview only renders for ~10 min after the last publish, so screenshot promptly and re-publish before re-checking a stale page.
+7. VISUAL CHECK (only when it earns its cost) — a screenshot is token-heavy and adds a round-trip, so do NOT screenshot by default: validate_page (errors + warnings) and the save-time auto-fix already catch the mechanical defects (off-canvas, wrapped-text overlap, contrast, missing data) for free. Screenshot ONLY when validation can't judge what you need: (a) you built from a REFERENCE and need to compare fidelity, (b) the USER asks to see/verify the look, or (c) a specific AESTHETIC doubt (color/imagery/composition). When you do: screenshot with YOUR OWN capability first — a browser/screenshot MCP (e.g. chrome-devtools) or any URL-capture tool (fresh + unlimited); only if you have none, call render_preview(page_id) (PNG; on a quota/rate-limit it returns ok:false → SKIP that round, don't fail the build). Take ONE shot, patch_page only the clear mismatches by id, re-publish (publish_page), and re-shoot ONLY if you changed something material — don't reflexively loop 2–3 rounds. For a clone, put your shot next to the reference (screenshot the reference URL too when you only have HTML) and compare section order, colors, spacing, image placement, sizing and text. The no-domain preview only renders for ~10 min after the last publish, so screenshot promptly and re-publish before re-checking a stale page.
 
 EDITING an existing page
 - find_pages / list_pages → let the user pick (or take a page_id from a URL).
@@ -167,4 +167,4 @@ 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.
-- VERIFY THE CLONE VISUALLY (don't trust the build blind): after saving, do the VISUAL CHECK from BUILDING step 7 — screenshot the rendered preview with your own browser/screenshot capability (or render_preview as fallback) and compare it side-by-side with the reference (screenshot the reference URL too if you only have HTML), then patch_page the elements that don't match and re-check. Eyeballing a reference and rebuilding once typically lands ~60% similar; the look-and-patch loop is what closes the gap.`;
+- 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/instructions.js

@@ -41,6 +41,6 @@ MODEL (essentials):
 
 - 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.
-- VISUAL CHECK after saving (do it for every clone/reference build, and whenever the look matters): don't trust the build blind — LOOK at the rendered page and fix what's off. SCREENSHOT IT WITH YOUR OWN CAPABILITY FIRST — if you have a browser/screenshot MCP (e.g. chrome-devtools) or any tool that captures a URL, screenshot the returned preview_url yourself (fresh + unlimited); ONLY if you have none, call render_preview(page_id), which returns a PNG (on a quota/429 it returns ok:false → skip the check that round, never fail the build). Compare your shot to the reference (screenshot the reference URL too when you only have HTML) — section order, colors, spacing, image placement, sizing, text — then patch_page each mismatch by id, re-publish (publish_page), and screenshot again; loop 2–3 rounds. Rebuilding once from a glance lands ~60% similar — the look-and-patch loop is what closes the gap. The no-domain preview only renders ~10 min after the last publish, so shoot promptly and re-publish before re-checking.
+- VISUAL CHECK — a screenshot costs tokens + a round-trip, so by DEFAULT do NOT screenshot. validate_page (errors + warnings) and the save-time auto-fix already catch the mechanical defects (off-canvas, wrapped-text overlap, contrast, missing data) token-free — trust them. Screenshot ONLY when it adds something validation can't: (a) you're CLONING a reference and need to compare pixel fidelity, (b) the USER asks to see/verify the look, or (c) you have a specific AESTHETIC doubt (color/imagery/composition) text-validation can't judge. When you do: SCREENSHOT WITH YOUR OWN CAPABILITY FIRST — a browser/screenshot MCP (e.g. chrome-devtools) or any URL-capture tool (fresh + unlimited); only if you have none, call render_preview(page_id) (PNG; on a quota/429 it returns ok:false → skip that round, never fail the build). Take ONE shot, patch_page only the clear mismatches by id, re-publish (publish_page), and re-shoot ONLY if you changed something material — do NOT reflexively loop 2–3 times. For a clone, compare to the reference (screenshot the reference URL too when you only have HTML) — section order, colors, spacing, image placement, sizing, text. The no-domain preview only renders ~10 min after the last publish, so shoot promptly and re-publish before re-checking.
 
 Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, layout, search_images, get_icon_svg, upload_images, render_preview, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;

package/package.json

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