webcake-landing-mcp 1.0.50 → 1.0.52

package/README.md

@@ -419,8 +419,9 @@ 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 })
@@ -467,11 +468,13 @@ 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.52",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "validate_page now errors when an element type that the renderer cannot animate (any type other than group, image-block, text-block, rectangle,…",
+    "vi": "validate_page nay báo lỗi khi một element có loại không được renderer hỗ trợ animation (chỉ group, image-block, text-block, rectangle, button,…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New patch_page tool edits an existing page by element id without re-sending the whole source: the agent sends per-element ops (update, replace,…",
     "vi": "Công cụ patch_page mới cho phép chỉnh sửa trang hiện có theo element id mà không cần gửi lại toàn bộ source: agent gửi các op theo element (update,…"
-  },
-  {
-    "v": "1.0.46",
-    "d": "09/06/2026",
-    "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…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -101,7 +101,7 @@ RULES
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.
 - events item: { "id", "type", "action", "target", ...action-specific extra fields }. TRIGGER (type): click & hover on any element; success & error on a FORM (success = after a successful submit, error = on validation failure); delay on any element (when it scrolls into view); unset on init. Action vocab per trigger: click→CLICK_ACTIONS, hover→HOVER_ACTIONS, success→SUCCESS_ACTIONS, error→ERROR_ACTIONS, delay→DELAY_ACTIONS (all returned by get_generation_guide). For element-targeting actions (open_popup, close_popup, scroll_to, show_section, hide_section, show_hide_element, change_tab, collapse) target = the target element's id; open_link/download_file target = URL; open_sms/send_email/phone_call target = phone/email; copy target = text (or element id when copyType='elementValue'); set_field_value target = field_name; target may be null (e.g. animation_hover). Each action also reads extra fields (e.g. open_link→targetURL/delayTime, scroll_to→scrollMore, change_tab→moveTo/tabIndex, lightbox→typeLightbox/alt, show_hide_element→onlyMode, open_app→appTarget+provider fields, set_field_value→set_value) — see the action maps for the full list.
-- ANIMATION: each breakpoint's config has config.animation = { "name":"none", "delay":0, "duration":3, "repeat":null }. Keep "none" unless an entrance animation is wanted.
+- ANIMATION: each breakpoint's config has config.animation = { "name":"none", "delay":0, "duration":3, "repeat":null }. Animations only run on these 9 element types: group, image-block, text-block, rectangle, button, countdown, line, list-paragraph, notify (renderer contract: landing_page_build/render/build/animate.js). Any other type with a non-"none" name renders stuck/dim in its pre-animation state — keep "none" on all other types. The name must be from the editor's animate.css set; common entrance families: fadeIn* (fadeInUp, fadeInDown, fadeInLeft, fadeInRight…), slideIn* (slideInUp, slideInDown, slideInLeft, slideInRight), zoomIn* (zoomIn, zoomInUp, zoomInDown…), bounceIn* (bounceIn, bounceInUp…), backIn* (backInDown, backInLeft…), flipIn* (flipInX, flipInY), lightSpeedIn* (lightSpeedInLeft, lightSpeedInRight), rotateIn* (rotateIn, rotateInDownLeft…), rollIn, jackInTheBox; attention seekers: bounce, pulse, tada, headShake, wobble, jello, heartBeat, rubberBand, shakeX, shakeY. The full set is enforced by validate_page — use an invalid name and the element renders stuck. NEVER set styles.opacity < 1 for a "subtle" or "muted" look — opacity is permanent and renders the element and all its content faded forever; use rgba() alpha on the color or background property instead.
 - Real data the page DISPLAYS must come from the user — never invent it: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, exact stats/social-proof numbers. If a value the page needs is missing, ASK for it (in intake, or pause before generating); use a clearly-labelled placeholder ONLY when the user explicitly declines, and tell them exactly what to fill. Write ALL page copy in the SAME language the user is chatting in (mirror it), with FULL, CORRECT diacritics/accents — for Vietnamese this means proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025"), NEVER accent-stripped "không dấu" text. Do not romanize, transliterate, or drop accent marks from any language.
 
 INTAKE — act as a DESIGN CONSULTANT, not a form. Goal: understand what the customer actually wants, then design as close to their intent as possible. Ask BEFORE generating, EVERY time (even a "quick"/"test" page).

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.
 

package/dist/domains/landing/validate.js

@@ -9,6 +9,7 @@
 import { readFileSync } from "node:fs";
 import Ajv2020Module from "ajv/dist/2020.js";
 import { CONTAINER_TYPES, FIELD_TYPES } from "./elements/index.js";
+import { ANIMATABLE_TYPES, ANIMATION_NAMES } from "./vocab.js";
 // ajv ships as CJS; under Node16 ESM the constructor is on `.default`.
 const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
 // Loaded at runtime (the build copies this JSON beside the compiled validator)
@@ -210,6 +211,48 @@ export function validatePage(input) {
                 });
             }
         }
