sbuilder-mcp 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.1] - 2026-09-10
+
+### Fixed
+- sb_add, sb_set, sb_move, sb_remove, sb_duplicate, sb_event and sb_bind now judge a write against a throwaway copy of the page before applying it, so a save the platform refuses is never applied to the draft or broadcast to a live session; previously the refused node stayed in the document and every later command was validated against a tree the caller never asked for, repeating the same complaint about an id it had never typed. A write is still refused only for problems it introduces, not for damage the page already had when the session opened it.
+- sb_import_page now builds its whole run of sections on a copy and commits them in one save, so a refusal partway through no longer leaves a page half imported with no way to tell which sections landed.
+
+## [0.16.0] - 2026-09-10
+
+### Added
+- sb_traits_for now returns a `translatable` block naming which of an element's specials a translation may safely rewrite, and which of its own specials must never be translated, since translating a non-content special (a lucide icon `name`, a `src` URL, a `filterSource` registry id) does not degrade the page, it breaks the render.
+- sb_api_find and sb_api_call now attach a `translation_fields` call sheet to every `/translations` operation, listing the translatable columns for each entity type and pointing to sb_traits_for for the per-element `node` vocabulary, since every translations route was already reachable with no way to know which fields were safe to send.
+- sb_set now warns once per node type when a field-skin config key (`payCardBg`, `choice*`, `slot*`, `file*`, and the rest of the 55-key vocabulary) is written on a form node whose renderer does not read it, naming the field node that actually renders it, since such a write is stored, saved and published but rendered nowhere.
+
+### Internal
+- The generated catalog gained a translations table (`translations.generated.ts`, 141 translatable specials across 58 elements, 156 keys classified as never-translate, 12 entity types with their columns) and a field-skin table (`fieldskin.generated.ts`), both cross-checked at codegen time against the platform's own registries rather than hand-kept.
+
 ## [0.15.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,22 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.1] - 2026-09-10
+
+### Fixed
+- sb_add, sb_set, sb_move, sb_remove, sb_duplicate, sb_event và sb_bind giờ đánh giá một lần ghi trên một bản sao tạm của trang trước khi áp dụng thật, để một lần save bị nền tảng từ chối không bao giờ được áp vào draft hay phát ra cho một phiên live đang xem; trước đây node bị từ chối vẫn ở lại trong document và mọi lệnh sau đó đều bị kiểm tra dựa trên một tree mà người gọi chưa từng yêu cầu, lặp lại cùng một lời phàn nàn về một id mà họ chưa từng gõ. Một lần ghi vẫn chỉ bị từ chối vì vấn đề do chính nó gây ra, không phải vì hư hỏng trang đã có sẵn từ trước khi phiên làm việc mở nó.
+- sb_import_page giờ dựng toàn bộ các section trong một lượt import trên một bản sao và commit chúng trong một lần save duy nhất, để một lần từ chối giữa chừng không còn để lại một trang import dở dang mà không cách nào biết những section nào đã vào được.
+
+## [0.16.0] - 2026-09-10
+
+### Added
+- sb_traits_for giờ trả về một khối `translatable` nêu tên những special nào của element có thể an toàn để một bản dịch ghi đè, và những special riêng của nó không bao giờ được dịch, vì dịch một special không phải nội dung (một `name` icon lucide, một URL `src`, một id registry `filterSource`) không làm trang xấu đi, mà làm hỏng hẳn phần render.
+- sb_api_find và sb_api_call giờ đính kèm một call sheet `translation_fields` vào mọi operation `/translations`, liệt kê các cột có thể dịch cho từng loại entity và trỏ tới sb_traits_for để lấy vocabulary riêng theo từng element cho entity `node`, vì trước đây mọi route translations đều đã gọi được mà không có cách nào biết field nào an toàn để gửi.
+- sb_set giờ cảnh báo một lần cho mỗi loại node khi một config key thuộc field-skin (`payCardBg`, `choice*`, `slot*`, `file*`, và phần còn lại trong vocabulary 55 key) được ghi trên một form node mà renderer của nó không đọc key đó, nêu tên field node thực sự render nó, vì việc ghi này vẫn được lưu, save và publish nhưng không được render ở đâu cả.
+
+### Internal
+- Catalog được sinh ra giờ có thêm bảng translations (`translations.generated.ts`, 141 special có thể dịch trên 58 element, 156 key được phân loại không bao giờ dịch, 12 loại entity cùng các cột của chúng) và bảng field-skin (`fieldskin.generated.ts`), cả hai đều được đối chiếu chéo lúc codegen với chính các registry của nền tảng thay vì giữ thủ công.
+
 ## [0.15.0] - 2026-09-10
 
 ### Added

package/dist/catalog/element-search.js

@@ -1,5 +1,6 @@
 import { ELEMENTS, TRAIT_WRITES } from './elements.generated.js';
 import { vocabulariesForWrites } from '../domains/site/vocabulary.js';
