webcake-landing-mcp 1.0.49 → 1.0.51

package/README.md

@@ -89,7 +89,7 @@ persists it (source-only — the page opens in the editor where re-saving render
 | **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, a JWT, or none (reference tools) |
 | **Hosted URL** — use our live server, nothing to install | No Node.js, teams, the claude.ai dialog | your personal `?jwt=` link / `x-webcake-jwt` header |
 
-The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `patch_page`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
+The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `patch_page`, `publish_page`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 > 🛠️ Prefer a shell-script installer (`install.sh`/`install.ps1`), a cloned local build, or hand-written per-IDE config? See **[docs/manual-install.md](docs/manual-install.md)**.
 
@@ -222,7 +222,8 @@ lands in logs). Any header that's missing falls back to the matching env var:
 | `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 SPA base (login connect page) |
-| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor/preview links |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor links |
+| `x-webcake-preview-base` | `WEBCAKE_PREVIEW_BASE` | overrides the public preview host used for `/preview/<id>` 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
@@ -292,7 +293,8 @@ flow can also be done entirely in the SPA, no backend route needed.)
 | `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 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_BUILDER_BASE` | No | Optional builder host for the editor links in the result. Defaults to the env preset, else derived from the API host (`api.x`→`builder.x`). |
+| `WEBCAKE_PREVIEW_BASE` | No | Optional public preview host for the `/preview/<id>` links — NOT the builder subdomain. Defaults to the env preset (`preview.localhost:5800` local / `staging.webcake.me` staging / `www.webcake.me` prod). |
 | `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
@@ -417,8 +419,12 @@ update_page({ page_id, source, dry_run: false })         # overwrite (dry_run=tr
 # Build a LARGE page incrementally (avoids the giant single create_page payload
 # that can drop the connection): small skeleton first, then one section at a time.
 create_page({ source: smallSkeleton, dry_run: false })   # → page_id
