webcake-landing-mcp 1.0.62 → 1.0.63

package/README.md

@@ -80,7 +80,8 @@ MCP (Model Context Protocol) server that teaches AI agents how to build a comple
 It exposes the element catalog, per-element usage hints + `specials`, the full page JSON Schema,
 valid element/page skeletons, a page validator, and tools to create or edit pages on the backend.
 The AI agent produces the full `{ page, popup, settings, options, cartConfigs }` JSON; `create_page`
-persists it (source-only — the page opens in the editor where re-saving renders it).
+persists it and auto-publishes (build + `publish_html`) so the preview renders immediately (the edit
+tools save source-only — re-publish via `publish_page` after edits).
 
 | Method | Best for | Auth |
 |--------|----------|------|
@@ -152,10 +153,12 @@ npx -y webcake-landing-mcp login    # opens the browser once, saves the token to
 
 …or set `WEBCAKE_ENV` (`local` | `staging` | `prod` — fills in all base URLs) + `WEBCAKE_JWT`.
 
-For `publish_page` to produce a **rendered** (non-blank) page, a build host is needed:
-- `prod` preset auto-configures `https://build.webcake.io` — no extra setup.
+For `publish_page` to actually put a page **live**, a build host is needed (it renders the
+`app`/`app_css` that the live `publish_html` route requires):
+- `prod` preset auto-configures `https://build.webcake.io` — no extra setup (the preset applies when the env resolves to `prod`: `WEBCAKE_ENV=prod`, `--env prod`, or `x-webcake-env: prod`).
 - For staging/local, set `WEBCAKE_BUILD_BASE=<url>` or send the `x-webcake-build-base` header per request.
-- Without it, `publish_page` falls back to source-only with `rendered:false` + a warning.
+- Without it, `publish_page` falls back to a legacy source-only save with `rendered:false, live:false` + a warning — nothing goes live.
+- A page is only **permanently** live with a `custom_domain`; without one the returned `/preview/<page_id>` link expires ~10 minutes after the publish.
 
 Everything else — the full env-var table, environment presets, per-request headers for the hosted
 server, the `login` browser flow (+ backend contract), and how to grab a JWT by hand — lives in

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.63",
+    "d": "11/06/2026",
+    "type": "Added",
+    "en": "create_page now auto-publishes after a successful create: builds the rendered app via the build host and calls the editor's publish_html route so…",
+    "vi": "create_page nay tự động publish sau khi tạo thành công: build rendered app qua build host rồi gọi route publish_html của editor để preview trang mới…"
+  },
   {
     "v": "1.0.62",
     "d": "11/06/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "html-box descriptor (get_element) has been rewritten to document COMPOSITE VISUALS as the primary use case: intricate non-interactive mockups such…",
     "vi": "Descriptor html-box (get_element) được viết lại để ghi lại COMPOSITE VISUALS là trường hợp sử dụng chính: các mockup phi tương tác phức tạp như…"
-  },
-  {
-    "v": "1.0.57",
-    "d": "11/06/2026",
-    "type": "Added",
-    "en": "New upload_images tool re-hosts up to 20 external image URLs or data: URIs as Webcake-hosted URLs (statics.pancake.vn) by downloading and uploading…",
-    "vi": "Công cụ upload_images mới tải lại tối đa 20 URL ảnh ngoài hoặc data: URI thành URL do Webcake lưu trữ (statics.pancake.vn) bằng cách tải về và…"
   }
 ]

package/dist/domains/landing/index.js

@@ -171,6 +171,42 @@ function normalizeBackgrounds(node) {
             normalizeBackgrounds(child);
     }
 }