+import { neverTranslatedOn, translatableSpecials } from '../domains/site/translate.js';
 /** Eight to choose from; the hints for the chosen one come with sb_traits_for. */
 export const DEFAULT_CATALOG_LIMIT = 8;
 /**
@@ -95,6 +96,24 @@ export function traitsFor(type, control) {
         // which, unlike `style`, are NOT open — this is the machine-readable
         // answer to "what does this element store", and often the only one.
         defaults: el.defaults,
+        // WHICH OF THIS ELEMENT'S STRINGS A TRANSLATION MAY REWRITE. Translating one
+        // of the others does not degrade the page, it BREAKS the render — `name` is
+        // a lucide icon id, `src` a URL, `filterSource` a registry id the renderer
+        // switches on. An empty list is the complete answer for an element whose
+        // only string is one of those, so it is reported rather than omitted.
+        ...(() => {
+            const may = translatableSpecials(el.type);
+            const own = Object.keys(el.defaults?.specials ?? {});
+            const never = neverTranslatedOn(el.type, own);
+            if (!may.length && !never.length)
+                return {};
+            return {
+                translatable: {
+                    specials: may,
+                    ...(never.length ? { never_translate: never } : {}),
+                },
+            };
+        })(),
         // WHAT THOSE KEYS ARE ALLOWED TO HOLD, for the few where guessing wrong is
         // silent. Attached to the ELEMENT rather than to a control, because the keys
         // that most need it are exactly the UNDECLARED ones: `collectionType` is in

package/dist/catalog/fieldskin.generated.js

@@ -0,0 +1,162 @@
+// GENERATED by scripts/gen-catalog.ts — do not edit by hand.
+// Source: <WB_REPO>/schema/src/elements/fieldSkin.ts (the vocabulary) and each
+// server/render/nodes/form*/css.go (which node emits which group).
+export const FIELD_SKIN_SOURCE = {
+    "nodes": 11,
+    "keys": 55
+};
+/**
+ * The field-skin config keys each form node's renderer actually reads.
+ *
+ * A knob written on a node that is not in its list is stored, saved, published
+ * and rendered NOWHERE — the documented case being payCard* on the FORM, which
+ * emits only the input vocabulary. Composed from the TS groups and asserted
+ * against the Go's own key literals at codegen.
+ */
+export const FIELD_SKIN_BY_NODE = {
+    "form": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-calendar": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-checkbox": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "choiceRowGap",
+        "choiceColGap",
+        "choiceGap",
+        "choiceSize",
+        "choiceBorderWidth",
+        "choiceBorderColor",
+        "choiceBg",
+        "choiceAccent",
+        "choiceRadius",
+        "choiceMarkWidth"
+    ],
+    "form-date": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-file": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fileGap",
+        "filePlaceholderWeight"
+    ],
+    "form-number": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-payment": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "payCardBg",
+        "payCardBorderColor",
+        "payCardBorderWidth",
+        "payCardRadius",
+        "payCardPadY",
+        "payCardPadX",
+        "payCardGap",
+        "payCardRowGap",
+        "payCardAccent",
+        "payCardSelectedBg",
+        "payCardHoverColor",
+        "payCardHoverBg",
+        "payCardText",
+        "payCardNameWeight",
+        "payCardDescOpacity",
+        "payCardBodyGap",
+        "payMarkerSize",
+        "payMarkerDot"
+    ],
+    "form-radio": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "choiceRowGap",
+        "choiceColGap",
+        "choiceGap",
+        "choiceSize",
+        "choiceBorderWidth",
+        "choiceBorderColor",
+        "choiceBg",
+        "choiceAccent",
+        "choiceDot"
+    ],
+    "form-select": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-text": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "fieldBg",
+        "fieldBorderColor",
+        "fieldBorderWidth",
+        "fieldRadius",
+        "fieldPadY",
+        "fieldPadX"
+    ],
+    "form-timeslot": [
+        "fieldStackGap",
+        "fieldReqColor",
+        "fieldHintOpacity",
+        "slotBg",
+        "slotBorderColor",
+        "slotBorderWidth",
+        "slotRadius",
+        "slotPadY",
+        "slotPadX",
+        "slotGap",
+        "slotMinWidth",
+        "slotMinHeight",
+        "slotAccent",
+        "slotHoverColor",
+        "slotSelectedWeight",
+        "slotMarkerSize",
+        "slotMarkerDot",
+        "slotMarkerGap"
+    ]
+};

package/dist/catalog/search.js

@@ -1,5 +1,6 @@
 import { API_OPERATIONS, API_DEFINITIONS } from './api.generated.js';
 import { REQUEST_SHAPES } from './shapes.generated.js';
