sbuilder-mcp 0.91.0 → 0.92.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.92.0] - 2026-10-26
+
+### Added
+- `sb_bind` accepts `record.url` and, on a page of type `record`, reads the collection linked through page-links so `record.*` bindings work outside any list, refusing `record.url` while the collection has no detail page.
+- `sb_review` reports `record_option_invalid` for form-select, radio and checkbox controls with `optionSource: "record"` that lack a collection, use a label that is not an ID field, or have a parent that is not a record-sourced form-select.
+- Form controls accept `optionSource: "record"` to take their options from a collection, and form-select supports `specials.urlParam` prefill such as `?hotel=rec_…&room=rec_…`.
+
+### Changed
+- `sb_review` no longer reports `no_data_context` or `record_relation_orphan` for nodes outside a list on a record page.
+- `sb_set` no longer writes `optionSource`, `recordLabelField`, `recordParentField` or `recordParentNode` per breakpoint, because they are now base-only config keys.
+- The API catalog is synced with web_builder v1.0.172 and gains the `record` page type, served at `/records/<id>`.
+
 ## [0.91.0] - 2026-10-23
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,18 @@ 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.92.0] - 2026-10-26
+
+### Added
+- `sb_bind` nhận `record.url` và, trên trang loại `record`, đọc collection gắn qua page-links để bind `record.*` ngoài mọi danh sách, đồng thời từ chối `record.url` khi collection chưa có trang chi tiết.
+- `sb_review` báo `record_option_invalid` cho control form-select, radio và checkbox có `optionSource: "record"` thiếu collection, dùng nhãn không phải ID field, hoặc có cha không phải form-select lấy từ record.
+- Các control form nhận `optionSource: "record"` để lấy option từ collection, và form-select hỗ trợ điền sẵn qua `specials.urlParam` như `?hotel=rec_…&room=rec_…`.
+
+### Changed
+- `sb_review` không còn báo `no_data_context` hay `record_relation_orphan` cho node nằm ngoài danh sách trên trang record.
+- `sb_set` không còn ghi `optionSource`, `recordLabelField`, `recordParentField` hay `recordParentNode` theo breakpoint, vì chúng nay là khoá config base-only.
+- Catalog API được đồng bộ với web_builder v1.0.172 và thêm loại trang `record`, phục vụ tại `/records/<id>`.
+
 ## [0.91.0] - 2026-10-23
 
 ### Added

package/dist/catalog/checkout.generated.js

@@ -361,7 +361,11 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "width": "100%"
             },
             "config": {
-                "optionSource": "manual"
+                "optionSource": "manual",
+                "recordCollectionId": "",
+                "recordLabelField": "",
+                "recordParentField": "",
+                "recordParentNode": ""
             },
             "specials": {
                 "name": "shipping_method",
@@ -372,7 +376,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "mapTo": "order.shippingMethod",
                 "options": [],
                 "defaultValue": "",
-                "placeholder": "Chọn phương thức vận chuyển"
+                "placeholder": "Chọn phương thức vận chuyển",
+                "urlParam": ""
             },
             "responsive": {},
             "events": [],
