webcake-landing-mcp 1.0.21 → 1.0.22

package/README.md

@@ -221,7 +221,8 @@ lands in logs). Any header that's missing falls back to the matching env var:
 | `x-webcake-env` | `WEBCAKE_ENV` | named environment (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | default org |
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | overrides the env preset's API base |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's app base |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's SPA base (login connect page) |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor/preview links |
 
 > The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need **no
 > token** — only the persistence tools (`create_page`, `update_page`, …) use it. Without a JWT, those return
@@ -290,7 +291,8 @@ flow can also be done entirely in the SPA, no backend route needed.)
 | `WEBCAKE_API_BASE` | No* | Backend base URL, e.g. `http://localhost:5800`. Required to persist (or set `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | No* | Account JWT (dashboard auth). Required to persist — expires, refresh when needed. |
 | `WEBCAKE_ORG_ID` | No | Default organization id for `create_page` (overridden by its `organization_id` arg). Omit → personal page. |
-| `WEBCAKE_APP_BASE` | No | Optional base used to build editor/preview URLs in the result. |
+| `WEBCAKE_APP_BASE` | No | Optional SPA base — used for the browser `login` connect page. |
+| `WEBCAKE_BUILDER_BASE` | No | Optional builder host for the editor/preview links in the result. Defaults to the env preset, else derived from the API host (`api.x`→`builder.x`). |
 | `WEBCAKE_CONFIG_DIR` | No | Dir for the saved `auth.json` written by `login` (default `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` and `WEBCAKE_JWT` are only needed for the persistence tools. The reference and
@@ -304,11 +306,13 @@ flow can also be done entirely in the SPA, no backend route needed.)
 Instead of setting both base URLs by hand, pick a named environment — one source of
 truth for the API + app bases:
 
-| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
-|-------------------------|-------------------------------|-------------------------------|
-| `local` | `http://localhost:5800` | `http://localhost:5173` |
-| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
-| `prod` | `https://api.webcake.io` | `https://webcake.io` |
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) | Builder base (`WEBCAKE_BUILDER_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|----------------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` | `http://builder.localhost:5800` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` | `https://builder.staging.webcake.io` |
+| `prod` | `https://api.webcake.io` | `https://webcake.io` | `https://builder.webcake.io` |
+
+> The **editor/preview link** returned after `create_page`/`update_page` opens on the **builder host** (above), not the API or SPA base.
 
 ```bash
 npx -y webcake-landing-mcp login --env local       # connect against your local SPA + API

package/README.vi.md

@@ -221,7 +221,8 @@ Header nào thiếu sẽ fallback về biến env tương ứng:
 | `x-webcake-env` | `WEBCAKE_ENV` | môi trường có tên (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | org mặc định |
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | ghi đè API base của preset |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | ghi đè app base của preset |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | ghi đè SPA base của preset (trang connect khi `login`) |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | ghi đè host builder dùng cho link editor/preview |
 
 > Tool tham chiếu + generation (`get_generation_guide`, `list_elements`, `validate_page`, …) **không cần
 > token** — chỉ tool lưu trữ (`create_page`, `update_page`, …) mới dùng. Không có JWT thì các tool đó trả
@@ -285,7 +286,8 @@ SPA cũng được, khỏi cần route backend.)
 | `WEBCAKE_API_BASE` | Không* | Base URL backend, ví dụ `http://localhost:5800`. Cần để lưu trang (hoặc đặt `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | Không* | JWT tài khoản (auth dashboard). Cần để lưu trang — sẽ hết hạn, làm mới khi cần. |
 | `WEBCAKE_ORG_ID` | Không | Organization mặc định cho `create_page` (bị ghi đè bởi tham số `organization_id`). Bỏ trống → trang cá nhân. |
-| `WEBCAKE_APP_BASE` | Không | Base tuỳ chọn để dựng URL editor/preview trong kết quả. |
+| `WEBCAKE_APP_BASE` | Không | SPA base tuỳ chọn — dùng cho trang connect khi `login` qua trình duyệt. |
+| `WEBCAKE_BUILDER_BASE` | Không | Host builder tuỳ chọn cho link editor/preview trong kết quả. Mặc định lấy theo preset môi trường, nếu không thì suy ra từ host API (`api.x`→`builder.x`). |
 | `WEBCAKE_CONFIG_DIR` | Không | Thư mục chứa `auth.json` do `login` ghi (mặc định `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` và `WEBCAKE_JWT` chỉ cần cho các tool lưu trữ. Các tool tham chiếu và kiểm tra
@@ -299,11 +301,13 @@ SPA cũng được, khỏi cần route backend.)
 Thay vì đặt thủ công cả hai base URL, hãy chọn một môi trường có tên — một nguồn sự thật duy nhất
 cho API + app base (mặc định là `prod`):
 
-| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
-|-------------------------|-------------------------------|-------------------------------|
-| `local` | `http://localhost:5800` | `http://localhost:5173` |
-| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
-| `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` |
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) | Builder base (`WEBCAKE_BUILDER_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|----------------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` | `http://builder.localhost:5800` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` | `https://builder.staging.webcake.io` |
+| `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` | `https://builder.webcake.io` |
+
+> **Link editor/preview** trả về sau `create_page`/`update_page` mở trên **host builder** (bảng trên), không phải API hay SPA base.
 
 ```bash
 npx -y webcake-landing-mcp login --env local       # đăng nhập vào SPA + API local

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.22",
+    "d": "07/06/2026",
+    "type": "Added",
+    "en": "New WEBCAKE_BUILDER_BASE environment variable, x-webcake-builder-base HTTP header, and ?builder_base= query parameter set the page-builder host used…",
+    "vi": "Biến môi trường WEBCAKE_BUILDER_BASE mới, HTTP header x-webcake-builder-base, và tham số truy vấn ?builder_base= cho phép đặt host của page-builder…"
+  },
   {
     "v": "1.0.21",
     "d": "07/06/2026",
@@ -33,12 +40,5 @@
     "type": "Fixed",
     "en": "get_element and get_generation_guide no longer suggest https://picsum.photos as an alternative image placeholder; agents are now directed to use…",
     "vi": "get_element và get_generation_guide không còn gợi ý https://picsum.photos làm ảnh placeholder thay thế; agent nay được hướng dẫn chỉ dùng…"
-  },
-  {
-    "v": "1.0.16",
-    "d": "06/06/2026",
-    "type": "Changed",
-    "en": "The server icon (served at /favicon.svg and embedded in serverInfo.icons) has been refined to the official Webcake brand mark: a green-gradient…",
-    "vi": "Icon server (phục vụ tại /favicon.svg và nhúng trong serverInfo.icons) đã được tinh chỉnh về đúng logo thương hiệu Webcake: ô bo góc gradient xanh…"
   }
 ]

package/dist/http.js

@@ -45,6 +45,7 @@ const QUERY_AUTH = {
     api_base: "x-webcake-api-base",
     org_id: "x-webcake-org-id",
     app_base: "x-webcake-app-base",
+    builder_base: "x-webcake-builder-base",
 };
 function applyQueryAuth(req) {
     const q = (req.url ?? "").indexOf("?");

package/dist/persistence/config.js

@@ -18,7 +18,9 @@
  *   WEBCAKE_API_BASE  e.g. http://localhost:5800   (required to call the backend)
  *   WEBCAKE_JWT       the account JWT               (required to call the backend)
  *   WEBCAKE_ORG_ID    optional default organization id for create_page
- *   WEBCAKE_APP_BASE  optional base for editor/preview URLs in the result
+ *   WEBCAKE_APP_BASE  optional SPA base (used for the login connect page)
+ *   WEBCAKE_BUILDER_BASE  optional builder host for editor/preview URLs in the result
+ *                     (defaults to the env preset, else derived from the API host)
  *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
  */
 import { homedir } from "node:os";
@@ -29,12 +31,14 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
  * base URLs. Selecting one (via the `--env` flag, WEBCAKE_ENV, the `x-webcake-env`
  * header, or `?env=` in the URL) fills in both bases so callers don't repeat them.
  * Explicit WEBCAKE_API_BASE / WEBCAKE_APP_BASE (or per-request overrides) win over
- * the preset. `apiBase` is the backend; `appBase` is the SPA (editor/preview/connect).
+ * the preset. `apiBase` is the backend; `appBase` is the SPA (login connect page);
+ * `builderBase` is the page builder host that serves the `/editor/v2` URL returned
+ * after create/update (a distinct host — NOT the API and NOT the SPA).
  */
 export const ENVIRONMENTS = {
-    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173" },
-    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io" },
-    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io" },
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800" },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io" },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io" },
 };
 export const ENV_NAMES = Object.keys(ENVIRONMENTS);
 /** True when `v` names a known environment (local|staging|prod). */
@@ -45,6 +49,23 @@ export function isEnvName(v) {
 export function resolveEnv(name) {
     return isEnvName(name) ? ENVIRONMENTS[name] : undefined;
 }
+/**
+ * Derive the page-builder host from the API base when no preset / explicit value is
+ * given: `api.<domain>` → `builder.<domain>`, otherwise `builder.<host>` (so
+ * `http://localhost:5800` → `http://builder.localhost:5800`, matching the presets).
+ */
+export function deriveBuilderBase(apiBase) {
+    if (!apiBase)
+        return undefined;
+    try {
+        const u = new URL(apiBase);
+        u.hostname = u.hostname.startsWith("api.") ? `builder.${u.hostname.slice(4)}` : `builder.${u.hostname}`;
+        return u.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function readConfig(overrides = {}) {
     const saved = readSavedConfig();
     // A named environment supplies default base URLs; explicit values still win.
@@ -58,12 +79,22 @@ export function readConfig(overrides = {}) {
         missing.push("WEBCAKE_JWT");
     if (missing.length)
         return { config: null, missing };
+    const cleanBase = base.replace(/\/+$/, "");
+    // The editor/preview URL lives on the builder host (e.g. builder.localhost:5800),
+    // not the API base (5800) nor the SPA (5173). Resolve it explicitly so the link
+    // returned to the user opens in the page builder.
+    const builderBase = (overrides.builderBase ??
+        process.env.WEBCAKE_BUILDER_BASE ??
+        preset?.builderBase ??
+        saved.builderBase ??
+        deriveBuilderBase(cleanBase))?.replace(/\/+$/, "");
     return {
         config: {
-            base: base.replace(/\/+$/, ""),
+            base: cleanBase,
             jwt: jwt,
             orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
             appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase)?.replace(/\/+$/, ""),
+            builderBase,
         },
         missing: [],
     };
@@ -79,7 +110,8 @@ function header(headers, name) {
  *   x-webcake-org-id     organization id
  *   x-webcake-env        named environment (local|staging|prod) for the base URLs
  *   x-webcake-api-base   backend base URL (overrides the env preset)
- *   x-webcake-app-base   editor/preview URL base (overrides the env preset)
+ *   x-webcake-app-base   SPA base used for the login connect page (overrides the preset)
+ *   x-webcake-builder-base  builder host for editor/preview URLs (overrides the preset)
  * Any header that is absent falls back to the corresponding env var in readConfig.
  */
 export function configFromHeaders(headers) {
@@ -90,6 +122,7 @@ export function configFromHeaders(headers) {
         jwt: header(headers, "x-webcake-jwt") ?? bearer,
         orgId: header(headers, "x-webcake-org-id"),
         appBase: header(headers, "x-webcake-app-base"),
+        builderBase: header(headers, "x-webcake-builder-base"),
         env: header(headers, "x-webcake-env"),
     };
 }

package/dist/persistence/webcake-client.js

@@ -15,6 +15,33 @@ function authHeaders(config, orgId) {
         headers["x-org-id"] = `${org}`;
     return headers;
 }
+/**
+ * Resolve the editor/preview link the backend returns onto the page-builder host
+ * (config.builderBase, e.g. builder.localhost:5800), NOT the API base. The backend
+ * may return either a path (`/editor/v2/<id>`) or an absolute URL on its own host
+ * (`http://localhost:5800/editor/v2/<id>`) — in both cases we keep only the
+ * path+query and re-root it on the builder host.
+ */
+export function toEditorUrl(config, raw) {
+    if (!raw)
+        return raw;
+    const builder = config.builderBase ?? config.appBase;
+    if (!builder)
+        return raw;
+    let pathQuery = raw;
+    if (/^https?:\/\//i.test(raw)) {
+        try {
+            const u = new URL(raw);
+            pathQuery = u.pathname + u.search + u.hash;
+        }
+        catch {
+            /* not a parseable URL — use as-is */
+        }
+    }
+    if (!pathQuery.startsWith("/"))
+        pathQuery = `/${pathQuery}`;
+    return `${builder.replace(/\/+$/, "")}${pathQuery}`;
+}
 /** Build (but do not send) the create request — used for dry-run previews. */
 export function buildRequest(config, name, source, orgId) {
     return {
@@ -88,7 +115,6 @@ export async function createPage(config, name, source, orgId) {
     const pageId = data?.page_id;
     const editorPath = data?.editor_url;
     const previewPath = data?.preview_url;
-    const app = config.appBase;
     if (!res.ok || !pageId) {
         // The backend's failure envelope is { success:false, message } on 422; auth
         // plugs return plain-text 401/403 (json is null). Surface the real reason
@@ -105,8 +131,8 @@ export async function createPage(config, name, source, orgId) {
         ok: true,
         status: res.status,
         page_id: pageId,
-        editor_url: app && editorPath ? `${app}${editorPath}` : editorPath,
-        preview_url: app && previewPath ? `${app}${previewPath}` : previewPath,
+        editor_url: toEditorUrl(config, editorPath),
+        preview_url: toEditorUrl(config, previewPath),
         organization_id: (orgId ?? config.orgId) ?? null,
         raw: data,
     };
@@ -190,7 +216,6 @@ export async function updatePageSource(config, pageId, source) {
     }
     const data = json?.data ?? json;
     const pageIdOut = data?.page_id;
-    const app = config.appBase;
     if (!res.ok || !pageIdOut) {
         const backendMsg = json?.message ?? json?.reason ?? (json ? undefined : text.slice(0, 200));
         return {
@@ -204,8 +229,8 @@ export async function updatePageSource(config, pageId, source) {
         ok: true,
         status: res.status,
         page_id: pageIdOut,
-        editor_url: app && data?.editor_url ? `${app}${data.editor_url}` : data?.editor_url,
-        preview_url: app && data?.preview_url ? `${app}${data.preview_url}` : data?.preview_url,
+        editor_url: toEditorUrl(config, data?.editor_url),
+        preview_url: toEditorUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         raw: data,
     };

package/dist/smoke.js

@@ -5,6 +5,7 @@
 import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, ELEMENTS, } from "./domains/landing/elements/index.js";
 import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { readConfig, resolveEnv, ENV_NAMES } from "./persistence/config.js";
+import { toEditorUrl } from "./persistence/webcake-client.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -212,7 +213,7 @@ check("clean form has no binding warnings", rbg.warnings.length === 0, rbg.warni
 console.log("== config: named environment presets (local/staging/prod) ==");
 {
     // Deterministic: isolate from any ambient WEBCAKE_* and the saved auth.json on the dev box.
-    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
+    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_BUILDER_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
         delete process.env[k];
     process.env.WEBCAKE_CONFIG_DIR = "/nonexistent/webcake-smoke";
     check("env names are local/staging/prod", setEq(new Set(ENV_NAMES), ["local", "staging", "prod"]), ENV_NAMES);
@@ -224,6 +225,20 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     check("readConfig(env=local) fills api+app base", local?.base === "http://localhost:5800" && local?.appBase === "http://localhost:5173", local);
     check("explicit base overrides the preset", readConfig({ env: "prod", base: "http://x:1", jwt: "t" }).config?.base === "http://x:1");
     check("unknown env leaves base missing", readConfig({ env: "bogus", jwt: "t" }).missing.includes("WEBCAKE_API_BASE"));
+    // builder host for editor/preview URLs (distinct from the api + app bases)
+    check("env presets carry builder bases", resolveEnv("prod")?.builderBase === "https://builder.webcake.io" && resolveEnv("local")?.builderBase === "http://builder.localhost:5800");
+    check("readConfig(env=prod) sets builderBase", prod?.builderBase === "https://builder.webcake.io", prod);
+    check("readConfig(env=local) sets builderBase", local?.builderBase === "http://builder.localhost:5800", local);
+    check("readConfig(env=staging) sets builderBase", readConfig({ env: "staging", jwt: "t" }).config?.builderBase === "https://builder.staging.webcake.io");
+    check("builderBase derives from a custom api base (api. → builder.)", readConfig({ base: "https://api.example.com", jwt: "t" }).config?.builderBase === "https://builder.example.com");
+    check("builderBase derives from a localhost api base", readConfig({ base: "http://localhost:5800", jwt: "t" }).config?.builderBase === "http://builder.localhost:5800");
+    check("explicit builderBase overrides the preset", readConfig({ env: "prod", builderBase: "https://b.test", jwt: "t" }).config?.builderBase === "https://b.test");
+    // editor/preview link is re-rooted on the builder host, whether the backend
+    // returns a path or an absolute URL on its own host.
+    const localCfg = readConfig({ env: "local", jwt: "t" }).config;
+    check("editor url from a path → builder host", toEditorUrl(localCfg, "/editor/v2/abc") === "http://builder.localhost:5800/editor/v2/abc");
+    check("editor url from an absolute api url → builder host", toEditorUrl(localCfg, "http://localhost:5800/editor/v2/abc?x=1") === "http://builder.localhost:5800/editor/v2/abc?x=1");
+    check("editor url passthrough when empty", toEditorUrl(localCfg, undefined) === undefined);
 }
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/web-guide.js

@@ -58,6 +58,9 @@ const ICONS = {
     arrow: '<path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>',
     clock: '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
     globe: '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>',
+    bulb: '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+    server: '<rect width="20" height="8" x="2" y="2" rx="2"/><rect width="20" height="8" x="2" y="14" rx="2"/><path d="M6 6h.01"/><path d="M6 18h.01"/>',
+    window: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M2 9h20"/><path d="M6 6.5h.01"/><path d="M9 6.5h.01"/>',
 };
 function icon(name) {
     return `<svg class="i" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${ICONS[name] ?? ""}</svg>`;
@@ -136,6 +139,14 @@ const T = {
         leadPost: " của bạn. Không kéo thả, không cài server — kết nối một lần là xong.",
         ctaStart: "Bắt đầu kết nối",
         ctaStar: "Star trên GitHub",
+        flowH2: "Mô hình hoạt động",
+        flow: [
+            { icon: "bulb", t: "Bạn", s: "ý tưởng" },
+            { icon: "brain", t: "Trợ lý AI", s: "Claude · Cursor" },
+            { icon: "server", t: "MCP", s: "webcake-landing" },
+            { icon: "window", t: "WebCake", s: "trang thật" },
+        ],
+        flowCap: "Bạn mô tả bằng lời → AI học mô hình thật từ MCP → MCP dựng JSON + kiểm tra → lưu thành trang thật trên WebCake. Bạn nhận link, mở editor, publish.",
         howH2: "Cách hoạt động",
         how: [
             {
@@ -206,6 +217,14 @@ const T = {
         leadPost: ". No drag-and-drop, no server to host — connect once and you're set.",
         ctaStart: "Get connected",
         ctaStar: "Star on GitHub",
+        flowH2: "How it flows",
+        flow: [
+            { icon: "bulb", t: "You", s: "your idea" },
+            { icon: "brain", t: "AI assistant", s: "Claude · Cursor" },
+            { icon: "server", t: "MCP", s: "webcake-landing" },
+            { icon: "window", t: "WebCake", s: "a real page" },
+        ],
+        flowCap: "You describe it in words → the AI learns the real model from the MCP → the MCP builds the JSON + validates → it's saved as a real WebCake page. You get a link, open the editor, publish.",
         howH2: "How it works",
         how: [
             {
@@ -440,6 +459,27 @@ export function guideHtml(origin, lang = "vi") {
   .feat li{display:flex;gap:13px;align-items:center;font-size:.97rem;padding:13px 16px}
   .feat li b{color:var(--ink)}
   .cta-row{display:flex;gap:12px;flex-wrap:wrap;margin:22px 0 6px}
+  /* Flow diagram: nodes connected by wires with a traveling "packet" */
+  .flow{display:flex;align-items:flex-start;gap:0;padding:24px 18px 18px;overflow-x:auto}
+  .flow .node{flex:0 0 auto;display:flex;flex-direction:column;align-items:center;gap:8px;text-align:center;width:104px}
+  .flow .node .ic{width:54px;height:54px;border-radius:16px}
+  .flow .node .ic .i{width:27px;height:27px}
+  .flow .node b{font-size:.93rem}
+  .flow .node span{font-size:.75rem;color:var(--mut)}
+  .flow .wire{flex:1 1 auto;min-width:30px;position:relative;height:2px;margin-top:27px;
+    background:linear-gradient(90deg,var(--line),rgba(29,185,84,.45),var(--line))}
+  .flow .wire .pkt{position:absolute;top:50%;left:0;width:9px;height:9px;margin:-5px 0 0 -4px;border-radius:50%;
+    background:var(--g);box-shadow:0 0 9px 1px rgba(29,185,84,.7)}
+  .flow .wire::after{content:"";position:absolute;right:-1px;top:50%;width:7px;height:7px;margin-top:-4px;
+    border-top:2px solid var(--g7);border-right:2px solid var(--g7);transform:rotate(45deg)}
+  .flow-cap{color:var(--mut);font-size:.9rem;margin:2px 2px 0;max-width:68ch}
+  @media(prefers-reduced-motion:no-preference){
+    .flow .wire .pkt{animation:pkt 2.4s ease-in-out infinite}
+    @keyframes pkt{0%{left:0;opacity:0}12%{opacity:1}88%{opacity:1}100%{left:100%;opacity:0}}
+    .flow .node .ic{animation:nodepop 2.4s ease-in-out infinite}
+  }
+  @media(prefers-reduced-motion:reduce){.flow .wire .pkt{display:none}}
+  @keyframes nodepop{0%,100%{box-shadow:none}50%{box-shadow:0 0 0 4px rgba(29,185,84,.12)}}
   .btn{display:inline-flex;align-items:center;gap:9px;padding:11px 19px;border-radius:11px;cursor:pointer;
     background:var(--g);color:#fff;text-decoration:none;font-weight:700;font-size:.93rem;
     box-shadow:0 4px 12px -4px rgba(29,185,84,.5);transition:transform .15s ease,background .15s ease}
@@ -540,6 +580,17 @@ export function guideHtml(origin, lang = "vi") {
     <a class="btn ghost" href="${GITHUB_URL}">${icon("star")} ${t.ctaStar}</a>
   </div>
 
+  <h2 class="reveal">${t.flowH2}</h2>
+  <div class="glass flow reveal">
+    ${t.flow
+        .map((n, i) => `<div class="node"><span class="ic" style="animation-delay:${(i * 0.8).toFixed(1)}s">${icon(n.icon)}</span><b>${n.t}</b><span>${n.s}</span></div>` +
+        (i < t.flow.length - 1
+            ? `<div class="wire"><i class="pkt" style="animation-delay:${(i * 0.8).toFixed(1)}s"></i></div>`
+            : ""))
+        .join("\n    ")}
+  </div>
+  <p class="flow-cap reveal">${t.flowCap}</p>
+
   <h2 class="reveal">${t.howH2}</h2>
   <div class="grid">
     ${t.how

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "bin": {