+        // animation contract — checked per breakpoint
+        // Source: landing_page_build/render/build/animate.js (animatable type list)
+        //         landing_page_backend/assets/editor/main/traits/TraitAnimation.vue (name set)
+        for (const bp of ["desktop", "mobile"]) {
+            const anim = node.responsive?.[bp]?.config?.animation;
+            if (!anim || typeof anim !== "object")
+                continue;
+            const animName = anim.name;
+            if (typeof animName !== "string" || animName === "none")
+                continue;
+            // name is present and not 'none' — check type animatability first
+            if (type && !ANIMATABLE_TYPES.has(type)) {
+                errors.push(`${path} (${type}) [${bp}]: the renderer cannot animate type "${type}" — ` +
+                    `the element will render stuck/dim in its pre-animation state. ` +
+                    `Fix: patch_page setting config:{${bp}:{animation:{name:'none',delay:0,duration:3,repeat:null}}} ` +
+                    `or move the animation onto an animatable wrapper (e.g. type "group").`);
+            }
+            // name must be in the known animate.css set
+            if (!ANIMATION_NAMES.has(animName)) {
+                errors.push(`${path} (${type ?? "?"}) [${bp}]: animation name "${animName}" is not in the editor's ` +
+                    `animate.css set — the keyframe is unknown and the animation never runs. ` +
+                    `Valid examples: fadeInUp, slideInLeft, zoomIn, bounceIn, backInDown, flipInX, lightSpeedInLeft, rotateIn, rollIn, jackInTheBox.`);
+            }
+        }
+        // styles.opacity < 1 renders the element permanently faded (exportCss.js emits opacity:<v>)
+        for (const bp of ["desktop", "mobile"]) {
+            const styles = node.responsive?.[bp]?.styles;
+            if (!styles || typeof styles !== "object")
+                continue;
+            const raw = styles.opacity;
+            if (raw === undefined || raw === null)
+                continue;
+            const v = typeof raw === "number" ? raw : typeof raw === "string" ? parseFloat(raw) : NaN;
+            if (!Number.isFinite(v))
+                continue; // non-numeric garbage → schema territory, skip
+            if (v < 1) {
+                warnings.push(`${path} (${type ?? "?"}) [${bp}]: styles.opacity=${v} — ` +
+                    `the element will render permanently faded. ` +
+                    `If unintended, fix via patch_page({op:'update',id:'${node.id ?? "?"}',styles:{${bp}:{opacity:1}}}); ` +
+                    `for a muted color use rgba() alpha on the color/background property instead.`);
+            }
+        }
         // countdown.language must be a key the renderer's lang table knows (or 'custom');
         // anything else (e.g. a locale code "vi"/"en") crashes the renderer with
         // "is not iterable" when it destructures lang[language].

package/dist/domains/landing/vocab.js

@@ -5,6 +5,47 @@
  * Derived from assets/render_v4/event/index.js.
  */
 export const CANVAS = { desktopWidth: 960, mobileWidth: 420, defaultSectionHeight: 800 };