+import { translationCallSheet } from '../domains/site/translate.js';
 /**
  * Term-hit scoring, weighted by field, and deliberately NOT fuzzy.
  *
@@ -82,6 +83,14 @@ export function describeOperation(op) {
     // The two warnings below are dropped when a shape is present: they exist
     // because the shape was unknown, and keeping them once it is known is prose
     // the model has to read past on its way to the answer.
+    // A TRANSLATIONS OPERATION IS REACHABLE AND WAS UNSAFE. Every route here is in
+    // the catalog, so an agent could call them all and had no way to know which
+    // fields are content — and translating the wrong special BREAKS the render
+    // rather than degrading it. Attached to the call sheet because that is where
+    // the agent already is when it decides what to send.
+    if (/\/translations(\/|$)/.test(op.path)) {
+        out.translation_fields = translationCallSheet();
+    }
     const shape = REQUEST_SHAPES[op.id];
     if (shape) {
         out.body_shape = shape;

package/dist/catalog/shapes.generated.js

@@ -4,7 +4,7 @@ export const SHAPE_SOURCE = {
     "fromHandlers": 166,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
-    "structsRead": 1637
+    "structsRead": 1641
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{siteId}/api-keys": {

package/dist/catalog/translations.generated.js

@@ -0,0 +1,656 @@
+// GENERATED by scripts/gen-catalog.ts — do not edit by hand.
+// Source: <WB_REPO>/schema/src/elements/translatableFields.ts
+export const TRANSLATION_SOURCE = {
+    "elements": 58,
+    "pairs": 141,
+    "neverKeys": 156,
+    "entityTypes": 12
+};
+/** Every entity type a translation record can name, including "node". */
+export const TRANSLATION_ENTITY_TYPES = [
+    "product",
+    "category",
+    "article",
+    "blogCategory",
+    "course",
+    "review",
+    "courseSection",
+    "courseLesson",
+    "node",
+    "page",
+    "uiString",
+    "mailString",
+    "siteLabel"
+];
+/**
+ * The specials a translation MAY rewrite, per element type.
+ *
+ * An element absent here has none. That is not an oversight: an icon's only
+ * string is a lucide id.
+ */
+export const TRANSLATABLE_SPECIALS = {
+    "popup": [
+        "closeLabel"
+    ],
+    "select": [
+        "placeholder",
+        "filterValues"
+    ],
+    "filter-checkbox": [
+        "filterValues"
+    ],
+    "filter-radio": [
+        "filterValues"
+    ],
+    "filter-color": [
+        "filterValues"
+    ],
+    "filter-tag": [
+        "filterValues"
+    ],
+    "account-info": [
+        "promptText",
+        "loginLabel"
+    ],
+    "cart-count": [
+        "placeholder"
+    ],
+    "cart-total": [
+        "label",
+        "placeholder"
+    ],
+    "order-history": [
+        "title",
+        "emptyText",
+        "signedOutText",
+        "lookupNumberPlaceholder",
+        "lookupContactPlaceholder",
+        "lookupButtonText"
+    ],
+    "order-receipt": [
+        "title",
+        "numberLabel",
+        "placedLabel",
+        "statusLabel",
+        "itemsLabel",
+        "totalLabel",
+        "dueLabel",
+        "unavailableText"
+    ],
+    "course-outline": [
+        "emptyText"
+    ],
+    "my-courses": [
+        "emptyText",
+        "signedOutText",
+        "continueText"
+    ],
+    "course-player": [
+        "completeLabel",
+        "completedLabel",
+        "certificateText",
+        "lockedText",
+        "lockedLabel",
+        "emptyText"
+    ],
+    "wishlist-list": [
+        "title",
+        "emptyText"
+    ],
+    "address-book": [
+        "title",
+        "emptyText",
+        "signedOutText",
+        "addLabel"
+    ],
+    "points-card": [
+        "title",
+        "signedOutText"
+    ],
+    "member-field": [
+        "prefix",
+        "suffix",
+        "guestText"
+    ],
+    "accordion-content": [
+        "label"
+    ],
+    "button": [
+        "text",
+        "textHtml"
+    ],
+    "cart-order": [
+        "emptyText"
+    ],
+    "payment-status": [
+        "paidTitle",
+        "paidText",
+        "pendingTitle",
+        "pendingText",
+        "failedTitle",
+        "failedText",
+        "retryLabel",
+        "referenceLabel"
+    ],
+    "collection-media": [
+        "alt"
+    ],
+    "divider": [
+        "label"
+    ],
+    "heading": [
+        "text",
+        "textHtml"
+    ],
+    "form-text": [
+        "label",
+        "placeholder",
+        "description"
+    ],
+    "form-number": [
+        "label",
+        "placeholder",
+        "description"
+    ],
+    "form-select": [
+        "label",
+        "options",
+        "placeholder",
+        "description"
+    ],
+    "form-address": [
+        "label",
+        "description",
+        "provinceLabel",
+        "wardLabel",
+        "detailLabel",
+        "provincePlaceholder",
+        "wardPlaceholder",
+        "detailPlaceholder",
+        "placeholder"
+    ],
+    "form-radio": [
+        "label",
+        "options",
+        "description"
+    ],
+    "form-payment": [
+        "label",
+        "description",
+        "methods"
+    ],
+    "form-timeslot": [
+        "label",
+        "description"
+    ],
+    "form-checkbox": [
+        "label",
+        "options",
+        "description"
+    ],
+    "form-date": [
+        "label",
+        "description",
+        "dayPlaceholder",
+        "monthPlaceholder",
+        "yearPlaceholder",
+        "dayLabel",
+        "monthLabel",
+        "yearLabel",
+        "timeLabel"
+    ],
+    "form-calendar": [
+        "label",
+        "placeholder",
+        "description"
+    ],
+    "form-file": [
+        "label",
+        "placeholder",
+        "hintText",
+        "description",
+        "buttonLabel"
+    ],
+    "form-paragraph": [
+        "text"
+    ],
+    "form-step-button": [
+        "text"
+    ],
+    "form-submit": [
+        "text",
+        "submittingText"
+    ],
+    "form-title": [
+        "text"
+    ],
+    "image": [
+        "alt"
+    ],
+    "image-comparison": [
+        "beforeAlt",
+        "afterAlt"
+    ],
+    "list-dataset": [
+        "loadMoreLabel"
+    ],
+    "list-item": [
+        "text"
+    ],
+    "product-image-feature": [
+        "alt"
+    ],
+    "search-input": [
+        "searchPlaceholder",
+        "searchClearLabel",
+        "searchToggleLabel"
+    ],
+    "tab-content": [
+        "label"
+    ],
+    "text": [
+        "text",
+        "textHtml"
+    ],
+    "text-marquee": [
+        "text"
+    ],
+    "text-marquee-item": [
+        "text"
+    ],
+    "breadcrumb": [
+        "crumbs",
+        "homeLabel"
+    ],
+    "menu": [
+        "menuItems"
+    ],
+    "chat-widget": [
+        "title"
+    ],
+    "qr-code": [
+        "alt",
+        "value"
+    ],
+    "bundle-items": [
+        "heading",
+        "quantitySeparator"
+    ],
+    "search-keywords": [
+        "keywordItems"
+    ],
+    "locale-switcher": [
+        "panelTitle"
+    ],
+    "theme-switcher": [
+        "lightLabel",
+        "darkLabel"
+    ]
+};
+/**
+ * Specials keys that must NEVER be translated, across every element.
+ *
+ * Translating one of these does not degrade the page — it BREAKS the render.
+ * Kept as the platform's whole classification rather than an allow-list,
+ * because a positive-only list goes stale silently as elements ship new strings.
+ */
+export const NEVER_TRANSLATED = [
+    "acceptedDates",
+    "addressGroup",
+    "addressLink",
+    "afterSrc",
+    "allowMultiple",
+    "allowedCodes",
+    "arrow",
+    "audience",
+    "authKind",
+    "autoComplete",
+    "availableDays",
+    "beforeSrc",
+    "bookMaxDays",
+    "bookMinDays",
+    "bookSlots",
+    "boundBundleItems",
+    "boundCompareCents",
+    "boundHref",
+    "boundHrefLabel",
+    "boundMoneyOverride",
+    "boundPriceCents",
+    "boundProductURL",
+    "boundValue",
+    "breakEnd",
+    "breakStart",
+    "button",
+    "capturesProduct",
+    "className",
+    "closeIcon",
+    "code",
+    "collectionIds",
+    "contentType",
+    "copyFrom",
+    "country",
+    "courseId",
+    "customCss",
+    "customName",
+    "ddFilterSource",
+    "ddFilterStash",
+    "ddSortStash",
+    "defaultMode",
+    "defaultVariant",
+    "dir",
+    "displayType",
+    "end",
+    "field",
+    "fileFormat",
+    "fileLimit",
+    "filterArity",
+    "filterAxis",
+    "filterBehavior",
+    "filterColors",
+    "filterExcluded",
+    "filterMatch",
+    "filterRanges",
+    "filterSource",
+    "filterTarget",
+    "filterTargets",
+    "filterValueMode",
+    "filterable",
+    "formId",
+    "formRules",
+    "format",
+    "hideWhenEmpty",
+    "hoverHostDepth",
+    "href",
+    "htmlTag",
+    "icon",
+    "iconEnabled",
+    "iconName",
+    "inputType",
+    "keywordAction",
+    "kind",
+    "labelMode",
+    "learnHref",
+    "limitChars",
+    "lockedHref",
+    "loginHref",
+    "logoShape",
+    "lookupEnabled",
+    "mapTo",
+    "mapType",
+    "maxCents",
+    "maxChars",
+    "maxLabelText",
+    "maxValue",
+    "menuId",
+    "minCents",
+    "minChars",
+    "minLabelText",
+    "minValue",
+    "moneyPayload",
+    "moreButtonEnabled",
+    "multiline",
+    "name",
+    "openOnHover",
+    "orderSource",
+    "orientation",
+    "overlayId",
+    "part",
+    "parts",
+    "pattern",
+    "patternCountries",
+    "patternPreset",
+    "payload",
+    "picker",
+    "poster",
+    "prefillValue",
+    "presetCode",
+    "provinceField",
+    "ratingValue",
+    "required",
+    "reviewForm",
+    "sameDefault",
+    "searchBehavior",
+    "searchClearSwap",
+    "searchDebounceMs",
+    "searchDisplay",
+    "searchIconPosition",
+    "searchMinChars",
+    "searchOnEnter",
+    "searchPages",
+    "searchScope",
+    "searchShowClear",
+    "searchTargets",
+    "searchable",
+    "segmentId",
+    "selectMode",
+    "sentRedirect",
+    "sentText",
+    "setRange",
+    "showCount",
+    "showCurrent",
+    "showDetail",
+    "showFlag",
+    "showHeading",
+    "showIcon",
+    "showLabel",
+    "showLogos",
+    "showMarker",
+    "showOutline",
+    "showPhone",
+    "showPlaceholder",
+    "source",
+    "specificDate",
+    "src",
+    "start",
+    "step",
+    "stepMode",
+    "stylePreset",
+    "symbolChar",
+    "target",
+    "trackUrl",
+    "variant",
+    "videoId",
+    "videoSrc"
+];
+/** The columns a translation may rewrite on each entity, SEO fields included. */
+export const TRANSLATABLE_ENTITY_FIELDS = {
+    "product": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "description",
+            "html": true
+        },
+        {
+            "key": "vendor"
+        },
+        {
+            "key": "attributes",
+            "list": "attributes"
+        },
+        {
+            "key": "seoTitle"
+        },
+        {
+            "key": "seoDescription"
+        },
+        {
+            "key": "seoKeywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "category": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "description",
+            "html": true
+        },
+        {
+            "key": "seoTitle"
+        },
+        {
+            "key": "seoDescription"
+        },
+        {
+            "key": "seoKeywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "article": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "summary"
+        },
+        {
+            "key": "content",
+            "html": true,
+            "multiline": true
+        },
+        {
+            "key": "tags"
+        },
+        {
+            "key": "seoTitle"
+        },
+        {
+            "key": "seoDescription"
+        },
+        {
+            "key": "seoKeywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "blogCategory": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "description"
+        },
+        {
+            "key": "seoTitle"
+        },
+        {
+            "key": "seoDescription"
+        },
+        {
+            "key": "seoKeywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "course": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "summary"
+        },
+        {
+            "key": "description",
+            "html": true,
+            "multiline": true
+        },
+        {
+            "key": "level"
+        },
+        {
+            "key": "instructorTitle"
+        },
+        {
+            "key": "instructorBio",
+            "html": true,
+            "multiline": true
+        },
+        {
+            "key": "tags"
+        },
+        {
+            "key": "seoTitle"
+        },
+        {
+            "key": "seoDescription"
+        },
+        {
+            "key": "seoKeywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "review": [
+        {
+            "key": "reply",
+            "html": true
+        }
+    ],
+    "courseSection": [
+        {
+            "key": "title"
+        }
+    ],
+    "courseLesson": [
+        {
+            "key": "title"
+        }
+    ],
+    "page": [
+        {
+            "key": "title"
+        },
+        {
+            "key": "description"
+        },
+        {
+            "key": "keywords"
+        },
+        {
+            "key": "ogTitle"
+        },
+        {
+            "key": "ogDesc"
+        }
+    ],
+    "uiString": [
+        {
+            "key": "text"
+        }
+    ],
+    "mailString": [
+        {
+            "key": "text"
+        }
+    ],
+    "siteLabel": [
+        {
+            "key": "text"
+        }
+    ]
+};

