webcake-landing-mcp 1.0.39 → 1.0.40

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`, …) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `list_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`, `list_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)**.
 
@@ -417,7 +417,7 @@ 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 })   # server fetches, appends, validates, saves
+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 })
 ```
 

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.40",
+    "d": "09/06/2026",
+    "type": "Added",
+    "en": "New ingest_html tool parses an HTML string into a compact reference AST (~2–5KB) that classifies sections by role (header, hero, features, form,…",
+    "vi": "Công cụ ingest_html mới phân tích cú pháp một chuỗi HTML thành AST tham chiếu thu gọn (~2–5KB) phân loại các section theo vai trò (header, hero,…"
+  },
   {
     "v": "1.0.39",
     "d": "08/06/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "get_generation_guide now includes an explicit workflow step (3b) directing the agent to call search_images for every image a page needs (hero,…",
     "vi": "get_generation_guide nay bổ sung bước workflow rõ ràng (3b) yêu cầu agent gọi search_images cho mọi hình ảnh trang cần (hero, sản phẩm, giới thiệu,…"
-  },
-  {
-    "v": "1.0.34",
-    "d": "08/06/2026",
-    "type": "Added",
-    "en": "New search_images tool queries Pexels stock photos by short English subject and returns ready-to-hotlink URLs at several sizes; use src.large for…",
-    "vi": "Công cụ search_images mới truy vấn ảnh stock Pexels theo chủ đề tiếng Anh ngắn gọn và trả về các URL sẵn sàng hotlink ở nhiều kích thước; dùng…"
   }
 ]

package/dist/core/expand.js

@@ -0,0 +1,71 @@
+const STD_KEYS = ["id", "type", "properties", "specials", "runtime", "events", "responsive", "children"];
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+/** Hydrate ONE (possibly sparse) element node against the factory default for its type. */
+export function expandNode(input, createElement) {
+    if (!isObj(input))
+        return input;
+    const type = input.type;
+    // No type → can't seed; pass through so the validator reports the missing type.
+    if (typeof type !== "string" || type === "")
+        return input;
+    let seed;
+    try {
+        const name = isObj(input.properties) && typeof input.properties.name === "string"
+            ? input.properties.name
+            : undefined;
+        seed = createElement(type, name ? { name } : undefined);
+    }
+    catch {
+        return input;
+    }
+    const out = { ...seed };
+    if (typeof input.id === "string")
+        out.id = input.id;
+    out.type = type;
+    out.properties = { ...seed.properties, ...(isObj(input.properties) ? input.properties : {}) };
+    out.specials = { ...seed.specials, ...(isObj(input.specials) ? input.specials : {}) };
+    out.runtime = isObj(input.runtime) ? input.runtime : seed.runtime;
+    out.events = Array.isArray(input.events) ? input.events : seed.events;
+    // responsive: merge config + styles per breakpoint over the seed; keep the
+    // seed breakpoint when the model omits it. (Provide BOTH breakpoints' styles
+    // for correct layout — only the boilerplate around them is defaulted here.)
+    out.responsive = { desktop: seed.responsive.desktop, mobile: seed.responsive.mobile };
+    for (const bp of ["desktop", "mobile"]) {
+        const inBp = isObj(input.responsive) ? input.responsive[bp] : undefined;
+        const seedBp = seed.responsive[bp];
+        out.responsive[bp] = isObj(inBp)
+            ? {
+                ...seedBp,
+                ...inBp,
+                config: { ...seedBp.config, ...(isObj(inBp.config) ? inBp.config : {}) },
+                styles: { ...seedBp.styles, ...(isObj(inBp.styles) ? inBp.styles : {}) },
+            }
+            : seedBp;
+    }
+    // children: replace with the (recursively expanded) provided children; else keep the seed's.
+    if (Array.isArray(input.children)) {
+        out.children = input.children.map((c) => expandNode(c, createElement));
+    }
+    else if (Array.isArray(seed.children)) {
+        out.children = seed.children;
+    }
+    // carry over any non-standard keys the model set (future-proofing).
+    for (const k of Object.keys(input)) {
+        if (!STD_KEYS.includes(k))
+            out[k] = input[k];
+    }
+    return out;
+}
+/** Hydrate every node in a page source ({ page, popup, dynamic_pages }). */
+export function expandSource(source, createElement) {
+    if (!isObj(source))
+        return source;
+    const out = { ...source };
+    if (Array.isArray(source.page))
+        out.page = source.page.map((s) => expandNode(s, createElement));
+    if (Array.isArray(source.popup))
+        out.popup = source.popup.map((p) => expandNode(p, createElement));
+    if (Array.isArray(source.dynamic_pages))
+        out.dynamic_pages = source.dynamic_pages.map((p) => expandNode(p, createElement));
+    return out;
+}

package/dist/domains/landing/guide.js

@@ -23,6 +23,7 @@ ELEMENT NODE (every element)
   "specials": { ...type-specific CONTENT... }, "runtime": {}, "events": [],
   "children": [ ... ] }  // children ONLY on container types
 - Cross-cutting config keys apply to EVERY element via the per-breakpoint config (responsive.<bp>.config): sticky/stickyPosition/stickyTop/stickyBottom/stickyLeft/stickyRight/stickyWidth/stickyHeight/stickyUnpinAtSections…, animation, hide, lock. The full per-element specials reference (every renderer-read key, including the rich select/checkbox-group/radio/survey option-object schema) lives in docs/element-specials-reference.md.
+- COMPACT AUTHORING (emit FEWER tokens): the server hydrates each element from its type's factory defaults, so you may OMIT boilerplate — \`properties\`, \`runtime\`, empty \`events\`/\`children\`, and each breakpoint's \`config\` (the default animation). Emit only id, type, the meaningful responsive.<bp>.styles for BOTH breakpoints, specials, and events when present. e.g. { "type":"text-block","id":"h1","responsive":{"desktop":{"styles":{"top":120,"left":80,"width":500,"height":70,"fontSize":48,"color":"rgba(20,30,25,1)"}},"mobile":{"styles":{"top":100,"left":20,"width":380,"height":60,"fontSize":32}}},"specials":{"text":"…"} } hydrates into the full node. A complete node still works.
 
 COORDINATE SYSTEM (critical)
 - Absolute-positioning canvas (NOT flexbox). Children carry top/left/width/height in px (numbers).

package/dist/domains/landing/index.js

@@ -4,6 +4,7 @@ import { INSTRUCTIONS } from "./instructions.js";
 import { LIBRARY, ELEMENT_TYPES, CONTAINER_TYPES, FIELD_TYPES, createElement } from "./elements/index.js";
 import { createPageSource } from "./page.js";
 import { validatePage, coercePage, pageSchema } from "./validate.js";
+import { expandSource } from "../../core/expand.js";
 /** The payload returned by the get_generation_guide tool. */
 export const guidePayload = {
     guide: GENERATION_GUIDE,
@@ -27,5 +28,13 @@ export const landingDomain = {
     createPageSource,
     validate: validatePage,
     coerce: coercePage,
+    expand: (input) => {
+        try {
+            return expandSource(coercePage(input), createElement);
+        }
+        catch {
+            return input; // bad JSON — let validate report it
+        }
+    },
     schema: pageSchema,
 };

package/dist/domains/landing/instructions.js

@@ -9,15 +9,17 @@ RULES (follow for every request):
 - INTAKE FIRST — do this EVERY time, even for a "quick"/"test" page. Do NOT jump straight to new_page_skeleton/create_page on the same turn as the request: ask the essentials, restate an outline, get a "yes", THEN build. Ask ONE short batch (3–6, with sensible defaults so the user answers fast) enough to understand the page's PURPOSE, name, look and layout: page purpose/goal, brand/page name, what they sell + price (sales/ads pages), primary color + logo/branding, sections & layout in order, primary CTA + destination, desktop+mobile or mobile-only, which organization. CONSULT, don't interrogate: SUGGEST so the user reacts to something concrete — propose a section flow (pick the archetype matching the page type) + a look (hero treatment + color/tone), and when the user is vague offer 2–3 directions to choose from; proactively suggest sections that fit their goal (social-proof, FAQ, countdown), but ask, don't silently add. Then restate the proposed design (section flow + CTA + color/tone) and WAIT for the user's confirmation, iterating until it matches their intent, before generating. Never assume or silently placeholder the page name, product, price, or colors — ask; only placeholder a core fact when the user explicitly declines to give it.
 - ASK for any real data the page will display — never invent it, and don't silently placeholder it. This includes: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, and exact stats/social-proof numbers. If a value the page needs is missing, ASK the user for it (in intake, or pause and ask before generating). Use a clearly-labelled placeholder ONLY when the user explicitly says to skip it — then tell them exactly what to fill in.
 - ALWAYS call validate_page and fix every error before create_page / update_page.
-- BUILD THE SOURCE IN ONE PASS — gather everything you need (call get_element / get_generation_guide for every section, popup, and element type) BEFORE assembling the source, then build the FULL tree once. Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the request.
-- create_page and update_page DEFAULT to dry_run=true. Dry-run EXACTLY ONCE: show it, then only send dry_run=false after the user confirms. If the dry-run reports validation problems, fix them via validate_page and re-run once — do not loop dry-runs to "check" the source.
-- 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 server fetches, appends, validates the whole tree, and saves). Small pages can still go in one create_page pass.
+- BUILD THE SOURCE IN ONE PASS — gather everything you need BEFORE assembling the source, then build the FULL tree once. BATCH the reads: when a section needs several element types (section + text-block + image-block + button + form + input), call get_element({types:[…]}) ONCE instead of one call per type — same for images, call search_images({queries:[…]}) ONCE with one query per image slot (it dedups + parallelizes and returns one best photo per query). Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the 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: get_page → change ONLY what was asked → keep every other element, its id, and coordinates → validate_page → update_page. Never regenerate the whole tree for a small change.
 - 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.
 
 MODEL (essentials):
 - Top-level: { page:[sections], popup:[popups], dynamic_pages:[], settings:{}, options:{mobileOnly,versionID}, cartConfigs:{isActive:false}, svariations:[] }. Popups are a SEPARATE top-level array, NOT inside page; currency lives in settings.currency (not options). Leave dynamic_pages/svariations as [] for a static page, but keep them on edit round-trips.
 - Element: { id, type, properties, responsive:{desktop,mobile:{config,styles}}, specials, children, runtime, events }. Absolute canvas: children carry numeric top/left/width/height (px) per breakpoint (canvas width desktop=960, mobile=420); sections own a height.
+- COMPACT AUTHORING (emit FEWER tokens — faster, cheaper): the server HYDRATES every element from its type's factory defaults, so OMIT the boilerplate. Send only: id, type, the meaningful responsive.desktop.styles + responsive.mobile.styles (positions/sizes/colors/font — provide BOTH breakpoints), specials (text/src/field_name…), and events ONLY when the element actually has them. You may DROP: properties, runtime, empty events/children, and each breakpoint's config (animation). A full node still works (it's just overlaid on the seed). Applies to create_page, update_page, add_section, validate_page — ~halves the JSON you emit per element.
 - CENTERING (the #1 layout defect — do the math, don't eyeball): to center a box compute left = round((canvas - width)/2) — 960 desktop, 420 mobile. textAlign:center only centers text inside the box, not the box itself. For a row of N items, center the whole row block (startLeft = round((canvas - (N*item + (N-1)*gap))/2)). Keep 0 ≤ left and left+width ≤ canvas on each breakpoint.
 - PAGE MARGIN (one shared axis — fixes the ragged/header-misaligned look): every section AND the header use the SAME column — left edge at 80 desktop / 20 mobile, right edge at 880 / 400 (content width 800 / 380). Header: logo at left=80, CTA right edge at 880 (its left = 880 − width). Never let one band start at left=80 and the next at left=140.
 - PREMIUM CRAFT (read "sang"): generous whitespace (don't cram; ~48–72px above each band's first element, ≥16–24px between elements); clear type scale (H1 40–56 / body 16–18, big jump); ONE accent used sparingly + neutrals; snap spacing to an 8px grid; reuse the same content width / margin / card+button radius across sections.
@@ -25,4 +27,4 @@ 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, list_organizations, create_page, list_pages, get_page, update_page, add_section.`;
+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, get_page, update_page, add_section.`;

package/dist/domains/landing/validate.js

@@ -323,6 +323,52 @@ export function validatePage(input) {
         const ms = sec?.responsive?.mobile?.styles ?? {};
         checkBounds(sec, rootCanvasD, num(ds.height) ?? DEFAULT_SECTION_HEIGHT, rootCanvasM, num(ms.height) ?? DEFAULT_SECTION_HEIGHT, `page[${i}]`);
     });
+    // 3b) Page margin axis — every band (header included) should put its
+    //     left-anchored content on ONE shared left margin. A header/section that
+    //     starts on a different left than the rest is the #1 "looks misaligned"
+    //     defect (and exactly what eyeballing `left` produces). For each section
+    //     compute its left-anchored content edge (desktop), then warn ONCE if those
+    //     edges diverge. Advisory only.
+    const leftEdgeFor = (sec) => {
+        if (!sec || !Array.isArray(sec.children))
+            return undefined;
+        let edge = Infinity;
+        for (const child of sec.children) {
+            const styles = child?.responsive?.desktop?.styles;
+            if (!styles)
+                continue;
+            const left = num(styles.left);
+            const width = num(styles.width);
+            if (left == null || width == null || left < 0)
+                continue;
+            // skip full-bleed backgrounds / near-full-width media (their left is 0-ish)
+            if (width >= rootCanvasD * 0.9)
+                continue;
+            // skip horizontally-centered content (its left is dictated by centering math)
+            if (Math.abs(left - (rootCanvasD - width) / 2) <= 16)
+                continue;
+            // only LEFT-anchored content participates (right-anchored CTAs sit on the right axis)
+            if (left >= rootCanvasD * 0.4)
+                continue;
+            if (left < edge)
+                edge = left;
+        }
+        return Number.isFinite(edge) ? edge : undefined;
+    };
+    const sectionEdges = [];
+    topList.forEach((sec, i) => {
+        const e = leftEdgeFor(sec);
+        if (e != null)
+            sectionEdges.push({ i, edge: e });
+    });
+    if (sectionEdges.length >= 2) {
+        const minEdge = Math.min(...sectionEdges.map((e) => e.edge));
+        const maxEdge = Math.max(...sectionEdges.map((e) => e.edge));
+        if (maxEdge - minEdge > 48) {
+            const list = sectionEdges.map((e) => `page[${e.i}] left=${e.edge}`).join(", ");
+            warnings.push(`Sections start on different left margins (${list}). Put every band's left-anchored content (the header logo included) on ONE shared left axis — e.g. left=${minEdge} desktop — so the page reads aligned, not ragged. This is the #1 header-misalignment defect.`);
+        }
+    }
     popups.forEach((p, i) => {
         const ds = p?.responsive?.desktop?.styles ?? {};
         const ms = p?.responsive?.mobile?.styles ?? {};

package/dist/persistence/html-ingest.js

@@ -0,0 +1,331 @@
+/**
+ * HTML → compact reference AST.
+ *
+ * Used by the `ingest_html` and `ingest_url` tools so a model can use an existing
+ * page (HTML string or URL) as a LAYOUT REFERENCE when building a Webcake page,
+ * without having to read the full HTML token-by-token. The AST groups the page
+ * into sections classified by role (hero/features/form/cta/footer/…) and
+ * extracts headings, ctas, images, form fields, and a few brand hints
+ * (top colors + fonts). The full text is NOT preserved — the model is meant to
+ * use this as an anchor and generate fresh content for the user's brand.
+ */
+import { parse } from "node-html-parser";
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_HTML_BYTES = 2_000_000; // 2MB
+const SECTION_TAGS = ["section", "main", "article", "header", "footer", "aside"];
+const HEADING_TAGS = ["h1", "h2", "h3", "h4"];
+export function parseHtml(html) {
+    if (!html || typeof html !== "string" || html.trim().length === 0) {
+        return { sections: [], warnings: ["empty input"] };
+    }
+    const root = parse(html, { lowerCaseTagName: true });
+    const head = root.querySelector("head");
+    const title = head?.querySelector("title")?.text?.trim() || undefined;
+    const description = head?.querySelector('meta[name="description"]')?.getAttribute("content")?.trim() || undefined;
+    const og_image = head?.querySelector('meta[property="og:image"]')?.getAttribute("content") || undefined;
+    const language = root.querySelector("html")?.getAttribute("lang") || undefined;
+    const body = root.querySelector("body") ?? root;
+    if (!body)
+        return { title, description, og_image, language, sections: [], warnings: ["no <body>"] };
+    // CSR heuristic — empty body usually means React/Vue/Next that hasn't rendered.
+    const bodyText = body.textContent.trim();
+    if (bodyText.length < 50) {
+        return {
+            title,
+            description,
+            og_image,
+            language,
+            sections: [],
+            warnings: [
+                "page appears client-rendered (<body> is essentially empty); ask the user for a screenshot — Claude can analyze it natively without this tool",
+            ],
+        };
+    }
+    const sectionEls = findSections(body);
+    const sections = sectionEls.map(classifySection);
+    // Brand hints from inline styles
+    const styleAttrs = [];
+    body.querySelectorAll("[style]").forEach((el) => {
+        const s = el.getAttribute("style");
+        if (s)
+            styleAttrs.push(s);
+    });
+    const colors = topColors(styleAttrs, 5);
+    const fonts = topFonts(styleAttrs, 3);
+    return {
+        title,
+        description,
+        og_image,
+        language,
+        sections,
+        colors: colors.length ? colors : undefined,
+        fonts: fonts.length ? fonts : undefined,
+    };
+}
+function findSections(body) {
+    // 1) Prefer explicit semantic tags.
+    const explicit = body.querySelectorAll(SECTION_TAGS.join(","));
+    if (explicit.length >= 2)
+        return explicit;
+    // 2) If body has a single <main>, look inside it.
+    const main = body.querySelector("main");
+    if (main) {
+        const inside = main.querySelectorAll(SECTION_TAGS.join(","));
+        if (inside.length >= 2)
+            return inside;
+        const directDivs = elementChildren(main).filter((c) => ["div", "section", "article"].includes(c.tagName?.toLowerCase() ?? ""));
+        if (directDivs.length >= 2)
+            return directDivs;
+    }
+    // 3) Fallback to top-level block children of body.
+    const bodyBlocks = elementChildren(body).filter((c) => ["div", "main", "section", "article"].includes(c.tagName?.toLowerCase() ?? ""));
+    if (bodyBlocks.length >= 2)
+        return bodyBlocks;
+    // 4) Single section — the whole body.
+    return [body];
+}
+function elementChildren(el) {
+    const out = [];
+    for (const n of el.childNodes) {
+        if (n && n.nodeType === 1)
+            out.push(n);
+    }
+    return out;
+}
+function classifySection(el) {
+    const tag = el.tagName?.toLowerCase();
+    if (tag === "header")
+        return classifyHeader(el);
+    if (tag === "footer")
+        return classifyFooter(el);
+    const form = el.querySelector("form");
+    if (form)
+        return classifyForm(el, form);
+    const heading = pickHeading(el);
+    const paragraphs = pickParagraphs(el);
+    const images = pickImages(el);
+    const ctas = pickCtas(el);
+    const subheading = heading ? pickSubheading(el, heading) : undefined;
+    if (images.length >= 4) {
+        return { role: "gallery", heading: text(heading), images };
+    }
+    if (countFeatureBlocks(el) >= 3) {
+        return { role: "features", heading: text(heading), subheading, ctas: ctas.length ? ctas : undefined };
+    }
+    if (heading?.tagName?.toLowerCase() === "h1" && (images.length > 0 || ctas.length > 0)) {
+        return {
+            role: "hero",
+            heading: text(heading),
+            subheading,
+            paragraphs: paragraphs.slice(0, 1),
+            images: images.slice(0, 1),
+            ctas: ctas.slice(0, 2),
+        };
+    }
+    if (ctas.length > 0 && paragraphs.length <= 1) {
+        return { role: "cta", heading: text(heading), subheading, ctas };
+    }
+    return {
+        role: "unknown",
+        heading: text(heading),
+        subheading,
+        paragraphs: paragraphs.slice(0, 3),
+        images: images.slice(0, 3),
+        ctas: ctas.length ? ctas : undefined,
+    };
+}
+function classifyHeader(el) {
+    const heading = pickHeading(el);
+    const links = el
+        .querySelectorAll("a")
+        .map((a) => ({ text: a.text.trim(), href: a.getAttribute("href") ?? "" }))
+        .filter((l) => l.text)
+        .slice(0, 12);
+    return { role: "header", heading: text(heading), links: links.length ? links : undefined };
+}
+function classifyFooter(el) {
+    const links = el
+        .querySelectorAll("a")
+        .map((a) => ({ text: a.text.trim(), href: a.getAttribute("href") ?? "" }))
+        .filter((l) => l.text)
+        .slice(0, 24);
+    const paragraphs = pickParagraphs(el).slice(0, 2);
+    return { role: "footer", links: links.length ? links : undefined, paragraphs: paragraphs.length ? paragraphs : undefined };
+}
+function classifyForm(el, form) {
+    const heading = pickHeading(el);
+    const subheading = heading ? pickSubheading(el, heading) : undefined;
+    const inputs = form.querySelectorAll("input, textarea, select");
+    const form_fields = inputs
+        .map((inp) => {
+        const tag = inp.tagName?.toLowerCase();
+        const type = tag === "input" ? inp.getAttribute("type") ?? "text" : tag === "textarea" ? "textarea" : "select";
+        const name = inp.getAttribute("name") || undefined;
+        const id = inp.getAttribute("id");
+        let label;
+        if (id) {
+            const lbl = form.querySelector(`label[for="${id}"]`);
+            if (lbl)
+                label = lbl.text.trim();
+        }
+        if (!label) {
+            const placeholder = inp.getAttribute("placeholder");
+            if (placeholder)
+                label = placeholder;
+        }
+        return { type, name, required: inp.hasAttribute("required") || undefined, label };
+    })
+        .filter((f) => f.type !== "hidden" && f.type !== "submit" && f.type !== "button");
+    const submit = form.querySelector('button[type="submit"], input[type="submit"]') ?? form.querySelector("button");
+    const submitText = (submit?.text?.trim() || submit?.getAttribute?.("value") || "").trim() || (form_fields.length ? "Submit" : undefined);
+    const ctas = submitText ? [{ text: submitText }] : [];
+    return {
+        role: "form",
+        heading: text(heading),
+        subheading,
+        form_fields: form_fields.length ? form_fields : undefined,
+        ctas: ctas.length ? ctas : undefined,
+    };
+}
+function pickHeading(el) {
+    for (const t of HEADING_TAGS) {
+        const h = el.querySelector(t);
+        if (h)
+            return h;
+    }
+    return undefined;
+}
+function pickSubheading(el, heading) {
+    // Use the first paragraph that doesn't equal the heading text.
+    const headingText = heading.text.trim();
+    for (const p of el.querySelectorAll("p")) {
+        const t = p.text.trim();
+        if (t && t !== headingText && t.length >= 8 && t.length <= 240)
+            return t;
+    }
+    return undefined;
+}
+function pickParagraphs(el) {
+    return el
+        .querySelectorAll("p")
+        .map((p) => p.text.trim())
+        .filter((t) => t.length > 10 && t.length < 500);
+}
+function pickImages(el) {
+    return el
+        .querySelectorAll("img")
+        .map((img) => img.getAttribute("src") || img.getAttribute("data-src") || "")
+        .filter((s) => s && !s.startsWith("data:"))
+        .slice(0, 12);
+}
+function pickCtas(el) {
+    const out = [];
+    el.querySelectorAll("button").forEach((b) => {
+        const t = b.text.trim();
+        if (t)
+            out.push({ text: t });
+    });
+    el.querySelectorAll("a").forEach((a) => {
+        const cls = (a.getAttribute("class") ?? "").toLowerCase();
+        if (/(btn|button|cta)/.test(cls)) {
+            const t = a.text.trim();
+            const href = a.getAttribute("href") ?? undefined;
+            if (t)
+                out.push({ text: t, href });
+        }
+    });
+    // Dedup by text.
+    const seen = new Set();
+    return out.filter((c) => (seen.has(c.text) ? false : (seen.add(c.text), true))).slice(0, 4);
+}
+function countFeatureBlocks(el) {
+    let count = 0;
+    for (const c of elementChildren(el)) {
+        if (c.querySelector(HEADING_TAGS.join(",")) && c.querySelector("p"))
+            count++;
+    }
+    if (count >= 3)
+        return count;
+    // Fallback: cards or list items that look like feature blocks.
+    return el.querySelectorAll('ul > li, [class*="card"], [class*="feature"]').length;
+}
+function text(el) {
+    const t = el?.text?.trim();
+    return t ? t.slice(0, 240) : undefined;
+}
+const COLOR_RE = /(?:rgba?|hsla?)\([^)]+\)|#[0-9a-fA-F]{3,8}\b/g;
+function topColors(styles, n) {
+    const counts = new Map();
+    for (const s of styles) {
+        const matches = s.match(COLOR_RE);
+        if (matches)
+            for (const c of matches) {
+                const k = c.toLowerCase();
+                counts.set(k, (counts.get(k) ?? 0) + 1);
+            }
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k]) => k);
+}
+const FONT_RE = /font-family\s*:\s*([^;]+)/gi;
+function topFonts(styles, n) {
+    const counts = new Map();
+    for (const s of styles) {
+        FONT_RE.lastIndex = 0;
+        let m;
+        while ((m = FONT_RE.exec(s)) !== null) {
+            const k = m[1].trim().replace(/['"]/g, "").split(",")[0].trim();
+            if (k)
+                counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k]) => k);
+}
+export async function fetchHtml(url, opts = {}) {
+    if (!/^https?:\/\//i.test(url)) {
+        return { ok: false, error: "URL must start with http:// or https://" };
+    }
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            headers: {
+                "User-Agent": opts.userAgent ?? "Mozilla/5.0 (compatible; webcake-landing-mcp/ingest_url)",
+                Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.5",
+            },
+            signal: ctrl.signal,
+            redirect: "follow",
+        });
+        if (!res.ok)
+            return { ok: false, status: res.status, error: `Server returned ${res.status}` };
+        const ctype = res.headers.get("content-type") ?? "";
+        if (!/html|xml|text/i.test(ctype)) {
+            return { ok: false, status: res.status, error: `Content-Type ${ctype} is not HTML` };
+        }
+        const reader = res.body?.getReader();
+        if (!reader)
+            return { ok: false, status: res.status, error: "no response body" };
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.length;
+            if (total > MAX_HTML_BYTES) {
+                await reader.cancel().catch(() => { });
+                return { ok: false, status: res.status, error: `Response exceeded ${MAX_HTML_BYTES} bytes` };
+            }
+            chunks.push(value);
+        }
+        const buf = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+        return { ok: true, status: res.status, html: buf.toString("utf-8") };
+    }
+    catch (e) {
+        return { ok: false, error: e?.name === "AbortError" ? "Request timed out" : e?.message ?? String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/persistence/webcake-client.js

@@ -3,6 +3,7 @@ const ORGS_ENDPOINT = "/api/v1/org/organizations";
 const PAGES_ENDPOINT = "/api/v1/ai/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";
 function authHeaders(config, orgId) {
     const headers = {
         "Content-Type": "application/json",
@@ -192,6 +193,71 @@ export function buildUpdateRequestRedacted(config, pageId, source) {
         body: body.replace(config.jwt, "***JWT***").slice(0, 400) + (body.length > 400 ? `… (${body.length} bytes)` : ""),
     };
 }
+/** Build (but do not send) the append-section request — for dry-run previews. */
+export function buildAppendRequestRedacted(config, pageId, sections) {
+    const body = JSON.stringify({ page_id: pageId, sections });
+    return {
+        method: "POST",
+        url: `${config.base}${APPEND_ENDPOINT}`,
+        headers: { ...authHeaders(config), Authorization: "Bearer ***JWT***", Cookie: "jwt=***JWT***" },
+        body: body.replace(config.jwt, "***JWT***").slice(0, 400) + (body.length > 400 ? `… (${body.length} bytes)` : ""),
+    };
+}
+/**
+ * Append section(s) to a page server-side via the dedicated append endpoint —
+ * ships ONLY the new section(s) (no whole-source get+put). The backend reads the
+ * stored source, appends, guards duplicate ids, and saves. Returns
+ * `endpoint_missing:true` on a 404 so the caller can fall back to get+merge+put
+ * against an older backend that lacks the route.
+ */
+export async function appendSection(config, pageId, sections) {
+    const url = `${config.base}${APPEND_ENDPOINT}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: authHeaders(config),
+            body: JSON.stringify({ page_id: pageId, sections }),
+        });
+    }
+    catch (e) {
+        return { ok: false, status: 0, error: `Network error calling ${url}: ${e?.message ?? e}` };
+    }
+    // No such route on an older backend → Phoenix 404. Signal a fallback.
+    if (res.status === 404) {
+        return { ok: false, status: 404, endpoint_missing: true, error: "append_section endpoint not found on backend" };
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        /* non-JSON */
+    }
+    const data = json?.data ?? json;
+    const pageIdOut = data?.page_id;
+    if (!res.ok || !pageIdOut) {
+        const backendMsg = json?.message ?? json?.reason ?? (json ? undefined : text.slice(0, 200));
+        return {
+            ok: false,
+            status: res.status,
+            raw: json ?? text.slice(0, 600),
+            error: `Backend returned ${res.status}${backendMsg ? `: ${backendMsg}` : ""}`,
+        };
+    }
+    return {
+        ok: true,
+        status: res.status,
+        page_id: pageIdOut,
+        editor_url: toEditorUrl(config, data?.editor_url),
+        preview_url: toEditorUrl(config, data?.preview_url),
+        organization_id: data?.organization_id ?? null,
+        section_count: data?.section_count,
+        sections_added: data?.sections_added,
+        raw: data,
+    };
+}
 /** Overwrite an existing page's source (source-only). */
 export async function updatePageSource(config, pageId, source) {
     const url = `${config.base}${UPDATE_ENDPOINT}`;