+/**
+ * Element types the runtime animator handles.
+ * Source: landing_page_build/render/build/animate.js — the switch statement
+ * that emits the animation CSS class only covers these 9 types. Any other type
+ * with config.animation.name != 'none' produces a broken CSS selector and the
+ * element stays in the pre-animation (dim/hidden) state permanently.
+ */
+export const ANIMATABLE_TYPES = new Set([
+    "group", "image-block", "text-block", "rectangle", "button",
+    "countdown", "line", "list-paragraph", "notify",
+]);
+/**
+ * Valid animation name values accepted by the editor and the renderer.
+ * Source: landing_page_backend/assets/editor/main/traits/TraitAnimation.vue
+ * (the animate.css-backed option list). Any name outside this set produces
+ * an unknown keyframe — the animation never runs and the element may render stuck.
+ */
+export const ANIMATION_NAMES = new Set([
+    "none",
+    "bounce", "flash", "pulse", "rubberBand", "shakeX", "shakeY", "headShake",
+    "swing", "swingCenter", "tada", "wobble", "jello", "heartBeat",
+    "backInDown", "backInLeft", "backInRight", "backInUp",
+    "backOutDown", "backOutLeft", "backOutRight", "backOutUp",
+    "bounceIn", "bounceInDown", "bounceInLeft", "bounceInRight", "bounceInUp",
+    "bounceOut", "bounceOutDown", "bounceOutLeft", "bounceOutRight", "bounceOutUp",
+    "fadeIn", "fadeInDown", "fadeInDownBig", "fadeInLeft", "fadeInLeftBig",
+    "fadeInRight", "fadeInRightBig", "fadeInUp", "fadeInUpBig",
+    "fadeInTopLeft", "fadeInTopRight", "fadeInBottomLeft", "fadeInBottomRight",
+    "fadeOut", "fadeOutDown", "fadeOutDownBig", "fadeOutLeft", "fadeOutLeftBig",
+    "fadeOutRight", "fadeOutRightBig", "fadeOutUp", "fadeOutUpBig",
+    "fadeOutTopLeft", "fadeOutTopRight", "fadeOutBottomRight", "fadeOutBottomLeft",
+    "flip", "flipInX", "flipInY", "flipOutX", "flipOutY",
+    "lightSpeedInRight", "lightSpeedInLeft", "lightSpeedOutRight", "lightSpeedOutLeft",
+    "rotateIn", "rotateInDownLeft", "rotateInDownRight", "rotateInUpLeft", "rotateInUpRight",
+    "rotateOut", "rotateOutDownLeft", "rotateOutDownRight", "rotateOutUpLeft", "rotateOutUpRight",
+    "hinge", "jackInTheBox", "rollIn", "rollOut",
+    "zoomIn", "zoomInDown", "zoomInLeft", "zoomInRight", "zoomInUp",
+    "zoomOut", "zoomOutDown", "zoomOutLeft", "zoomOutRight", "zoomOutUp",
+    "slideInDown", "slideInLeft", "slideInRight", "slideInUp",
+    "slideOutDown", "slideOutLeft", "slideOutRight", "slideOutUp",
+]);
 export const EVENT_TRIGGERS = ["click", "hover", "success", "error", "unset", "delay"];
 // Click-trigger actions. "Extra:" lists the action-specific event-object fields
 // the dispatcher reads beyond { id, type, action, target } (render_v4/event/index.js).

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";
@@ -103,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;
@@ -134,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;
@@ -179,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;
@@ -279,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) {
@@ -328,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;
@@ -392,7 +415,7 @@ export function buildPublishRequestRedacted(config, pageId, sourceString, opts =
 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 });
+        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");
@@ -408,6 +431,9 @@ async function postToHost(url, headers, body) {
             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);
     });
@@ -429,7 +455,8 @@ export async function publishPage(config, pageId, sourceString, opts = {}) {
         ({ status, text } = await postToHost(url, { ...authHeaders(config), Accept: "*/*" }, publishBody(sourceString, opts)));
     }
     catch (e) {
-        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+        const e2 = timeoutOrNetworkError(url, e);
+        return { ok: false, status: e2.status, error: e2.error };
     }
     let json = null;
     try {