package/dist/domains/site/document.js

@@ -130,6 +130,29 @@ export class PageDoc {
         applyPatches(this.doc, patches);
         this.revision += 1;
     }
+    /**
+     * What this document WOULD be with these patches applied — a throwaway copy,
+     * so the real one is untouched.
+     *
+     * It exists so a write can be judged before it is made. Applying first and
+     * validating after leaves a refused edit sitting in the draft: the platform
+     * declines the save, the node stays, and every later command is then judged
+     * against a tree the caller never asked for and cannot see. Driving the real
+     * server, that arrived as three `sb_add` calls in a row all answering with the
+     * same complaint about a node id the caller had never typed.
+     *
+     * A JSON round-trip rather than anything cleverer. A page is hundreds of KB,
+     * which is a millisecond, and it is paid only on a write that is actually
+     * being committed — never on a dry run, never on a read.
+     */
+    preview(patches) {
+        const copy = new PageDoc(JSON.parse(JSON.stringify(this.doc)), this.revision);
+        // Carried, not re-derived: a validator that saw a different root key on the
+        // copy than on the original would be judging a different page.
+        copy.adoptedRootKey = this.adoptedRootKey;
+        copy.apply(patches);
+        return copy;
+    }
     /**
      * A compressed tree — id, type, name, child count, and the flags that change
      * what a caller may safely do with a node.

package/dist/domains/site/fieldskin.js

@@ -0,0 +1,59 @@
+import { FIELD_SKIN_BY_NODE } from '../../catalog/fieldskin.generated.js';
+/**
+ * A FORM'S FIELDS ARE STYLED BY CONFIG KEYS, AND THE WRONG LEVEL IS SILENT.
+ *
+ * `fieldSkin.ts` / `fieldskin.go` hold the vocabulary, and each form node's
+ * `css.go` emits only the group it names. A knob written on a node that does not
+ * read it is stored, saved, published, and rendered NOWHERE — the same shape as
+ * a binding outside the `specials` namespace.
+ *
+ * CLAUDE.md carried the rule as PROSE ("form/css.go emits only FieldKnobs, so
+ * payCard* written on the form is stored and rendered nowhere"), which is a
+ * hand-kept summary of a 55-key table across 11 nodes. It is generated now: the
+ * groups from `fieldSkin.ts` (pure data), the node mapping from each `css.go`'s
+ * `fieldskin.<Group>` identifier, and the vocabulary cross-checked against the
+ * Go's own key literals at codegen.
+ *
+ * THE ANSWER IS PER NODE, not per key: `payCardBg` is real and rendered on
+ * `form-payment`, and dead on `form`. So a caller is told which node DOES read
+ * it, which is the only thing that turns the warning into a fix.
+ */
+/** Every field-skin key, across every form node. */
+const ALL_KEYS = new Set(Object.values(FIELD_SKIN_BY_NODE).flat());
+/** Does this node's renderer read this skin key? */
+export function readsSkinKey(nodeType, key) {
+    return (FIELD_SKIN_BY_NODE[nodeType] ?? []).includes(key);
+}
+/** The node types whose renderer DOES read a key — the fix half of the warning. */
+export function nodesReading(key) {
+    return Object.entries(FIELD_SKIN_BY_NODE)
+        .filter(([, keys]) => keys.includes(key))
+        .map(([type]) => type)
+        .sort();
+}
+/**
+ * The warning for field-skin keys written on a node that renders none of them.
+ *
+ * Only fires for a key that IS a skin knob somewhere — an unknown config key is
+ * not this module's business, and claiming it would put a false positive on
+ * every ordinary write. A node that reads no skin keys at all (an ordinary
+ * heading) is equally not the target: the mistake this catches is a skin key on
+ * the WRONG form node, which is the one the platform documents.
+ */
+export function skinLevelNote(nodeType, keys) {
+    const misplaced = keys.filter((k) => ALL_KEYS.has(k) && !readsSkinKey(nodeType, k));
+    if (!misplaced.length)
+        return null;
+    const detail = misplaced
+        .map((k) => {
+        const readers = nodesReading(k);
+        return `${k} (read by ${readers.join(', ') || 'no node'})`;
+    })
+        .join('; ');
+    return (`"${nodeType}" renders none of these field-skin keys, so they would be stored, saved, ` +
+        `published and read by nothing: ${detail}. A skin knob is emitted only by the node whose ` +
+        'css.go names its group — the FORM dresses every field it holds with the input vocabulary, ' +
+        'and a payment card, choice group, timeslot or file field carries its own. Write them on ' +
+        'the field node, which lives in the FORM DOCUMENT ' +
+        '(PUT /api/sites/{siteId}/forms/{id}/document), not on the page.');
+}