+// ---------------------------------------------------------------------------
+// misplaced-animation normalization: models regularly emit the animation object
+// directly under responsive.<bp> instead of responsive.<bp>.config.animation —
+// the single most common "must NOT have additional properties" schema error,
+// and one a patch op:'update' can never fix (update merges; it cannot delete
+// the stray key). The intent is unambiguous, so move it where the editor reads
+// it: into config.animation (the author's explicit non-'none' config.animation
+// wins if both are set), then drop the stray key. Deterministic + idempotent,
+// so the expand(compact(x)) == expand(x) invariant holds.
+// ---------------------------------------------------------------------------
+/** Walk a tree node and relocate responsive.<bp>.animation → config.animation in-place (mutates). */
+function normalizeMisplacedAnimation(node) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const bp of ["desktop", "mobile"]) {
+        const rbp = node.responsive?.[bp];
+        if (!rbp || typeof rbp !== "object")
+            continue;
+        const stray = rbp.animation;
+        if (stray !== undefined) {
+            if (stray && typeof stray === "object") {
+                rbp.config = rbp.config && typeof rbp.config === "object" ? rbp.config : {};
+                const existing = rbp.config.animation;
+                const existingWins = existing && typeof existing === "object" && typeof existing.name === "string" && existing.name !== "none";
+                if (!existingWins) {
+                    rbp.config.animation = { name: "none", delay: 0, duration: 3, repeat: null, ...stray };
+                }
+            }
+            delete rbp.animation;
+        }
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children)
+            normalizeMisplacedAnimation(child);
+    }
+}
 /** Apply all post-expand normalizations to every node in a page source. */
 function normalizeSource(source) {
     if (!source || typeof source !== "object")
@@ -178,6 +214,7 @@ function normalizeSource(source) {
     for (const arr of ["page", "popup", "dynamic_pages"]) {
         if (Array.isArray(source[arr])) {
             for (const node of source[arr]) {
+                normalizeMisplacedAnimation(node);
                 normalizeImageBlocks(node);
                 normalizeBorderRadius(node);
                 normalizeBackgrounds(node);

package/dist/domains/landing/instructions.js

@@ -21,7 +21,7 @@ RULES (follow for every request):
   · patch_page (live-page) timed out → response returns a draft_id (patched source cached). Retry patch_page({ draft_id, dry_run:false }) with no patches — the COMMIT-AS-IS path.
   · update_page validation failed → the page already has a page_id → patch_page({ page_id, patches:[…] }) the offending ids.
   COMMIT-AS-IS (retry path after timeout): patch_page({ draft_id, dry_run:false }) with NO patches — skips the apply step, re-validates, then saves. This is the universal retry for any timed-out write.
-  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 ~30 min.
+  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. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts), CSS custom-property palette, 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), every real image URL found in the AST (images, background_images, og_image) MUST be re-hosted via upload_images and reused in the corresponding slot; do NOT replace them with search_images stock photos. 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.
@@ -37,6 +37,6 @@ 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). SOURCE PRIORITY: (1) images the user provided or that exist in the reference HTML/URL → re-host via upload_images and use those exact images; (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). Only if search_images returns ok:false, FALL BACK to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height>. (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.
 
-- PREVIEW vs PUBLISH: the preview_url returned by create_page/update_page/add_section lives on the PREVIEW host (preview.localhost:5800 local / staging.webcake.me staging / www.webcake.me prod — NOT the builder subdomain) and renders the stored source immediately — share it as-is for review. When the user wants the page LIVE (public/published, optionally on their custom domain), call publish_page({ page_id, custom_domain?, custom_path?, dry_run:false }).
+- 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.`;

package/dist/domains/landing/validate.js

@@ -125,6 +125,57 @@ export function coercePage(input) {
         return JSON.parse(input);
     return input;
 }
+/**
+ * Resolve an ajv instancePath (e.g. "/page/1/children/2/responsive/desktop") to
+ * the deepest ELEMENT (object with string id + type) along it, plus the final
+ * value the path lands on. The positional path alone is the #1 reason a model
+ * patches the WRONG element after a schema error — indices are easy to miscount;
+ * ids are not.
+ */
+function describeInstancePath(page, instancePath) {
+    if (!instancePath || instancePath === "/")
+        return {};
+    let cur = page;
+    let el;
+    for (const rawSeg of instancePath.split("/").slice(1)) {
+        if (cur == null || typeof cur !== "object")
+            return { id: el?.id, type: el?.type };
+        const seg = rawSeg.replace(/~1/g, "/").replace(/~0/g, "~");
+        cur = Array.isArray(cur) ? cur[Number(seg)] : cur[seg];
+        if (cur && typeof cur === "object" && typeof cur.id === "string" && typeof cur.type === "string")
+            el = cur;
+    }
+    return { id: el?.id, type: el?.type, value: cur };
+}
+/**
+ * Format one ajv error as an ACTIONABLE message: positional path + ajv message,
+ * plus the offending property name (additionalProperties), the actual bad value
+ * (enum/type), and — crucially — the enclosing element's id/type so the fix can
+ * target the right element by id on the first try. For stray-key errors it also
+ * names the only op that can fix them: patch update MERGES, so deleting a key
+ * needs op:'replace' (or, on a rebuild, simply omitting the key).
+ */
+function describeSchemaError(page, err) {
+    const path = err.instancePath || "/";
+    let msg = `schema ${path} ${err.message}`;
+    const at = describeInstancePath(page, path);
+    const extraKey = err.params?.additionalProperty;
+    if (extraKey)
+        msg += ` — offending key: "${extraKey}"`;
+    if ((err.keyword === "enum" || err.keyword === "type" || err.keyword === "const") &&
+        (typeof at.value === "string" || typeof at.value === "number" || typeof at.value === "boolean")) {
+        msg += ` — got: ${JSON.stringify(at.value)}`;
+    }
+    if (at.id)
+        msg += ` — element id="${at.id}"${at.type ? ` (type ${at.type})` : ""}`;
+    if (extraKey && at.id) {
+        msg +=
+            `. patch_page op:'update' MERGES and cannot delete this key — fix via ` +
+                `{op:'replace', id:'${at.id}', element:<the clean node without "${extraKey}">}` +
+                (extraKey === "animation" ? ` (animation belongs in responsive.<bp>.config.animation, not responsive.<bp>)` : "");
+    }
+    return msg;
+}
 export function validatePage(input) {
     const errors = [];
     const warnings = [];
@@ -135,11 +186,13 @@ export function validatePage(input) {
     catch (e) {
         return { valid: false, errors: [`Invalid JSON: ${e.message}`], warnings: [], stats: { sections: 0, popups: 0, elements: 0, ids: 0 } };
     }
-    // 1) Structural (JSON Schema)
+    // 1) Structural (JSON Schema) — each error names the enclosing ELEMENT (id +
+    //    type) and the offending key/value, so a fix can target the right element
+    //    by id instead of decoding positional indices.
     const ok = validateSchema(page);
     if (!ok && validateSchema.errors) {
         for (const err of validateSchema.errors) {
-            errors.push(`schema ${err.instancePath || "/"} ${err.message}`);
+            errors.push(describeSchemaError(page, err));
         }
     }
     // 2) Semantic

package/dist/persistence/draft-cache.js

@@ -29,7 +29,11 @@
  * CALLER's own creds, so a draft only ever yields a page in the caller's account.
  */
 import { randomUUID } from "node:crypto";
-const TTL_MS = 30 * 60 * 1000; // 30 minutes
+/** Draft lifetime — default 2 hours. Override via WEBCAKE_DRAFT_TTL_MS env. */
+const TTL_MS = (() => {
+    const v = parseInt(process.env.WEBCAKE_DRAFT_TTL_MS ?? "", 10);
+    return Number.isFinite(v) && v > 0 ? v : 2 * 60 * 60 * 1000;
+})();
 const MAX_ENTRIES = 50;
 const store = new Map();
 function sweep(now) {

package/dist/persistence/webcake-client.js

@@ -27,13 +27,22 @@ const SEARCH_PAGES_ENDPOINT = "/api/v1/ai/search_pages";
 const PAGE_SOURCE_ENDPOINT = "/api/v1/ai/page_source";
 const UPDATE_ENDPOINT = "/api/v1/ai/update_page_source";
 const APPEND_ENDPOINT = "/api/v1/ai/append_section";
-// The editor's own publish route (NOT under /api/v1/ai): saves the source as a
-// new version and creates/updates the page_published record (+ optional custom
-// domain/path) so the page goes live. NOTE: this scope is host-constrained to
-// the BUILDER host (router scope `host: "builder."`), so the request goes to
-// config.builderBase, not the API base.
-const publishEndpoint = (pageId) => `/api/pages/${encodeURIComponent(pageId)}/edit/publish`;
-const publishUrl = (config, pageId) => `${(config.builderBase ?? config.base).replace(/\/+$/, "")}${publishEndpoint(pageId)}`;
+// The editor's own publish routes (NOT under /api/v1/ai). Both scopes are
+// host-constrained to the BUILDER host (router scope `host: "builder."`), so
+// requests go to config.builderBase, not the API base.
+//
+// /edit/publish_html is what the editor's publish button calls and the ONLY
+// route that creates/updates the PagePublishedV2 record — the record EVERY
+// public serving path reads (render_custom_domain → get_published_by_domain_path_v2
+// → serves page_published_v2.app). It expects the rendered app/app_css in the body.
+//
+// /edit/publish is LEGACY: it saves the source (+app/app_css onto the page_source
+// row, which only the ~10-minute /preview/:id window serves) and writes a
+// PagePublished v1 record that no serving path reads. Kept only as the
+// source-only fallback when no build host is available.
+const publishHtmlEndpoint = (pageId) => `/api/pages/${encodeURIComponent(pageId)}/edit/publish_html`;
+const legacyPublishEndpoint = (pageId) => `/api/pages/${encodeURIComponent(pageId)}/edit/publish`;
+const publishUrl = (config, pageId, rendered) => `${(config.builderBase ?? config.base).replace(/\/+$/, "")}${rendered ? publishHtmlEndpoint(pageId) : legacyPublishEndpoint(pageId)}`;
 function authHeaders(config, orgId) {
     const headers = {
         "Content-Type": "application/json",
@@ -73,14 +82,36 @@ export function toEditorUrl(config, raw) {
         pathQuery = `/${pathQuery}`;
     return `${builder.replace(/\/+$/, "")}${pathQuery}`;
 }
+/**
+ * Build a SELF-LOGGING-IN editor link. The bare `/editor/v2/<id>` route sits
+ * behind the backend's `:passport` pipeline (jwt COOKIE or Bearer header), so a
+ * plain editor URL 401s ("Token not found") in any browser that isn't already
+ * logged in to Webcake. The builder host exposes `GET /transport?token=&redirect_uri=`
+ * (public; AuthController.transport) which sets the `jwt` cookie and redirects —
+ * so we wrap the editor URL in it, carrying the SAME jwt the MCP call used
+ * (env / auth.json / per-request header). The token is the caller's own
+ * credential, but the link logs into their account — share it with the page
+ * owner only, never publish it. Preview links stay UNWRAPPED (they're public).
+ */
+export function toEditorLoginUrl(config, raw) {
+    const editor = toEditorUrl(config, raw);
+    if (!editor || !config.jwt)
+        return editor;
+    const builder = config.builderBase ?? config.appBase;
+    if (!builder)
+        return editor;
+    return `${builder.replace(/\/+$/, "")}/transport?token=${encodeURIComponent(config.jwt)}&redirect_uri=${encodeURIComponent(editor)}`;
+}
 /**
  * Resolve the public preview link (`/preview/<page_id>`) onto the PREVIEW host
  * (config.previewBase) — NOT the builder subdomain. The /preview/:id route only
  * exists on the root preview hosts (preview.localhost:5800 local /
- * staging.webcake.me staging / www.webcake.me prod); the v4 renderer there serves
- * the STORED `app`/`app_css` build columns — an MCP-created page's preview is
- * blank until publish_page (with a build host) runs or the page is re-saved in
- * the Webcake editor.
+ * staging.webcake.me staging / www.webcake.me prod); the v4 renderer there
+ * serves the page_source row's STORED `app`/`app_css` build columns, and only
+ * for ~10 minutes after the last source save (then "Preview page is expired").
+ * An MCP-created page's preview is blank until a rendered publish_page runs or
+ * the page is re-saved in the Webcake editor — and even then the link is
+ * ephemeral; only a custom_domain publish gives a permanent URL.
  */
 export function toPreviewUrl(config, raw) {
     if (!raw)
@@ -191,7 +222,7 @@ export async function createPage(config, name, source, orgId) {
         ok: true,
         status: res.status,
         page_id: pageId,
-        editor_url: toEditorUrl(config, editorPath),
+        editor_url: toEditorLoginUrl(config, editorPath),
         preview_url: toPreviewUrl(config, previewPath),
         organization_id: (orgId ?? config.orgId) ?? null,
         raw: data,
@@ -337,7 +368,7 @@ export async function appendSection(config, pageId, sections) {
         ok: true,
         status: res.status,
         page_id: pageIdOut,
-        editor_url: toEditorUrl(config, data?.editor_url),
+        editor_url: toEditorLoginUrl(config, data?.editor_url),
         preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         section_count: data?.section_count,
@@ -383,7 +414,7 @@ export async function updatePageSource(config, pageId, source) {
         ok: true,
         status: res.status,
         page_id: pageIdOut,
-        editor_url: toEditorUrl(config, data?.editor_url),
+        editor_url: toEditorLoginUrl(config, data?.editor_url),
         preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         raw: data,
@@ -467,39 +498,70 @@ export async function buildPageApp(buildBase, pageId, source) {
     }
     return { ok: true, app, app_css, status: res.status };
 }
-function publishBody(sourceString, opts = {}) {
-    // The publish action expects `source` as a JSON STRING (it Jason.decode!s it),
-    // plus optional custom_domain/custom_path. is_publish marks the save as a
-    // publish in save_page_with_source. app/app_css are the rendered HTML produced
-    // by the build host — when present the page renders without the editor.
-    const payload = {
-        source: sourceString,
+/**
+ * Body for the editor's /edit/publish_html route — mirrors the payload the
+ * editor's PublishModal sends (see landing_page_backend assets/editor
+ * PublishModal.vue): the saved source rides as the `data_node` JSON STRING (the
+ * route Jason.decode!s it and stores it via save_page_with_source), there is NO
+ * `source` key, and `settings` (with `mobile_only` folded in from
+ * options.mobileOnly) is stored on the PagePublishedV2 record the public
+ * serving paths read. `render_type: "v4"` only when a domain is attached —
+ * exactly what the editor sends. `auto: false` so the publish creates a version.
+ */
+function publishHtmlBody(source, opts = {}) {
+    const hasDomain = !!opts.customDomain;
+    return JSON.stringify({
+        custom_domain: opts.customDomain ?? "",
+        custom_path: opts.customPath ?? "",
+        selected_custom_domain: hasDomain,
+        data_node: JSON.stringify(source),
+        render_type: hasDomain ? "v4" : null,
+        app: opts.app,
+        app_css: opts.app_css ?? "",
+        settings: { ...(source?.settings ?? {}), mobile_only: source?.options?.mobileOnly ?? false },
+        type: 1,
+        auto: false,
+    });
+}
+/**
+ * Body for the LEGACY /edit/publish route (source-only fallback): `source` as a
+ * JSON STRING plus custom_domain/custom_path; is_publish marks the save as a
+ * publish in save_page_with_source. No PagePublishedV2 record is written, so
+ * nothing goes live — the page only renders in the editor / the short-lived
+ * /preview window after a build.
+ */
+function legacyPublishBody(source, opts = {}) {
+    return JSON.stringify({
+        source: JSON.stringify(source),
         custom_domain: opts.customDomain ?? "",
         custom_path: opts.customPath ?? "",
         is_publish: true,
-    };
-    if (opts.app != null)
-        payload["app"] = opts.app;
-    if (opts.app_css != null)
-        payload["app_css"] = opts.app_css;
-    return JSON.stringify(payload);
+    });
+}
+function publishRequestBody(source, opts, rendered) {
+    return rendered ? publishHtmlBody(source, opts) : legacyPublishBody(source, opts);
 }
-/** Build (but do not send) the publish request with the token masked — for dry-run previews. */
-export function buildPublishRequestRedacted(config, pageId, sourceString, opts = {}) {
-    // Build a preview body: replace actual app/app_css content with size hints so the
-    // preview is readable while still showing whether rendered HTML is included.
+/**
+ * Build (but do not send) the publish request with the token masked — for
+ * dry-run previews. `willRender` says whether the real run will call the build
+ * host and take the publish_html path (dry_run itself never builds, so the
+ * preview stands in a size hint / placeholder for app/app_css).
+ */
+export function buildPublishRequestRedacted(config, pageId, source, opts = {}, willRender = opts.app != null) {
+    // Replace actual app/app_css content with size hints (or a placeholder when
+    // the build runs later) so the preview stays readable.
     const previewOpts = { ...opts };
-    if (opts.app != null)
-        previewOpts.app = `<${opts.app.length} bytes>`;
-    if (opts.app_css != null)
-        previewOpts.app_css = `<${opts.app_css.length} bytes>`;
-    const body = publishBody(sourceString, previewOpts);
+    if (willRender) {
+        previewOpts.app = opts.app != null ? `<${opts.app.length} bytes>` : "<built by the build host on dry_run=false>";
+        previewOpts.app_css = opts.app_css != null ? `<${opts.app_css.length} bytes>` : "<built by the build host on dry_run=false>";
+    }
+    const body = publishRequestBody(source, previewOpts, willRender);
     return {
         method: "POST",
-        url: publishUrl(config, pageId),
+        url: publishUrl(config, pageId, willRender),
         headers: { ...authHeaders(config), Authorization: "Bearer ***JWT***", Cookie: "jwt=***JWT***" },
         body: body.replace(config.jwt, "***JWT***").slice(0, 600) + (body.length > 600 ? `… (${body.length} bytes)` : ""),
-        rendered: opts.app != null,
+        rendered: willRender,
     };
 }
 // ---------------------------------------------------------------------------
@@ -580,22 +642,27 @@ async function postToHost(url, headers, body) {
     });
 }
 /**
- * Publish a page: saves the source as a new version and creates/updates the
- * page_published record (live status + optional custom domain/path). When
- * opts.app/app_css are provided (built by buildPageApp) the page renders
- * immediately without needing the editor. Returns the resulting public URL —
- * `https://<domain>/<path>` when a custom domain is attached, else the
- * preview-host link (`<previewBase>/preview/<page_id>`).
+ * Publish a page. With opts.app/app_css (built by buildPageApp) it POSTs the
+ * editor's /edit/publish_html route, which creates/updates the PagePublishedV2
+ * record — the one the public serving paths read — so the page actually goes
+ * LIVE. Without them it falls back to the legacy /edit/publish route, which
+ * only saves the source as a new version (nothing goes live).
+ *
+ * Returns the resulting public URL — `https://<domain>/<path>` when a custom
+ * domain is attached, else the preview-host link
+ * (`<previewBase>/preview/<page_id>`), which the backend only serves for ~10
+ * minutes after the publish (then "Preview page is expired").
  */
-export async function publishPage(config, pageId, sourceString, opts = {}) {
-    const url = publishUrl(config, pageId);
+export async function publishPage(config, pageId, source, opts = {}) {
+    const rendered = opts.app != null;
+    const url = publishUrl(config, pageId, rendered);
     let status;
     let text;
     try {
         // The builder-host pipeline runs an `accepts ["html"]` plug (it serves the
         // editor SPA); a literal application/json Accept gets a 406, so send */*
         // like the browser does — the action still returns JSON.
-        ({ status, text } = await postToHost(url, { ...authHeaders(config), Accept: "*/*" }, publishBody(sourceString, opts)));
+        ({ status, text } = await postToHost(url, { ...authHeaders(config), Accept: "*/*" }, publishRequestBody(source, opts, rendered)));
     }
     catch (e) {
         const e2 = timeoutOrNetworkError(url, e);
@@ -624,6 +691,20 @@ export async function publishPage(config, pageId, sourceString, opts = {}) {
     const path = data?.path ?? null;
     const previewUrl = toPreviewUrl(config, `/preview/${pageId}`);
     const publishedUrl = domain ? `https://${domain}${path ? `/${String(path).replace(/^\/+/, "")}` : ""}` : previewUrl;
+    // The publish_html response data is PagePublishedV2.json — it carries the full
+    // app/app_css/source/data_node columns. Keep only the small identifying fields.
+    const raw = data && typeof data === "object"
+        ? {
+            id: data.id,
+            page_id: data.page_id,
+            domain: data.domain,
+            path: data.path,
+            status: data.status,
+            version_id: data.version_id,
+            render_type: data.render_type,
+            type: data.type,
+        }
+        : data;
     return {
         ok: true,
         status,
@@ -632,7 +713,8 @@ export async function publishPage(config, pageId, sourceString, opts = {}) {
         preview_url: previewUrl,
         domain,
         path,
-        rendered: opts.app != null,
-        raw: data,
+        rendered,
+        live: rendered,
+        raw,
     };
 }

package/dist/smoke.js

@@ -10,7 +10,7 @@ import { compactSource, deepEq, sparseTemplate } from "./core/compact.js";
 import { parseHtml } from "./persistence/html-ingest.js";
 import { warningsField } from "./mcp/response.js";
 import { readConfig, resolveEnv, ENV_NAMES, configFromHeaders } from "./persistence/config.js";
-import { toEditorUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
+import { toEditorUrl, toEditorLoginUrl, toPreviewUrl, buildPublishRequestRedacted } from "./persistence/webcake-client.js";
 import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
 import { putDraft, getDraft, updateDraft, deleteDraft } from "./persistence/draft-cache.js";
 import { buildConnectUrl, parseCallback } from "./auth/login.js";
@@ -132,6 +132,45 @@ check("bad page detects duplicate id", r2.errors.some((e) => e.includes("Duplica
 check("bad page detects children-on-noncontainer", r2.errors.some((e) => e.includes("not a container")), r2.errors);
 check("bad page detects missing mobile", r2.errors.some((e) => e.toLowerCase().includes("mobile")), r2.errors);
 check("bad page warns missing field_name", r2.warnings.some((w) => w.includes("field_name")), r2.warnings);
+console.log("== validate: schema errors name the element id + offending key ==");
+{
+    // A stray key directly under responsive.<bp> is the classic schema error a
+    // model cannot act on from the positional path alone — the message must name
+    // the element id, the stray key, and the only op that can delete it (replace).
+    const strayed = structuredClone(good);
+    strayed.page[0].children[0].responsive.desktop.zoomy = 1;
+    const rs = validatePage(strayed);
+    check("stray key fails schema", !rs.valid, rs);
+    const schemaErr = rs.errors.find((e) => e.includes("additional properties")) ?? "";
+    check("schema error names the offending key", schemaErr.includes('offending key: "zoomy"'), schemaErr);
+    check("schema error names the element id", schemaErr.includes('element id="btn1"'), schemaErr);
+    check("schema error prescribes op:'replace'", schemaErr.includes("op:'replace'") && schemaErr.includes("cannot delete"), schemaErr);
+    // A bad enum value reports what was actually there.
+    const badType = structuredClone(good);
+    badType.page[0].children[0].type = "txt-block";
+    const rt = validatePage(badType);
+    const enumErr = rt.errors.find((e) => e.includes("got:")) ?? "";
+    check("enum error reports the bad value + element id", enumErr.includes('"txt-block"') && enumErr.includes('element id="btn1"'), rt.errors);
+}
+console.log("== expand: relocates misplaced responsive.<bp>.animation into config ==");
+{
+    // Models regularly emit animation at the breakpoint level (schema error a
+    // patch update can never fix) — domain.expand moves it where the editor
+    // reads it, so the page validates on the FIRST create_page.
+    const misplaced = structuredClone(good);
+    misplaced.page[0].children[0].responsive.desktop.animation = { name: "fadeInUp", delay: 0, duration: 2, repeat: null };
+    const fixed = landingDomain.expand(misplaced);
+    const bp = fixed.page[0].children[0].responsive.desktop;
+    check("stray animation key removed", bp.animation === undefined, bp);
+    check("animation moved into config", bp.config?.animation?.name === "fadeInUp" && bp.config?.animation?.duration === 2, bp.config);
+    check("relocated page validates", validatePage(fixed).valid, validatePage(fixed).errors);
+    // An explicit non-'none' config.animation wins over the stray key.
+    const both = structuredClone(good);
+    both.page[0].children[0].responsive.desktop.animation = { name: "fadeInUp" };
+    both.page[0].children[0].responsive.desktop.config.animation = { name: "zoomIn", delay: 1, duration: 4, repeat: null };
+    const kept = landingDomain.expand(both).page[0].children[0].responsive.desktop;
+    check("explicit config.animation wins over the stray key", kept.config.animation.name === "zoomIn" && kept.animation === undefined, kept.config);
+}
 console.log("== validate: accepts JSON string input ==");
 const r3 = validatePage(JSON.stringify(good));
 check("string input parsed & valid", r3.valid, r3.errors);
@@ -540,6 +579,15 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     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);
+    // The RETURNED editor link must sign the browser in: the /editor route sits
+    // behind the jwt-cookie passport, so the link is wrapped in the builder
+    // host's public /transport?token=&redirect_uri= cookie-setting redirect.
+    const loginUrl = toEditorLoginUrl(localCfg, "/editor/v2/abc");
+    check("editor login url goes through /transport on the builder host", loginUrl.startsWith("http://builder.localhost:5800/transport?token="), loginUrl);
+    check("editor login url carries the jwt as token", loginUrl.includes("token=t&"), loginUrl);
+    check("editor login url percent-encodes the redirect target", loginUrl.endsWith(`redirect_uri=${encodeURIComponent("http://builder.localhost:5800/editor/v2/abc")}`), loginUrl);
+    check("editor login url passthrough when empty", toEditorLoginUrl(localCfg, undefined) === undefined);
+    check("editor login url stays bare without a jwt", toEditorLoginUrl({ ...localCfg, jwt: "" }, "/editor/v2/abc") === "http://builder.localhost:5800/editor/v2/abc");
     // The PREVIEW link lives on its own root host (NOT the builder subdomain):
     // preview.localhost:5800 / staging.webcake.me / www.webcake.me.
     check("env presets carry preview bases", resolveEnv("local")?.previewBase === "http://preview.localhost:5800" && resolveEnv("staging")?.previewBase === "https://staging.webcake.me" && resolveEnv("prod")?.previewBase === "https://www.webcake.me");
@@ -552,11 +600,23 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     check("preview url from an absolute api url → preview host", toPreviewUrl(localCfg, "http://localhost:5800/preview/abc?x=1") === "http://preview.localhost:5800/preview/abc?x=1");
     check("preview url passthrough when empty", toPreviewUrl(localCfg, undefined) === undefined);
     check("preview url falls back to builder when previewBase missing", toPreviewUrl({ ...localCfg, previewBase: undefined }, "/preview/abc") === "http://builder.localhost:5800/preview/abc");
-    // publish request preview: JWT must be masked everywhere.
-    const pub = buildPublishRequestRedacted({ ...localCfg, jwt: "SECRETJWT" }, "pg1", JSON.stringify({ page: [] }), { customDomain: "shop.example.com", customPath: "sale" });
-    check("publish request hits the editor publish route on the BUILDER host", pub.url === "http://builder.localhost:5800/api/pages/pg1/edit/publish", pub.url);
-    check("publish request masks the JWT", !JSON.stringify(pub).includes("SECRETJWT"), pub);
-    check("publish request carries domain/path + source string", pub.body.includes("shop.example.com") && pub.body.includes("custom_path") && pub.body.includes("is_publish"), pub.body);
+    // publish request preview: JWT must be masked everywhere. Without a build
+    // (willRender=false) the LEGACY source-only route is used…
+    const pub = buildPublishRequestRedacted({ ...localCfg, jwt: "SECRETJWT" }, "pg1", { page: [] }, { customDomain: "shop.example.com", customPath: "sale" });
+    check("legacy publish preview hits /edit/publish on the BUILDER host", pub.url === "http://builder.localhost:5800/api/pages/pg1/edit/publish", pub.url);
+    check("legacy publish preview masks the JWT", !JSON.stringify(pub).includes("SECRETJWT"), pub);
+    check("legacy publish preview carries domain/path + source string", pub.body.includes("shop.example.com") && pub.body.includes("custom_path") && pub.body.includes("is_publish"), pub.body);
+    check("legacy publish preview is marked rendered:false", pub.rendered === false, pub);
+    // …with a build (willRender=true) the editor's publish_html route — the only
+    // one that writes the PagePublishedV2 record public serving reads — is used,
+    // with the editor-shaped body (data_node, no `source` key).
+    const pubHtml = buildPublishRequestRedacted({ ...localCfg, jwt: "SECRETJWT" }, "pg1", { page: [], options: { mobileOnly: true } }, { customDomain: "shop.example.com" }, true);
+    check("rendered publish preview hits /edit/publish_html on the BUILDER host", pubHtml.url === "http://builder.localhost:5800/api/pages/pg1/edit/publish_html", pubHtml.url);
+    check("rendered publish preview masks the JWT", !JSON.stringify(pubHtml).includes("SECRETJWT"), pubHtml);
+    check("rendered publish preview uses the editor body shape", pubHtml.body.includes("data_node") && pubHtml.body.includes("selected_custom_domain") && pubHtml.body.includes("render_type"), pubHtml.body);
+    check("rendered publish preview folds mobile_only into settings", pubHtml.body.includes('"mobile_only":true'), pubHtml.body);
+    check("rendered publish preview stands in a placeholder for the unbuilt app", pubHtml.body.includes("built by the build host"), pubHtml.body);
+    check("rendered publish preview is marked rendered:true", pubHtml.rendered === true, pubHtml);
 }
 console.log("== login: connect URL + loopback callback parsing (offline) ==");
 {

package/dist/tools/persistence.js

@@ -17,6 +17,46 @@ import { putDraft, getDraft, updateDraft, deleteDraft } from "../persistence/dra
 export function registerPersistenceTools(server, domain) {
     // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
     const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
+    // After a successful CREATE, build the rendered app and publish via the
+    // editor's publish_html route so the page renders immediately — without this
+    // a fresh page's preview is a blank shell until publish_page runs or the page
+    // is re-saved in the editor. Failures here never fail the create (the page
+    // exists either way); the result tells the caller how to retry. Skipped when
+    // no build host is configured (a source-only legacy publish renders nothing).
+    const autoPublish = async (config, pageId, source) => {
+        if (!config.buildBase) {
+            return {
+                published: false,
+                skipped: true,
+                note: "No build host configured (WEBCAKE_BUILD_BASE env / x-webcake-build-base header; prod preset auto-configures https://build.webcake.io) — created source-only; the preview stays blank until publish_page runs with a build host or the page is re-saved in the editor.",
+            };
+        }
+        console.error(`[create_page] auto-publish: building ${pageId} via ${config.buildBase}`);
+        const build = await buildPageApp(config.buildBase, pageId, source);
+        if (!build.ok) {
+            console.error(`[create_page] auto-publish build failed: ${build.error}`);
+            return {
+                published: false,
+                error: `Build host failed (${build.error ?? "unknown error"})`,
+                hint: `The page was CREATED fine — only the rendering publish failed. Retry via publish_page({ page_id: "${pageId}", dry_run: false }).`,
+            };
+        }
+        const outcome = await publishPage(config, pageId, source, { app: build.app, app_css: build.app_css });
+        if (!outcome.ok) {
+            console.error(`[create_page] auto-publish publish failed: ${outcome.error}`);
+            return {
+                published: false,
+                status: outcome.status,
+                error: outcome.error,
+                hint: `The page was CREATED fine — only the rendering publish failed. Retry via publish_page({ page_id: "${pageId}", dry_run: false }).`,
+            };
+        }
+        return {
+            published: true,
+            rendered: true,
+            note: "Auto-published (no domain): the preview link renders for ~10 minutes after each publish, then expires. For a permanent public URL attach a domain via publish_page({ page_id, custom_domain, dry_run:false }).",
+        };
+    };
     // 8) List organizations -----------------------------------------------------
     server.tool("list_organizations", "Returns the account's Webcake organizations (id, name, is_default). The default org (type===1, usually the personal workspace) is where pages normally go. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {}, { title: "List Webcake Organizations", readOnlyHint: true, openWorldHint: true }, async (_args, extra) => {
         const { config, missing } = cfgFor(extra);
@@ -31,7 +71,7 @@ export function registerPersistenceTools(server, domain) {
         return text(await listOrganizations(config));
     });
     // 9) Create page (persist) --------------------------------------------------
-    server.tool("create_page", "Persists a page source to the configured Webcake backend: creates a NEW page and saves the source (source-only — opens in the editor where re-saving renders it). Validates first. DEFAULTS to dry_run=true (validates, caches the source as draft_id, returns the HTTP request it WOULD send, token masked); dry_run=false to actually create. Accepts draft_id from a previous call (validation failure, dry_run, or a timed-out create) — re-runs from the cached source without re-sending the full JSON. Organization resolution on the real run (dry_run=false): (1) explicit organization_id wins; pass the string 'personal' to save without any org. (2) WEBCAKE_ORG_ID env / x-webcake-org-id header wins. (3) Otherwise list_organizations is called: 0 orgs or lookup fails → personal (no org); exactly 1 org → used automatically (result includes organization_auto_selected:true); 2+ orgs → returns ok:false with the org list and asks the caller to re-call with organization_id. Real writes need WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+    server.tool("create_page", "Persists a page source to the configured Webcake backend: creates a NEW page, saves the source, then AUTO-PUBLISHES it (builds the rendered app on the build host + publishes via the editor's publish_html route) so the preview renders immediately — set publish:false to skip, and note the no-domain preview link still expires ~10 minutes after each publish (publish_page with custom_domain gives a permanent URL). A failed auto-publish never fails the create (result.publish says how to retry). Validates first. DEFAULTS to dry_run=true (validates, caches the source as draft_id, returns the HTTP request it WOULD send, token masked); dry_run=false to actually create. Accepts draft_id from a previous call (validation failure, dry_run, or a timed-out create) — re-runs from the cached source without re-sending the full JSON. Organization resolution on the real run (dry_run=false): (1) explicit organization_id wins; pass the string 'personal' to save without any org. (2) WEBCAKE_ORG_ID env / x-webcake-org-id header wins. (3) Otherwise list_organizations is called: 0 orgs or lookup fails → personal (no org); exactly 1 org → used automatically (result includes organization_auto_selected:true); 2+ orgs → returns ok:false with the org list and asks the caller to re-call with organization_id. Real writes need WEBCAKE_API_BASE + WEBCAKE_JWT.", {
         source: z
             .any()
             .optional()
@@ -49,7 +89,11 @@ export function registerPersistenceTools(server, domain) {
             .boolean()
             .optional()
             .describe("Default TRUE — validate, cache the source as draft_id, and preview the request without sending. Set false to actually create."),
-    }, { title: "Create Webcake Page", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ source, draft_id, name, organization_id, dry_run }, extra) => {
+        publish: z
+            .boolean()
+            .optional()
+            .describe("Default TRUE — after a successful create, automatically build the rendered app and publish (publish_html) so the preview renders immediately. Set false to create source-only (blank preview until publish_page runs)."),
+    }, { title: "Create Webcake Page", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ source, draft_id, name, organization_id, dry_run, publish }, extra) => {
         const isDry = dry_run !== false; // default true (safe)
         // --- Resolve source: from cache (draft_id) or from the argument ---
         let expanded;
@@ -60,7 +104,7 @@ export function registerPersistenceTools(server, domain) {
                 return text({
                     created: false,
                     reason: "draft_expired",
-                    hint: "The cached draft is gone (expired after ~30 min or evicted). Re-send the full source via create_page({ source:…, dry_run:false }).",
+                    hint: "The cached draft is gone (expired after ~2 h or evicted). Re-send the full source via create_page({ source:…, dry_run:false }).",
                 });
             }
             if (cached.kind != null && cached.kind !== "page") {
@@ -104,7 +148,7 @@ export function registerPersistenceTools(server, domain) {
                 errors: result.errors,
                 ...warningsField(result.warnings),
                 draft_id: existingDraftId,
-                hint: "Do NOT rebuild the whole source — it is cached as draft_id. Fix ONLY the listed elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged tree and creates the page. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements/get_element if unsure of the exact type name). The draft expires in ~30 min.",
+                hint: "Do NOT rebuild the whole source — it is cached as draft_id. Each error names the offending element id — fix ONLY those elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged tree and creates the page. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements/get_element if unsure). A stray/extra key ('must NOT have additional properties') → { op:'replace', id, element:<clean node> } — op:'update' MERGES and cannot delete a key. The draft expires in ~2 h.",
             });
         }
         const parsed = domain.coerce(expanded);
@@ -149,6 +193,11 @@ export function registerPersistenceTools(server, domain) {
                 missing_env: missing,
                 target_organization_id: orgId ?? config?.orgId ?? null,
                 organization_note: organizationNote,
+                publish_step: publish === false
+                    ? { would_run: false, note: "publish:false — the real run will create source-only (blank preview until publish_page)." }
+                    : config?.buildBase
+                        ? { would_run: true, build_host: config.buildBase, note: "After creating, the real run auto-builds the rendered app and publishes (publish_html) so the preview renders immediately." }
+                        : { would_run: false, note: "No build host configured — the real run creates source-only (blank preview). Set WEBCAKE_BUILD_BASE env or x-webcake-build-base header (prod preset auto-configures) to enable auto-publish." },
                 draft_id: existingDraftId,
                 request: config
                     ? buildRequestRedacted(config, pageName, parsed, orgId)
@@ -238,9 +287,15 @@ export function registerPersistenceTools(server, domain) {
         const outcome = await createPage(config, pageName, parsed, resolvedOrgId);
         if (outcome.ok) {
             deleteDraft(existingDraftId); // created — drop the draft
+            // Auto-publish (default): build + publish_html so the preview renders
+            // immediately. Never fails the create — result.publish carries the state.
+            const publishOutcome = publish === false
+                ? { published: false, skipped: true, note: "publish:false — created source-only; the preview stays blank until publish_page runs." }
+                : await autoPublish(config, outcome.page_id, parsed);
             return text({
                 created: true,
                 ...outcome,
+                publish: publishOutcome,
                 ...warningsField(result.warnings),
                 ...(organizationAutoSelected ? { organization_auto_selected: true } : {}),
                 ...(organizationNote ? { note: organizationNote } : {}),
@@ -248,12 +303,21 @@ export function registerPersistenceTools(server, domain) {
         }
         // Failure (including timeout): keep the draft so the model can retry.
         updateDraft(existingDraftId, expanded);
+        // A backend 404/5xx on a route that normally works is usually a transient
+        // deploy/restart window — the fix is to RETRY THE SAME REQUEST, not to
+        // change parameters. (Observed failure mode: a transient 404 with an
+        // organization_id made the model "work around" it by dropping the org —
+        // the page then landed in personal instead of the requested workspace.)
+        const transient = outcome.status === 404 || (outcome.status ?? 0) >= 500 || outcome.status === 0;
         return text({
             created: false,
             ...outcome,
             ...warningsField(result.warnings),
             draft_id: existingDraftId,
-            hint: `Create failed — source is cached. Retry via create_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ draft_id: "${existingDraftId}", patches:[…], dry_run:false }). The draft expires in ~30 min.`,
+            hint: `Create failed — source is cached. Retry via create_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ draft_id: "${existingDraftId}", patches:[…], dry_run:false }). The draft expires in ~2 h.` +
+                (transient
+                    ? ` A ${outcome.status === 0 ? "network error" : outcome.status} from the backend is usually TRANSIENT (deploy/restart window) — retry the SAME draft with the SAME organization_id after a short pause. Do NOT drop or change organization_id to work around it: the page would land in the wrong workspace.`
+                    : ""),
         });
     });
     // 10) List pages ------------------------------------------------------------
@@ -354,7 +418,7 @@ export function registerPersistenceTools(server, domain) {
                 return text({
                     updated: false,
                     reason: "draft_expired",
-                    hint: "The cached draft is gone (expired after ~30 min or evicted). Re-send the full source via update_page({ page_id, source:…, dry_run:false }).",
+                    hint: "The cached draft is gone (expired after ~2 h or evicted). Re-send the full source via update_page({ page_id, source:…, dry_run:false }).",
                 });
             }
             if (cached.kind !== "update") {
@@ -441,7 +505,7 @@ export function registerPersistenceTools(server, domain) {
             ...outcome,
             ...warningsField(result.warnings),
             draft_id: existingDraftId,
-            hint: `Update failed — source is cached. Retry via update_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ page_id: "${resolvedPageId}", patches:[…] }). The draft expires in ~30 min.`,
+            hint: `Update failed — source is cached. Retry via update_page({ draft_id: "${existingDraftId}", dry_run: false }) or fix elements via patch_page({ page_id: "${resolvedPageId}", patches:[…] }). The draft expires in ~2 h.`,
         });
     });
     // 13) Add section (incremental build) ---------------------------------------
@@ -514,7 +578,7 @@ export function registerPersistenceTools(server, domain) {
                 return text({
                     added: false,
                     reason: "draft_expired",
-                    hint: "The cached section draft is gone (expired after ~30 min or evicted). Re-send the sections via add_section({ page_id, sections:[…] }).",
+                    hint: "The cached section draft is gone (expired after ~2 h or evicted). Re-send the sections via add_section({ page_id, sections:[…] }).",
                 });
             }
             if (cached.kind !== "sections") {
@@ -571,7 +635,7 @@ export function registerPersistenceTools(server, domain) {
                 errors: result.errors,
                 ...warningsField(result.warnings),
                 draft_id: existingDraftId,
-                hint: "Do NOT rebuild the section batch — it is cached as draft_id. Fix ONLY the listed elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged shell and appends the sections. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' }. The draft expires in ~30 min.",
+                hint: "Do NOT rebuild the section batch — it is cached as draft_id. Each error names the offending element id — fix ONLY those elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged shell and appends the sections. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' }. A stray/extra key ('must NOT have additional properties') → { op:'replace', id, element:<clean node> } — op:'update' MERGES and cannot delete a key. The draft expires in ~2 h.",
             });
         }
         const { config, missing } = cfgFor(extra);
@@ -756,13 +820,13 @@ export function registerPersistenceTools(server, domain) {
         }
         return touched;
     };
-    server.tool("patch_page", "Edits a page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Targets EITHER a live page (page_id) OR a cached draft source (draft_id). Draft sources come from: (a) create_page — failed validation or timed-out network call → patched/committed tree is CREATED as a new page once valid; (b) add_section dry_run or validation/network failure → patched/committed shell is APPENDED to the stored page once valid; (c) update_page or live-page patch_page — timed-out/failed network call → re-committed via updatePageSource. Send only a list of per-element ops; the MCP loads the source, applies them, validates the WHOLE merged tree (blocks on errors), and saves. Ops: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'; `type` fixes a wrong element type), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. EMPTY/OMITTED patches with a draft_id = commit the cached draft as-is (skip apply, still validate, then honor dry_run) — this is the RETRY PATH after a timeout. Use this to fix the elements a failed create_page/update_page/add_section reported instead of rebuilding. DEFAULTS to dry_run=true (loads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (a draft_id sections-patch only needs creds to actually append; a page_id patch reads the live page so needs creds even on dry_run).", {
+    server.tool("patch_page", "Edits a page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Targets EITHER a live page (page_id) OR a cached draft source (draft_id). Draft sources come from: (a) create_page — failed validation or timed-out network call → patched/committed tree is CREATED as a new page once valid; (b) add_section dry_run or validation/network failure → patched/committed shell is APPENDED to the stored page once valid; (c) update_page or live-page patch_page — timed-out/failed network call → re-committed via updatePageSource. Send only a list of per-element ops; the MCP loads the source, applies them, validates the WHOLE merged tree (blocks on errors), and saves. Ops: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'; `type` fixes a wrong element type; update CANNOT delete an existing/stray key — schema 'additional properties' errors need op:'replace'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. EMPTY/OMITTED patches with a draft_id = commit the cached draft as-is (skip apply, still validate, then honor dry_run) — this is the RETRY PATH after a timeout. Use this to fix the elements a failed create_page/update_page/add_section reported instead of rebuilding. DEFAULTS to dry_run=true (loads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (a draft_id sections-patch only needs creds to actually append; a page_id patch reads the live page so needs creds even on dry_run).", {
         page_id: z.string().optional().describe("Edit a LIVE page by id (from create_page, list_pages, or find_pages; must be owned by the account). Provide page_id OR draft_id. For a sections or update draft_id you may also pass page_id here to override the stored page target."),
         draft_id: z.string().optional().describe("Commit or fix a CACHED source: from create_page (failed/timed-out → new page created once valid), add_section (dry_run or failure → sections appended), or update_page/live-page patch (timed-out/failed → updatePageSource retried). The originating tool's error/dry_run response returns draft_id. Provide page_id OR draft_id. Empty/omitted patches = commit the cached draft as-is (the RETRY PATH after a timeout)."),
         patches: z
             .any()
             .optional()
-            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted; set `type` to fix a wrong element type); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container. `element` may be a SPARSE node (id/type/styles/specials/events only) — the server hydrates omitted boilerplate from factory defaults. OMIT (or pass empty array) when draft_id is given and you just want to commit/retry the cached draft as-is."),
+            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted; set `type` to fix a wrong element type; update MERGES — it cannot DELETE an existing/stray key, so 'must NOT have additional properties' errors need op:'replace' with a clean node); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container. `element` may be a SPARSE node (id/type/styles/specials/events only) — the server hydrates omitted boilerplate from factory defaults. OMIT (or pass empty array) when draft_id is given and you just want to commit/retry the cached draft as-is."),
         dry_run: z
             .boolean()
             .optional()
@@ -787,7 +851,7 @@ export function registerPersistenceTools(server, domain) {
                 return text({
                     patched: false,
                     reason: "draft_expired",
-                    hint: "The cached draft is gone (expired after ~30 min or evicted). Re-send the full source via create_page.",
+                    hint: "The cached draft is gone (expired after ~2 h or evicted). Re-send the full source via create_page.",
                 });
             }
             base = draft.source; // already an expanded full tree
@@ -931,7 +995,7 @@ export function registerPersistenceTools(server, domain) {
                     ...warningsField(result.warnings),
                     patches_applied: applied,
                     draft_id,
-                    hint: "Still invalid — fix the remaining errors with another patch_page({ draft_id, patches:[…] }). Your applied fixes are kept in the draft.",
+                    hint: "Still invalid — fix the remaining errors with another patch_page({ draft_id, patches:[…] }); your applied fixes are kept in the draft. Each error names the offending element id — target THAT id. A stray/extra key ('must NOT have additional properties') needs op:'replace' with a clean node (op:'update' merges; it cannot delete a key). Do NOT rebuild with create_page — the draft already holds everything.",
                 });
             }
             const parsed = domain.coerce(expanded);
@@ -1071,6 +1135,9 @@ export function registerPersistenceTools(server, domain) {
             else {
                 updateDraft(draft_id, base); // keep for retry
             }
+            // A page created via the fix-after-error path gets the same auto-publish
+            // as a direct create_page (build + publish_html so the preview renders).
+            const publishOutcome = outcome.ok ? await autoPublish(config, outcome.page_id, parsed) : undefined;
             return text({
                 patched: outcome.ok,
                 created: outcome.ok,
@@ -1081,6 +1148,7 @@ export function registerPersistenceTools(server, domain) {
                 preview_url: outcome.preview_url,
                 status: outcome.status,
                 error: outcome.error,
+                ...(publishOutcome ? { publish: publishOutcome } : {}),
                 ...warningsField(result.warnings),
                 ...(outcome.ok ? {} : { draft_id, hint: `Create failed — fixes kept in draft. Retry patch_page({ draft_id: "${draft_id}", dry_run:false }) or resolve the error first.` }),
             });
@@ -1134,11 +1202,11 @@ export function registerPersistenceTools(server, domain) {
             error: outcome.error,
             ...warningsField(result.warnings),
             draft_id: liveDraftId,
-            hint: `Save failed — the patched source is cached. Retry via patch_page({ draft_id: "${liveDraftId}", dry_run: false }) with no patches. The draft expires in ~30 min.`,
+            hint: `Save failed — the patched source is cached. Retry via patch_page({ draft_id: "${liveDraftId}", dry_run: false }) with no patches. The draft expires in ~2 h.`,
         });
     });
     // 15) Publish page (go live) -------------------------------------------------
-    server.tool("publish_page", "Publishes an EXISTING page: builds the rendered app via the Webcake build host (POST <buildBase>/render/build) when available — prod default https://build.webcake.io, override with WEBCAKE_BUILD_BASE env / x-webcake-build-base header — so the published page and /preview/<page_id> render immediately without opening the editor. When no build host is configured or the build fails, falls back to source-only publish with a warning (page will appear blank until re-saved in the Webcake editor or a build host is configured). Saves the source as a new version and creates/updates the page_published record (live status), optionally attaching a custom domain/path. DEFAULTS to dry_run=true (network-free: does NOT call the build host on dry_run). Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+    server.tool("publish_page", "Publishes an EXISTING page LIVE via the editor's publish_html route: builds the rendered app on the Webcake build host (POST <buildBase>/render/build; prod default https://build.webcake.io, override with WEBCAKE_BUILD_BASE env / x-webcake-build-base header), then creates/updates the PagePublishedV2 record — the record ALL public serving reads. With custom_domain the page goes live at that domain (it must already point at Webcake). WITHOUT a domain there is NO permanent public URL: the returned preview link (<previewBase>/preview/<page_id>) only renders for ~10 minutes after the publish, then shows 'Preview page is expired' — tell the user to attach a domain for a lasting URL. If no build host is configured or the build fails, falls back to the LEGACY source-only publish route with a warning (saves a version; nothing goes live; the page stays blank). DEFAULTS to dry_run=true (network-free: does NOT call the build host on dry_run). Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
         page_id: z.string().describe("The page id to publish (must be owned by the account)."),
         custom_domain: z
             .string()
@@ -1152,15 +1220,18 @@ export function registerPersistenceTools(server, domain) {
         if (!config)
             return text({ published: false, reason: "missing_env", missing_env: missing });
         // Publish re-saves the page's CURRENT stored source (the publish endpoint
-        // requires the source in the request), so read it first — even on dry_run,
-        // to show the real payload.
+        // requires it in the request), so read it first — even on dry_run, to show
+        // the real payload.
         const res = await getPageSource(config, page_id);
         if (!res.ok || res.source == null) {
             return text({ published: false, reason: "page_not_found", status: res.status, error: res.error ?? "No source on this page." });
         }
-        const sourceString = JSON.stringify(res.source);
         const opts = { customDomain: custom_domain, customPath: custom_path };
         const buildBase = config.buildBase;
+        // Only the preview window serves a domain-less publish, and only briefly.
+        const previewExpiryNote = custom_domain
+            ? undefined
+            : "No custom_domain — the page has NO permanent public URL. The preview link only renders for ~10 minutes after the publish, then shows 'Preview page is expired'. Attach a custom_domain (already pointed at Webcake) for a lasting URL.";
         if (isDry) {
             // dry_run is network-free — do NOT call the build host.
             return text({
@@ -1171,13 +1242,16 @@ export function registerPersistenceTools(server, domain) {
                     ? `https://${custom_domain}${custom_path ? `/${custom_path}` : ""}`
                     : toPreviewUrl(config, `/preview/${page_id}`),
                 build_step: buildBase
-                    ? { would_run: true, build_host: buildBase, note: "Build host will be called on dry_run=false to produce rendered app/app_css." }
-                    : { would_run: false, note: "No build host configured — publish will be source-only. Set WEBCAKE_BUILD_BASE env or x-webcake-build-base header (prod preset: https://build.webcake.io) to enable rendered output." },
-                request: buildPublishRequestRedacted(config, page_id, sourceString, opts),
+                    ? { would_run: true, build_host: buildBase, note: "Build host will be called on dry_run=false to produce rendered app/app_css, then the page is published live via the editor's publish_html route." }
+                    : { would_run: false, note: "No build host configured — publish will fall back to the LEGACY source-only route (nothing goes live). Set WEBCAKE_BUILD_BASE env or x-webcake-build-base header (prod preset: https://build.webcake.io) to publish for real." },
+                ...(previewExpiryNote ? { note: previewExpiryNote } : {}),
+                request: buildPublishRequestRedacted(config, page_id, res.source, opts, !!buildBase),
                 hint: "Re-run with dry_run=false to actually publish.",
             });
         }
-        // Real publish: attempt to build app/app_css first when a build host is available.
+        // Real publish: build app/app_css first — required for the publish_html
+        // (live) route. Without a successful build we fall back to the legacy
+        // source-only route rather than publishing a blank PagePublishedV2 record.
         let app;
         let app_css;
         let rendered = false;
@@ -1192,17 +1266,20 @@ export function registerPersistenceTools(server, domain) {
                 console.error(`[publish_page] build ok — app ${app?.length ?? 0}B css ${app_css?.length ?? 0}B`);
             }
             else {
-                buildWarning = `Build host failed (${buildResult.error ?? "unknown error"}) — publishing source-only. The page will appear blank until it is re-saved in the Webcake editor or a working build host is configured.`;
+                buildWarning = `Build host failed (${buildResult.error ?? "unknown error"}) — fell back to the legacy source-only publish: a version was saved but NOTHING WENT LIVE (the live publish_html route needs the rendered app). Fix the build host and re-run publish_page.`;
                 console.error(`[publish_page] build failed: ${buildResult.error}`);
             }
         }
         else {
-            buildWarning = "No build host configured (WEBCAKE_BUILD_BASE env / x-webcake-build-base header; prod preset has https://build.webcake.io automatically). Publishing source-only — the page will appear blank until it is re-saved in the Webcake editor or a build host is configured.";
+            buildWarning = "No build host configured (WEBCAKE_BUILD_BASE env / x-webcake-build-base header; prod preset has https://build.webcake.io automatically). Fell back to the legacy source-only publish: a version was saved but NOTHING WENT LIVE (the live publish_html route needs the rendered app).";
         }
         const publishOpts = { ...opts, app, app_css };
-        const outcome = await publishPage(config, page_id, sourceString, publishOpts);
+        const outcome = await publishPage(config, page_id, res.source, publishOpts);
         return text({
             published: outcome.ok,
+            // live = the PagePublishedV2 record public serving reads was written
+            // (publish_html route). The legacy fallback only saves a version.
+            live: outcome.ok && rendered,
             rendered,
             page_id,
             url: outcome.published_url,
@@ -1211,6 +1288,7 @@ export function registerPersistenceTools(server, domain) {
             path: outcome.path,
             status: outcome.status,
             error: outcome.error,
+            ...(outcome.ok && previewExpiryNote ? { note: previewExpiryNote } : {}),
             ...(buildWarning ? { warning: buildWarning } : {}),
         });
     });

package/package.json

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