sbuilder-mcp 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ 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.42.0] - 2026-09-14
+
+### Added
+- sb_traits_for now returns specials_values alongside config_values, growing the legal-value vocabulary from 3 globally-unique keys to 26 keys scoped per element (cart-total's part, breadcrumb's source, divider's contentType/contentPosition/orientation, dropdown/popover's panelAlign/placement, media-dataset's layout, popup's triggerType, tab's tabPosition, product-image-feature's mainImageSource, list-dataset's loadingMode, locale-switcher's labelMode, member-field's field, and the shared backgroundSceneSource among them), so a control whose name does not match its write key still resolves to the right vocabulary; sb_set now warns when a written value falls outside the element's vocabulary, naming the values that actually do something.
+- sb_set now warns when a config or specials write targets a key that no renderer, editor, or runtime reads anywhere in the platform, instead of storing it silently with no effect at all; the first catalog scan of every seeded key against the platform's own source found exactly one, config.splitDirection on image-comparison.
+- npm run codegen and npm run codegen:check now warn when an element's own AI hints describe it in "renders only through/inside" language while the element is missing from the inert-element table or its rejection ledger, catching drift like the quickview element that had already shipped unnoticed.
+- The catalog now covers the platform's background 3D scene feature on flex-section, flex-block and dataset-block (backgroundSceneSource, effect, gallery, model, veil and color config keys), reachable through sb_traits_for and sb_add.
+- A product's shape (sb_api_find / sb_api_call) now includes modelUrl, the product's optional 3D model URL, and the binding-source count grew from 78 to 79 to cover it.
+- chat-widget's launcher text is now translatable through sb_traits_for's translatable field, alongside its existing title.
+
+## [0.41.0] - 2026-09-13
+
+### Added
+- `sb_templates` / `sb_template_use` gain four new built-in layout patterns — `sb_product_shelf` and `sb_category_strip` are real `list-dataset` repeaters bound to the catalogue rather than static tiles, `sb_brand_wall` frames library logos with `contain` instead of a photograph's median-ratio crop, and `sb_trust_band` composes icon-plus-line reassurances from exact platform icon ids.
+- `sb_api_find` and `sb_api_call` now attach a `product_traps` note to the four operations that create or replace a whole product, naming three facts a `ProductInput` body cannot show on its own: price lives on the variant rather than the product, a colliding slug is silently renamed rather than refused, and an image can be ingested straight from a URL in one hop.
+- The inert-element table grew from 3 to 20 entries after an audit of all 113 catalog elements, adding `quickview`, `bundle-items`, `chat-widget`, `currency-switcher`, `theme-switcher`, `form-step-count`, `form-step-button`, `order-receipt`, `payment-status`, `points-card`, `points-prompt`, `list-empty`, `list-loading`, `rating-stars`, `accordion-content`, `menu-drawer` and `menu-panel` — elements that render convincingly on the first write while doing nothing useful, so `sb_add` can now warn about them before publish.
+- `sb_import_site` now reads a sitemap index's own child filenames to tell record pages (products, categories, brands, tags) from page-shaped ones, and excludes the record kinds from the import plan by default instead of picking whichever URLs happen to win the page cap.
+
+### Fixed
+- `sb_import` and `sb_import_site` no longer turn an `<svg>`'s wrapper or utility class into a confident wrong icon; a class candidate is only considered when it carries a prefix a real icon set actually stamps, ranked by length only as a tie-break among those.
+- `sb_import` and `sb_import_site` now build a captured list as a real `list` of `list-item` nodes carrying the platform's own marker icon, instead of a column of text nodes each with a literal bullet glyph glued on.
+- The `structure` fidelity score no longer reports arrangement loss on pages with lists; the shape comparison now counts a captured list's rows as real children instead of scoring the list as an empty leaf.
+- `sb_import_site`'s theme write and its per-node color/font-size stamping no longer fight each other; the four token fields a default style preset already resolves through the theme are dropped from the stamped literals once the theme write actually lands, so an imported page's colors stay controlled by the theme instead of a literal that silently outranks it forever.
+- The `coverage` score reported by `sb_import` and `sb_import_site` no longer counts text the importer deliberately declines (chrome, hidden elements, form controls, decorative content) as lost content, and no longer misses text in a bare top-level `<nav>` or a hidden `<select>` that the page-section walk never visits at all.
+
 ## [0.40.0] - 2026-09-13
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,31 @@ 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.42.0] - 2026-09-14
+
+### Added
+- sb_traits_for giờ trả thêm specials_values bên cạnh config_values, mở rộng bảng giá trị hợp lệ từ 3 khóa dùng chung toàn cục lên 26 khóa gắn theo từng phần tử (part của cart-total, source của breadcrumb, contentType/contentPosition/orientation của divider, panelAlign/placement của dropdown/popover, layout của media-dataset, triggerType của popup, tabPosition của tab, mainImageSource của product-image-feature, loadingMode của list-dataset, labelMode của locale-switcher, field của member-field, cùng backgroundSceneSource dùng chung), nhờ đó một control có tên khác với key nó ghi vẫn tra đúng bảng giá trị. sb_set giờ cảnh báo khi giá trị được ghi nằm ngoài bảng giá trị của phần tử đó, nêu rõ những giá trị thật sự có tác dụng.
+- sb_set giờ cảnh báo khi một lệnh ghi config hoặc specials nhắm vào một key mà không renderer, không editor, không runtime nào trong nền tảng đọc tới, thay vì âm thầm lưu lại mà không có tác dụng gì; lượt quét đầu tiên đối chiếu mọi key được seed với chính mã nguồn nền tảng tìm ra đúng một trường hợp, config.splitDirection trên image-comparison.
+- npm run codegen và npm run codegen:check giờ cảnh báo khi mô tả AI hint của một phần tử dùng ngôn ngữ kiểu "chỉ render qua/bên trong" nhưng phần tử đó lại vắng mặt trong bảng phần tử "inert" lẫn sổ loại trừ của nó, bắt được các trường hợp trôi dạt như phần tử quickview từng lên hàng mà không ai để ý.
+- Catalog giờ bao phủ tính năng nền cảnh 3D của nền tảng trên flex-section, flex-block và dataset-block (các config key backgroundSceneSource, effect, gallery, model, veil và màu sắc), có thể tra qua sb_traits_for và dùng qua sb_add.
+- Shape của sản phẩm (sb_api_find / sb_api_call) giờ có thêm modelUrl, URL mô hình 3D tùy chọn của sản phẩm, và số nguồn binding tăng từ 78 lên 79 để bao phủ nó.
+- Chữ trên nút mở chat của chat-widget giờ dịch được qua field translatable của sb_traits_for, cùng với title vốn đã có.
+
+## [0.41.0] - 2026-09-13
+
+### Added
+- `sb_templates` / `sb_template_use` có thêm bốn layout dựng sẵn — `sb_product_shelf` và `sb_category_strip` là repeater `list-dataset` thật, gắn vào catalogue thay vì các ô tĩnh; `sb_brand_wall` đóng khung logo lấy từ thư viện bằng `contain` thay vì crop theo tỉ lệ trung vị của ảnh chụp; `sb_trust_band` ghép các dòng cam kết icon-kèm-chữ từ đúng các id icon của nền tảng.
+- `sb_api_find` và `sb_api_call` giờ đính kèm ghi chú `product_traps` vào bốn operation tạo hoặc thay thế toàn bộ một sản phẩm, nêu rõ ba điều mà body `ProductInput` không tự nói lên được: giá nằm ở variant chứ không phải ở product, một slug trùng bị đổi tên âm thầm chứ không bị từ chối, và có thể nạp ảnh thẳng từ URL trong một bước thay vì hai.
+- Bảng phần tử "inert" tăng từ 3 lên 20 mục sau khi rà soát toàn bộ 113 phần tử trong catalog, thêm `quickview`, `bundle-items`, `chat-widget`, `currency-switcher`, `theme-switcher`, `form-step-count`, `form-step-button`, `order-receipt`, `payment-status`, `points-card`, `points-prompt`, `list-empty`, `list-loading`, `rating-stars`, `accordion-content`, `menu-drawer` và `menu-panel` — những phần tử trông có vẻ hoàn chỉnh ngay ở lần ghi đầu tiên nhưng không làm được gì cả, nên `sb_add` giờ có thể cảnh báo về chúng trước khi publish.
+- `sb_import_site` giờ đọc tên file của từng sitemap con trong một sitemap index để phân biệt trang dữ liệu (sản phẩm, danh mục, thương hiệu, tag) với trang nội dung thông thường, và mặc định loại các trang dữ liệu khỏi kế hoạch import thay vì chọn đại URL nào thắng giới hạn số trang.
+
+### Fixed
+- `sb_import` và `sb_import_site` không còn biến class wrapper hay class tiện ích của một `<svg>` thành một icon sai nhưng trông chắc chắn đúng; một class chỉ được xét khi mang tiền tố mà một bộ icon thật sự dùng, và chỉ xếp hạng theo độ dài như một cách phân định giữa các ứng viên đó.
+- `sb_import` và `sb_import_site` giờ dựng một danh sách đã capture thành `list` thật gồm các `list-item`, mang icon đánh dấu riêng của nền tảng, thay vì một cột các node văn bản mỗi cái gắn cứng một ký tự bullet.
+- Điểm `structure` trong đo lường fidelity không còn báo mất cấu trúc trên các trang có danh sách; phép so sánh hình dạng giờ tính các dòng của một danh sách đã capture là con thật thay vì tính danh sách đó như một lá rỗng.
+- Bản ghi theme của `sb_import_site` và việc gán màu/cỡ chữ literal lên từng node không còn triệt tiêu lẫn nhau; bốn field token mà một style preset mặc định vốn đã phân giải qua theme sẽ bị bỏ khỏi các literal được gán ngay khi bản ghi theme thực sự có hiệu lực, nhờ đó màu sắc của trang được import vẫn do theme kiểm soát thay vì một literal âm thầm đè lên nó mãi mãi.
+- Điểm `coverage` mà `sb_import` và `sb_import_site` báo cáo không còn tính phần chữ mà importer chủ động bỏ qua (chrome, phần tử ẩn, control của form, nội dung trang trí) là nội dung bị mất, và không còn bỏ sót chữ nằm trong một `<nav>` cấp cao nhất hay một `<select>` ẩn mà lượt duyệt theo section chưa bao giờ chạm tới.
+
 ## [0.40.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -94,7 +94,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_move` | Move a node to another parent |
 | `sb_remove` | Remove a node and its subtree |
 | `sb_duplicate` | Copy a node and its subtree under fresh ids, right after the original |
