sbuilder-mcp 0.2.2 → 0.3.0

package/dist/catalog/elements.generated.js

@@ -1,5 +1,5 @@
 export const ELEMENT_SOURCE = {
-    "count": 106,
+    "count": 107,
     "docSchemaVersion": 2
 };
 export const ELEMENTS = {
@@ -670,6 +670,34 @@ export const ELEMENTS = {
         "locked": false,
         "hideInLayer": false,
         "childAllows": [],
+        "events": {
+            "click": [
+                "go_to_url",
+                "open_page",
+                "popup",
+                "open_menu",
+                "close_menu",
+                "toggle_menu",
+                "open_cart",
+                "close_cart",
+                "go_to_checkout",
+                "cart_remove",
+                "cart_increment",
+                "cart_decrement",
+                "change_tab",
+                "open_dropdown",
+                "close_dropdown",
+                "toggle_dropdown",
+                "logout_customer",
+                "toggle_wishlist"
+            ]
+        },
+        "bindingEvents": {
+            "click": [
+                "open_cart",
+                "go_to_checkout"
+            ]
+        },
         "defaults": {
             "specials": {
                 "text": "Button",
@@ -878,6 +906,17 @@ export const ELEMENTS = {
         "locked": false,
         "hideInLayer": false,
         "childAllows": [],
+        "events": {
+            "click": [
+                "go_to_url",
+                "open_page",
+                "popup",
+                "change_tab",
+                "open_dropdown",
+                "close_dropdown",
+                "toggle_dropdown"
+            ]
+        },
         "defaults": {
             "specials": {
                 "src": "",
@@ -1025,6 +1064,28 @@ export const ELEMENTS = {
         "locked": false,
         "hideInLayer": false,
         "childAllows": [],
+        "events": {
+            "click": [
+                "go_to_url",
+                "open_page",
+                "popup",
+                "open_menu",
+                "close_menu",
+                "toggle_menu",
+                "open_cart",
+                "close_cart",
+                "go_to_checkout",
+                "cart_remove",
+                "cart_increment",
+                "cart_decrement",
+                "change_tab",
+                "open_dropdown",
+                "close_dropdown",
+                "toggle_dropdown",
+                "logout_customer",
+                "toggle_wishlist"
+            ]
+        },
         "defaults": {
             "specials": {
                 "name": "StarFill",
@@ -3984,6 +4045,170 @@ export const ELEMENTS = {
             "signed-in"
         ]
     },
+    "order-receipt": {
+        "type": "order-receipt",
+        "label": "Order receipt",
+        "category": "advanced",
+        "isContainer": false,
+        "isRootOnly": false,
+        "locked": false,
+        "hideInLayer": false,
+        "childAllows": [],
+        "defaults": {
+            "specials": {
+                "title": "Chi tiết đơn hàng",
+                "numberLabel": "Mã đơn hàng",
+                "placedLabel": "Ngày đặt",
+                "statusLabel": "Trạng thái",
+                "itemsLabel": "Sản phẩm",
+                "totalLabel": "Tổng cộng",
+                "dueLabel": "Còn phải trả",
+                "unavailableText": "Không tải được chi tiết đơn hàng. Bạn có thể tra cứu bằng mã đơn hàng trong trang tài khoản."
+            },
+            "style": {
+                "width": "100%"
+            }
+        },
+        "inspector": [
+            {
+                "tab": "general",
+                "groups": [
+                    {
+                        "key": "receipt_content",
+                        "label": "Content",
+                        "controls": [
+                            "receipt_title",
+                            "receipt_number_label",
+                            "receipt_placed_label",
+                            "receipt_status_label",
+                            "receipt_items_label"
+                        ]
+                    },
+                    {
+                        "key": "receipt_totals",
+                        "label": "Totals",
+                        "controls": [
+                            "receipt_total_label",
+                            "receipt_due_label"
+                        ]
+                    },
+                    {
+                        "key": "receipt_unavailable",
+                        "label": "Unavailable",
+                        "controls": [
+                            "receipt_unavailable_text"
+                        ]
+                    },
+                    {
+                        "key": "size",
+                        "label": "Size",
+                        "controls": [
+                            "width_select",
+                            "height_select",
+                            "size_bounds"
+                        ]
+                    },
+                    {
+                        "key": "background",
+                        "label": "Background",
+                        "controls": [
+                            "bg_color",
+                            "bg_image"
+                        ]
+                    },
+                    {
+                        "key": "shape",
+                        "label": "Shape",
+                        "controls": [
+                            "border",
+                            "corner",
+                            "shadow"
+                        ]
+                    }
+                ]
+            },
+            {
+                "tab": "advanced",
+                "groups": [
+                    {
+                        "key": "spacing",
+                        "label": "Spacing",
+                        "controls": [
+                            "padding_margin"
+                        ]
+                    },
+                    {
+                        "key": "display",
+                        "label": "Display",
+                        "controls": [
+                            "display"
+                        ]
+                    },
+                    {
+                        "key": "animation",
+                        "label": "Animation",
+                        "controls": [
+                            "animation"
+                        ]
+                    },
+                    {
+                        "key": "class_css",
+                        "label": "Class",
+                        "controls": [
+                            "class_css"
+                        ]
+                    }
+                ]
+            }
+        ],
+        "controls": [
+            "receipt_title",
+            "receipt_number_label",
+            "receipt_placed_label",
+            "receipt_status_label",
+            "receipt_items_label",
+            "receipt_total_label",
+            "receipt_due_label",
+            "receipt_unavailable_text",
+            "width_select",
+            "height_select",
+            "size_bounds",
+            "bg_color",
+            "bg_image",
+            "border",
+            "corner",
+            "shadow",
+            "padding_margin",
+            "display",
+            "animation",
+            "class_css"
+        ],
+        "description": "Shows the order a shopper has just paid for on a checkout completion page: order number, date, status, the items, the total, and anything still owed. Reads one order through the signed receipt grant the payment return endpoint puts in the completion URL, so it works for a guest who has no account.",
+        "useWhen": [
+            "Building the checkout completion page a shopper lands on after paying at a gateway.",
+            "The store takes card or wallet payments and wants the buyer to see what they bought without signing in.",
+            "Pairing with payment-status, which reports the MONEY; this reports the ORDER."
+        ],
+        "avoidWhen": [
+            "On any page other than the completion page — every other page is reached without the signed grant, so the block hides itself and renders nothing.",
+            "As an order history list: this shows exactly one order. Use order-history for a signed-in shopper’s past orders.",
+            "To show a home address or per-line prices — the receipt read is deliberately reduced and carries neither."
+        ],
+        "contentTips": [
+            "Word the labels the way the store talks about orders; every string here is yours, not the platform’s.",
+            "The \"still owed\" row prints only when something is actually outstanding, so its label can say so plainly.",
+            "The unavailable sentence is read by someone whose link has expired — point them at where the order really lives."
+        ],
+        "semantics": [
+            "order",
+            "receipt",
+            "checkout",
+            "completion",
+            "confirmation",
+            "ecommerce",
+            "guest"
+        ]
+    },
     "course-outline": {
         "type": "course-outline",
         "label": "Course Syllabus",
@@ -5576,6 +5801,29 @@ export const ELEMENTS = {
         "locked": false,
         "hideInLayer": false,
         "childAllows": [],
+        "events": {
+            "form:submit": [
+                "popup",
+                "close_popup",
+                "open_cart",
+                "close_cart"
+            ],
+            "form:success": [
+                "go_to_url",
+                "open_page",
+                "popup",
+                "close_popup",
+                "open_cart",
+                "close_cart",
+                "go_to_checkout"
+            ],
+            "form:error": [
+                "popup",
+                "close_popup",
+                "open_cart",
+                "close_cart"
+            ]
+        },
         "defaults": {
             "specials": {
                 "formId": "",
@@ -5716,7 +5964,7 @@ export const ELEMENTS = {
         "avoidWhen": [
             "A single button or link is all that is needed — a form asks the visitor to type, which is a much larger request than a click.",
             "The data belongs to an existing flow that already has its own surface (adding to the cart, checking out).",
-            "Sign-in, registration or password reset: those need storefront customer accounts, which do not exist yet, so a form there would submit into nothing."
+            "A `custom` form for sign-in or registration: use the LOGIN / REGISTER / FORGOT / RESET types instead. Storefront customer accounts exist — those types submit through /_wb/account/* rather than the submissions table, and a custom form pointed at the same job stores a password in a response row."
         ],
         "contentTips": [
             "Ask for the fewest fields that make the request answerable. Every additional field measurably reduces the number of people who finish.",
@@ -23374,6 +23622,13 @@ export const ELEMENTS = {
         "locked": false,
         "hideInLayer": false,
         "childAllows": [],
+        "events": {
+            "click": [
+                "go_to_url",
+                "open_page",
+                "popup"
+            ]
+        },
         "defaults": {
             "style": {
                 "width": "100%",
@@ -32088,6 +32343,94 @@ export const TRAIT_WRITES = {
             }
         ]
     },
+    "receipt_title": {
+        "key": "receipt_title",
+        "label": "Section title",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "title",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_number_label": {
+        "key": "receipt_number_label",
+        "label": "Order number label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "numberLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_placed_label": {
+        "key": "receipt_placed_label",
+        "label": "Date label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "placedLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_status_label": {
+        "key": "receipt_status_label",
+        "label": "Status label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "statusLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_items_label": {
+        "key": "receipt_items_label",
+        "label": "Items label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "itemsLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_total_label": {
+        "key": "receipt_total_label",
+        "label": "Total label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "totalLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_due_label": {
+        "key": "receipt_due_label",
+        "label": "Outstanding label",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "dueLabel",
+                "type": "string"
+            }
+        ]
+    },
+    "receipt_unavailable_text": {
+        "key": "receipt_unavailable_text",
+        "label": "Unavailable message",
+        "writes": [
+            {
+                "target": "specials",
+                "writeKey": "unavailableText",
+                "type": "string"
+            }
+        ]
+    },
     "member_audience": {
         "key": "member_audience",
         "label": "Show to",

package/dist/core/tree.js

@@ -4,6 +4,15 @@ export const SPEC_OVERLAY_ID = 'overlayId';
 /** The specials stamps a composed global section carries. */
 export const SPEC_GLOBAL_ID = 'globalId';
 export const SPEC_GLOBAL_KIND = 'globalKind';
+/**
+ * The OPTIMISTIC FENCE on a shared master, one per kind.
+ *
+ * Compose writes it, the save sends it back as `expectRev`, and the platform
+ * refuses a stale one with a warning and a 200 — so a client that does not
+ * re-stamp from the save's own report silently drops every edit after the first.
+ */
+export const SPEC_GLOBAL_REV = 'globalRev';
+export const SPEC_OVERLAY_REV = 'overlayRev';
 export const SPEC_GLOBAL_REF = 'globalRef';
 /** The specials stamps a composed APP BLOCK carries (appblocks.go:97-100). */
 export const SPEC_APP_BLOCK_ID = 'appBlockId';

package/dist/domains/site/builder.js

@@ -1,6 +1,6 @@
 import { isOverlay, subtreeIds, ancestors, appBlockRoot, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REF, } from '../../core/tree.js';
 import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
-import { createNode, mintSatellites } from './node.js';
+import { bindingsForConfig, createNode, mintSatellites } from './node.js';
 import { refuseSecondTemplate } from './traps.js';
 import { genId } from './ids.js';
 /** Append sentinel: splice clamps a too-large index, and `isSyncablePatch`
@@ -252,17 +252,13 @@ function rebindPatch(doc, id, keys) {
     if (!touchesAxis)
         return null;
     const node = doc.node(id);
-    const meta = ELEMENTS[node.data.type];
-    const table = meta?.bindingsFor;
-    if (!table)
-        return null;
     const cfg = node.config ?? {};
-    const source = String(keys.datasetSource ?? cfg.datasetSource ?? 'product');
-    const kind = String(keys.kind ?? cfg.kind ?? '');
-    const next = table[`${source}|${kind}`];
+    // The config the node will HAVE once these keys land — the axis is read off
+    // the result of the write, not off either half of it.
+    const next = bindingsForConfig(node.data.type, { ...cfg, ...keys, datasetSource: keys.datasetSource ?? cfg.datasetSource ?? 'product' });
     if (!next)
         return null;
-    return { op: 'set', path: ['nodes', id, 'bindings'], value: JSON.parse(JSON.stringify(next)) };
+    return { op: 'set', path: ['nodes', id, 'bindings'], value: next };
 }
 /**
  * Copy a node and everything under it, under fresh ids, beside the original.

package/dist/domains/site/document.js

@@ -1,6 +1,27 @@
 import { applyPatches } from '../../core/patch.js';
 import { childrenOf, isOverlay, appBlockRoot } from '../../core/tree.js';
 import { bandOf, isGlobal } from './traps.js';
+import { SATELLITE_RULES } from '../../catalog/elements.generated.js';
+/**
+ * The satellite nodes this one owns, as {id, config key} pairs.
+ *
+ * Read from the GENERATED rules rather than a hand-kept list, so an element the
+ * platform gives a satellite is covered the day the catalog is regenerated. A
+ * key pointing at an id the document does not hold is skipped rather than
+ * reported: a dangling pointer is `validateForSave`'s business, not the map's.
+ */
+function satellitesOf(doc, id) {
+    const node = doc.nodes[id];
+    const rules = SATELLITE_RULES[node?.data?.type ?? ''] ?? [];
+    const out = [];
+    for (const rule of rules) {
+        const satId = node?.config?.[rule.configKey];
+        if (typeof satId === 'string' && satId && doc.nodes[satId]) {
+            out.push({ id: satId, key: rule.configKey });
+        }
+    }
+    return out;
+}
 /**
  * One page's document, in memory.
  *
@@ -139,8 +160,19 @@ export class PageDoc {
                 out.global = true;
             if (appBlockRoot(this.doc, id) === id)
                 out.app = true;
-            if (level + 1 < depth && kidIds.length > 0) {
-                out.kids = kidIds.map((k) => line(k, level + 1));
+            if (level + 1 < depth) {
+                // Satellites come FIRST, and are counted apart from `children`: they are
+                // this node's own chrome, not content in it, and mixing the two would
+                // make the child count disagree with `data.nodes` — the number every
+                // index-taking call (sb_add, sb_move) is written against.
+                const sats = satellitesOf(this.doc, id).map((sat) => {
+                    const l = line(sat.id, level + 1);
+                    l.satellite = sat.key;
+                    return l;
+                });
+                const kids = kidIds.map((k) => line(k, level + 1));
+                if (sats.length || kids.length)
+                    out.kids = [...sats, ...kids];
             }
             return out;
         };

package/dist/domains/site/node.js

@@ -5,6 +5,43 @@ import { genId } from './ids.js';
 function copy(v) {
     return JSON.parse(JSON.stringify(v));
 }
+/**
+ * The bindings an element carries for a given config, or null when its data
+ * axis says nothing about this pair.
+ *
+ * Reads the generated `bindingsFor` table — the platform's own
+ * `datasetBindings(type, config)` answers, enumerated at codegen.
+ *
+ * THE KIND FALLBACK IS THE POINT. The table is keyed `${datasetSource}|${kind}`,
+ * but TEN elements with a table declare no default `config.kind` at all —
+ * `list-dataset`, `dataset-block`, `media-dataset`, `collection-media`,
+ * `product-variants`, `quantity-dataset` and friends, which is most of what a
+ * store is built from. For those the key came out `category|`, matched nothing,
+ * and the lookup returned null: a `list-dataset` switched to collections kept
+ * `bind-target` → `product_list` and repeated PRODUCTS under a heading that said
+ * collections. Every `<source>|*` row of such an element is identical (they have
+ * no kind axis to vary on), so the first row for the source IS the answer, and
+ * falling back to it is what makes the axis reachable at all.
+ */
+export function bindingsForConfig(type, config) {
+    const table = ELEMENTS[type]?.bindingsFor;
+    if (!table)
+        return null;
+    const source = String(config?.datasetSource ?? '');
+    if (!source)
+        return null;
+    const kind = String(config?.kind ?? '');
+    const exact = table[`${source}|${kind}`];
+    if (exact)
+        return copy(exact);
+    // No kind axis on this element: any row for the source carries the same answer.
+    const prefix = `${source}|`;
+    for (const [key, value] of Object.entries(table)) {
+        if (key.startsWith(prefix))
+            return copy(value);
+    }
+    return null;
+}
 /**
  * Mint a node seeded from its element's catalog defaults.
  *
@@ -21,6 +58,7 @@ export function createNode(type, opts = {}) {
     }
     const d = meta.defaults;
     const states = d.states;
+    const config = { ...copy(d.config ?? {}), ...(opts.config ?? {}) };
     return {
         id: genId(type),
         data: {
@@ -33,7 +71,7 @@ export function createNode(type, opts = {}) {
             custom: {},
         },
         style: { ...copy(d.style ?? {}), ...(opts.style ?? {}) },
-        config: { ...copy(d.config ?? {}), ...(opts.config ?? {}) },
+        config,
         specials: { ...copy(d.specials ?? {}), ...(opts.specials ?? {}) },
         responsive: copy(d.responsive ?? {}),
         ...(states ? { states: copy(states) } : {}),
@@ -49,12 +87,17 @@ export function createNode(type, opts = {}) {
         // placeholder forever. Found on a live page: four product cards reading
         // "$0.00" with no titles, on a catalogue that had four products.
         //
-        // Codegen bakes the factory's answer for the DEFAULT config. A caller who
-        // overrides `config.kind` or `config.datasetSource` in the same call is
-        // changing which field the element binds, and that re-derivation lives in
-        // the platform — so the bindings here follow the defaults, and a changed
-        // kind needs an explicit sb_bind.
-        bindings: copy(d.bindings ?? []),
+        // Codegen bakes the factory's answer for EVERY config pair, not just the
+        // default one, so a caller who overrides `config.kind` or
+        // `config.datasetSource` in the same call is answered here rather than left
+        // holding the default entity's bindings. It used to be left: `sb_add` with
+        // `datasetSource: "category"` minted a repeater still bound to
+        // `product_list`, saved, published, and repeated products under a heading
+        // that said collections — with no warning on any of the four steps, because
+        // a wrong binding renders exactly like a right one until you read the data.
+        // `sb_set` re-derives on the same table for the same reason; the two paths
+        // must not disagree about what a config means.
+        bindings: bindingsForConfig(type, config) ?? copy(d.bindings ?? []),
     };
 }
 /**

package/dist/domains/site/readiness.js

@@ -110,6 +110,47 @@ export function readinessGaps(input) {
             fix: 'Add at least one shipping method (sb_api_find "shipping methods").',
         });
     }
+    // THE OTHER FIXED PATHS.
+    //
+    // `page.FixedPathTypes` is four — search, checkout, complete, account — and
+    // each resolves to the site's PUBLISHED page of that type
+    // (storefront/typeroute.go). `complete` is the one that backstops itself: with
+    // no completion page the storefront serves a built-in receipt, measured 200 on
+    // a live store that had none. The other three 404, and `/account` and
+    // `/search` 404 QUIETLY — nothing links to them by default, so the merchant
+    // finds out when a shopper who wants their order history does.
+    //
+    // Separate from the five above, and after them, because these do not stand
+    // between the store and a PAID ORDER: a shop with no account page still takes
+    // money. They stand between it and a finished website, which is the next
+    // question a merchant asks.
+    for (const [type, id, what, fix] of [
+        [
+            'account',
+            'accountPage',
+            '/account 404s. A shopper has no way to see their orders, addresses or saved items, and ' +
+                'the account elements (account-info, address-book, wishlist-list, points-card) have ' +
+                'nowhere to live.',
+            'Create a page of type "account" and publish it. Put login and register forms behind a ' +
+                'member-gate with audience "guests", and the profile behind audience "members".',
+        ],
+        [
+            'search',
+            'searchPage',
+            '/search 404s, so a search box in the header sends every shopper to a dead page.',
+            'Create a page of type "search" and publish it.',
+        ],
+    ]) {
+        if (!pages || published(pages, type))
+            continue;
+        const draft = drafted(pages, type);
+        gaps.push({
+            id,
+            draft,
+            problem: what,
+            fix: draft ? `Publish the ${type} page that already exists.` : fix,
+        });
+    }
     if (input.globalNodes !== null && !opensCart([...input.pageNodes, ...input.globalNodes])) {
         gaps.push({
             id: 'cartTrigger',