webcake-storefront-mcp 1.5.0 → 1.6.0

package/dist/api.js

@@ -139,8 +139,16 @@ export class WebcakeCmsApi {
     listPages() {
         return this.request("GET", `/api/v1/site/${this.siteId}/pages`);
     }
+    /** Create a page. The backend creates the page AND its source in one call, so `source`
+     *  is REQUIRED and must be a JSON string (stringified here if an object is passed).
+     *  `slug`/`is_homepage` are NOT applied at create — set them afterwards via updatePage. */
     createPage(params) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body: params });
+        const body = { ...params };
+        if (body.source != null && typeof body.source !== "string")
+            body.source = JSON.stringify(body.source);
+        if (body.source == null)
+            body.source = JSON.stringify({ sections: [] });
+        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body });
     }
     updatePage(pageId, params) {
         return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page`, { body: params });
@@ -169,8 +177,21 @@ export class WebcakeCmsApi {
     saveSite(params = {}) {
         return this.request("POST", `/api/v1/site/${this.siteId}/save`, { body: params, timeout: 60000 });
     }
-    publishSite(params = {}) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/publish`, { body: params, timeout: 60000 });
+    /** Publish the site live. /publish runs the full "save" pipeline, which OVERWRITES
+     *  site.settings with the body's `settings` — so we send the CURRENT settings (else
+     *  they'd be nulled, disabling use_store/use_blog/etc.). Other collections default to []. */
+    async publishSite(params = {}) {
+        let settings = params.settings;
+        if (settings === undefined) {
+            settings = await this.getSiteSettings().catch(() => ({}));
+        }
+        // The save pipeline stores site.settings as a JSON STRING — an object body is
+        // rejected (422). Stringify unless the caller already passed a string.
+        const settingsStr = typeof settings === "string" ? settings : JSON.stringify(settings || {});
+        return this.request("POST", `/api/v1/site/${this.siteId}/publish`, {
+            body: { global_sources: [], global_sections: [], page_contents: [], ...params, settings: settingsStr },
+            timeout: 60000,
+        });
     }
     uploadImageBase64({ base64, content_type } = {}) {
         return this.request("POST", `/api/v1/site/${this.siteId}/media/content/b64`, {

package/dist/builder/attributes.js

@@ -0,0 +1,340 @@
+// Per-element attribute reference, so get_element can teach an AI the MEANINGFUL keys
+// of each BuilderX element (specials/config/events/bindings) — not just the empty
+// factory skeleton (117/132 factories ship empty specials). Sources of truth:
+//   - builderx_spa/src/common/data.js (real example nodes)
+//   - builderx_spa/src/common/factory.js (per-type factories)
+//   - builderx_spa panel/trait components
+//   - real published pages mined from the backend DB
+// Only real keys are listed here (no invented attributes).
+import { readFileSync } from "node:fs";
+let OBSERVED = {};
+try {
+    OBSERVED = JSON.parse(readFileSync(new URL("./element-keys.generated.json", import.meta.url), "utf8"));
+}
+catch {
+    OBSERVED = {};
+}
+// Editor-internal / junk keys to hide from the attribute report.
+const NOISE_KEYS = new Set(["undefined", "locked", "loaded", "isChangeSection"]);
+// Cross-cutting specials available on virtually every element.
+export const SHARED_SPECIALS = {
+    custom_class: "CSS class(es) on the element — target it with .your-class in site custom CSS.",
+    custom_css: "Raw CSS scoped to this element.",
+    element_async: "Mark the element async/lazy (advanced — usually leave unset).",
+    event_name_custom: "Custom analytics event name fired on interaction.",
+};
+// Generic layout keys every node's runtime.config may carry (documented in the build
+// guide); listed here so describeAttributes can flag them as 'generic, not element-specific'.
+export const GENERIC_CONFIG = new Set([
+    "grid", "columns", "rows", "columnStart", "columnEnd", "rowStart", "rowEnd",
+    "constraintX", "constraintY", "heightUnit", "widthUnit", "loaded", "area", "lockCellGrid",
+    "isHidden", "position", "isChangeSection", "useStickyLayoutOther", "columnGap", "rowGap",
+    // absolute/relative position internals (set by the editor, not authored by hand):
+    "absBottom", "absBottomCenterY", "absLeftCenterX", "absRight", "absRightCenterX", "absTopCenterY",
+    "relBottom", "relBottomCenterY", "relLeftCenterX", "relRight", "relRightCenterX", "relTop",
+    "relTopCenterY", "relLeft", "relWidth", "relHeight", "vhHeight", "vwHeight", "relMaxWidth",
+    "leftUnit", "rightUnit", "topUnit", "bottomUnit", "topCenterYUnit", "rightCenterXUnit",
+    "widthScreen", "cornerRadiusUnit", "borderEdges", "widthBg", "heightBg", "topBg", "leftBg",
+    "rightBg", "bottomBg", "scaleX", "scaleY", "scaleL", "scaleT", "origin", "activeIndex",
+]);
+// Cross-element key dictionary: meanings for keys that recur across many element types
+// (so even un-curated elements get useful descriptions). specials + config keys mixed.
+export const SHARED_KEY_DICT = {
+    // content / generic
+    text: "Text / HTML content.",
+    tag: "Semantic tag (h1..h6, p).",
+    src: "Media URL (hosted).",
+    image_alt: "Alt text (SEO / accessibility).",
+    typographyTheme: "Apply a site typography preset.",
+    text_animation_type: "Text entrance animation.",
+    marker: "List marker style (none/dotList/numberList/imageList).",
+    tabIndex: "Tab/focus order.",
+    shapeType: "Shape kind (rectangle/etc.).",
+    // layout / display
+    displayStyle: "Visual layout variant of the element.",
+    columns: "Number of columns / items per row.",
+    responsive: "Responsive sizing mode (autofit/fixed).",
+    gap_column: "Horizontal gap between items (px).",
+    gap_row: "Vertical gap between items (px).",
+    image_ratio: "Image aspect ratio (16/9, 4/3, 1/1, …).",
+    img_object_fit: "Image fit: cover/contain/fill/stretch.",
+    image_width: "Image width within the card.",
+    image_placement: "Image position relative to text (column/row).",
+    slideItems: "Visible slides/items in a slider.",
+    slideWidth: "Slide/card width (px).",
+    item_show: "How many items to display.",
+    autoplay: "Auto-advance (boolean).",
+    loop: "Loop playback/slides (boolean).",
+    showControl: "Show playback/nav controls (boolean).",
+    minimum_card_width: "Minimum card width (px, autofit).",
+    // links / nav
+    link: "Destination URL (custom link).",
+    linkType: "Link kind: page|category|blog_category|brand|product_tag|custom.",
+    linkPage: "Target page id (linkType=page).",
+    linkPageTarget: "Open target for the page link (_self/_blank).",
+    linkCategory: "Target product category id.",
+    linkBlogCategory: "Target blog category id.",
+    linkTarget: "Open target (_self/_blank).",
+    categoryId: "Category id this item points to.",
+    isCustom: "Use a custom link instead of an internal target (boolean).",
+    isSync: "Auto-sync with site pages/categories (boolean).",
+    name: "Display label.",
+    // commerce
+    category_id: "Product category id to source items from.",
+    products_per_load: "Products fetched per page/scroll.",
+    promotion_id: "Linked promotion id.",
+    original_price_position: "Where the compare-at price shows (left/right).",
+    show_categories: "Show category labels (boolean).",
+    // form (also in FIELD below)
+    options: "Choices [{id,name}] for a select/radio/checkbox.",
+    field_type: "Underlying field type.",
+};
+// Common form-field specials reused by every input-like element.
+const FIELD = {
+    field_name: "Submission key this field maps to (e.g. full_name, email, phone_number, note, address, password).",
+    label: "Visible label text.",
+    placeholder: "Placeholder text.",
+    show_label: "Show the label (boolean).",
+    required: "Field is required (boolean).",
+    validate: "Enable validation (boolean).",
+};
+export const ELEMENT_ATTRS = {
+    // ── content ──
+    text: {
+        specials: { text: "Rich text / HTML content.", tag: "Semantic tag: h1|h2|h3|h4|h5|h6|p.", typographyTheme: "Apply a site typography preset.", marker: "List marker: none|dotList|numberList|imageList." },
+        config: { strokeColor: "Text stroke colour." },
+        events: "click, hover (in events[]) — links/actions on text are common.",
+        notes: "Set specials.text (HTML) + specials.tag. Style via runtime.style (color, fontSize, fontWeight, textAlign, lineHeight, letterSpacing).",
+    },
+    "text-dataset": {
+        config: {}, events: "none",
+        bindings: ["product::product_name", "product::product_price", "cart_item::cart_item_name", "cart_item::cart_item_price", "order_item::product_name", "customer_address::full_name"],
+        notes: "Text bound to live data — set bindings[].target to a source::field; no static specials.text.",
+    },
+    image: {
+        specials: { src: "Image URL (hosted).", image_alt: "Alt text (SEO/accessibility)." },
+        config: { src: "Image URL (mirror of specials.src).", ratio: "Aspect ratio.", minWidth: "Min width (px).", minHeight: "Min height (px).", sizeThumbnail: "Thumbnail size." },
+        events: "click, hover (link/lightbox) — very common.",
+        notes: "Put the hosted URL in runtime.config.src (and specials.src). Use search_images/upload_images to get URLs.",
+    },
+    "image-dataset": {
+        events: "none",
+        bindings: ["product::product_image", "cart_item::cart_item_image", "order_item::product_image", "customer_address::pdc"],
+        notes: "Image bound to live data — set bindings[].target; no static src.",
+    },
+    video: {
+        specials: { src: "Video URL.", thumbnail: "Poster image URL.", time: "Duration label (e.g. '10.0s').", type: "Source type (e.g. store)." },
+        events: "none",
+    },
+    "video-dataset": { events: "none", bindings: ["lesson::lesson_video"], notes: "Video bound to a dataset field." },
+    rectangle: {
+        specials: { shapeType: "Shape kind.", custom_css: "Raw CSS for the shape." },
+        config: { mask: "Mask id/shape.", maskId: "Mask reference." },
+        events: "click, hover — often used as a clickable card/background.",
+        notes: "Coloured box / divider / background. Style via runtime.style (background, border*, boxShadow).",
+    },
+    line: { events: "none", notes: "Separator line — style via runtime.style background/border." },
+    gallery: { specials: { media: "Array of media (image) objects." }, config: { showThumbnail: "Show thumbnails.", showNavigation: "Show nav arrows.", thumbnailPosition: "none|top|bottom|left|right." }, events: "none" },
+    carousel: { config: { slideWidth: "Slide width (px).", slideItems: "Visible slides count." }, events: "none", notes: "Holds slide children." },
+    swiper: { config: {}, events: "none", notes: "Swiper carousel — holds slide children." },
+    slide: { events: "none", notes: "A single slide inside a carousel/swiper." },
+    embed: { specials: { iframe: "Raw HTML / iframe markup." }, events: "none" },
+    googlemap: { specials: { iframe: "Google Maps embed iframe string." }, events: "none" },
+    countdown: { specials: { time: "Target date/time.", type: "Countdown mode." }, events: "none", notes: "Timer; check the live skeleton for exact specials." },
+    breadcrumb: { specials: { options: "Per-context paths (search/product/category/blog/post/default).", icon: "Separator string e.g. '>'." }, events: "none" },
+    "list-ordered": { specials: { tableItems: "Column definitions [{name,key,i18nKey}]." }, events: "none" },
+    // ── layout ──
+    section: {
+        specials: { global: "Mark as a global/shared section (reused across pages).", custom_class: "CSS class.", layout: "Nested layout payload (advanced)." },
+        events: "none",
+        notes: "Top-level band; centred 3-column grid. Children go in the centre column (new_section handles this).",
+    },
+    container: { specials: { tabIndex: "Tab order.", custom_class: "CSS class.", custom_css: "Raw CSS." }, config: { maxWidth: "Max width.", maxWidthUnit: "Max-width unit.", fixedPosition: "Sticky/fixed positioning.", animation: "Entrance animation." }, events: "click, hover — clickable groups are common.", notes: "Generic grid box; nest children with their own grid." },
+    row: { events: "none", notes: "Simple horizontal wrapper." },
+    tabs: { specials: { activeTab: "Default active tab index." }, events: "none", notes: "Tabbed container." },
+    collapse: { events: "none", notes: "Accordion container (collapse-item children)." },
+    "collapse-item": { events: "none", notes: "One accordion panel." },
+    "custom-layout": { events: "none", notes: "Free-form layout container." },
+    "layout-dataset": { events: "none", bindings: ["product::*"], notes: "Repeating layout bound to a dataset." },
+    // ── button ──
+    button: { specials: { text: "Button label." }, events: "click — set the action in events[] (open page/link/scroll/popup/add-to-cart...).", notes: "Label in specials.text; behaviour in events[]." },
+    "submit-button": { specials: { text: "Button label (e.g. 'Đăng nhập')." }, events: "submit — submits its parent form.", notes: "Place inside a form." },
+    "paypal-button": { events: "none", notes: "PayPal payment button (provider-handled)." },
+    "button-login-google": { specials: { text: "Label e.g. 'Đăng nhập với Google'." }, events: "click (OAuth)." },
+    "button-login-facebook": { specials: { text: "Label e.g. 'Đăng nhập với Facebook'." }, events: "click (OAuth)." },
+    "current-location": { specials: { text: "Label.", field_name: "current location.", field_type: "current-location." }, events: "click (geolocation)." },
+    // ── form ──
+    form: {
+        specials: {
+            type: "Form behaviour — one of: form_login | form_signup | form_order | form_discount | subscribe | order_tracking | form_booking | form_search_agency | question_form.",
+            submit_success: "Action after a successful submit (e.g. show a message / redirect).",
+            message: "Success message text.",
+            show_message: "Show a success message after submit (boolean).",
+            show_message_time: "How long the success message stays (seconds).",
+        },
+        config: { backgroundInput: "Input background.", labelColor: "Label colour.", placeholderColor: "Placeholder colour.", textPadding: "Input padding (px).", labelMarginBottom: "Gap below label (px)." },
+        events: "none",
+        notes: "Wrap input fields as children; put a submit-button inside. specials.type selects what the form does on submit.",
+    },
+    input: { specials: { ...FIELD, type: "Input type (default text)." }, config: { textPadding: "Padding.", backgroundInput: "Background." }, events: "none" },
+    email: { specials: { ...FIELD, validate_email: "Email regex." }, events: "none", notes: "field_name usually 'email'." },
+    "phone-number": { specials: { ...FIELD }, events: "none", notes: "field_name usually 'phone_number'." },
+    "retype-phone-number": { specials: { ...FIELD }, events: "none" },
+    password: { specials: { ...FIELD, field_type: "password.", validate_password: "Password regex." }, events: "none", notes: "field_name 'password'." },
+    "retype-password": { specials: { ...FIELD, validate_password: "Password regex." }, events: "none" },
+    "current-password": { specials: { ...FIELD, validate_password: "Password regex." }, events: "none" },
+    "text-area": { specials: { ...FIELD }, events: "none", notes: "Multi-line; field_name often 'note'." },
+    select: { specials: { ...FIELD, options: "Choices [{id,name}] (or {type,name,image,active}).", defaultValue: "Selected option id." }, config: { arrowColor: "Dropdown arrow colour.", optionBorderColor: "Option border." }, events: "none" },
+    "group-select": { specials: { ...FIELD, options: "Choices [{id,name}]." }, events: "none" },
+    checkbox: { specials: { field_name: FIELD.field_name, label: FIELD.label, show_label: FIELD.show_label, required: FIELD.required }, events: "none" },
+    "checkbox-group": { specials: { ...FIELD, options: "Choices [{id,name}]." }, config: { gap: "Item spacing.", column: "Columns." }, events: "none" },
+    "checkbox-item": { specials: { label: "Option text." }, events: "none" },
+    radio: { specials: { field_name: FIELD.field_name, label: FIELD.label, show_label: FIELD.show_label, required: FIELD.required }, events: "none" },
+    "radio-group": { specials: { ...FIELD, options: "Choices [{id,name,events?,connects?}]." }, config: { gap: "Item spacing.", column: "Columns." }, events: "none" },
+    address: { specials: { field_name: "province_id/district_id/commune_id.", label: FIELD.label, placeholder: FIELD.placeholder, show_label: FIELD.show_label, country: "Country code (e.g. 84).", required_province: "Require province.", required_districts: "Require district.", required_commune: "Require commune." }, events: "none" },
+    "detect-address": { specials: { ...FIELD, field_type: "detect_address." }, events: "none" },
+    "postal-code": { specials: { ...FIELD }, events: "none" },
+    country: { specials: { ...FIELD }, events: "none" },
+    "input-file": { specials: { ...FIELD, isTransferImage: "Transfer as image (boolean)." }, events: "none" },
+    "input-number": { specials: { ...FIELD }, events: "none" },
+    "input-date": { specials: { ...FIELD, type: "date | time." }, events: "none" },
+    "input-search": { specials: { field_name: "search.", label: FIELD.label, placeholder: FIELD.placeholder }, events: "none" },
+    "otp-input": { specials: { ...FIELD, isOpenModalOtp: "Open OTP modal (boolean)." }, events: "none" },
+    "rating-input": { specials: { field_name: FIELD.field_name, label: FIELD.label, show_label: FIELD.show_label }, events: "none" },
+    identity: { specials: { ...FIELD }, events: "none", notes: "Email-or-phone login field; field_name 'identity'." },
+    switch: { events: "none", notes: "Toggle; style width/height." },
+    // ── commerce ──
+    "grid-product": {
+        specials: { displayStyle: "default | only_image | border.", original_price_position: "left | right." },
+        config: { columns: "Products per row.", responsive: "autofit | fixed.", item_show: "How many products to show.", image_ratio: "16/9|3/2|4/3|1/1|9/16|2/3|3/4.", img_object_fit: "cover|contain|fill|stretch.", gap_column: "Column gap.", gap_row: "Row gap.", product_info_alignment: "left|center|right." },
+        events: "none",
+        bindings: ["product::product_image", "product::product_name", "product::product_price"],
+        notes: "Lists store products. Requires a 'store' page / use_store. Configure columns + image_ratio.",
+    },
+    "slider-product": { specials: { displayStyle: "default|only_image|border.", original_price_position: "left|right." }, config: { slideItems: "Visible products.", slideWidth: "Card width.", image_ratio: "Aspect ratio." }, events: "none", bindings: ["product::product_image", "product::product_name", "product::product_price"] },
+    "product-gallery": { events: "none", notes: "Product detail image gallery (product page)." },
+    "product-image-carousel": { events: "none", notes: "Product image carousel (product page)." },
+    "cart-items": { events: "none", bindings: ["cart_item::cart_item_image", "cart_item::cart_item_name", "cart_item::cart_item_price", "cart_item::cart_item_total_price", "cart_item::cart_item_prod_attr"], notes: "Cart line items (cart page)." },
+    "cart-icon": { specials: { svg: "Icon SVG.", itemCount: "Badge count." }, events: "click — opens cart." },
+    "quantity-input": { events: "none", notes: "Quantity stepper (product/cart)." },
+    attr: { events: "none", notes: "Product attribute selector (variations)." },
+    payment: { events: "none", notes: "Payment methods block (checkout)." },
+    "delivery-method": { specials: { options: "[{type: delivery|store_pickup, name, active}]." }, events: "none" },
+    "order-items": { events: "none", bindings: ["order_item::product_image", "order_item::product_name", "order_item::product_quantity", "order_item::product_attrs", "order_item::items_sum_up_price"], notes: "Order summary lines." },
+    "order-history": { events: "none", notes: "Member order history (member page)." },
+    coupon: { events: "none", notes: "Coupon / discount code input." },
+    "product-overlay": { specials: { type: "discount | custom." }, events: "none", notes: "Badge overlaid on a product card." },
+    "product-review": {
+        specials: {
+            title: "Heading text.", show_heading: "Show the heading (boolean).", reviews_per_page: "Reviews per page.",
+            show_avatar: "Show reviewer avatar (boolean).", avatar_size: "Avatar size (px).", reply_avatar_size: "Reply avatar size (px).",
+            avatar_border_radius: "Avatar corner radius.", avatar_border_color: "Avatar border colour.", avatar_border_size: "Avatar border width.",
+            show_rating_breakdown: "Show the star breakdown (boolean).", show_sorting: "Show sort control (boolean).", show_filter: "Show filter (boolean).",
+            show_publish_date: "Show the review date (boolean).", require_email: "Require email to review (boolean).", require_phone_number: "Require phone (boolean).",
+            type_view_more: "How more reviews load (paginate/expand).",
+        },
+        events: "none", notes: "Product reviews block (product page).",
+    },
+    "number-step": {
+        specials: {
+            minValue: "Minimum value.", maxValue: "Maximum value.", numberUnit: "Unit label.", count: "Step amount.",
+            filter: "Filter mode.", use_button_filter: "Use buttons to filter (boolean).", shortened: "Abbreviate large numbers (boolean).",
+        },
+        events: "none", notes: "Numeric stepper / counter.",
+    },
+    "masonry-review": { specials: { view_product_mode: "How linked products display in the review wall." }, events: "none", notes: "Masonry wall of reviews." },
+    "flash-sale": { specials: { promotion_advance_id: "Promotion id (or 'none')." }, events: "none" },
+    promotions: { events: "none", bindings: ["promotion_item::image", "promotion_item::name", "promotion_item::code", "promotion_item::description", "promotion_item::end_date"] },
+    "promotions-short": { events: "none", bindings: ["promotion_item::name", "promotion_item::code"] },
+    "grid-category": { config: { columns: "Categories per row." }, events: "none", notes: "Lists product categories. Create categories first (create_product_category)." },
+    "slider-category": { config: { columns: "Visible categories." }, events: "none" },
+    "customer-address": { events: "none", bindings: ["customer_address::full_name", "customer_address::address", "customer_address::phone_number", "customer_address::pdc", "customer_address::is_default"], notes: "Member saved addresses." },
+    wishlist: { specials: { svg: "Icon SVG.", itemCount: "Badge count." }, events: "click." },
+    "favorite-icon": { events: "click — toggle favourite." },
+    "bonus-items": { specials: { typeBonus: "combo_product | other." }, events: "none" },
+    // ── navigation ──
+    menu: { specials: { type: "horizontal | vertical | hamburger | anchor.", sync: "Auto-sync items with site pages (boolean)." }, events: "none", notes: "Holds menu-item children." },
+    "menu-item": { specials: { name: "Link label.", isCustom: "Custom link (boolean).", linkType: "page | category | blog_category | brand | product_tag | custom.", linkCategory: "Linked category id.", categoryId: "Category id.", syncSubmenu: "Auto-build submenu (boolean)." }, events: "click — navigates.", notes: "Set linkType + the matching id (or a custom href) to point the link." },
+    "menu-anchor-item": { specials: { name: "Label.", isCustom: "Custom.", linkType: "Link kind.", categoryId: "Category id." }, events: "click — scrolls to an anchor." },
+    submenu: { events: "none", notes: "Dropdown under a menu-item." },
+    "menu-droppable": { events: "none" },
+    "member-bar": { events: "none", notes: "Logged-in member bar (account links)." },
+    "member-dropdown": { events: "none" },
+    dropdown: { events: "click/hover — toggles dropdown-content." },
+    "dropdown-content": { events: "none" },
+    "language-menu": { events: "none", notes: "Language switcher." },
+    // ── blog ──
+    "post-list": { events: "none", notes: "Lists blog articles. Create blog category + articles first." },
+    "slider-post": { config: { slideItems: "Visible posts.", slideWidth: "Card width." }, events: "none" },
+    "grid-blog": { specials: { showBlogs: "Categories to show [{...}]." }, config: { columns: "Posts per row." }, events: "none" },
+    "slider-blog": { specials: { showBlogs: "Categories to show." }, config: { columns: "Visible posts." }, events: "none" },
+    "post-overlay": { specials: { type: "regular | custom." }, events: "none", notes: "Post card overlay (post page)." },
+    "blog-overlay": { specials: { type: "regular | custom." }, events: "none" },
+};
+const describe = (type, key, where) => {
+    const curated = ELEMENT_ATTRS[type] || {};
+    return (curated[where] && curated[where][key]) || SHARED_KEY_DICT[key] || (where === "specials" ? SHARED_SPECIALS[key] : undefined);
+};
+/**
+ * Build a COMPLETE attribute report for an element type, merging three sources:
+ *  - curated tables (ELEMENT_ATTRS) + dictionaries (human meaning),
+ *  - the full real key surface mined from published pages + factory defaults (OBSERVED),
+ *  - the live skeleton (factory defaults).
+ * Every real key is surfaced; ones we have meaning for are described, the rest are
+ * listed by name so the AI knows they exist. No invented keys.
+ */
+export function describeAttributes(type, skeleton) {
+    const curated = ELEMENT_ATTRS[type] || {};
+    const obs = OBSERVED[type] || { specials: [], config: [], style: [], bindings: [], events: false };
+    const skSpecials = (skeleton && skeleton.specials) || {};
+    const skConfig = (skeleton && ((skeleton.runtime && skeleton.runtime.config) || skeleton.config)) || {};
+    // ── specials: every real key, described where known ──
+    const specialKeys = new Set([
+        ...Object.keys(curated.specials || {}),
+        ...obs.specials,
+        ...Object.keys(skSpecials),
+    ]);
+    const specials = {};
+    const moreSpecials = [];
+    for (const k of [...specialKeys].sort()) {
+        if (NOISE_KEYS.has(k) || k in SHARED_SPECIALS)
+            continue; // shared ones listed separately
+        const d = describe(type, k, "specials");
+        if (d)
+            specials[k] = d;
+        else
+            moreSpecials.push(k);
+    }
+    // ── config: element-specific only (drop generic grid/position internals) ──
+    const configKeys = new Set([
+        ...Object.keys(curated.config || {}),
+        ...obs.config,
+        ...Object.keys(skConfig),
+    ]);
+    const config = {};
+    const moreConfig = [];
+    for (const k of [...configKeys].sort()) {
+        if (NOISE_KEYS.has(k) || GENERIC_CONFIG.has(k))
+            continue;
+        const d = describe(type, k, "config");
+        if (d)
+            config[k] = d;
+        else
+            moreConfig.push(k);
+    }
+    const style = (obs.style || []).filter((k) => !NOISE_KEYS.has(k)).sort();
+    return {
+        specials: Object.keys(specials).length ? specials : undefined,
+        more_specials: moreSpecials.length ? moreSpecials : undefined, // real but un-annotated
+        common_specials: Object.keys(SHARED_SPECIALS), // available on almost every element
+        config: Object.keys(config).length ? config : undefined,
+        more_config: moreConfig.length ? moreConfig : undefined, // real but un-annotated (mostly visual)
+        style: style.length ? style : undefined,
+        events: curated.events || (obs.events ? "supports events[] (click/hover/submit actions)" : "none observed"),
+        bindings: (curated.bindings && curated.bindings.length ? curated.bindings : obs.bindings) || undefined,
+        notes: curated.notes,
+        common_specials_note: "custom_class/custom_css/element_async/event_name_custom work on almost every element.",
+        layout_hint: "runtime.style holds CSS (width/height/color/fontSize/background/border…); runtime.config holds grid placement (see get_build_guide). On save these expand into bp1..bp4.",
+        coverage: obs.seen ? `${obs.seen} real instances mined` : "factory default only",
+    };
+}

package/dist/builder/catalog.js

@@ -5,6 +5,7 @@
 // create* function, (2) attach curated, human-readable metadata (category + summary)
 // so an AI agent can understand the palette, and (3) expose helpers the MCP tools use.
 import * as F from "./factory.js";
+import { describeAttributes } from "./attributes.js";
 // Probe every factory once with safe default opts to learn the type string it produces
 // and whether it is a container (has a children array). Calling with {children:[]} is
 // safe for all 132 factories (verified) — none throw.
@@ -180,7 +181,9 @@ export function getElement(type) {
     const d = describeType(type);
     // A live skeleton straight from the factory = authoritative shape for this type.
     const skeleton = buildElement(type, {});
-    return { ...d, skeleton };
+    // Curated + skeleton-derived attribute reference so the agent knows the meaningful keys.
+    const attributes = describeAttributes(type, skeleton);
+    return { ...d, attributes, skeleton };
 }
 export const ELEMENT_TYPES = ALL_TYPES;
 export const CONTAINER_TYPE_SET = CONTAINER_TYPES;