@@ -466,7 +471,9 @@ export const CHECKOUT_FORM_DOCUMENT = {
             },
             "config": {
                 "columns": 1,
-                "optionSource": "manual"
+                "optionSource": "manual",
+                "recordCollectionId": "",
+                "recordLabelField": ""
             },
             "specials": {
                 "name": "xuat_hoa_don_vat",
@@ -2271,7 +2278,11 @@ export const FORM_TEMPLATES = {
                         "width": "100%"
                     },
                     "config": {
-                        "optionSource": "manual"
+                        "optionSource": "manual",
+                        "recordCollectionId": "",
+                        "recordLabelField": "",
+                        "recordParentField": "",
+                        "recordParentNode": ""
                     },
                     "specials": {
                         "name": "shipping_method",
@@ -2282,7 +2293,8 @@ export const FORM_TEMPLATES = {
                         "mapTo": "order.shippingMethod",
                         "options": [],
                         "defaultValue": "",
-                        "placeholder": "Chọn phương thức vận chuyển"
+                        "placeholder": "Chọn phương thức vận chuyển",
+                        "urlParam": ""
                     },
                     "responsive": {},
                     "events": [],
@@ -2376,7 +2388,9 @@ export const FORM_TEMPLATES = {
                     },
                     "config": {
                         "columns": 1,
-                        "optionSource": "manual"
+                        "optionSource": "manual",
+                        "recordCollectionId": "",
+                        "recordLabelField": ""
                     },
                     "specials": {
                         "name": "xuat_hoa_don_vat",
@@ -4199,7 +4213,11 @@ export const FORM_TEMPLATES = {
                         "width": "100%"
                     },
                     "config": {
-                        "optionSource": "manual"
+                        "optionSource": "manual",
+                        "recordCollectionId": "",
+                        "recordLabelField": "",
+                        "recordParentField": "",
+                        "recordParentNode": ""
                     },
                     "specials": {
                         "name": "loai_phong",
@@ -4214,7 +4232,8 @@ export const FORM_TEMPLATES = {
                             "Phòng gia đình"
                         ],
                         "defaultValue": "",
-                        "placeholder": "Chọn loại phòng"
+                        "placeholder": "Chọn loại phòng",
+                        "urlParam": ""
                     },
                     "responsive": {},
                     "events": [],
@@ -4422,7 +4441,9 @@ export const FORM_TEMPLATES = {
                     },
                     "config": {
                         "columns": 1,
-                        "optionSource": "manual"
+                        "optionSource": "manual",
+                        "recordCollectionId": "",
+                        "recordLabelField": ""
                     },
                     "specials": {
                         "name": "muc_do_hai_long",

package/dist/catalog/deadkeys.generated.js

@@ -1,7 +1,7 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 5944,
-    "identifiers": 109564,
-    "seededKeys": 454,
+    "files": 5966,
+    "identifiers": 109792,
+    "seededKeys": 457,
     "dead": 0
 };
 /**

package/dist/catalog/elements.generated.js

@@ -8304,13 +8304,18 @@ export const ELEMENTS = {
                     "Tùy chọn 3"
                 ],
                 "defaultValue": "",
-                "placeholder": "Chọn một mục"
+                "placeholder": "Chọn một mục",
+                "urlParam": ""
             },
             "style": {
                 "width": "100%"
             },
             "config": {
-                "optionSource": "manual"
+                "optionSource": "manual",
+                "recordCollectionId": "",
+                "recordLabelField": "",
+                "recordParentField": "",
+                "recordParentNode": ""
             }
         },
         "inspector": [
@@ -8476,7 +8481,9 @@ export const ELEMENTS = {
             },
             "config": {
                 "columns": 1,
-                "optionSource": "manual"
+                "optionSource": "manual",
+                "recordCollectionId": "",
+                "recordLabelField": ""
             },
             "style": {
                 "width": "100%"
@@ -8967,7 +8974,9 @@ export const ELEMENTS = {
             },
             "config": {
                 "columns": 1,
-                "optionSource": "manual"
+                "optionSource": "manual",
+                "recordCollectionId": "",
+                "recordLabelField": ""
             },
             "style": {
                 "width": "100%"
@@ -49348,6 +49357,7 @@ export const ELEMENT_VALUES = {
                 "category",
                 "manual",
                 "product",
+                "record",
                 "tag"
             ],
             "readBy": "OPTION_SOURCES (schema/src/elements/formOptionSource.ts)"
@@ -49363,6 +49373,7 @@ export const ELEMENT_VALUES = {
                 "category",
                 "manual",
                 "product",
+                "record",
                 "tag"
             ],
             "readBy": "OPTION_SOURCES (schema/src/elements/formOptionSource.ts)"
@@ -49389,6 +49400,7 @@ export const ELEMENT_VALUES = {
                 "category",
                 "manual",
                 "product",
+                "record",
                 "tag"
             ],
             "readBy": "OPTION_SOURCES (schema/src/elements/formOptionSource.ts)"
@@ -50186,11 +50198,15 @@ export const BASE_ONLY_CONFIG = [
     "backgroundSceneUrl",
     "backgroundSceneModelUrl",
     "rowLimit",
+    "optionSource",
     "recordCollectionId",
     "recordField",
     "recordFieldType",
     "recordFilterField",
     "recordFilterValue",
+    "recordLabelField",
+    "recordParentField",
+    "recordParentNode",
     "recordRelationField",
     "recordSortDesc",
     "recordSortField"

package/dist/catalog/shapes.generated.js

@@ -4,7 +4,7 @@ export const SHAPE_SOURCE = {
     "fromHandlers": 334,
     "fromSwaggerOnly": 10,
     "withReadOnly": 29,
-    "structsRead": 3457
+    "structsRead": 3459
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{id}/ai-credits/purchase": {

package/dist/catalog/source.generated.js

@@ -1,7 +1,7 @@
 // GENERATED by scripts/gen-catalog.ts — do not edit by hand.
 // The platform commit every other generated file here describes.
 export const PLATFORM_SOURCE = {
-    "commit": "4a6a6b151a18713d4f6c3235f063b870d314a968",
-    "committedAt": "2026-10-23T14:44:15+07:00",
+    "commit": "05168e6e00f55abbddc7895a29a15f030ca060fa",
+    "committedAt": "2026-10-26T09:25:34+07:00",
     "dirty": false
 };

package/dist/catalog/storepages.generated.js

@@ -1624,6 +1624,11 @@ export const PAGE_TYPES = [
         "ownSlug": false,
         "routePattern": "/brands/{slug}"
     },
+    {
+        "type": "record",
+        "group": "store",
+        "ownSlug": false
+    },
     {
         "type": "search",
         "group": "main",

package/dist/domains/site/findings.js

@@ -120,6 +120,10 @@ export const FIX = {
         'datasetSource is "record" — one card template, rows edited as data. Logic the platform has ' +
         'no native control for yet (visitor filters, computed totals) may stay in code, reading ' +
         'GET /_wb/collections/{slug}/records instead of its own copy.',
+    record_option_invalid: 'Point it at a collection and its label column: sb_set id "<id>", namespace config, keys ' +
+        '{ "optionSource": "record", "recordCollectionId": "col_…", "recordLabelField": "fld_…" } (base). A dependent ' +
+        'select adds "recordParentNode": "<parent form-select id>" and "recordParentField": "<reference fld_… of this ' +
+        'collection pointing at the parent\'s>". Values are record ids; prefill with specials.urlParam.',
     record_filter_invalid: 'Aim it at ONE collection\'s record list(s) and a field: sb_set id "<id>", namespace specials, keys ' +
         '{ "filterSource": "record", "filterAxis": "fld_…", "filterTargets": ["<list id>"], "filterBehavior": "filter" } — ' +
         'axis types text/select/reference/url/date/boolean/integer/number. A sort select takes filterValues ' +

package/dist/domains/site/record.js

@@ -12,9 +12,10 @@ export const RECORD_FIELD_ID = /^fld_[0-9a-f]{16}$/;
 /**
  * A `record.*` source a context can supply: `record.<fid>`, `record.html.<fid>`,
  * `record.money.<fid>` (a number/integer field formatted in the site's currency),
- * or `record.id` — the row's own record id (recordContext.ts).
+ * `record.id` — the row's own record id — or `record.url` — `/records/<id>`, emitted
+ * only when the row's collection has a published record detail page (recordContext.ts).
  */
-export const RECORD_SOURCE = /^record\.(?:id|(?:html\.|money\.)?fld_[0-9a-f]{16})$/;
+export const RECORD_SOURCE = /^record\.(?:id|url|(?:html\.|money\.)?fld_[0-9a-f]{16})$/;
 /** The field types `record.money.<fid>` formats — recordContext.ts RECORD_MONEY_FIELD_TYPES. */
 export const RECORD_MONEY_TYPES = new Set(['number', 'integer']);
 /** The only record source `specials.boundHtml` admits — schema/src/rawSinkBindings.ts:102. */
@@ -85,9 +86,9 @@ export function recordScope(nodeAt, id) {
  */
 export function recordFieldProblem(source, scope) {
     if (!scope.length) {
-        return `"${source}" sits in no record-list row — only a list-dataset with datasetSource "record" (or a relation list inside one) supplies a record, so it would render its placeholder.`;
+        return `"${source}" sits in no record-list row and this is no record detail page — only a list-dataset with datasetSource "record" (or a relation list inside one), or a page of type "record" attached to a collection, supplies a record, so it would render its placeholder.`;
     }
-    if (source === 'record.id')
+    if (source === 'record.id' || source === 'record.url')
         return undefined;
     const html = source.startsWith('record.html.');
     const money = source.startsWith('record.money.');

package/dist/domains/site/review.js

@@ -636,6 +636,9 @@ opts = {}) {
                 const parentCfg = up && d.nodes[up] ? d.nodes[up].config : undefined;
                 const nested = parentCfg?.datasetSource === 'record';
                 const rel = String(cfg.recordRelationField ?? '');
+                // A record detail page (web_builder #160) is the parent of a relation list
+                // placed on it outside any list.
+                const pageParent = opts.pageType === 'record' && !up;
                 if (nested && !rel) {
                     out.push({
                         code: 'record_relation_unset',
@@ -647,7 +650,7 @@ opts = {}) {
                         fix: fill('record_relation_unset', { id }),
                     });
                 }
-                else if (rel && (!nested || !RECORD_FIELD_ID.test(rel))) {
+                else if (rel && ((!nested && !pageParent) || !RECORD_FIELD_ID.test(rel))) {
                     out.push({
                         code: 'record_relation_orphan',
                         nodeId: id,
@@ -670,6 +673,38 @@ opts = {}) {
                     });
                 }
             }
+            // FORM OPTIONS FROM A COLLECTION (web_builder #159, contract §7.2). Every miss renders
+            // a choice field with only its placeholder (no authored fallback), or a room list that
+            // never narrows — and the server refuses any other answer as not_an_option.
+            if (['form-select', 'form-radio', 'form-checkbox'].includes(type) && String(cfg.optionSource ?? '').trim() === 'record') {
+                const why = [];
+                if (!String(cfg.recordCollectionId ?? '').trim())
+                    why.push('config.recordCollectionId names no collection');
+                if (!RECORD_FIELD_ID.test(String(cfg.recordLabelField ?? '')))
+                    why.push('config.recordLabelField is not a field ID');
+                const pNode = String(cfg.recordParentNode ?? '');
+                const pField = String(cfg.recordParentField ?? '');
+                if (pNode || pField) {
+                    const pc = d.nodes[pNode]?.config;
+                    if (type !== 'form-select')
+                        why.push('only a form-select narrows by a parent field');
+                    else if (!pNode || !pField)
+                        why.push('recordParentNode and recordParentField go together');
+                    else if (d.nodes[pNode]?.data.type !== 'form-select' || String(pc?.optionSource ?? '').trim() !== 'record')
+                        why.push(`recordParentNode "${pNode}" is not a record-sourced form-select`);
+                    else if (!RECORD_FIELD_ID.test(pField))
+                        why.push(`recordParentField "${pField}" is not a field ID`);
+                }
+                if (why.length) {
+                    out.push({
+                        code: 'record_option_invalid',
+                        nodeId: id,
+                        type,
+                        problem: `A choice field listing records that shows no options or never narrows: ${why.join('; ')}.`,
+                        fix: fill('record_option_invalid', { id }),
+                    });
+                }
+            }
             // RECORD FILTERS (web_builder PR #157, contract §7.1): a filter/sort control aimed at a
             // record list. Every miss below renders a control that empties the list or narrows nothing.
             {
@@ -730,7 +765,8 @@ opts = {}) {
                 while (list && d.nodes[list] && d.nodes[list].data.type !== 'list-dataset')
                     list = d.nodes[list].data.parent;
                 const lcfg = list && d.nodes[list] ? d.nodes[list].config : undefined;
-                if (lcfg?.datasetSource !== 'record') {
+                // On a record detail page the PAGE supplies the record outside any list.
+                if (lcfg?.datasetSource !== 'record' && !(opts.pageType === 'record' && !list)) {
                     out.push({
                         code: 'no_data_context',
                         nodeId: id,

package/dist/tools/live.js

@@ -745,21 +745,23 @@ export function registerLiveTools(server, ctx, session) {
         // `force` gets past it, recorded under `forced`.
         if (RECORD_SOURCE.test(source)) {
             const scope = recordScope((x) => (d.has(x) ? d.node(x) : undefined), id);
-            // Resolved only when there is something to read: an empty scope is refused below
-            // without a fetch, and must not fail on a missing SB_SITE first.
-            const site = scope.length ? siteFor(ctx, session.page()?.siteId) : '';
+            const open = session.page();
+            const site = siteFor(ctx, open?.siteId);
+            const get = async (path) => request({ base: ctx.base, method: 'GET', path: `/api/sites/${encodeURIComponent(site)}${path}`, token: siteToken(ctx), fetchImpl: ctx.fetchImpl });
             let withFields;
             try {
+                // A RECORD DETAIL PAGE (web_builder #160) supplies its record outside any list:
+                // the collections attached to it are the scope.
+                if (!scope.length && open) {
+                    const links = (await get(`/page-links?pageId=${encodeURIComponent(open.pageId)}&linkType=recordCollection`));
+                    for (const l of links.links ?? [])
+                        if (l.linkId)
+                            scope.push(l.linkId);
+                }
                 withFields = await Promise.all(scope.map(async (cid) => {
                     if (!cid)
                         return { collectionId: '(none set)', fields: [] };
-                    const got = (await request({
-                        base: ctx.base,
-                        method: 'GET',
-                        path: `/api/sites/${encodeURIComponent(site)}/collections/${encodeURIComponent(cid)}/fields`,
-                        token: siteToken(ctx),
-                        fetchImpl: ctx.fetchImpl,
-                    }));
+                    const got = (await get(`/collections/${encodeURIComponent(cid)}/fields`));
                     return { collectionId: cid, fields: got.fields ?? [] };
                 }));
             }
@@ -776,6 +778,26 @@ export function registerLiveTools(server, ctx, session) {
                     if (why)
                         throw new Error(`sbuilder: ${why}`);
                 });
+                // record.url resolves only for a collection with an attached record page.
+                const cid = scope[0];
+                if (source === 'record.url' && cid) {
+                    let attached = true;
+                    try {
+                        await get(`/page-links/recordCollection/${encodeURIComponent(cid)}`);
+                    }
+                    catch (e) {
+                        if (e.status !== 404)
+                            throw e;
+                        attached = false;
+                    }
+                    soft(guard, () => {
+                        if (!attached) {
+                            throw new Error(`sbuilder: collection ${cid} has no record detail page, so record.url is never emitted and the link ` +
+                                'stays a plain button. Create a page of type "record", attach it with PUT ' +
+                                `/api/sites/{siteId}/page-links/recordCollection/${cid} {pageId}, and publish it.`);
+                        }
+                    });
+                }
             }
         }
         const forced = guard.forced.length ? { forced: guard.forced } : {};

package/package.json

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