-| `sb_templates` | The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band — composed against the page's own tokens |
+| `sb_templates` | The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band, product shelf, category strip, brand wall, trust band — composed against the page's own tokens |
 | `sb_template_use` | Instantiate a template into a page |
 | `sb_page_list` | Every page on the site |
 | `sb_page_create` | Create a page — a store type arrives with the editor's own starting document; `type` is the route for checkout, product, category, post, course |
@@ -113,7 +113,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_undo` | Put back what a PUT replaced. The SECOND answer for a page, not the only one: the platform has versions, history and restore (`sb_api_find` "page versions"), which outlive this process — reach for those first and use this for every other shaped PUT |
 
 Twenty-eight tools, **524 API operations** (175 of the 234 writes carrying a body shape read
-off the handler), 112 elements, 78 binding sources. `sb_api_find`
+off the handler), 113 elements, 79 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything
 the platform can do stays reachable — and operations added to the platform arrive with the
 next `npm run codegen`.

package/README.vi.md

@@ -91,7 +91,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_move` | Chuyển node sang cha khác |
 | `sb_remove` | Xoá node và cả cây con |
 | `sb_duplicate` | Nhân bản một node và cả cây con dưới id mới, ngay sau bản gốc |
-| `sb_templates` | Section template đã lưu của cửa hàng, cộng bộ layout DỰNG SẴN — hero, ba lợi ích, số liệu, FAQ, dải kêu gọi — soạn theo token của chính trang |
+| `sb_templates` | Section template đã lưu của cửa hàng, cộng bộ layout DỰNG SẴN — hero, ba lợi ích, số liệu, FAQ, dải kêu gọi, kệ sản phẩm, dải danh mục, dải logo, dải cam kết — soạn theo token của chính trang |
 | `sb_template_use` | Thả một template vào trang |
 | `sb_page_list` | Mọi trang của site |
 | `sb_page_create` | Tạo một trang — trang cửa hàng sinh ra đã có sẵn tài liệu như trong editor; `type` là đường đi cho checkout, product, category, post, course |