package/dist/domains/site/translate.js

@@ -0,0 +1,72 @@
+import { NEVER_TRANSLATED, TRANSLATABLE_ENTITY_FIELDS, TRANSLATABLE_SPECIALS, TRANSLATION_ENTITY_TYPES, } from '../../catalog/translations.generated.js';
+/**
+ * WHICH CONTENT A TRANSLATION MAY REWRITE — AND WHICH BREAKS THE PAGE.
+ *
+ * A multi-language store was REACHABLE and UNSAFE. Every translations route is
+ * in the catalog — read, write, auto-fill, the review queue — so an agent could
+ * call them all and had no way to know which fields are content.
+ *
+ * The platform's registry says why that matters: the element registry declares
+ * 117 `(element, special)` pairs across 66 keys, INTERLEAVED in one object —
+ *
+ *   text · label · alt · emptyText · searchPlaceholder            ← content
+ *   htmlTag · videoId · filterSource · contentType · src · name   ← NOT
+ *
+ * — and translating one of the second group "does not degrade the page, it
+ * breaks the render": `name` is a lucide icon id, `src` is a URL,
+ * `filterSource` is a registry id the Go predicate switches on. An agent
+ * walking a page document and translating every string it finds hits all three,
+ * and the page it hands back renders wrong with nothing reporting why.
+ *
+ * A NEGATIVE ANSWER HERE IS INFORMATION, not an absence. `icon` has no
+ * translatable specials at all, and that is the correct, complete answer.
+ *
+ * NO NEW TOOL: this rides inside `sb_traits_for`'s result and the call sheet
+ * `sb_api_find` already prints for a translations operation.
+ */
+/** The specials a translation may rewrite on this element. Empty is an answer. */
+export function translatableSpecials(elementType) {
+    return TRANSLATABLE_SPECIALS[elementType] ?? [];
+}
+/** Would translating this key break a render, whatever element it is on? */
+export function isNeverTranslated(key) {
+    return NEVER_TRANSLATED.includes(key);
+}
+/**
+ * The specials this element HAS that must never be translated.
+ *
+ * Named per element rather than handed over as the whole 156-key list, because
+ * the answer a caller needs is about the node in front of it — and a list that
+ * long, on every element, is the kind of weight that makes a result unreadable.
+ */
+export function neverTranslatedOn(elementType, ownKeys) {
+    const ok = new Set(translatableSpecials(elementType));
+    return ownKeys.filter((k) => !ok.has(k) && isNeverTranslated(k));
+}
+/** The columns a translation may rewrite on an entity, or null for an unknown one. */
+export function entityFields(entityType) {
+    return TRANSLATABLE_ENTITY_FIELDS[entityType] ?? null;
+}
+export function entityTypes() {
+    return TRANSLATION_ENTITY_TYPES;
+}
+/**
+ * The vocabulary a translations operation needs, for its call sheet.
+ *
+ * The ENTITY FIELDS are the body of it; `node` is called out separately because
+ * it is the one entity type with no column list — a node translation is keyed
+ * by (node id, special), so its vocabulary is per element and lives in
+ * `sb_traits_for`. Without that sentence the empty answer for `node` reads as
+ * "nothing on a node is translatable", which is the opposite of true.
+ */
+export function translationCallSheet() {
+    return {
+        entity_types: TRANSLATION_ENTITY_TYPES,
+        entity_fields: TRANSLATABLE_ENTITY_FIELDS,
+        node_note: 'entityType "node" has no column list because a node translation is keyed by (node id, ' +
+            'specials key). Ask sb_traits_for <element> for `translatable` — it names the specials ' +
+            'that element allows. Translating any OTHER special BREAKS the render rather than ' +
+            'degrading it: `name` is a lucide icon id, `src` a URL, `filterSource` a registry id the ' +
+            'renderer switches on. Never walk a document translating every string you find.',
+    };
+}

