sbuilder-mcp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ 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.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,16 @@ 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.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/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/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';
@@ -441,6 +442,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,6 +498,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 } : {}),
                 ...(note ? { note } : {}),
             });
@@ -497,6 +521,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 +533,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 } : {}),
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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",