@@ -110,7 +110,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè. Với TRANG thì đây là đường về thứ hai chứ không phải duy nhất: nền tảng có version, history và restore (`sb_api_find` "page versions"), và chúng sống lâu hơn tiến trình này — hãy dùng chúng trước, còn tool này cho mọi PUT có hình dạng khác |
 
 Hai mươi tám tool, **524 operation API** (175 trong 234 lệnh ghi có hình dạng body đọc thẳng
-từ handler), 112 element, 78 nguồn binding. `sb_api_find` là
+từ handler), 113 element, 79 nguồn binding. `sb_api_find` là
 một chỉ mục chứ không phải mỗi endpoint một tool, nên danh sách tool vẫn ngắn trong khi mọi
 thứ nền tảng làm được vẫn với tới — và operation mới thêm bên nền tảng sẽ tự có sau lần
 `npm run codegen` kế tiếp.

package/dist/catalog/api.generated.js

@@ -8717,7 +8717,7 @@ export const API_OPERATIONS = [
                 "in": "query",
                 "required": false,
                 "type": "string",
-                "description": "image | video | font | other"
+                "description": "image | video | font | model | other"
             },
             {
                 "name": "search",
@@ -17503,6 +17503,10 @@ export const API_DEFINITIONS = {
                     }
                 ]
             },