package/dist/tools/importpage.js

@@ -121,13 +121,24 @@ export function registerImportTools(server, ctx, session) {
                 `Skipped: ${JSON.stringify(shot.skipped)}. A page that builds itself with scripts ` +
                 'after load, or one behind a login, reads as empty here.');
         }
+        // STAGED ON A COPY, committed once.
+        //
+        // Each section's patch set is computed from the tree the previous one
+        // left, so they have to be applied in order — but applying them to the
+        // REAL document means a refusal at the end leaves the page half imported,
+        // with no way for the caller to tell which half. Building on a throwaway
+        // and committing the whole run through `applyAndSave` keeps the import
+        // all-or-nothing, and keeps it to one save and one live frame.
         const added = [];
+        const all = [];
+        const staged = doc.preview([]);
         for (const spec of specs) {
-            const { patches, ids } = addSubtree(doc, doc.doc.root_node_id, spec);
-            session.applyAndPublish(patches);
+            const { patches, ids } = addSubtree(staged, staged.doc.root_node_id, spec);
+            staged.apply(patches);
+            all.push(...patches);
             added.push(ids[0]);
         }
-        await session.save();
+        await session.applyAndSave(all);
         return text({
             read: shot.url,
             added_sections: added,

package/dist/tools/live.js

@@ -452,8 +452,7 @@ export function registerLiveTools(server, ctx, session) {
         const patches = setEvent(d, id, trigger ?? 'click', action, payload);
         if (dry_run !== false)
             return text({ dry_run: true, patches });
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ node: id, trigger: trigger ?? 'click', action, rev: d.rev });
     });
     server.registerTool('sb_bind', {
@@ -481,8 +480,7 @@ export function registerLiveTools(server, ctx, session) {
         const patches = bindNode(d, id, source, field, action);
         if (dry_run !== false)
             return text({ dry_run: true, patches });
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ bound: id, source, field, ...(action ? { action } : {}), rev: d.rev });
     });
 }