-add_section({ page_id, sections: heroSection, dry_run: false })   # backend appends server-side (no whole-source get+put)
-add_section({ page_id, sections: [formSection, footerSection], dry_run: false })
+add_section({ page_id, sections: heroSection })          # dry_run=true → validates + returns draft_id
+add_section({ page_id, draft_id, dry_run: false })       # re-run with draft_id — no re-send of sections
+add_section({ page_id, sections: [formSection, footerSection], dry_run: false })  # or skip dry-run entirely
+
+# Go LIVE (the preview link works without this — publish to attach a domain / set live status)
+publish_page({ page_id, custom_domain: "shop.example.com", custom_path: "sale", dry_run: false })
 ```
 
 `create_page` calls **`POST {WEBCAKE_API_BASE}/api/v1/ai/create_page_from_source`** on the backend.
@@ -462,11 +468,14 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 | Tool | Description |
 |------|-------------|
 | `list_organizations` | List the account's organizations (id, name, is_default). Default = the `is_default` org. |
-| `create_page` | Persist a generated source as a new page (source-only). **Defaults to `dry_run=true`.** |
+| `create_page` | Persist a generated source as a new page (source-only). Validates, caches the source as `draft_id`, then creates. On validation failure, timeout, or network error the draft is kept — retry via `create_page({ draft_id, dry_run:false })` or fix via `patch_page({ draft_id, patches })`. **Defaults to `dry_run=true`.** |
 | `list_pages` | List the account's pages (id, name, organization_id, updated_at) to pick one to edit. |
 | `find_pages` | Search the account's pages by name, domain, and/or page id (AND-combined) to locate one to edit; returns id, name, org, custom/default domain, updated_at. |
 | `get_page` | Fetch an existing page's decoded source tree, COMPACTED to the sparse authoring shape (factory-default boilerplate stripped — far fewer tokens; `compact:false` for the raw tree). Edit and send back as-is. |
-| `update_page` | Overwrite an existing page's source with an edited tree. **Defaults to `dry_run=true`.** |
+| `update_page` | Overwrite an existing page's source with an edited tree. Validates, caches the source as `draft_id`, then saves. On timeout or failure the draft is kept — retry via `update_page({ draft_id, dry_run:false })` or `patch_page({ draft_id, dry_run:false })` (no patches). **Defaults to `dry_run=true`.** |
+| `add_section` | Append section(s) to an existing page without re-sending the whole source (incremental-build path). Always caches the batch as `draft_id`; re-run with `{ page_id, draft_id, dry_run:false }` — no need to re-send sections. Validation failure, timeout, or network error also keeps the draft — fix via `patch_page({ draft_id, patches })` or retry `patch_page({ draft_id, dry_run:false })` with no patches. **Defaults to `dry_run=true`.** |
+| `patch_page` | Edit a page by element id without re-sending the whole source. Targets a live page (`page_id`) OR a cached draft (`draft_id`). Draft kinds: `create_page` (creates page once valid), `add_section` (appends once valid), `update_page`/live-patch (retries updatePageSource). **Empty/omitted patches + `draft_id` = commit-as-is (the universal timeout-retry path).** Live-page path pre-caches the patched source before the network call and returns `draft_id` for recovery. **Defaults to `dry_run=true`.** |
+| `publish_page` | Publish a page (live status, optional custom domain/path). The preview link works WITHOUT publishing — publish only to go live. **Defaults to `dry_run=true`.** |
 
 ---
 

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.51",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "create_page, update_page, and add_section dry-run responses now include a draft_id, and all three tools now accept draft_id as an input parameter:…",
+    "vi": "Các response dry-run của create_page, update_page và add_section nay đều trả về draft_id, đồng thời cả ba công cụ đều nhận draft_id làm tham số đầu…"
+  },
+  {
+    "v": "1.0.50",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "New publish_page tool makes a page live: reads the page's current stored source, saves it as a new version, and creates or updates the…",
+    "vi": "Công cụ publish_page mới giúp đưa trang lên live: đọc source đang lưu của trang, lưu thành phiên bản mới và tạo hoặc cập nhật bản ghi…"
+  },
   {
     "v": "1.0.49",
     "d": "10/06/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "validate_page now emits an advisory warning when no section, button, or text on the page carries a non-neutral color (white, black, or grey),…",
     "vi": "validate_page nay phát cảnh báo tư vấn khi không có section, button hay text nào trên trang mang màu thực sự (không phải trắng, đen hoặc xám), giúp…"
-  },
-  {
-    "v": "1.0.45",
-    "d": "09/06/2026",
-    "type": "Changed",
-    "en": "get_generation_guide workflow condensed to four steps: element-type reads and image fetches are now batched into single calls…",
-    "vi": "Workflow trong get_generation_guide được rút gọn xuống còn bốn bước: việc đọc loại phần tử và tìm ảnh nay được gộp thành các lần gọi batch duy nhất…"
-  },
-  {
-    "v": "1.0.44",
-    "d": "09/06/2026",
-    "type": "Added",
-    "en": "New find_pages tool searches the account's pages by name, domain (matches custom_domain or default_domain), and/or page id (filters are…",
-    "vi": "Công cụ find_pages mới tìm kiếm các trang trong tài khoản theo tên, domain (khớp với custom_domain hoặc default_domain), và/hoặc page id (các bộ lọc…"
   }
 ]

package/dist/domains/landing/instructions.js

@@ -14,10 +14,15 @@ RULES (follow for every request):
 - create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
 - LARGE PAGES (4+ sections) — build INCREMENTALLY to avoid the giant single create_page payload that can drop the connection: create_page with a SMALL skeleton (empty/near-empty page) to get a page_id, then call add_section once per section (each call ships ONLY that section; the backend appends it server-side and rejects duplicate ids — no whole-source get+put). Small pages can still go in one create_page pass.
 - EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates. For a SMALL edit, PREFER patch_page over update_page: send only the changed elements by id (ops: update/replace/remove/add) instead of re-shipping the whole tree — the MCP fetches the live source, merges, validates and saves server-side. Use update_page only when you're rewriting most of the page. Never regenerate the whole tree for a small change.
-- FIX-AFTER-ERROR (don't rebuild — this is the #1 time-waster): when create_page / update_page / add_section returns validation errors, DO NOT regenerate and re-send the whole source. Send only the fix via patch_page:
-  · create_page failed → its error returns a draft_id (the source is cached server-side). Call patch_page({ draft_id, patches:[…], dry_run:false }) with ops fixing ONLY the listed elements; it re-validates the merged tree and CREATES the page. A wrong element type is the most common error → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements if unsure). The draft keeps your fixes across rounds and expires in ~30 min.
-  · update_page / add_section failed → the page already has a page_id → patch_page({ page_id, patches:[…] }) the offending ids.
-  Either way you ship a tiny diff, not the large payload that drops the connection.
+- FIX-AFTER-ERROR / RETRY-AFTER-TIMEOUT (don't rebuild — this is the #1 time-waster): every mutating tool (create_page, update_page, add_section, patch_page) writes the payload to a draft cache BEFORE the network call and returns a draft_id. On validation failure, timeout, or any network error, the draft is kept — retry or fix without re-sending the full JSON:
+  · create_page failed validation OR timed out → its error returns a draft_id (full source cached). Call patch_page({ draft_id, patches:[…], dry_run:false }) to fix ONLY the listed elements, or retry create_page({ draft_id, dry_run:false }) as-is after a timeout.
+  · add_section failed validation, timed out, or returned dry_run=true → response returns a draft_id (section batch cached). Call patch_page({ draft_id, patches:[…], dry_run:false }) to fix elements and append, or retry patch_page({ draft_id, dry_run:false }) (no patches) to commit as-is.
+  · update_page timed out or failed → response returns a draft_id (full source cached). Retry update_page({ draft_id, dry_run:false }) or patch_page({ draft_id, dry_run:false }) with no patches.
+  · 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.
+- 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 and ask which to use; default to the is_default org. 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. (2) HTML string → call ingest_html(html) to get a compact AST. (3) URL → call ingest_url(url) for the same AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts) — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. 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.
 
@@ -32,4 +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). PREFER REAL PHOTOS — 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.
 
-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, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page.`;
+- 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 }).
+
+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, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page, publish_page.`;

package/dist/persistence/config.js

@@ -19,8 +19,11 @@
  *   WEBCAKE_JWT       the account JWT               (required to call the backend)
  *   WEBCAKE_ORG_ID    optional default organization id for create_page
  *   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
+ *   WEBCAKE_BUILDER_BASE  optional builder host for the editor URLs in the result
  *                     (defaults to the env preset, else derived from the API host)
+ *   WEBCAKE_PREVIEW_BASE  optional public preview host for the /preview/<id> links —
+ *                     NOT the builder subdomain (defaults to the env preset:
+ *                     preview.localhost:5800 / staging.webcake.me / www.webcake.me)
  *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
  */
 import { homedir } from "node:os";
@@ -36,9 +39,9 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
  * 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", 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" },
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800", previewBase: "http://preview.localhost:5800" },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io", previewBase: "https://staging.webcake.me" },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io", previewBase: "https://www.webcake.me" },
 };
 export const ENV_NAMES = Object.keys(ENVIRONMENTS);
 /** True when `v` names a known environment (local|staging|prod). */
@@ -88,6 +91,16 @@ export function readConfig(overrides = {}) {
         preset?.builderBase ??
         saved.builderBase ??
         deriveBuilderBase(cleanBase))?.replace(/\/+$/, "");
+    // The public preview link (/preview/<id>) is served on its OWN root host — NOT
+    // the builder subdomain (preview.localhost:5800 / staging.webcake.me /
+    // www.webcake.me). When nothing matches, default to the backend's own preview
+    // domain (its @preview_domain) so the link still lands on a host that serves
+    // the /preview/:id route.
+    const previewBase = (overrides.previewBase ??
+        process.env.WEBCAKE_PREVIEW_BASE ??
+        preset?.previewBase ??
+        saved.previewBase ??
+        "https://www.webcake.me").replace(/\/+$/, "");
     return {
         config: {
             base: cleanBase,
@@ -95,6 +108,7 @@ export function readConfig(overrides = {}) {
             orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
             appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase)?.replace(/\/+$/, ""),
             builderBase,
+            previewBase,
         },
         missing: [],
     };
@@ -111,7 +125,8 @@ function header(headers, name) {
  *   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   SPA base used for the login connect page (overrides the preset)
- *   x-webcake-builder-base  builder host for editor/preview URLs (overrides the preset)
+ *   x-webcake-builder-base  builder host for editor URLs (overrides the preset)
+ *   x-webcake-preview-base  public preview host for /preview/<id> links (overrides the preset)
  * Any header that is absent falls back to the corresponding env var in readConfig.
  */
 export function configFromHeaders(headers) {
@@ -123,6 +138,7 @@ export function configFromHeaders(headers) {
         orgId: header(headers, "x-webcake-org-id"),
         appBase: header(headers, "x-webcake-app-base"),
         builderBase: header(headers, "x-webcake-builder-base"),
+        previewBase: header(headers, "x-webcake-preview-base"),
         env: header(headers, "x-webcake-env"),
     };
 }

package/dist/persistence/draft-cache.js

@@ -1,11 +1,30 @@
 /**
- * Tiny in-memory store for page sources that FAILED create_page validation, so the
- * model can fix ONLY the broken elements (patch_page with a draft_id) instead of
- * re-emitting the whole source. The create-before-save gap: a failed create has no
- * page_id to patch against, so we hold the source here keyed by a random draft_id.
+ * Tiny in-memory store for sources that need a cache — three kinds:
+ *
+ *  - 'page'    (default/absent): a full page source whose create_page FAILED validation
+ *              OR whose create_page network call failed/timed-out after validation passed.
+ *              The create-before-save gap: a failed create has no page_id to patch
+ *              against, so we hold the source here keyed by a random draft_id.
+ *              Commit path: create_page({draft_id, dry_run:false}) or
+ *              patch_page({draft_id, patches?, dry_run:false}).
+ *
+ *  - 'sections': the expanded throwaway shell built by add_section when dry_run=true
+ *              or when section validation fails / the append network call fails, so the
+ *              model never has to re-send the section payload between dry-run → real call
+ *              or after a fix/timeout round.
+ *              `source` holds the shell { page:[<new sections>], … }; `page_id` is
+ *              the live page the sections will be appended to.
+ *              Commit path: add_section({page_id, draft_id, dry_run:false}) or
+ *              patch_page({draft_id, patches?, dry_run:false}).
+ *
+ *  - 'update' : a full page source for updatePageSource on an EXISTING page whose
+ *              update_page/patch_page network call failed or timed-out after validation
+ *              passed. `page_id` is the live page to overwrite.
+ *              Commit path: update_page({draft_id, dry_run:false}) or
+ *              patch_page({draft_id, patches?, dry_run:false}).
  *
  * Bounded + TTL'd; a lost draft (process restart, eviction, expiry) just means the
- * model falls back to re-sending the full source via create_page — never a failure.
+ * model falls back to re-sending the full source — never a failure.
  * Process-global, but draft_ids are random/unguessable AND persisting still uses the
  * CALLER's own creds, so a draft only ever yields a page in the caller's account.
  */

package/dist/persistence/pexels-client.js

@@ -18,6 +18,11 @@
  * route is served by this same server in `serve` mode (see src/http.ts).
  */
 const PEXELS_SEARCH_ENDPOINT = "https://api.pexels.com/v1/search";
+/** Fetch timeout for Pexels/proxy calls — matches the Webcake client default. */
+const PEXELS_TIMEOUT_MS = (() => {
+    const v = parseInt(process.env.WEBCAKE_HTTP_TIMEOUT_MS ?? "", 10);
+    return Number.isFinite(v) && v > 0 ? v : 60_000;
+})();
 /** Default hosted proxy that holds a shared Pexels key (override with PEXELS_PROXY_BASE). */
 export const PEXELS_PROXY_DEFAULT = "https://mcp.toolvn.io.vn";
 /** Path of the proxy's image-search route (served by this server in `serve` mode). */
@@ -72,9 +77,12 @@ export async function searchPexels(key, params) {
     const url = `${PEXELS_SEARCH_ENDPOINT}?${buildSearchQuery(params).toString()}`;
     let res;
     try {
-        res = await fetch(url, { method: "GET", headers: { Authorization: key } });
+        res = await fetch(url, { method: "GET", headers: { Authorization: key }, signal: AbortSignal.timeout(PEXELS_TIMEOUT_MS) });
     }
     catch (e) {
+        if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+            return { ok: false, status: 0, error: `request timed out after ${PEXELS_TIMEOUT_MS}ms calling Pexels` };
+        }
         return { ok: false, status: 0, error: `Network error calling Pexels: ${e?.message ?? e}` };
     }
     const body = await res.text();
@@ -102,9 +110,12 @@ export async function searchImagesViaProxy(base, params) {
     const url = `${base.replace(/\/+$/, "")}${PEXELS_PROXY_PATH}?${buildSearchQuery(params).toString()}`;
     let res;
     try {
-        res = await fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+        res = await fetch(url, { method: "GET", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(PEXELS_TIMEOUT_MS) });
     }
     catch (e) {
+        if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+            return { ok: false, status: 0, error: `request timed out after ${PEXELS_TIMEOUT_MS}ms calling image proxy ${base}` };
+        }
         return { ok: false, status: 0, error: `Network error calling image proxy ${base}: ${e?.message ?? e}` };
     }
     const body = await res.text();

package/dist/persistence/webcake-client.js

@@ -1,3 +1,23 @@
+/** Default fetch timeout in ms. Override via WEBCAKE_HTTP_TIMEOUT_MS env. */
+const HTTP_TIMEOUT_MS = (() => {
+    const v = parseInt(process.env.WEBCAKE_HTTP_TIMEOUT_MS ?? "", 10);
+    return Number.isFinite(v) && v > 0 ? v : 60_000;
+})();
+/** Build an AbortSignal that fires after `ms` milliseconds. */
+function timeoutSignal(ms) {
+    return AbortSignal.timeout(ms);
+}
+/** Wrap a fetch error or AbortError in the standard {ok:false} shape. */
+function timeoutOrNetworkError(url, e) {
+    if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+        return {
+            ok: false,
+            status: 0,
+            error: `request timed out after ${HTTP_TIMEOUT_MS}ms — the backend may still complete it; check before re-creating to avoid duplicates`,
+        };
+    }
+    return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+}
 const CREATE_ENDPOINT = "/api/v1/ai/create_page_from_source";
 const ORGS_ENDPOINT = "/api/v1/org/organizations";
 const PAGES_ENDPOINT = "/api/v1/ai/pages";
@@ -5,6 +25,13 @@ 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)}`;
 function authHeaders(config, orgId) {
     const headers = {
         "Content-Type": "application/json",
@@ -44,6 +71,33 @@ export function toEditorUrl(config, raw) {
         pathQuery = `/${pathQuery}`;
     return `${builder.replace(/\/+$/, "")}${pathQuery}`;
 }
+/**
+ * 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 reads
+ * the stored page_source directly, so the link works without publishing.
+ */
+export function toPreviewUrl(config, raw) {
+    if (!raw)
+        return raw;
+    const preview = config.previewBase;
+    if (!preview)
+        return toEditorUrl(config, raw); // legacy fallback
+    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 `${preview.replace(/\/+$/, "")}${pathQuery}`;
+}
 /** Build (but do not send) the create request — used for dry-run previews. */
 export function buildRequest(config, name, source, orgId) {
     return {
@@ -69,10 +123,10 @@ export async function listOrganizations(config) {
     const url = `${config.base}${ORGS_ENDPOINT}`;
     let res;
     try {
-        res = await fetch(url, { method: "GET", headers: authHeaders(config) });
+        res = await fetch(url, { method: "GET", headers: authHeaders(config), signal: timeoutSignal(HTTP_TIMEOUT_MS) });
     }
     catch (e) {
-        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+        return timeoutOrNetworkError(url, e);
     }
     const text = await res.text();
     let json = null;
@@ -100,10 +154,10 @@ export async function createPage(config, name, source, orgId) {
     const req = buildRequest(config, name, source, orgId);
     let res;
     try {
-        res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+        res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body, signal: timeoutSignal(HTTP_TIMEOUT_MS) });
     }
     catch (e) {
-        return { ok: false, status: 0, error: `Network error calling ${req.url}: ${e?.message ?? e}` };
+        return timeoutOrNetworkError(req.url, e);
     }
     const text = await res.text();
     let json = null;
@@ -134,7 +188,7 @@ export async function createPage(config, name, source, orgId) {
         status: res.status,
         page_id: pageId,
         editor_url: toEditorUrl(config, editorPath),
-        preview_url: toEditorUrl(config, previewPath),
+        preview_url: toPreviewUrl(config, previewPath),
         organization_id: (orgId ?? config.orgId) ?? null,
         raw: data,
     };
@@ -145,10 +199,11 @@ export async function createPage(config, name, source, orgId) {
 async function getJson(url, config) {
     let res;
     try {
-        res = await fetch(url, { method: "GET", headers: authHeaders(config) });
+        res = await fetch(url, { method: "GET", headers: authHeaders(config), signal: timeoutSignal(HTTP_TIMEOUT_MS) });
     }
     catch (e) {
-        return { ok: false, status: 0, json: null, text: "", error: `Network error calling ${url}: ${e?.message ?? e}` };
+        const e2 = timeoutOrNetworkError(url, e);
+        return { ok: false, status: 0, json: null, text: "", error: e2.error };
     }
     const text = await res.text();
     let json = null;
@@ -245,10 +300,11 @@ export async function appendSection(config, pageId, sections) {
             method: "POST",
             headers: authHeaders(config),
             body: JSON.stringify({ page_id: pageId, sections }),
+            signal: timeoutSignal(HTTP_TIMEOUT_MS),
         });
     }
     catch (e) {
-        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+        return timeoutOrNetworkError(url, e);
     }
     // No such route on an older backend → Phoenix 404. Signal a fallback.
     if (res.status === 404) {
@@ -278,7 +334,7 @@ export async function appendSection(config, pageId, sections) {
         status: res.status,
         page_id: pageIdOut,
         editor_url: toEditorUrl(config, data?.editor_url),
-        preview_url: toEditorUrl(config, data?.preview_url),
+        preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         section_count: data?.section_count,
         sections_added: data?.sections_added,
@@ -294,10 +350,11 @@ export async function updatePageSource(config, pageId, source) {
             method: "POST",
             headers: authHeaders(config),
             body: JSON.stringify({ page_id: pageId, source }),
+            signal: timeoutSignal(HTTP_TIMEOUT_MS),
         });
     }
     catch (e) {
-        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+        return timeoutOrNetworkError(url, e);
     }
     const text = await res.text();
     let json = null;
@@ -323,8 +380,115 @@ export async function updatePageSource(config, pageId, source) {
         status: res.status,
         page_id: pageIdOut,
         editor_url: toEditorUrl(config, data?.editor_url),
-        preview_url: toEditorUrl(config, data?.preview_url),
+        preview_url: toPreviewUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         raw: data,
     };
 }
+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.
+    return JSON.stringify({
+        source: sourceString,
+        custom_domain: opts.customDomain ?? "",
+        custom_path: opts.customPath ?? "",
+        is_publish: true,
+    });
+}
+/** Build (but do not send) the publish request with the token masked — for dry-run previews. */
+export function buildPublishRequestRedacted(config, pageId, sourceString, opts = {}) {
+    const body = publishBody(sourceString, opts);
+    return {
+        method: "POST",
+        url: publishUrl(config, pageId),
+        headers: { ...authHeaders(config), Authorization: "Bearer ***JWT***", Cookie: "jwt=***JWT***" },
+        body: body.replace(config.jwt, "***JWT***").slice(0, 400) + (body.length > 400 ? `… (${body.length} bytes)` : ""),
+    };
+}
+/**
+ * POST to a host-scoped route. Node's fetch cannot reach `*.localhost` hosts
+ * (browsers special-case .localhost; Node's DNS does not, and undici forbids a
+ * manual Host header) — so for those we connect to loopback via node:http and
+ * carry the real host in the Host header. Everything else uses plain fetch.
+ */
+async function postToHost(url, headers, body) {
+    const u = new URL(url);
+    if (!u.hostname.endsWith(".localhost")) {
+        const res = await fetch(url, { method: "POST", headers, body, signal: timeoutSignal(HTTP_TIMEOUT_MS) });
+        return { status: res.status, text: await res.text() };
+    }
+    const { request } = await import("node:http");
+    return new Promise((resolve, reject) => {
+        const req = request({
+            host: "127.0.0.1",
+            port: u.port || 80,
+            path: u.pathname + u.search,
+            method: "POST",
+            headers: { ...headers, Host: u.host },
+        }, (res) => {
+            let data = "";
+            res.on("data", (c) => (data += c));
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, text: data }));
+        });
+        req.setTimeout(HTTP_TIMEOUT_MS, () => {
+            req.destroy(new Error(`request timed out after ${HTTP_TIMEOUT_MS}ms`));
+        });
+        req.on("error", reject);
+        req.end(body);
+    });
+}
+/**
+ * Publish a page: saves the source as a new version and creates/updates the
+ * page_published record (live status + optional custom domain/path). Returns the
+ * resulting public URL — `https://<domain>/<path>` when a custom domain is
+ * attached, else the preview-host link (`<previewBase>/preview/<page_id>`).
+ */
+export async function publishPage(config, pageId, sourceString, opts = {}) {
+    const url = publishUrl(config, pageId);
+    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)));
+    }
+    catch (e) {
+        const e2 = timeoutOrNetworkError(url, e);
+        return { ok: false, status: e2.status, error: e2.error };
+    }
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        /* non-JSON */
+    }
+    const resOk = status >= 200 && status < 300;
+    const success = json?.success !== false && resOk;
+    if (!success) {
+        const backendMsg = json?.message ?? json?.reason ?? (json ? undefined : text.slice(0, 200));
+        return {
+            ok: false,
+            status,
+            raw: json ?? text.slice(0, 600),
+            error: `Backend returned ${status}${backendMsg ? `: ${backendMsg}` : ""}`,
+        };
+    }
+    const data = json?.data ?? json;
+    const domain = data?.domain ?? null;
+    const path = data?.path ?? null;
+    const previewUrl = toPreviewUrl(config, `/preview/${pageId}`);
+    const publishedUrl = domain ? `https://${domain}${path ? `/${String(path).replace(/^\/+/, "")}` : ""}` : previewUrl;
+    return {
+        ok: true,
+        status,
+        page_id: pageId,
+        published_url: publishedUrl,
+        preview_url: previewUrl,
+        domain,
+        path,
+        raw: data,
+    };
+}