+            "modelUrl": {
+                "description": "ModelURL is the product's 3D model (.glb / .gltf), so a page can show the\nthing itself instead of photographs of it.\n\nONE model, not a gallery — which is why this is a scalar beside the two\nslices above rather than a third one. A product has one shape; a second\nmodel of the same product would be a different colourway or a different\nproduct, and both of those already have somewhere to live. Making it a\nlist \"for later\" would cost a migration to take back and would force\nevery reader to answer \"which one\" with no rule to answer it by.\n\nEmpty is the normal value and means \"no model\": every product that\nexisted before this field, and every product in every store that sells\nthings nobody has modelled.\n\nIt is a URL into this site's own media library in the ordinary case, but\nnothing here requires that — an externally hosted .glb is a legitimate\nvalue, and the usage adapter simply finds no match for one, which is the\ntrue answer.",
+                "type": "string"
+            },
             "moneyOverride": {
                 "description": "MoneyOverride is an opaque per-product money-display override (compact-convert\nrules + exchange-rate overrides), stored as a JSONB blob. The domain keeps it\nopaque — it is decoded at the render boundary (bindings.ProductSource →\nrender.ProductData) — so products stays decoupled from render/money, the same\nway the site settings document is an opaque blob. Empty ({}/null) → no override.",
                 "type": "array",

package/dist/catalog/checkout.generated.js

@@ -556,7 +556,21 @@ export const CHECKOUT_PAGE_DOCUMENT = {
                 "paddingTop": "48px",
                 "paddingBottom": "48px"
             },
-            "config": {},
+            "config": {
+                "backgroundSceneSource": "",
+                "backgroundSceneEffect": "gradient-mesh",
+                "backgroundSceneGallery": "podium",
+                "backgroundSceneSpeed": "normal",
+                "backgroundSceneIntensity": "normal",
+                "backgroundSceneColors": "theme",
+                "backgroundSceneColor1": "#171717",
+                "backgroundSceneColor2": "#ffffff",
+                "backgroundSceneColor3": "#6b7280",
+                "backgroundSceneUrl": "",
+                "backgroundSceneModelUrl": "",
+                "backgroundSceneVeil": 0,
+                "backgroundSceneVeilColor": "#000000"
+            },
             "specials": {
                 "stylePreset": "container-section"
             },

package/dist/catalog/deadkeys.generated.js

@@ -0,0 +1,29 @@
+export const DEAD_KEY_SOURCE = {
+    "files": 3966,
+    "identifiers": 76235,
+    "seededKeys": 384,
+    "dead": 1
+};
+/**
+ * Keys an element SEEDS and no renderer anywhere reads.
+ *
+ * Keyed by the key NAME, not by `namespace.key`: the index is a flat set of
+ * identifiers, so it cannot tell one namespace from the other and a key read
+ * anywhere is read in both.
+ *
+ * A write to one of these stores, saves, publishes and renders exactly as
+ * before. `sb_set` says so at the moment of the write; nothing refuses it,
+ * because the platform accepts the value and a refusal here would invent a rule
+ * it does not have.
+ */
+export const DEAD_KEYS = {
+    "splitDirection": {
+        "key": "splitDirection",
+        "namespaces": [
+            "config"
+        ],
+        "seededBy": [
+            "image-comparison"
+        ]
+    }
+};

package/dist/catalog/element-search.js

@@ -1,5 +1,5 @@
 import { ELEMENTS, TRAIT_WRITES } from './elements.generated.js';
-import { animationValues, animationVocabulary, vocabulariesForWrites } from '../domains/site/vocabulary.js';
+import { animationValues, animationVocabulary, elementVocabularies, sharedVocabularies, 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;
@@ -120,10 +120,28 @@ export function traitsFor(type, control) {
         // this element's defaults and in its control list, and no TRAIT_WRITES entry
         // names it — so a per-control attachment reaches none of them, which is how
         // the first version of this was wrong.
+        //
+        // TWO FIELDS RATHER THAN ONE, because the caller writes two namespaces and
+        // `sb_set` takes them separately. Every entry names its `writeKey`, which is
+        // the half a control name does not give you: `divider_orientation` writes
+        // `orientation`, and eleven of the thirteen joined controls are like it.
         ...(() => {
             const keys = new Set([...Object.keys(el.defaults?.config ?? {}), ...el.controls]);
-            const vocab = vocabulariesForWrites([...keys]);
-            return Object.keys(vocab).length ? { config_values: vocab } : {};
+            // The globally-unique three keep their own key AS the write key; saying so
+            // is what lets a reader take every entry in this object the same way.
+            const config = Object.fromEntries(Object.entries(vocabulariesForWrites([...keys])).map(([k, v]) => [k, { writeKey: k, ...v }]));
+            const specials = {};
+            const own = { ...sharedVocabularies(el.defaults ?? {}), ...elementVocabularies(el.type) };
+            for (const [k, { target, ...v }] of Object.entries(own)) {
+                // `target` is dropped rather than repeated: the field it lands in is the
+                // namespace, and a key restated on every entry is the dilution the token
+                // budget has already caught twice on this one result.
+                (target === 'specials' ? specials : config)[k] = v;
+            }
+            return {
+                ...(Object.keys(config).length ? { config_values: config } : {}),
+                ...(Object.keys(specials).length ? { specials_values: specials } : {}),
+            };
         })(),
         // THE ENTRANCE ANIMATION, for the 73 element types that offer it. It does
         // not ride in `config_values` because it is not a word — it is an OBJECT