package/dist/tools/page.js

@@ -9,6 +9,7 @@ import { detachNote, presetIdOf, presetLayer } from '../domains/site/theme.js';
 import { inertHintsFor } from '../domains/site/inert.js';
 import { hasSeed, seedDocument, seedSummary, seededTypes } from '../domains/site/storepage.js';
 import { unknownValueNote } from '../domains/site/vocabulary.js';
+import { skinLevelNote } from '../domains/site/fieldskin.js';
 import { siteTheme } from '../domains/site/theme-fetch.js';
 import { request, redact } from '../transport/http.js';
 import { siteToken } from './credentialpick.js';
@@ -100,6 +101,36 @@ export class PageSession {
             this.live.cursor(box.x + box.w / 2, box.y + box.h / 2);
         }
     }
+    /**
+     * The only sanctioned way to write: judge, then apply, publish and save.
+     *
+     * SPLITTING THESE WAS THE BUG. Every tool used to call `applyAndPublish` and
+     * then `save()`, and a save the platform would refuse threw with the patches
+     * already in the draft — and already broadcast to anyone watching the page
+     * live. The refused node then sat there, so the NEXT command was validated
+     * against a tree the caller had never asked for and got the same complaint
+     * about an id they had never typed. Three `sb_add` calls in a row, three
+     * identical refusals, and three copies of the element quietly in the page.
+     *
+     * The check runs on a COPY (`PageDoc.preview`), so a write that cannot be
+     * stored is never applied at all — no rollback to get wrong, and no phantom
+     * frame for a peer in the room to have to un-see.
+     *
+     * IT REFUSES ONLY WHAT THIS WRITE INTRODUCES. A page that arrived broken —
+     * damage stored before this session opened it — must not become a page nobody
+     * can edit, because the edit that repairs it is also a write. Pre-existing
+     * problems are left to `save()`, which names them.
+     */
+    async applyAndSave(patches) {
+        const d = this.current();
+        const before = new Set(validateForSave(d));
+        const introduced = validateForSave(d.preview(patches)).filter((p) => !before.has(p));
+        if (introduced.length > 0) {
+            throw new Error(`sbuilder: refusing to save — ${introduced.join(' ')}`);
+        }
+        this.applyAndPublish(patches);
+        await this.save();
+    }
     applyRemote(patches) {
         this.doc?.apply(patches);
     }
@@ -286,8 +317,7 @@ export function registerPageTools(server, ctx) {
                 ...(inert ? { inert } : {}),
             });
         }
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ added: ids, rev: d.rev, ...(inert ? { inert } : {}) });
     });
     server.registerTool('sb_set', {
@@ -441,6 +471,28 @@ export function registerPageTools(server, ctx) {
             }
         }
         const valueNote = valueNotes.join(' ');
+        // A FIELD-SKIN KNOB ON THE WRONG NODE renders nowhere. The FORM dresses
+        // every field it holds with the input vocabulary; a payment card, choice
+        // group, timeslot or file field carries its own, and a knob written on a
+        // node whose css.go does not name that group is stored and read by
+        // nothing. Once per node TYPE, because the answer is about the type.
+        const skinNotes = [];
+        const skinSeen = new Set();
+        for (const e of batch) {
+            if (e.namespace !== 'config')
+                continue;
+            const type = d.doc.nodes[e.id]?.data.type ?? '';
+            if (!type || skinSeen.has(type))
+                continue;
+            const n = skinLevelNote(type, Object.keys(e.keys));
+            if (!n)
+                continue;
+            skinSeen.add(type);
+            const once = ctx.notices.once(`field-skin:${type}`, n);
+            if (once)
+                skinNotes.push(once);
+        }
+        const skinNote = skinNotes.join(' ');
         // THE STICKY WARNING IS COMPUTED AGAINST THE DOCUMENT AS IT WILL BE, so
         // the dry run and the real run say the same thing. A caller who is told
         // only after committing has already shipped a header that does not move.
@@ -475,13 +527,13 @@ export function registerPageTools(server, ctx) {
                 ...(baseNote ? { base_only: baseNote } : {}),
                 ...(presetNote ? { preset: presetNote } : {}),
                 ...(valueNote ? { value: valueNote } : {}),
+                ...(skinNote ? { field_skin: skinNote } : {}),
                 ...(Object.keys(hostNotes).length ? { hover_host: hostNotes } : {}),
                 ...(note ? { note } : {}),
             });
         }
         const warnings = stuck();
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         for (const t of touched) {
             const w = globalWarning(d.doc, t.id);
             if (w)
@@ -497,6 +549,7 @@ export function registerPageTools(server, ctx) {
                 ...(baseNote ? { base_only: baseNote } : {}),
                 ...(presetNote ? { preset: presetNote } : {}),
                 ...(valueNote ? { value: valueNote } : {}),
+                ...(skinNote ? { field_skin: skinNote } : {}),
                 ...(hostNotes[batch[0].id] ? { hover_host: hostNotes[batch[0].id] } : {}),
             });
         }
@@ -508,6 +561,7 @@ export function registerPageTools(server, ctx) {
             ...(baseNote ? { base_only: baseNote } : {}),
             ...(presetNote ? { preset: presetNote } : {}),
             ...(valueNote ? { value: valueNote } : {}),
+            ...(skinNote ? { field_skin: skinNote } : {}),
             ...(Object.keys(hostNotes).length ? { hover_host: hostNotes } : {}),
         });
     });
@@ -525,8 +579,7 @@ export function registerPageTools(server, ctx) {
         const patches = moveNode(d, id, parent_id, index);
         if (dry_run !== false)
             return text({ dry_run: true, patches });
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ moved: id, rev: d.rev });
     });
     server.registerTool('sb_remove', {
@@ -538,8 +591,7 @@ export function registerPageTools(server, ctx) {
         const patches = removeNode(d, id);
         if (dry_run !== false)
             return text({ dry_run: true, removing: patches.length });
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ removed: id, rev: d.rev });
     });
     server.registerTool('sb_review', {
@@ -582,8 +634,7 @@ export function registerPageTools(server, ctx) {
         const { patches, ids } = duplicateNode(d, id);
         if (dry_run !== false)
             return text({ dry_run: true, would_copy: ids.length });
-        session.applyAndPublish(patches);
-        await session.save();
+        await session.applyAndSave(patches);
         return text({ duplicated: id, into: ids[0], nodes: ids.length, rev: d.rev });
     });
     server.registerTool('sb_templates', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",